feat: contributor docs, arch diagrams, canonical Railway guide, env-c…

.github/CODEOWNERS

@@ -1,12 +1,41 @@
-# Default owners for everything in the repository
+# CODEOWNERS — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+#
+# Each line is a file pattern followed by one or more owners.
+# The last matching rule takes precedence.
+#
+# @SynapsVault/core must approve every PR. The more specific rules below
+# ensure the right sub-team is also notified for their area.
+
+# Default: all files require core team approval
 * @SynapsVault/core
 
-# Kubernetes manifests, Dockerfiles, and CI/CD workflows
-/k8s/ @SynapsVault/core
-/backend/ @SynapsVault/core
-/frontend/ @SynapsVault/core
-/.github/ @SynapsVault/core
+# Kubernetes manifests and Kustomize overlays — infra team
+/k8s/ @SynapsVault/core @SynapsVault/infra
+
+# Dockerfiles — infra team
+/backend/Dockerfile @SynapsVault/core @SynapsVault/infra
+/frontend/Dockerfile @SynapsVault/core @SynapsVault/infra
+
+# CI / CD workflows and Actions config — infra team
+/.github/workflows/ @SynapsVault/core @SynapsVault/infra
+/.github/dependabot.yml @SynapsVault/core @SynapsVault/infra
+/.github/app-versions.yml @SynapsVault/core @SynapsVault/infra
+
+# Issue / PR templates — any core member
+/.github/ISSUE_TEMPLATE/ @SynapsVault/core
+/.github/PULL_REQUEST_TEMPLATE.md @SynapsVault/core
 
-# Operational scripts and backup/restore runbooks
+# Deployment and operational scripts
 /scripts/ @SynapsVault/core
+
+# Monitoring configuration (alerts, dashboards, recording rules)
+/monitoring/ @SynapsVault/core
+
+# Runbooks and guides
 /docs/ @SynapsVault/core
+
+# Security-sensitive files — always require a security-aware core review
+/SECURITY.md @SynapsVault/core
+/k8s/secrets.yaml @SynapsVault/core @SynapsVault/infra
+/.github/workflows/deploy-k8s.yml @SynapsVault/core @SynapsVault/infra
+/.github/workflows/backup.yml @SynapsVault/core @SynapsVault/infra

.github/ISSUE_TEMPLATE/bug_report.md

@@ -8,29 +8,45 @@ assignees: ""
 
 ## Affected Component
 
-- [ ] `scripts/` (contract deploy/rollback, seed, smoke test, backup/restore/db-rollback)
-- [ ] `k8s/` (Kubernetes / Kustomize manifests)
+<!-- Check all that apply. -->
+
+- [ ] `scripts/` — contract deploy/rollback, seed, smoke test, backup/restore/db-rollback
+- [ ] `scripts/check-env.js` — environment variable validation
+- [ ] `k8s/` — Kubernetes / Kustomize manifests
 - [ ] `backend/Dockerfile` or `frontend/Dockerfile`
-- [ ] `monitoring/` (Prometheus, Alertmanager, Grafana)
-- [ ] `.github/workflows/` (CI, K8s deploy, contract deploy, backups)
-- [ ] `docs/` (runbooks and guides)
+- [ ] `monitoring/` — Prometheus, Alertmanager, Grafana
+- [ ] `.github/workflows/` — CI, K8s deploy, contract deploy, backups
+- [ ] `docs/` — runbooks and guides
+- [ ] `docker-compose.yml` / `.env.example`
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| OS / Shell | |
+| Node.js version (`node --version`) | |
+| npm version (`npm --version`) | |
+| Target network | `testnet` / `mainnet` / `futurenet` / `local` |
+| Deploy target | `compose` / `k8s` / `railway` |
+| Relevant tool versions (kubectl, docker, etc.) | |
 
 ## Steps to Reproduce
 
 1.
 2.
 3.
 
-## Expected Behavior
+## Expected Behaviour
+
+<!-- What should happen? -->
 
