settld 0.1.1 → 0.1.5

package/docs/marketing/show-hn-post.md

@@ -0,0 +1,45 @@
+# Show HN Draft
+
+## Title (pick one)
+
+1. Show HN (Repost): Settld – verify-before-release gateway for HTTP 402 (x402) APIs (OSS)
+2. Show HN (Repost): Settld – verifiable settlement receipts for agent spend (OSS)
+3. Show HN (Repost): Settld – deterministic release/refund decisions + receipt trail for x402
+
+---
+
+## Post Body
+
+Hi HN,
+
+Settld is an open source artifact protocol + verifier for producing hash-bound “settlement receipts”: deterministic records that tie *terms + evidence refs + a release/refund decision* together so a counterparty can verify what happened without trusting your database.
+
+Fastest way to try it is the in-repo x402 gateway demo (about 10 minutes):
+
+```bash
+npm ci && npm run quickstart:x402
+```
+
+It runs a local Settld API, a mock upstream that returns `HTTP 402 Payment Required` + `x-payment-required`, and a thin gateway. First request returns `402` plus `x-settld-gate-id`. Retry with that gate id and `x-payment: paid`, and the gateway calls Settld to:
+
+`hold -> verify -> release/refund (+ optional holdback)` and returns a receipt-like trail via `x-settld-*` headers (and a `GET /x402/gate/:id` inspection endpoint).
+
+Full quickstart (Docker + Linux notes): `docs/QUICKSTART_X402_GATEWAY.md`
+
+Two boundaries up front:
+
+- This is not a payment processor. The demo uses `X402_AUTOFUND=1` to simulate funding in an internal ledger so escrow-style holds can be created.
+- Multi-hop “agents hiring agents” is not automatic today. The repo includes an `AgreementDelegation.v1` primitive + deterministic cycle checks when a gate is bound to an agreement graph; full compositional settlement is still in progress.
+
+Feedback I’d love:
+
+1. If you’re shipping agent workflows that spend money today, what evidence would you require to automate release/refund?
+2. Where would this break first in your stack: metering, dispute windows, refunds/chargebacks, or trust anchors?
+
+---
+
+## Submission Notes (not part of the post)
+
+- Post Tue-Thu mornings ET if you want feedback quickly.
+- If someone says “just use Stripe Connect”: Stripe moves money; Settld decides how much should move based on verifiable evidence, deterministically.
+- If someone says “just use a smart contract”: smart contracts can enforce on-chain state; Settld is about verifying off-chain work completion and producing portable, deterministic receipts.

package/docs/ops/ARTIFACT_VERIFICATION_STATUS.md

@@ -0,0 +1,43 @@
+# Artifact Verification Status API
+
+This endpoint provides a normalized verification signal for an artifact:
+
+- `green`: verification passed
+- `amber`: insufficient evidence or unknown proof state
+- `red`: verification failed
+
+## Endpoint
+
+- `GET /artifacts/{artifactId}/status`
+  - Scopes: `ops_read` or `audit_read` or `finance_read`
+
+## Bulk status in ops job list
+
+- `GET /ops/jobs` includes inline verification fields per job:
+  - `verificationStatus` (`green` | `amber` | `red`)
+  - `evidenceCount`, `activeEvidenceCount`
+  - `slaCompliancePct`
+  - `verification` (full normalized verification object)
+- Scopes: `ops_read` or `audit_read`
+
+## Response shape
+
+The API returns:
+
+- Artifact identity fields (`artifactId`, `artifactType`, `artifactHash`, `jobId`, `sourceEventId`)
+- `verification` object with:
+  - `verificationStatus` (`green` | `amber` | `red`)
+  - `proofStatus` (`PASS` | `INSUFFICIENT_EVIDENCE` | `FAIL` | `null`)
+  - `reasonCodes`, `missingEvidence`
+  - `evidenceCount`, `activeEvidenceCount`
+  - `slaCompliancePct`
+  - Coverage metrics (`requiredZones`, `reportedZones`, `belowThresholdZones`, `missingZoneCount`, `excusedZones`)
+
+## Example
+
+```sh
+curl -sS "http://localhost:3000/artifacts/art_123/status" \
+  -H "x-proxy-tenant-id: tenant_default" \
+  -H "x-settld-protocol: 1.0" \
+  -H "x-proxy-ops-token: <ops_read_token>" | jq
+```

