settld 0.1.2 → 0.2.0

package/docs/ops/MCP_COMPATIBILITY_MATRIX.md

@@ -0,0 +1,30 @@
+# 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 | local host-cert matrix harness | stdio | yellow | 2026-02-21 | `npm run test:ci:mcp-host-cert-matrix` | Validates host config write/idempotency for Claude MCP wiring; live interactive paid-tool validation in Claude desktop remains separate. |
+| Cursor | local host-cert matrix harness | stdio | yellow | 2026-02-21 | `npm run test:ci:mcp-host-cert-matrix` | Validates host config write/idempotency for Cursor MCP wiring; live interactive paid-tool validation in Cursor app remains separate. |
+| Codex | local host-cert matrix harness | stdio | yellow | 2026-02-21 | `npm run test:ci:mcp-host-cert-matrix` | Validates host config write/idempotency for Codex MCP wiring; live interactive paid-tool validation in Codex desktop remains separate. |
+| OpenClaw | local host-cert matrix harness | stdio | yellow | 2026-02-21 | `npm run test:ci:mcp-host-cert-matrix` | Validates host config write/idempotency for OpenClaw MCP wiring; live interactive paid-tool validation in OpenClaw app remains separate. |
+| Generic MCP host bootstrap path | local CI smoke | stdio | green | 2026-02-21 | `npm run test:ci:mcp-host-smoke` | Runs the MCP host smoke flow (API + magic-link + runtime bootstrap + MCP initialize/tools/list + `settld.about`) and writes `artifacts/ops/mcp-host-smoke.json`. |
+| Host config write matrix (Codex/Claude/Cursor/OpenClaw) | local CI smoke | config bootstrap | green | 2026-02-21 | `npm run test:ci:mcp-host-cert-matrix` | Verifies `scripts/setup/host-config.mjs` writes valid Settld MCP entries and remains idempotent across all supported hosts. |
+| Generic MCP HTTP client | local repo test harness | HTTP bridge | green | 2026-02-21 | `node --test test/mcp-stdio-spike.test.js test/mcp-paid-exa-tool.test.js test/mcp-paid-weather-tool.test.js test/mcp-paid-llm-tool.test.js test/x402-gateway-autopay.test.js` | 6/6 passing with paid-tool runtime metadata checks and x402 settlement header verification. |
+| MCP paid runtime policy metadata gate | local repo test harness | stdio + x402 gateway | green | 2026-02-21 | `node --test test/mcp-paid-exa-tool.test.js test/mcp-paid-weather-tool.test.js test/mcp-paid-llm-tool.test.js test/x402-gateway-autopay.test.js` | Paid MCP tools now fail-closed if `x-settld-policy-decision`, `x-settld-policy-hash`, `x-settld-decision-id`, settlement, or verification headers are missing. |

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.

package/docs/ops/P0_BACKEND_PROGRESS.md