-## Actual Behavior / Logs
+## Actual Behaviour / Error Output
 
 ```text
-Paste relevant error output or logs here (redact any secrets or keys).
+Paste relevant error output or logs here.
+IMPORTANT: redact any secrets, keys, or connection strings before pasting.
 ```
 
-## Environment
+## Additional Context
 
-- OS / Shell:
-- Node.js version:
-- Target network (`testnet` / `mainnet` / `futurenet`):
+<!-- Links to related issues, relevant config snippets (redacted), or screenshots. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,20 +1,45 @@
 ---
 name: Feature / Operational Enhancement
-about: Propose an improvement to deployment automation, observability, or runbooks
+about: Propose an improvement to deployment automation, observability, scripts, or runbooks
 title: "[feat] "
 labels: ["enhancement"]
 assignees: ""
 ---
 
 ## Problem Statement
 
-<!-- Describe the operational gap, risk, or manual toil this enhancement addresses. -->
+<!-- Describe the operational gap, risk, manual toil, or missing capability this addresses.
+     Be specific: what breaks, what takes too long, what is undocumented? -->
 
 ## Proposed Solution
 
-<!-- Describe the desired behavior, script flags, manifest changes, or documentation updates. -->
+<!-- Describe the desired behaviour: new script flags, manifest changes, CI job additions,
+     documentation restructuring, etc. Keep it concrete. -->
+
+## Alternatives Considered
+
+<!-- What other approaches did you consider, and why did you rule them out? -->
+
+## Affected Components
+
+<!-- Check all that apply. -->
+
+- [ ] `scripts/` — deployment or operational scripts
+- [ ] `k8s/` — Kubernetes manifests / Kustomize overlays
+- [ ] `backend/Dockerfile` or `frontend/Dockerfile`
+- [ ] `.github/workflows/` — CI or deploy workflows
+- [ ] `monitoring/` — alerting or dashboards
+- [ ] `docs/` — runbooks or guides
+- [ ] `docker-compose.yml` / `.env.example`
 
 ## Acceptance Criteria
 
+<!-- Define done. Each criterion should be independently verifiable. -->
+
+- [ ]
 - [ ]
 - [ ]
+
+## Additional Context
+
+<!-- Links to related issues, external docs, or prior discussion. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,9 +7,53 @@
 <!-- Link the issue(s) resolved, e.g. Closes #12 -->
 Closes #
 
+## Type of change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature or enhancement
+- [ ] Documentation update
+- [ ] Dependency upgrade
+- [ ] Refactor / code quality improvement
+
+## Changes made
+
+<!-- List the files and components changed, and why. -->
+
+-
+-
+
+## Testing
+
+<!-- Describe how you tested this change. -->
+
 ## Verification Checklist
 
+**Environment**
+- [ ] `node scripts/check-env.js --target compose` passes (no placeholder values)
+
+**Scripts**
 - [ ] Shell scripts pass `shellcheck scripts/*.sh` and `bash -n scripts/*.sh`
 - [ ] Node scripts and unit tests pass (`npm test`)
-- [ ] Kubernetes manifests render and validate cleanly (`kubectl kustomize k8s/` / `kubeconform -strict`)
-- [ ] Documentation in `docs/` or `README.md` has been updated if operational behavior changed
+- [ ] ESLint passes (`npm run lint`)
+- [ ] Prettier check passes (`npm run format:check`)
+
+**Kubernetes** _(skip if no `k8s/` changes)_
+- [ ] Manifests render cleanly (`kubectl kustomize k8s/ > /dev/null`)
+- [ ] `kubeconform -strict` reports no errors
+- [ ] `kube-linter lint` reports no errors
+
+**Monitoring** _(skip if no `monitoring/` changes)_
+- [ ] `promtool check rules monitoring/alert-rules.yml` passes
+- [ ] `amtool check-config monitoring/alertmanager.yml` passes
+
+**Docker Compose** _(skip if no compose/Dockerfile changes)_
+- [ ] `docker compose config --quiet` passes with `.env.example`
+
+**Documentation**
+- [ ] `docs/` or `README.md` updated if operational behaviour changed
+- [ ] `docs/ENVIRONMENT-VARIABLES.md` updated if any env var was added/changed
+- [ ] Cross-links point to the right canonical guides (no duplicated Railway/k8s content)
+
+**Security**
+- [ ] No secrets, keys, or real credentials introduced in any file
+- [ ] `k8s/secrets.yaml` not added to `k8s/kustomization.yaml`