package/docs/ops/BILLING_WEBHOOK_REPLAY.md

@@ -0,0 +1,105 @@
+# Stripe Billing Webhook Replay Guardrail Runbook
+
+Use this runbook when Stripe webhook ingestion shows replayable dead-letter volume or subscription drift risk.
+
+## Preconditions
+
+- You have `finance_read` + `finance_write` scopes for the affected tenant.
+- Environment is set:
+  - `SETTLD_BASE_URL`
+  - `PROXY_OPS_TOKEN`
+  - `SETTLD_TENANT_ID`
+- `curl` and `jq` are available.
+
+## Reproducible command set
+
+### 1) Snapshot reconcile report
+
+```bash
+curl -sS \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/reconcile/report?limit=200" | jq .
+```
+
+Focus on:
+- `rejectedReasonCounts`
+- `replayableRejectedCount`
+- `sourceCounts`
+
+### 2) List replay candidates
+
+```bash
+curl -sS \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/dead-letter?limit=200" | jq .
+```
+
+Optional filters:
+- `.../dead-letter?reason=<reason>&eventType=<eventType>&limit=200`
+
+### 3) Dry-run replay
+
+```bash
+curl -sS -X POST \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "content-type: application/json" \
+  -d '{"dryRun":true,"limit":200}' \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/dead-letter/replay" | jq .
+```
+
+### 4) Execute replay
+
+```bash
+curl -sS -X POST \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "content-type: application/json" \
+  -d '{"dryRun":false,"limit":200}' \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/dead-letter/replay" | jq .
+```
+
+### 5) Validate post-replay state
+
+```bash
+curl -sS \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/reconcile/report?limit=200" | jq .
+```
+
+### 6) Scripted flow (recommended)
+
+```bash
+# Dry-run (default)
+scripts/dev/billing-webhook-replay.sh
+
+# Execute replay
+DRY_RUN=0 scripts/dev/billing-webhook-replay.sh
+
+# Scoped replay by reason/event type
+DRY_RUN=0 REASON=reconcile_apply_failed EVENT_TYPE=customer.subscription.updated \
+  scripts/dev/billing-webhook-replay.sh
+```
+
+## On-call validation checklist
+
+- [ ] Baseline report captured (`reconcile/report`) and incident ticket updated with snapshot.
+- [ ] Replay candidate count and reasons reviewed (`dead-letter`).
+- [ ] Dry-run replay performed and no schema/permission errors observed.
+- [ ] Live replay executed (`dryRun=false`) with `summary.failed == 0` (or failures documented).
+- [ ] Post-replay report shows expected movement in:
+  - [ ] `replayableRejectedCount` (downward or unchanged with reason)
+  - [ ] `ingestBreakdown.replayed` (upward)
+  - [ ] `sourceCounts.dead_letter_replay` (upward)
+- [ ] Tenant billing plan state verified:
+  - [ ] `GET /ops/finance/billing/plan`
+- [ ] Incident notes include replay scope (`reason`, `eventType`, `auditIds`) and final counts.
+
+## Rollback / safety notes
+
+- Replay is idempotent at event level; do not mutate historical audit rows manually.
+- If replay failures increase (`dead_letter_replay_apply_failed`), stop and investigate root cause before rerunning.
+- Never disable signature verification as an incident workaround.

package/docs/ops/CI_FLAKE_BUDGET.md

@@ -0,0 +1,31 @@
+# CI Flake Budget
+
+This repo runs with a strict flake budget for paid-call kernel coverage.
+
+## Policy
+
+- Budget: 0
+- No hidden retries in CI for test workflows.
+- No `continue-on-error: true` for test jobs.
+- No shell-level suppression (`|| true`) for test commands.
+
+## Scope
+
+- `.github/workflows/tests.yml`
+- The paid-call kernel suite job (`mcp_paid_call_kernel_suite`)
+- Existing `unit_tests` and quickstart smoke jobs
+
+## Escalation
+
+If a test flakes:
+
+1. Open/attach an issue immediately (`type:ops` or `type:bug`).
+2. Either:
+   - fix the test in the same PR, or
+   - quarantine with explicit owner + expiry date + follow-up issue.
+3. Do not merge by masking failure with retries or error suppression.
+
+## Enforcement
+
+`scripts/ci/flake-budget-guard.mjs` enforces the policy markers and blocks forbidden flaky-tolerance patterns in `tests.yml`.
+