@@ -0,0 +1,150 @@
+# P0 Backend Progress Tracker
+
+Status date: February 13, 2026
+
+This tracker is the source of truth for P0 backend execution status in code.
+
+## Scope
+
+P0 backend scope tracked here:
+
+1. Hosted baseline hardening controls
+2. Real-money payout controls and rail safety
+3. Deterministic reconciliation + enforcement evidence
+4. Billing/runtime and launch-gate alignment
+
+## Shipped in this change set
+
+- [x] Tenant-level real-money payout gate (production providers require explicit tenant enablement)
+- [x] Tenant-level payout kill switch
+- [x] Tenant-level max single payout cap
+- [x] Tenant-level daily payout exposure cap
+- [x] Tenant-level allowed provider allowlist
+- [x] Optional signed provider event ingestion enforcement for money-rail events
+- [x] Stripe production payout submit endpoint executes `/v1/transfers` with deterministic metadata mapping
+- [x] Stripe Connect payout submit enforces `stripe_connect:<acct_...>` counterparty destination in production mode
+- [x] Submit endpoint idempotency + ops audit trail (`MONEY_RAIL_OPERATION_SUBMITTED`)
+- [x] Stripe Connect KYB/capability sync endpoint updates payout eligibility from provider account state
+- [x] Chargeback policy automation (`hold|net`) with negative-balance payout enforcement
+- [x] Chargeback exposure API for per-party outstanding/recovered tracking
+- [x] Chargeback evidence automation command emits deterministic run artifact hash (optional Ed25519 signature)
+- [x] Hosted baseline evidence automation command (health/status/metrics + optional rate-limit probe + optional backup/restore drill)
+- [x] Design-partner run packet generator chaining reconcile + chargeback evidence into one hashable/signable artifact
+- [x] Periodic money-rail reconciliation scheduler with advisory-lock safety
+- [x] Money-rail reconciliation maintenance run endpoint with ops audit trail
+- [x] Maintenance status surface now includes money-rail reconciliation state/result
+- [x] Money-rail controls surfaced through existing billing plan control-plane API
+- [x] Runtime billing catalog aligns with public pricing (including Growth $0.007/run via milli-cent accounting)
+- [x] CI smoke runs exact local tarball `npx --package ./settld-<version>.tgz` command path
+
+Implemented in:
+
+- `src/api/app.js`
+- `src/api/maintenance.js`
+- `src/core/billing-plans.js`
+- `src/api/openapi.js`
+- `scripts/ci/cli-pack-smoke.mjs`
+- `scripts/ops/money-rails-chargeback-evidence.mjs`
+- `scripts/ops/hosted-baseline-evidence.mjs`
+- `scripts/ops/design-partner-run-packet.mjs`
+- `test/api-e2e-ops-money-rails.test.js`
+- `test/api-e2e-billing-plan-enforcement.test.js`
+- `test/api-e2e-ops-maintenance-money-rails-reconcile.test.js`
+- `test/pg-maintenance-money-rails-reconcile-lock.test.js`
+
+## API behavior now enforced
+
+- `POST /ops/payouts/{partyId}/{period}/enqueue`
+  - Rejects with `REAL_MONEY_DISABLED` when provider is production and tenant real-money is not enabled.
+  - Rejects with `PAYOUT_KILL_SWITCH_ACTIVE` when kill switch is on.
+  - Rejects with `PAYOUT_AMOUNT_LIMIT_EXCEEDED` when single payout exceeds tenant cap.
+  - Rejects with `PAYOUT_DAILY_LIMIT_EXCEEDED` when projected daily exposure exceeds tenant cap.
+  - Rejects with `MONEY_RAIL_PROVIDER_NOT_ALLOWED` when provider is outside tenant allowlist.
+
+- `POST /ops/money-rails/{providerId}/events/ingest`
+  - Supports optional signed-ingest verification when provider config requires it.
+  - Validates `x-proxy-provider-signature` (`t=<unix>,v1=<hmac_sha256_hex>`) against configured provider webhook secret.
+
+- `POST /ops/money-rails/{providerId}/operations/{operationId}/submit`
+  - Submits initiated payout operations to the provider.
+  - For production Stripe providers, calls Stripe `/v1/transfers` and transitions operation to `submitted` with `providerRef=transfer_id`.
+  - Enforces Connect destination shape (`stripe_connect:<acct_...>`) and returns `STRIPE_CONNECT_COUNTERPARTY_REQUIRED` when invalid.
+  - Returns `MONEY_RAIL_SUBMIT_INVALID_STATE` when operation is no longer submit-eligible.
+
+- `GET /ops/finance/money-rails/chargebacks`
+  - Returns deterministic per-party chargeback exposure (`outstanding`, `recovered`, counts) with optional `providerId|partyId|period` filters.
+
+- `POST /ops/finance/money-rails/stripe-connect/accounts/sync`
+  - Pulls Stripe Account state (`/v1/accounts/{accountId}`) and syncs Connect account capability/KYB fields.
+  - Updates `payoutsEnabled`/`transfersEnabled` + KYB status and requirement sets.
+  - Supports deterministic idempotency replay and records `STRIPE_CONNECT_ACCOUNTS_SYNC` ops audit.
+
+- `POST /ops/maintenance/money-rails-reconcile/run`
+  - Runs periodic-grade money-rail reconciliation on demand with advisory lock safety.
+  - Persists `MoneyRailReconcileReport.v1` artifacts with deterministic report hashes.
+  - Writes `MAINTENANCE_MONEY_RAIL_RECONCILE_RUN` audit records with outcome/runtime/summary.
+
+- `GET /ops/status`
+  - Exposes `maintenance.moneyRailReconciliation` (enabled/interval/limits/last run/result/audit refs).
+
+- `GET/PUT /ops/finance/billing/plan`
+  - Returns and persists `billing.moneyRails` controls.
+
+## Validation evidence
+
+Executed and passing:
+
+- `node --test test/api-e2e-ops-money-rails.test.js`
+- `node --test test/api-e2e-ops-maintenance-money-rails-reconcile.test.js`
+- `node --test test/api-e2e-billing-plan-enforcement.test.js`
+- `node scripts/ci/cli-pack-smoke.mjs`
+- `node scripts/ops/money-rails-chargeback-evidence.mjs --help`
+- `node scripts/ops/hosted-baseline-evidence.mjs --help`
+- `node scripts/ops/design-partner-run-packet.mjs --help`
+
+## Current hosted evidence snapshot (2026-02-13)
+
+- [x] `ops:hosted-baseline:evidence` passes against `https://api.settld.work` for:
+  - health/status
+  - required metrics presence
+  - billing catalog/quotas validation
+- [x] Production hosted-baseline backup/restore evidence is now passing.
+  - Captured at: `2026-02-13T02:19:48.251Z`
+  - Artifact: `artifacts/ops/hosted-baseline-prod.json`
+  - `artifactHash`: `2a5833fd44e6b904ed87763e2d1212e02ffcd9583c4d50fdd5b2cffa3d99a597`
+  - Backup/restore: `checks.backupRestore.ok=true`
+  - External archive path: `/home/aiden/ops-evidence/settld/hosted-baseline/2026-02-13`
+- [x] Staging hosted-baseline backup/restore evidence is now passing.
+  - Captured at: `2026-02-13T02:26:37.785Z`
+  - Artifact: `artifacts/ops/hosted-baseline-staging.json`
+  - `artifactHash`: `354f339d1c668eccb000416a231309ed6f3a5614539d43448aad9f6f3ca0dc28`
+  - Backup/restore: `checks.backupRestore.ok=true`
+  - External archive path: `/home/aiden/ops-evidence/settld/hosted-baseline/2026-02-13`
+
+### Money-Rail Chargeback + Design-Partner Packet (2026-02-13)
+
+- [x] Chargeback/refund simulation evidence run captured and signed.
+  - Tenant: `tenant_p0_evidence_20260213_v9`
+  - Period: `2026-02`
+  - Artifact: `artifacts/ops/chargeback-evidence-tenant_p0_evidence_20260213_v9.json`
+  - `artifactHash`: `a7df81308cfed250ecc93a2997758f09d91a807beb74f3a8cd8aaee3f181fbe7`
+
+- [x] Design-partner run packet captured and signed (reconcile is expected to fail when a chargeback reversal is present).
+  - Tenant: `tenant_p0_evidence_20260213_v9`
+  - Period: `2026-02`
+  - Artifact: `artifacts/ops/design-partner-run-packet-tenant_p0_evidence_20260213_v9.json`
+  - `artifactHash`: `c6eaa09b8ee4f662cb95403800d87cf89ace865bd6e7c29bfe09b5ab5a2b7e62`
+  - Reconcile report hash: `36e8e5fb2ed0af3574aa41c8d72e66020fe19130bb185daa67af079983354cac`
+  - External archive path: `/home/aiden/ops-evidence/settld/p0/2026-02-13/tenant_p0_evidence_20260213_v9`
+
+## Remaining P0 work (outside this code drop)
+
+- [x] Execute hosted baseline evidence runs in staging/prod with `--run-backup-restore true` and archive signed artifacts
+- [x] Execute chargeback/refund simulation runs and archive signed artifacts
+- [x] Execute design-partner run packets against live partner tenants (repeatable, no manual DB edits)
+
+References:
+
+- `docs/ops/HOSTED_BASELINE_R2.md`
+- `docs/ops/PAYMENTS_ALPHA_R5.md`
+- `planning/kernel-v0-truth-audit.md`