.github/workflows/ci.yml

@@ -107,6 +107,15 @@ jobs:
         run: npm ci
       - name: Syntax-check scripts
         run: for f in scripts/*.js scripts/*.cjs; do node --check "$f"; done
+      - name: Check env placeholders (compose target)
+        run: |
+          cp .env.example .env
+          node scripts/check-env.js --target compose --env-file .env || true
+          # In CI the .env.example intentionally contains placeholders.
+          # This step validates that check-env.js itself runs without crashing;
+          # the actual placeholder check is enforced in deploy workflows where
+          # real secrets are available via GitHub Actions secrets.
+          node scripts/check-env.js --help > /dev/null
       - name: Unit tests
         run: npm test
       - name: CLI smoke tests
@@ -197,6 +206,11 @@ jobs:
         run: npm ci
       - name: Prepare env
         run: cp .env.example .env
+      - name: Check env (compose)
+        # .env.example contains placeholder values; this is a best-effort check
+        # to ensure check-env.js runs. Failures are informational only in CI
+        # because secrets are not available in this job.
+        run: node scripts/check-env.js --target compose --env-file .env || true
       - name: Start stack
         run: docker compose up -d --wait
       - name: Run smoke test

.github/workflows/deploy-k8s.yml

@@ -236,6 +236,41 @@ jobs:
             echo "ready=true" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Validate environment variables (k8s target)
+        # Fail fast if any required variable is missing or contains a placeholder.
+        # Secrets are mapped from GitHub Actions secrets into the environment so
+        # the script can verify they have been filled in.
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }}
+          SUPABASE_URL: ${{ vars.SUPABASE_URL }}
+          SUPABASE_STORAGE_BUCKET: ${{ vars.SUPABASE_STORAGE_BUCKET }}
+          STELLAR_NETWORK: ${{ vars.STELLAR_NETWORK }}
+          SOROBAN_RPC_URL: ${{ vars.SOROBAN_RPC_URL }}
+          USDC_CONTRACT_ID: ${{ vars.USDC_CONTRACT_ID }}
+          PAY_TO: ${{ vars.PAY_TO }}
+          AGENT_SECRET_KEY: ${{ secrets.AGENT_SECRET_KEY }}
+          REGISTRY_SECRET_KEY: ${{ secrets.REGISTRY_SECRET_KEY }}
+          STELLAR_CONTRACT_VAULT_REGISTRY: ${{ vars.STELLAR_CONTRACT_VAULT_REGISTRY }}
+          STELLAR_CONTRACT_ACCESS_LEASE: ${{ vars.STELLAR_CONTRACT_ACCESS_LEASE }}
+          STELLAR_CONTRACT_SUBSCRIPTION: ${{ vars.STELLAR_CONTRACT_SUBSCRIPTION }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          ADMIN_API_KEY: ${{ secrets.ADMIN_API_KEY }}
+          STELLAR_SECRET_KEY: ${{ secrets.STELLAR_SECRET_KEY }}
+          STELLAR_PUBLIC_KEY: ${{ vars.STELLAR_PUBLIC_KEY }}
+          POSTGRES_USER: ${{ vars.POSTGRES_USER || 'postgres' }}
+          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD || 'postgres' }}
+          POSTGRES_DB: ${{ vars.POSTGRES_DB || 'app' }}
+          SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+        run: node scripts/check-env.js --target k8s
+
       - name: Set up kubectl
         if: steps.config.outputs.ready == 'true'
         uses: azure/setup-kubectl@v5