package/docs/ops/GO_LIVE_GATE_S13.md

@@ -0,0 +1,27 @@
+# S13 Go-Live Gate
+
+This gate operationalizes `STLD-T182`.
+
+## Command
+
+```bash
+RUN_THROUGHPUT_DRILL=1 \
+ALLOW_THROUGHPUT_SKIP=0 \
+GO_LIVE_TEST_COMMAND="node --test test/settlement-kernel.test.js && node --test test/api-e2e-ops-money-rails.test.js && node --test test/api-e2e-ops-finance-net-close.test.js && node --test test/api-e2e-ops-arbitration-workspace.test.js && node --test test/api-e2e-ops-command-center.test.js && node --test test/api-e2e-billing-plan-enforcement.test.js" \
+node scripts/ci/run-go-live-gate.mjs
+node scripts/ci/build-launch-cutover-packet.mjs
+```
+
+## Required checks
+
+- Deterministic critical test suite passes.
+- 10x throughput drill report passes.
+- Throughput incident rehearsal report passes.
+- Lighthouse tracker shows at least 3 accounts in `paid_production_settlement_confirmed`/`production_active` with `signedAt`, `goLiveAt`, and `productionSettlementRef` populated.
+
+## Output
+
+- `artifacts/gates/s13-go-live-gate.json`
+- `artifacts/gates/s13-launch-cutover-packet.json`
+
+Gate is **fail-closed**: non-zero exit on any failed required check.

package/docs/ops/HOSTED_BASELINE_R2.md