package/docs/ops/PAYMENTS_ALPHA_R5.md

@@ -0,0 +1,105 @@
+# Payments Alpha (R5) - Design Partner Scope
+
+This runbook defines the private real-money alpha while Kernel v0 remains public with ledger/test-fund flows.
+
+## Objective
+
+Validate mapping from kernel settlement artifacts to real payment rails with 3-5 design partners, without opening public GA risk surface.
+
+## Non-Goals (Alpha)
+
+- No public self-serve real-money onboarding.
+- No generalized multi-rail support.
+- No claim of universal chargeback protection.
+
+## Required Design Decisions
+
+- Merchant-of-record model is explicitly documented.
+- Holdback/challenge window mapping to payout timing is explicit and testable.
+- Refund and chargeback policy defines behavior when reversals exceed retained holdback.
+
+## Required Implementation Surfaces
+
+- Feature flag gate per tenant for real-money flows.
+- Rail adapter integration (for example Stripe Connect) with webhook ingestion and signed webhook verification.
+- Reconciliation tables keyed by settlement/receipt/adjustment IDs.
+- Periodic reconciliation job that produces mismatch reports.
+- Ops view for mismatch triage with reason codes.
+
+### Implementation status snapshot (2026-02-12)
+
+- Implemented in API runtime:
+  - Tenant-level real-money payout gate
+  - Tenant-level payout kill switch
+  - Tenant-level single-payout cap
+  - Tenant-level daily payout cap
+  - Tenant-level provider allowlist
+  - Optional signed provider-event ingestion enforcement for money rails
+  - Stripe Connect account mapping endpoints + payout counterparty enforcement
+  - Stripe Connect KYB/capability sync endpoint (`POST /ops/finance/money-rails/stripe-connect/accounts/sync`) pulling `/v1/accounts/{accountId}`
+  - Stripe production payout submit endpoint (`POST /ops/money-rails/{providerId}/operations/{operationId}/submit`) calling `/v1/transfers`
+  - Chargeback negative-balance policy automation (`hold|net`) + exposure API
+  - Scheduled money-rail reconciliation maintenance with advisory locks + audit trail
+  - Runtime billing catalog alignment for `free|builder|growth|enterprise` (Growth `$0.007/run` preserved with milli-cent accounting)
+- Source: `src/api/app.js`, `test/api-e2e-ops-money-rails.test.js`
+- Source (maintenance scheduler): `src/api/maintenance.js`, `test/api-e2e-ops-maintenance-money-rails-reconcile.test.js`
+- Source (billing alignment): `src/core/billing-plans.js`, `test/api-e2e-billing-plan-enforcement.test.js`
+- Source (chargeback evidence automation): `scripts/ops/money-rails-chargeback-evidence.mjs`
+- Source (design-partner run packet automation): `scripts/ops/design-partner-run-packet.mjs`
+- Tracker: `docs/ops/P0_BACKEND_PROGRESS.md`
+
+## Chargeback Evidence Command
+
+Use this command to capture a deterministic chargeback drill artifact that includes API call traces, computed checks, and a stable `artifactHash`:
+
+```bash
+npm run ops:money-rails:chargeback:evidence -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_design_partner_1 \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --provider-id stripe_prod_us \
+  --operation-id op_example_123 \
+  --period 2026-02 \
+  --expect-outstanding-cents 2000 \
+  --out ./artifacts/chargeback-evidence-2026-02.json
+```
+
+Optional signature fields:
+
+- `--signing-key-file <pkcs8_ed25519_pem>`
+- `--signature-key-id <key_id>`
+
+## Design-partner run packet command
+
+Use this command to generate one signed/hashable packet that chains:
+
+1. money-rail reconciliation evidence
+2. chargeback evidence
+
+```bash
+npm run ops:design-partner:run-packet -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_design_partner_1 \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --provider-id stripe_prod_us \
+  --period 2026-02 \
+  --chargeback-operation-id op_example_123 \
+  --chargeback-party-id pty_example_123 \
+  --chargeback-payout-period 2026-03 \
+  --expect-chargeback-payout-code NEGATIVE_BALANCE_PAYOUT_HOLD \
+  --out ./artifacts/ops/design-partner-run-packet-2026-02.json
+```
+
+## Risk Controls
+
+- Tenant-level transaction/payout limits.
+- Daily mismatch alert threshold.
+- Kill switch to disable payouts by tenant.
+- Manual override workflow for reconciliation exceptions.
+
+## Acceptance Criteria
+
+- Every external money movement maps to a kernel receipt or adjustment reference.
+- Reconciliation report is zero-drift in normal flows and explainable for induced failure scenarios.
+- Chargeback/refund simulation runbook is executed and recorded.
+- Design partner tenants can complete the same flow repeatedly without manual DB edits.

