added a madarin readme

.dockerignore

@@ -0,0 +1,19 @@
+.git
+.gitignore
+node_modules
+dist
+tests
+coverage
+*.log
+.env
+.env.*
+.env.example
+.npmrc
+README.md
+CONTRIBUTING.md
+LICENSE
+stdout
+docker-compose*.yaml
+systemd/
+docs/
+templates/

.env.example

@@ -0,0 +1,39 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# sorokeep — environment variable reference
+#
+# Copy this file to .env and fill in the values for your deployment target.
+# Docker Compose will automatically load variables from a .env file in the
+# same directory as docker-compose.yaml.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Network ───────────────────────────────────────────────────────────────────
+# Which Stellar network the daemon will monitor.
+# Accepted values: mainnet | testnet | standalone
+SOROKEEP_NETWORK=standalone
+
+# ── Soroban RPC endpoint ──────────────────────────────────────────────────────
+# Full URL to the Soroban RPC endpoint.
+# When running alongside the Quickstart container, the service name "stellar"
+# resolves inside the Docker bridge network.
+#
+# Local devnet (default):
+SOROKEEP_RPC_URL=http://stellar:8000/soroban/rpc
+#
+# Stellar Testnet public endpoint:
+# SOROKEEP_RPC_URL=https://soroban-testnet.stellar.org
+
+# ── Polling interval ──────────────────────────────────────────────────────────
+# How often (in milliseconds) the daemon checks contract TTLs.
+# Minimum: 10000 (10 seconds)
+# Default: 300000 (5 minutes)
+# Recommended for local devnet: 30000 (30 seconds)
+SOROKEEP_POLLING_INTERVAL=300000
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+# Log verbosity level (debug | info | warn | error).
+# Set to "debug" for local development / devnet runs.
+LOG_LEVEL=info
+
+# ── Node environment ──────────────────────────────────────────────────────────
+# Keep "production" unless you are actively hacking on the daemon itself.
+NODE_ENV=production

.github/CODEOWNERS

@@ -0,0 +1,13 @@
+# Default owner for everything in the repo, unless a more specific rule below matches.
+*                           @AbdulmalikAlayande
+
+# Anything touching secret-key handling or transaction submission gets
+# mandatory review — see SECURITY.md for why these paths are sensitive.
+/src/core/extension.ts     @AbdulmalikAlayande
+/src/core/channels.ts      @AbdulmalikAlayande
+/src/core/vault.ts         @AbdulmalikAlayande
+/src/core/aws_secrets.ts   @AbdulmalikAlayande
+/src/db/schema.sql         @AbdulmalikAlayande
+
+/.github/                  @AbdulmalikAlayande
+/SECURITY.md                @AbdulmalikAlayande

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,80 @@
+name: Bug Report
+description: Something in sorokeep isn't working as expected
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, check the [open issues](https://github.com/AbdulmalikAlayande/sorokeep/issues) for a duplicate.
+        If this is a security vulnerability (key leakage, unintended transactions, signature bypass), do **not** file it here — use [Security Advisories](https://github.com/AbdulmalikAlayande/sorokeep/security/advisories/new) instead.
+
+  - type: input
+    id: version
+    attributes:
+      label: Sorokeep version
+      description: Output of `sorokeep --version` or the npm version installed
+      placeholder: "1.0.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: command
+    attributes:
+      label: Which command or component?
+      options:
+        - watch
+        - status
+        - daemon
+        - alerts
+        - guard (auto-extension)
+        - costs
+        - restore
+        - resources
+        - budget
+        - channels
+        - inspect
+        - check
+        - db
+        - MCP server
+        - Other / not command-specific
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What you expected vs. what actually happened
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps, including the exact command(s) run. Redact contract IDs/secrets if they're sensitive.
+      placeholder: |
+        1. sorokeep watch C... --network testnet
+        2. sorokeep guard C... --keypair-env STELLAR_SECRET_KEY --auto-extend
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs or error output
+      description: Paste any error output or daemon logs. Sorokeep never logs secret keys, but double-check before pasting.
+      render: shell
+
+  - type: input
+    id: network
+    attributes:
+      label: Network
+      placeholder: "testnet / mainnet / local sandbox"
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      placeholder: "22.x"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,55 @@
+name: Feature Request
+description: Propose a new capability or improvement
+labels: ["enhancement", "needs-discussion"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Per [CONTRIBUTING.md](https://github.com/AbdulmalikAlayande/sorokeep/blob/main/CONTRIBUTING.md#larger-contributions), open an issue and get alignment **before** writing code for anything beyond a small fix — especially new CLI commands, schema changes, or changes to the monitor/daemon cycle. This template is that discussion.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the gap or pain point. Prefer a real scenario over an abstract one.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you build? A new command, a new alert channel, a schema change, etc.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which area does this touch?
+      options:
+        - New alert channel
+        - CLI command / UX
+        - Database schema
+        - Monitor / daemon cycle
+        - Auto-extension logic
+        - MCP server / tools
+        - Docs
+        - CI/CD / release process
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Anything else you thought about, including "do nothing" if relevant
+
+  - type: checkboxes
+    id: willing
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to implement this myself with guidance
+        - label: I'm proposing this for someone else to pick up

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## What does this PR do?
+
+<!-- One or two sentences. Link the issue this addresses, if any: Closes #123 -->
+
+## Why?
+
+<!-- The motivation — what problem this solves or what it enables. -->
+
+## Does this touch secret-key handling or transaction submission?
+
+<!-- If yes (extension.ts, channels.ts, restore, key resolution from env/AWS/Vault), say so explicitly — reviewers will scrutinize this path per SECURITY.md. -->
+
+- [ ] Yes — see notes above
+- [ ] No
+
+## Checklist
+
+- [ ] Tests pass (`npm test`)
+- [ ] Type check passes (`npx tsc --noEmit`)
+- [ ] Lint passes (`npm run lint`)
+- [ ] Tests cover the new functionality (TDD preferred — see [CONTRIBUTING.md](../CONTRIBUTING.md#test-driven-development))
+- [ ] No unnecessary dependencies added
+- [ ] Commit messages follow [conventional format](../CONTRIBUTING.md#commits)
+- [ ] No `console.log` in core logic
+- [ ] ADR added if this is a significant design decision (see [docs/adr](../docs/adr))
+- [ ] E2E sandbox tested, if this touches RPC or daemon behavior (see [docs/e2e-sandbox.md](../docs/e2e-sandbox.md))

.github/workflows/ci.yml

@@ -1,23 +1,47 @@
-name: CI
+name: CI Pipeline
 
 on:
   push:
-    branches: [main]
+    branches: [ "main" ]
   pull_request:
-    branches: [main]
+    branches: [ "main" ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
-  test:
+  build-and-test:
     runs-on: ubuntu-latest
+
     strategy:
       matrix:
-        node-version: [22]
+        node-version: [22.x]
+
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
-      - run: npm ci
-      - run: npx vitest run
-      - run: npx tsc --noEmit
+    - name: Checkout Repository
+      uses: actions/checkout@v4
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+
+    - name: Clean Install Dependencies
+      run: npm ci
+
+    - name: Audit Dependencies
+      run: npm audit --audit-level=high
+
+    - name: Lint Code
+      run: npm run lint
+
+    - name: Run Tests
+      run: npm run test -- --coverage
+
+    - name: Build Project
+      run: npm run build