@@ -0,0 +1,129 @@
+# Sprint R2: Hosted Baseline (Staging + Production)
+
+This is the minimum hosted setup for a real product surface.
+
+## 1) Environment topology
+
+- `staging.app.settld.work` (frontend, Vercel)
+- `staging.api.settld.work` (API, Railway)
+- `app.settld.work` (frontend, Vercel)
+- `api.settld.work` (API, Railway)
+- Separate Postgres instances/schemas and separate secret sets for staging/prod.
+- Separate signing keys per environment (never reuse signer keys across staging/prod).
+
+## 2) Railway service split
+
+Create two Railway services from this repo per environment:
+
+- `settld-api`:
+  - start command: `npm run start:prod`
+- `settld-worker`:
+  - start command: `npm run start:maintenance`
+
+Both services must point at the same environment DB and secret set for that environment.
+
+## 3) Required runtime controls
+
+- Tenant rate limiting:
+  - `PROXY_RATE_LIMIT_RPM`
+  - `PROXY_RATE_LIMIT_BURST`
+- API-key rate limiting:
+  - `PROXY_RATE_LIMIT_PER_KEY_RPM`
+  - `PROXY_RATE_LIMIT_PER_KEY_BURST`
+- Tenant quotas:
+  - `PROXY_QUOTA_*` and `PROXY_QUOTA_PLATFORM_*` envs from `docs/CONFIG.md`.
+
+## 4) Observability + alerts
+
+Scrape `/metrics` and enable rules from `deploy/observability/prometheus-rules.yml`.
+
+R2-required alerts:
+
+- replay mismatches: `replay_mismatch_gauge`
+- stuck disputes: `disputes_over_sla_gauge`, `arbitration_over_sla_gauge`
+- stuck holds: `settlement_holds_over_24h_gauge`
+- worker lag: `worker_outbox_pending_total_gauge`, `worker_deliveries_pending_total_gauge`
+
+Reference: `docs/ALERTS.md`.
+
+## 5) Backups + restore drill
+
+- Backup/restore scripts: `scripts/backup-pg.sh`, `scripts/restore-pg.sh`
+- Full drill script: `scripts/backup-restore-test.sh`
+- Run at least weekly for staging and monthly for production.
+- Record evidence in incident/runbook logs (timestamp, operator, pass/fail, DB snapshot IDs).
+
+## 6) Clerk onboarding handoff (app -> API)
+
+The app should map Clerk identity/org to a tenant ID, then bootstrap that tenant on the API side.
+
+Recommended server-side flow:
+
+1. User signs up/signs in via Clerk at `*.app.settld.work`.
+2. App backend chooses tenant ID (for example: `tenant_<clerk_org_id>`).
+3. App backend calls:
+   - `POST /ops/tenants/bootstrap` (with a privileged ops token, server-side only)
+4. App stores/bootstrap-returns tenant API key and presents onboarding state + Explorer links.
+
+## 7) New-tenant acceptance run
+
+Use this command to prove onboarding is self-serve and conformance-ready:
+
+```bash
+npm run ops:tenant:bootstrap:conformance -- \
+  --base-url https://staging.api.settld.work \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --tenant-id "tenant_demo_$(date +%s)"
+```
+
+This performs:
+
+- tenant bootstrap
+- API key issuance
+- kernel conformance run with that new tenant/API key
+
+## 8) Acceptance bar (R2)
+
+- Brand-new tenant can be created from app onboarding flow.
+- Tenant receives API key without manual DB edits.
+- Tenant can run kernel conformance against staging/prod.
+- Explorer, replay, and closepack flows are reachable for that tenant.
+
+## 9) Hosted baseline evidence command
+
+Use the ops command below to collect a deterministic hosted-baseline evidence artifact (health, ops status, metrics, alert metric presence, billing catalog/quotas, optional rate-limit probe, optional backup/restore drill evidence):
+
+```bash
+npm run ops:hosted-baseline:evidence -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_default \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --environment staging \
+  --rate-limit-mode optional \
+  --rate-limit-probe-requests 20 \
+  --out ./artifacts/ops/hosted-baseline-evidence-staging.json
+```
+
+If you want the command to execute the backup/restore drill inline:
+
+```bash
+npm run ops:hosted-baseline:evidence -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_default \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --environment staging \
+  --run-backup-restore true \
+  --database-url "$DATABASE_URL" \
+  --restore-database-url "$RESTORE_DATABASE_URL" \
+  --require-backup-restore true \
+  --out ./artifacts/ops/hosted-baseline-evidence-staging.json
+```
+
+Important:
+
+- `DATABASE_URL` and `RESTORE_DATABASE_URL` must be real connection strings (not redacted placeholders like `postgres://...`).
+- Quick preflight:
+
+```bash
+node -e 'for (const n of ["DATABASE_URL","RESTORE_DATABASE_URL"]) { const v=(process.env[n]||"").trim(); if (!v) { console.error(`${n}=missing`); process.exitCode=1; continue; } const u=new URL(v); console.log(`${n} host=${u.hostname} protocol=${u.protocol}`); }'
+```

package/docs/ops/KERNEL_V0_SHIP_GATE.md

@@ -0,0 +1,67 @@
+# Kernel v0 Ship Gate
+
+This is the fail-closed release gate for shipping the current Kernel v0 OSS rails.
+
+## Command
+
+```bash
+node scripts/ci/run-kernel-v0-ship-gate.mjs
+```
+
+Optional:
+
+```bash
+RUN_KERNEL_V0_QUICKSTART_SMOKE=0 node scripts/ci/run-kernel-v0-ship-gate.mjs
+```
+
+Report output:
+
+- `artifacts/gates/kernel-v0-ship-gate.json`
+
+## CI enforcement
+
+1. `.github/workflows/tests.yml` runs `kernel_v0_ship_gate` on every `push` to `main`.
+2. `.github/workflows/release.yml` blocks release unless that same commit has a successful `kernel_v0_ship_gate` result from `tests.yml`.
+
+## Included checks
+
+1. Launch-claim truth gate (`check-kernel-v0-launch-gate.mjs --mode prepublish`)
+2. Core x402 e2e confidence suite
+3. API/SDK contract freeze + OpenAPI snapshot checks
+4. x402 quickstart smoke (`quickstart:x402`, default on)
+
+Any failed check stops the sequence and returns non-zero.
+
+## Rollout plan
+
+1. Canary: ship to internal/demo environments and run full gate before every cut.
+2. Scale-out: ship to design-partner environments after two consecutive green gate runs.
+3. Full OSS release: publish only when the latest gate report is green and attached to release notes.
+
+## Rollback triggers
+
+Rollback immediately if any of the following happen after release:
+
+1. Deterministic replay/receipt verification mismatch in production-like flow.
+2. x402 authorize/verify path starts returning unexpected non-contract error codes.
+3. Quickstart regression (`quickstart:x402`) fails on clean environment.
+
+## Rollback execution
+
+1. Freeze new rollout and revert to previous known-good release/tag.
+2. Re-run ship gate against rollback candidate.
+3. Re-open rollout only after green gate + root-cause note.
+
+## Monitoring and alerting
+
+Track at minimum:
+
+1. `x402` authorize/verify success and conflict code distribution.
+2. Receipt verification failures.
+3. Quickstart smoke health in CI cadence.
+
+## Owner / on-call
+
+- Release owner: Platform/Kernel maintainer
+- Escalation owner: API maintainer
+- Rollback approver: Tech lead on-call