package/docs/ops/PILOT_ONBOARDING_RUNBOOK.md

@@ -0,0 +1,112 @@
+# Pilot Onboarding Runbook (x402 Gateway)
+
+Goal: install a design partner in one afternoon and prove a known-good `402 -> authorize -> verify -> settled` flow.
+
+## 1. Prerequisites
+
+- Runtime: Node 20+, Docker available for hosted acceptance checks.
+- Access:
+  - Settld API base URL (`SETTLD_BASE_URL`)
+  - tenant id (`SETTLD_TENANT_ID`)
+  - ops token (`PROXY_OPS_TOKEN`) to mint scoped API keys
+- Pilot safety defaults:
+  - `X402_PILOT_KILL_SWITCH=0`
+  - `X402_PILOT_MAX_AMOUNT_CENTS=100`
+  - `X402_PILOT_DAILY_LIMIT_CENTS=1000`
+
+## 2. Environment Setup (15-20m)
+
+```bash
+export SETTLD_BASE_URL='https://api.settld.work'
+export SETTLD_TENANT_ID='tenant_default'
+export PROXY_OPS_TOKEN='tok_ops'
+```
+
+Mint a scoped API key:
+
+```bash
+curl -sS -X POST "$SETTLD_BASE_URL/ops/api-keys" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H 'x-settld-protocol: 1.0' \
+  -H 'content-type: application/json' \
+  -d '{"scopes":["ops_read","ops_write","audit_read","finance_read","finance_write"]}' | jq .
+```
+
+## 3. Gateway Deploy (10-15m)
+
+Use the local smoke stack as the deployment sanity baseline:
+
+```bash
+scripts/dev/smoke-x402-gateway.sh
+```
+
+For hosted deployment, configure gateway env:
+
+- `SETTLD_API_URL=<api base>`
+- `SETTLD_API_KEY=<keyId.secret>`
+- `UPSTREAM_URL=<paid upstream base>`
+- `X402_AUTOFUND=1` for pilot/demo rails only
+
+## 4. Sandbox vs Production Mode
+
+| Mode | Required vars | Notes |
+|---|---|---|
+| `sandbox` | `SETTLD_DEMO_CIRCLE_MODE=sandbox`, `X402_REQUIRE_EXTERNAL_RESERVE=1` | Safe pilot proving reserve path without live funds |
+| `production` | `SETTLD_DEMO_CIRCLE_MODE=production`, live Circle vars (`CIRCLE_API_KEY`, wallet ids, token id) | Keep strict caps and provider allowlist on |
+
+## 5. Known-Good Health Check Flow (10m)
+
+1. Gateway health:
+
+```bash
+curl -sS http://127.0.0.1:8402/healthz | jq .
+```
+
+2. First request returns `402` + `x-settld-gate-id`:
+
+```bash
+FIRST_HEADERS=$(mktemp)
+curl -sS -D "$FIRST_HEADERS" 'http://127.0.0.1:8402/exa/search?q=pilot+health' -o /tmp/pilot-first-body.json
+GATE_ID=$(awk 'tolower($1)=="x-settld-gate-id:" {print $2}' "$FIRST_HEADERS" | tr -d '\r')
+echo "$GATE_ID"
+```
+
+3. Retry with gate id returns `200` and settlement headers:
+
+```bash
+curl -sS -D /tmp/pilot-second-headers.txt \
+  -H "x-settld-gate-id: $GATE_ID" \
+  'http://127.0.0.1:8402/exa/search?q=pilot+health' -o /tmp/pilot-second-body.json
+```
+
+4. Confirm gate resolved in API:
+
+```bash
+curl -sS "$SETTLD_BASE_URL/x402/gate/$GATE_ID" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "authorization: Bearer $SETTLD_API_KEY" \
+  -H 'x-settld-protocol: 1.0' | jq '{gateId:.gate.gateId,status:.gate.status,settlement:.settlement.status}'
+```
+
+Expected: `status=resolved` and non-locked settlement.
+
+## 6. Rollback Procedure (Fail-Closed)
+
+1. Activate kill switch:
+
+```bash
+export X402_PILOT_KILL_SWITCH=1
+```
+
+2. Restart API/gateway with kill switch active.
+3. Verify authorize rejects with `X402_PILOT_KILL_SWITCH_ACTIVE`.
+4. Drain in-flight checks; stop new pilot traffic.
+5. Revert risky config (prod reserve mode, provider allowlist overrides).
+6. Run health checks again in sandbox mode before re-opening traffic.
+
+## 7. Pilot Exit Criteria
+
+- Health check flow passes end-to-end.
+- Reliability report generated (`X402PilotReliabilityReport.v1`) and within thresholds.
+- Rollback drill executed once and documented.