package/docs/ops/LIGHTHOUSE_PRODUCTION_CLOSE.md

@@ -0,0 +1,51 @@
+# Lighthouse Production Close
+
+Tracks `STLD-T180` with repo-auditable evidence.
+
+## Source of truth
+
+- `planning/launch/lighthouse-production-tracker.json`
+
+## Account status model
+
+- `targeting`
+- `contracting`
+- `integration_in_progress`
+- `go_live_scheduled`
+- `paid_production_settlement_confirmed`
+- `production_active`
+
+## Required evidence per account
+
+- Signed commercial date (`signedAt`)
+- Go-live date (`goLiveAt`)
+- Production settlement reference (`productionSettlementRef`)
+
+`productionSettlementRef` should point to a deterministic, queryable settlement artifact ID or run settlement ID.
+
+## Launch criterion
+
+At least 3 accounts must be in `paid_production_settlement_confirmed` or `production_active` with non-empty `productionSettlementRef`.
+
+## Validation path
+
+The go-live gate uses `scripts/ci/lib/lighthouse-tracker.mjs` for readiness checks and requires all active accounts to include:
+- `signedAt` (valid ISO timestamp)
+- `goLiveAt` (valid ISO timestamp and not earlier than `signedAt`)
+- `productionSettlementRef` (non-empty)
+
+## Update commands
+
+Update tracker rows with validation instead of manual JSON edits:
+
+```bash
+npm run ops:lighthouse:update -- \
+  --account lh_001 \
+  --status paid_production_settlement_confirmed \
+  --company-name "Example Co" \
+  --owner "am@settld" \
+  --signed-at 2026-02-10T12:00:00.000Z \
+  --go-live-at 2026-02-11T15:30:00.000Z \
+  --settlement-ref settle_run_abc123 \
+  --notes "First paid production settlement."
+```

package/docs/ops/MCP_COMPATIBILITY_MATRIX.md

@@ -0,0 +1,28 @@
+# MCP Compatibility Matrix
+
+Track real host compatibility evidence here. Update on every major host release or Settld MCP change.
+
+## Status legend
+
+- `green`: passes required flow end-to-end
+- `yellow`: partially working; known gaps
+- `red`: blocked
+
+## Required flow (all hosts)
+
+1. Host discovers `settld.*` tools.
+2. `settld.about` succeeds.
+3. One paid tool call succeeds (`settld.exa_search_paid` or `settld.weather_current_paid`).
+4. `x-settld-*` settlement/verification headers are present.
+5. Artifact output exists and verifies.
+
+## Matrix
+
+| Host | Host Version | Transport | Status | Last Verified (UTC) | Evidence Link | Notes |
+|---|---|---|---|---|---|---|
+| Claude | TBD | stdio | TBD | TBD | TBD | |
+| Cursor | TBD | stdio | TBD | TBD | TBD | |
+| Codex | TBD | stdio | TBD | TBD | TBD | |
+| OpenClaw | TBD | stdio | TBD | TBD | TBD | |
+| Generic MCP host bootstrap path | local CI smoke | stdio | green | 2026-02-20 | `npm run test:ci:mcp-host-smoke` | Boots API + magic-link, generates runtime MCP env, runs `mcp:probe`, and calls `settld.about`; report at `artifacts/ops/mcp-host-smoke.json`. |
+| Generic MCP HTTP client | local repo test harness | HTTP bridge | green | 2026-02-20 | `node --test test/mcp-stdio-spike.test.js test/mcp-http-gateway.test.js test/mcp-paid-exa-tool.test.js test/mcp-paid-weather-tool.test.js test/mcp-paid-llm-tool.test.js test/demo-mcp-paid-exa.test.js` | 9/9 passing in local CI-style run |