package/docs/ops/PRODUCTION_DEPLOYMENT_CHECKLIST.md

@@ -0,0 +1,140 @@
+# Production Deployment Checklist
+
+Use this checklist to launch and verify a real hosted Settld environment.
+
+## Phase 0: Preflight
+
+1. Confirm branch protection includes:
+   - `tests / kernel_v0_ship_gate`
+   - `tests / production_cutover_gate`
+   - `tests / offline_verification_parity_gate` (NOO-50)
+   - `tests / onboarding_policy_slo_gate`
+   - `tests / onboarding_host_success_gate`
+   - `tests / deploy_safety_smoke` (hosted baseline evidence path)
+2. Confirm release workflow is blocked unless NOO-50 and the kernel/cutover gates are green for the release commit.
+3. Confirm release workflow runs NOO-65 promotion guard and blocks publish lanes if `release-promotion-guard.json` verdict is not pass/override-pass.
+4. Confirm staging and production have separate domains, databases, secrets, and signer keys.
+5. Confirm required services are deployable: `npm run start:prod`, `npm run start:maintenance`, `npm run start:x402-gateway`.
+6. Configure GitHub Environment `production_cutover_gate` with:
+   - `PROD_BASE_URL`
+   - `PROD_TENANT_ID`
+   - `PROD_OPS_TOKEN`
+   - optional `PROD_PROTOCOL` (`1.0`)
+7. Require manual reviewers on `production_cutover_gate` before workflow secret access.
+
+## Phase 1: Environment + secrets
+
+1. Provision Postgres and store `DATABASE_URL`.
+2. Set `STORE=pg`, `NODE_ENV=production`, `PROXY_MIGRATE_ON_STARTUP=1`.
+3. Set scoped `PROXY_OPS_TOKENS`.
+4. Configure rate limits and quotas from `docs/CONFIG.md`.
+5. Configure gateway secrets: `SETTLD_API_URL`, `SETTLD_API_KEY`, `UPSTREAM_URL`.
+
+## Phase 2: Deploy services
+
+1. Deploy `settld-api`.
+2. Deploy `settld-maintenance`.
+3. Deploy `x402-gateway`.
+4. Verify service health:
+
+```bash
+curl -fsS https://api.settld.work/healthz
+curl -fsS https://gateway.settld.work/healthz
+```
+
+## Phase 3: Baseline ops verification
+
+1. Run hosted baseline evidence command:
+
+```bash
+npm run ops:hosted-baseline:evidence -- \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --ops-token "$SETTLD_OPS_TOKEN" \
+  --environment production \
+  --out ./artifacts/ops/hosted-baseline-evidence-production.json
+```
+
+2. Confirm alert metric presence and health signals.
+3. Run backup/restore drill evidence path at least once before opening customer traffic.
+
+## Phase 4: MCP compatibility verification
+
+1. Run core MCP automated tests:
+
+```bash
+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
+```
+
+2. Run the hosted-style MCP smoke gate (API + magic-link bootstrap + MCP probe):
+
+```bash
+npm run test:ci:mcp-host-smoke
+```
+
+This emits a machine-readable report at:
+
+`artifacts/ops/mcp-host-smoke.json`
+
+3. Run host quickstart validation from `docs/QUICKSTART_MCP_HOSTS.md` for:
+   Claude, Cursor, Codex, and OpenClaw.
+
+4. Update `docs/ops/MCP_COMPATIBILITY_MATRIX.md` with pass/fail + date.
+
+5. Run clean-env onboarding host success gate:
+
+```bash
+npm run test:ops:onboarding-host-success-gate -- \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --api-key "$SETTLD_API_KEY" \
+  --attempts 3 \
+  --min-success-rate-pct 90 \
+  --report artifacts/gates/onboarding-host-success-gate.json \
+  --metrics-dir artifacts/ops/onboarding-host-success
+```
+
+## Phase 5: Paid call + receipt proof
+
+1. Run a paid demo flow:
+
+```bash
+npm run demo:mcp-paid-exa
+```
+
+2. Confirm artifacts exist:
+   `artifacts/mcp-paid-exa/.../summary.json` and gate/settlement evidence files in the same run directory.
+3. Verify receipt path using existing verifier tooling.
+
+## Phase 6: Go-live decision gate
+
+Ship only when all are true:
+
+1. Kernel v0 ship gate, production cutover gate, and NOO-50 parity gate are green.
+2. Onboarding/policy SLO gate is green (`artifacts/gates/onboarding-policy-slo-gate.json`).
+3. Onboarding host success gate is green (`artifacts/gates/onboarding-host-success-gate.json`).
+4. Hosted baseline evidence is green.
+5. Go-live gate and launch cutover packet reports are present:
+   - `artifacts/gates/s13-go-live-gate.json`
+   - `artifacts/gates/s13-launch-cutover-packet.json`
+   - generated from a successful `go-live-gate` workflow run for the release commit
+6. NOO-65 promotion guard passes with required artifact binding (`artifacts/gates/release-promotion-guard.json`).
+7. MCP compatibility matrix is green for supported hosts.
+8. Paid MCP run artifacts verify cleanly.
+9. Rollback runbook has been rehearsed.
+
+Run the live environment cutover gate before opening traffic:
+
+`Actions -> production-cutover-gate -> Run workflow`
+
+## Phase 7: Post-release
+
+1. Monitor `/metrics` + SLO dashboards.
+2. Track weekly reliability report (`docs/ops/X402_PILOT_WEEKLY_METRICS.md`).
+3. Re-run compatibility checks on every major host release.