package/docs/ops/MINIMUM_PRODUCTION_TOPOLOGY.md

@@ -0,0 +1,89 @@
+# Minimum Production Topology
+
+This is the smallest topology that supports real paid agent tool calls with audit evidence.
+
+## 1) Required runtime components
+
+| Component | Purpose | Start command |
+|---|---|---|
+| `settld-api` | control plane + kernel APIs + receipts + ops endpoints | `npm run start:prod` |
+| `settld-maintenance` | reconciliation/cleanup/maintenance ticks | `npm run start:maintenance` |
+| `postgres` | system of record for tenants, gates, receipts, ops state | managed Postgres |
+| `x402-gateway` | payment challenge/authorize/verify wrapper for paid tool calls | `npm run start:x402-gateway` |
+| paid upstream tool API(s) | actual provider tools (`/exa`, `/weather`, etc.) | provider-specific |
+
+Without all five, the end-to-end paid tool path is incomplete.
+
+## 2) Recommended production shape
+
+- `app.settld.work` -> frontend (Vercel or equivalent)
+- `api.settld.work` -> `settld-api`
+- `gateway.settld.work` -> `x402-gateway` (or internal service DNS)
+- Separate staging/prod stacks with separate DBs (or schemas + strict separation), separate secret sets, and separate signing keys.
+
+Reference baseline: `docs/ops/HOSTED_BASELINE_R2.md`.
+
+## 3) Minimum environment contract
+
+### `settld-api`
+
+- `NODE_ENV=production`
+- `STORE=pg`
+- `DATABASE_URL`
+- `PROXY_PG_SCHEMA`
+- `PROXY_MIGRATE_ON_STARTUP=1` (or run migrations out-of-band)
+- `PROXY_OPS_TOKENS` (scoped ops tokens)
+- `PROXY_FINANCE_RECONCILE_ENABLED=1`
+- `PROXY_MONEY_RAIL_RECONCILE_ENABLED=1`
+
+Primary config source: `docs/CONFIG.md`.
+
+### `settld-maintenance`
+
+- Same DB/env set as `settld-api`
+- `PROXY_MAINTENANCE_INTERVAL_SECONDS` tuned for your traffic profile
+
+### `x402-gateway`
+
+- `SETTLD_API_URL` (usually `https://api.settld.work`)
+- `SETTLD_API_KEY` (`keyId.secret`)
+- `UPSTREAM_URL` (provider tool base URL)
+- `HOLDBACK_BPS`
+- `DISPUTE_WINDOW_MS`
+- optional signature controls for provider verification
+
+Reference flow: `docs/QUICKSTART_X402_GATEWAY.md`.
+
+## 4) Non-negotiable controls
+
+1. Rate limits enabled (`PROXY_RATE_LIMIT_*`, per-tenant and per-key).
+2. Quotas configured (`PROXY_QUOTA_*` + `PROXY_QUOTA_PLATFORM_*`).
+3. Ops auth scoped via `PROXY_OPS_TOKENS` (no broad shared token in prod).
+4. Backups + restore drills on schedule (`scripts/backup-restore-test.sh`).
+5. `/metrics` scraped and alert rules enabled (`docs/ALERTS.md`).
+
+## 5) What must be hosted vs optional
+
+Must host for real customer traffic:
+
+1. `settld-api`
+2. `settld-maintenance`
+3. Postgres
+4. `x402-gateway`
+5. At least one paid upstream provider API
+
+Optional at first:
+
+1. Receiver service (`npm run start:receiver`)
+2. Finance sink (`npm run start:finance-sink`)
+3. Magic-link UI service
+
+## 6) Definition of "usable in production"
+
+A deployment is considered usable when all are true:
+
+1. `GET /healthz` is green on API and gateway.
+2. Hosted baseline evidence command passes for the environment.
+3. One paid MCP tool call succeeds end-to-end with artifact output.
+4. Receipt verification succeeds and is replay-auditable.
+5. Rollback path is documented and tested.