settld 0.1.2 → 0.1.5

package/docs/QUICKSTART_SDK_PYTHON.md

@@ -0,0 +1,111 @@
+# Quickstart: First verified agent run (Python SDK)
+
+Goal: run one end-to-end agent transaction (register identities, append run events, verify `green`, release settlement) using Python.
+
+## 0) Install deps
+
+```sh
+npm ci
+```
+
+## 1) Start the API with a local ops token
+
+```sh
+export PROXY_OPS_TOKEN=dev_ops_token
+npm run dev:api
+```
+
+## 2) Create an API key for SDK calls
+
+In a second shell:
+
+```sh
+export SETTLD_BASE_URL=http://127.0.0.1:3000
+export SETTLD_TENANT_ID=tenant_default
+export SETTLD_API_KEY="$(
+  curl -sS -X POST "$SETTLD_BASE_URL/ops/api-keys" \
+    -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d '{"scopes":["ops_read","ops_write","finance_read","finance_write","audit_read"],"description":"python sdk quickstart"}' \
+  | jq -r '.keyId + "." + .secret'
+)"
+```
+
+## 3) Run the Python SDK example
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/examples/sdk-first-verified-run.py
+```
+
+Expected output:
+
+```json
+{
+  "runId": "run_sdk_py_...",
+  "payeeAgentId": "agt_py_payee_...",
+  "payerAgentId": "agt_py_payer_...",
+  "runStatus": "completed",
+  "verificationStatus": "green",
+  "settlementStatus": "released"
+}
+```
+
+## 4) Use the helper directly in code
+
+```python
+from settld_api_sdk import SettldClient
+
+client = SettldClient(
+    base_url="http://127.0.0.1:3000",
+    tenant_id="tenant_default",
+    api_key="keyId.secret",
+    x_api_key="magic_link_api_key",  # optional for Magic Link deployments that enforce x-api-key
+)
+
+result = client.first_verified_run(
+    {
+        "payee_agent": {"publicKeyPem": "...", "owner": {"ownerType": "service", "ownerId": "svc_a"}},
+        "payer_agent": {"publicKeyPem": "...", "owner": {"ownerType": "service", "ownerId": "svc_b"}},
+        "payer_credit": {"amountCents": 5000},
+        "settlement": {"amountCents": 1200},
+        "run": {"taskType": "translation"},
+    }
+)
+```
+
+## 5) Run a paid marketplace RFQ flow
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/examples/sdk-first-paid-rfq.py
+```
+
+Expected output:
+
+```json
+{
+  "rfqId": "rfq_py_...",
+  "runId": "run_rfq_py_...",
+  "posterAgentId": "agt_py_poster_...",
+  "bidderAgentId": "agt_py_bidder_...",
+  "verificationStatus": "green",
+  "settlementStatus": "released"
+}
+```
+
+## 6) Pull tenant analytics + trust graph (Magic Link)
+
+```python
+analytics = client.get_tenant_analytics("tenant_default", {"month": "2026-02", "bucket": "day", "limit": 20})
+graph = client.get_tenant_trust_graph("tenant_default", {"month": "2026-02", "minRuns": 1, "maxEdges": 200})
+diff = client.diff_tenant_trust_graph("tenant_default", {"baseMonth": "2026-01", "compareMonth": "2026-02", "limit": 50})
+```
+
+Or run the prebuilt script:
+
+```sh
+SETTLD_BASE_URL=http://127.0.0.1:8787 \
+SETTLD_TENANT_ID=tenant_default \
+SETTLD_X_API_KEY=test_key \
+npm run sdk:analytics:py
+```

package/docs/QUICKSTART_VERIFY.md

@@ -0,0 +1,54 @@
+# Quickstart: Verify a bundle
+
+Goal: verify a Settld bundle directory and produce a stable machine-readable receipt (`VerifyCliOutput.v1`) suitable for CI gating and audit retention.
+
+## From source (this repo)
+
+Install dependencies:
+
+```sh
+npm ci
+```
+
+Verify a bundle fixture (strict):
+
+```sh
+export SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON="$(node -e "import fs from 'node:fs'; const t=JSON.parse(fs.readFileSync('test/fixtures/bundles/v1/trust.json','utf8')); process.stdout.write(JSON.stringify(t.governanceRoots||{}))")"
+node packages/artifact-verify/bin/settld-verify.js --format json --strict --job-proof test/fixtures/bundles/v1/jobproof/strict-pass > settld-verify-output.json
+```
+
+Optional: emit SARIF for GitHub annotations:
+
+```sh
+node packages/artifact-verify/bin/settld-verify.js --format sarif --strict --job-proof test/fixtures/bundles/v1/jobproof/strict-pass > settld-verify.sarif
+```
+
+## Strict vs non-strict
+
+- **Strict** (`--strict`): audit posture; missing required protocol surfaces are hard failures.
+- **Non-strict** (omit `--strict`): compatibility posture; missing legacy surfaces become warnings.
+
+## Warnings and CI gating
+
+- Warnings are structured codes (see `docs/spec/WARNINGS.md`).
+- To fail CI when warnings exist, add `--fail-on-warnings`.
+
+## Trust anchors
+
+Strict verification needs trusted governance root keys. Provide them via:
+
+- `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON`
+- `SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON` (only if you want to verify timestamp proofs)
+
+See `docs/spec/TRUST_ANCHORS.md`.
+
+## Output + provenance
+
+`settld-verify --format json` emits `VerifyCliOutput.v1`:
+
+- `ok`: overall CLI verdict (includes `--fail-on-warnings`)
+- `verificationOk`: underlying verification verdict
+- `errors[]` / `warnings[]`: stable codes, deterministically sorted
+- `tool.version` / `tool.commit`: provenance identifiers
+
+If `tool.version` or `tool.commit` cannot be determined, you may see warnings like `TOOL_VERSION_UNKNOWN` / `TOOL_COMMIT_UNKNOWN` (see `docs/spec/TOOL_PROVENANCE.md`).

package/docs/QUICKSTART_X402_GATEWAY.md

@@ -0,0 +1,317 @@
+# Quickstart: x402 Gateway (Verify Before Release)
+
+Goal: in ~10 minutes, run a local Settld API + a mock x402 upstream + the Settld x402 gateway, then complete a `402 -> authorize -> verify -> release` flow and get a deterministic receipt trail.
+
+## TL;DR (one command)
+
+```bash
+npm ci && npm run quickstart:x402
+```
+
+Success: prints `OK`, `gateId=...`, and `gateStateUrl=...`.
+
+By default the script keeps services running until you press Ctrl+C. To run once and exit (CI-friendly):
+
+```bash
+npm ci && SETTLD_QUICKSTART_KEEP_ALIVE=0 npm run quickstart:x402
+```
+
+If you already ran `npm ci` in this repo, you can skip it:
+
+```bash
+npm run quickstart:x402
+```
+
+Ports can be overridden if you already have something running on `3000/8402/9402`:
+
+- `SETTLD_QUICKSTART_API_PORT`
+- `SETTLD_QUICKSTART_GATEWAY_PORT`
+- `SETTLD_QUICKSTART_UPSTREAM_PORT`
+
+## 0) Prereqs
+
+- Node.js 20+
+- Bash (for the copy/paste snippets below)
+- `curl`
+
+Optional:
+
+- Docker Engine 20.10+ (only if you want to run the gateway via container)
+  - Linux: this quickstart includes Linux-safe Docker networking options (do not assume `host.docker.internal` works without configuration).
+
+## 1) Start a local Settld API (in-memory)
+
+From repo root:
+
+```bash
+npm ci
+```
+
+Then:
+
+```bash
+PROXY_OPS_TOKEN=tok_ops PORT=3000 npm run dev:api
+```
+
+In another terminal, confirm:
+
+```bash
+curl -fsS http://127.0.0.1:3000/healthz
+```
+
+## 2) Mint an API key (no jq required)
+
+This mints a tenant API key using the dev ops token (`PROXY_OPS_TOKEN`). The gateway uses `SETTLD_API_KEY` (not the ops token) to call Settld.
+
+```bash
+SETTLD_API_KEY="$(
+  set -euo pipefail
+  curl -fsS -X POST http://127.0.0.1:3000/ops/api-keys \
+    -H "x-proxy-ops-token: tok_ops" \
+    -H "authorization: Bearer tok_ops" \
+    -H "x-proxy-tenant-id: tenant_default" \
+    -H "content-type: application/json" \
+    -d '{"scopes":["ops_read","ops_write","finance_read","finance_write","audit_read"],"description":"x402 gateway quickstart"}' \
+  | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>{const j=JSON.parse(d);if(!j?.keyId||!j?.secret){console.error("unexpected response:",d);process.exit(1)}process.stdout.write(`${j.keyId}.${j.secret}`)})'
+)"
+export SETTLD_API_KEY
+if [ -n "$SETTLD_API_KEY" ]; then
+  echo "SETTLD_API_KEY minted"
+else
+  echo "FAILED: SETTLD_API_KEY empty" >&2
+fi
+```
+
+## 3) Start a mock x402 upstream
+
+The upstream will return `HTTP 402` with both `x-payment-required` and `PAYMENT-REQUIRED` until the gateway retries with a `SettldPay` authorization token.
+
+```bash
+PORT=9402 \
+SETTLD_PAY_KEYSET_URL='http://127.0.0.1:3000/.well-known/settld-keys.json' \
+node services/x402-gateway/examples/upstream-mock.js
+```
+
+If your Settld API is not on port `3000`, set `SETTLD_PAY_KEYSET_URL` to the correct `/.well-known/settld-keys.json` URL so the provider can verify SettldPay tokens offline.
+
+In another terminal:
+
+```bash
+curl -fsS http://127.0.0.1:9402/healthz
+```
+
+### Strict request binding for side-effecting tools
+
+For side-effecting tools, set provider offer `requestBindingMode: "strict"` (or `idempotency: "side_effecting"` in manifests that feed the provider wrapper). In strict mode, provider-kit computes a canonical request fingerprint and requires the SettldPay token payload to carry a matching `requestBindingSha256`. Replaying the same token with a different path/query/body is rejected with `402` and code `SETTLD_PAY_REQUEST_BINDING_MISMATCH`.
+
+## 3.5) Provider signature key (demo)
+
+This quickstart uses provider-signed responses as a minimal correctness check:
+
+- the upstream mock signs a response hash with Ed25519
+- the gateway verifies the signature before releasing funds
+
+Export the upstream mock's dev-only public key:
+
+```bash
+export X402_PROVIDER_PUBLIC_KEY_PEM="$(cat <<'EOF'
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA7zJ+oQLAO6F4Xewe7yJB1mv5TxsLo5bGZI7ZJPuFB6s=
+-----END PUBLIC KEY-----
+EOF
+)"
+```
+
+## 4) Start the x402 gateway (thin proxy)
+
+### Option A: run from source (fastest)
+
+```bash
+SETTLD_API_URL="http://127.0.0.1:3000" \
+SETTLD_API_KEY="$SETTLD_API_KEY" \
+UPSTREAM_URL="http://127.0.0.1:9402" \
+HOLDBACK_BPS=0 \
+DISPUTE_WINDOW_MS=3600000 \
+X402_AUTOFUND=1 \
+X402_PROVIDER_PUBLIC_KEY_PEM="$X402_PROVIDER_PUBLIC_KEY_PEM" \
+PORT=8402 \
+npm run dev:x402-gateway
+```
+
+Notes:
+
+- `X402_AUTOFUND=1` is for local demo only. It simulates funding the payer so escrow holds can be created without a real payment rail.
+
+### Option B: run via Docker (same config surface)
+
+Important:
+
+- On macOS/Windows (Docker Desktop), `host.docker.internal` works by default.
+- On Linux, `host.docker.internal` is usually not defined. If you run the gateway in Docker while your Settld API + mock upstream are running on the host, use one of the Linux commands below:
+  - Recommended: `--add-host=host.docker.internal:host-gateway` (Docker Engine 20.10+)
+  - Alternative: `--network host` and use `127.0.0.1` URLs (not available on Docker Desktop; often not supported with rootless Docker)
+
+Pull the image:
+
+```bash
+docker pull ghcr.io/aidenlippert/settld/x402-gateway:latest
+```
+
+If `docker pull` fails with `denied`, either:
+
+- build locally from this repo (no dependencies; copies `src/core` + `services/x402-gateway`):
+
+```bash
+docker build -t settld/x402-gateway:local -f services/x402-gateway/Dockerfile .
+```
+
+and replace `ghcr.io/aidenlippert/settld/x402-gateway:latest` with `settld/x402-gateway:local` in the `docker run` commands below.
+
+macOS/Windows (Docker Desktop):
+
+```bash
+docker run --rm -p 8402:8402 \
+  -e SETTLD_API_URL="http://host.docker.internal:3000" \
+  -e SETTLD_API_KEY="$SETTLD_API_KEY" \
+  -e UPSTREAM_URL="http://host.docker.internal:9402" \
+  -e HOLDBACK_BPS=0 \
+  -e DISPUTE_WINDOW_MS=3600000 \
+  -e X402_AUTOFUND=1 \
+  -e X402_PROVIDER_PUBLIC_KEY_PEM="$X402_PROVIDER_PUBLIC_KEY_PEM" \
+  -e PORT=8402 \
+  ghcr.io/aidenlippert/settld/x402-gateway:latest
+```
+
+Linux (recommended, bridge networking):
+
+```bash
+docker run --rm -p 8402:8402 \
+  --add-host=host.docker.internal:host-gateway \
+  -e SETTLD_API_URL="http://host.docker.internal:3000" \
+  -e SETTLD_API_KEY="$SETTLD_API_KEY" \
+  -e UPSTREAM_URL="http://host.docker.internal:9402" \
+  -e HOLDBACK_BPS=0 \
+  -e DISPUTE_WINDOW_MS=3600000 \
+  -e X402_AUTOFUND=1 \
+  -e X402_PROVIDER_PUBLIC_KEY_PEM="$X402_PROVIDER_PUBLIC_KEY_PEM" \
+  -e PORT=8402 \
+  ghcr.io/aidenlippert/settld/x402-gateway:latest
+```
+
+Linux alternative (host networking):
+
+```bash
+docker run --rm --network host \
+  -e SETTLD_API_URL="http://127.0.0.1:3000" \
+  -e SETTLD_API_KEY="$SETTLD_API_KEY" \
+  -e UPSTREAM_URL="http://127.0.0.1:9402" \
+  -e HOLDBACK_BPS=0 \
+  -e DISPUTE_WINDOW_MS=3600000 \
+  -e X402_AUTOFUND=1 \
+  -e X402_PROVIDER_PUBLIC_KEY_PEM="$X402_PROVIDER_PUBLIC_KEY_PEM" \
+  -e PORT=8402 \
+  ghcr.io/aidenlippert/settld/x402-gateway:latest
+```
+
+Confirm:
+
+```bash
+curl -fsS http://127.0.0.1:8402/healthz
+```
+
+## 5) Drive the 402 -> verify -> release flow
+
+### 5.0 One-shot smoke test (copy/paste; fails fast)
+
+This asserts the expected HTTP status codes and (with the default upstream + gateway config in this doc) checks that the released/refunded cents are consistent.
+
+```bash
+set -euo pipefail
+
+h402="$(curl -sS -D - -o /dev/null http://127.0.0.1:8402/resource)"
+echo "$h402" | grep -qE '^HTTP/.* 402 '
+echo "$h402" | grep -qi '^x-payment-required:'
+amount_cents="$(echo "$h402" | tr -d '\r' | grep -i '^x-payment-required:' | sed -n 's/.*amountCents=\([0-9][0-9]*\).*/\1/p' | head -n 1)"
+test -n "$amount_cents"
+GATE_ID="$(echo "$h402" | awk 'tolower($1) == "x-settld-gate-id:" {print $2}' | tr -d '\r' | head -n 1)"
+test -n "$GATE_ID"
+echo "gateId=$GATE_ID"
+
+h200="$(curl -sS -D - -o /dev/null http://127.0.0.1:8402/resource -H "x-settld-gate-id: $GATE_ID")"
+echo "$h200" | grep -qE '^HTTP/.* 200 '
+
+settlement_status="$(echo "$h200" | awk 'tolower($1) == "x-settld-settlement-status:" {print $2}' | tr -d '\r' | head -n 1)"
+released_cents="$(echo "$h200" | awk 'tolower($1) == "x-settld-released-amount-cents:" {print $2}' | tr -d '\r' | head -n 1)"
+refunded_cents="$(echo "$h200" | awk 'tolower($1) == "x-settld-refunded-amount-cents:" {print $2}' | tr -d '\r' | head -n 1)"
+test "$settlement_status" = "released"
+test "$released_cents" = "$amount_cents"
+test "$refunded_cents" = "0"
+
+echo "OK"
+```
+
+Notes:
+
+- If you set `HOLDBACK_BPS>0`, the gateway may emit `x-settld-holdback-*` headers (a follow-on settlement).
+
+### 5.1 First request (expect 402 + x-settld-gate-id)
+
+```bash
+curl -isS http://127.0.0.1:8402/resource | sed -n '1,40p'
+```
+
+Extract the gate id:
+
+```bash
+GATE_ID="$(
+  curl -isS http://127.0.0.1:8402/resource \
+    | awk 'tolower($1) == "x-settld-gate-id:" {print $2}' \
+    | tr -d '\r' \
+    | head -n 1
+)"
+echo "gateId=$GATE_ID"
+```
+
+### 5.2 Second request (retry with gate id; gateway auto-authorizes payment)
+
+```bash
+curl -isS http://127.0.0.1:8402/resource \
+  -H "x-settld-gate-id: $GATE_ID" | sed -n '1,80p'
+```
+
+You should see:
+
+- `HTTP 200`
+- `x-settld-response-sha256: ...`
+- `x-settld-verification-status: green|red`
+- `x-settld-verification-codes: ...` (optional; reason codes when verification is forced red)
+- `x-settld-settlement-status: released`
+- `x-settld-released-amount-cents`, `x-settld-refunded-amount-cents`
+- `x-settld-holdback-status`, `x-settld-holdback-amount-cents` (when `HOLDBACK_BPS>0`)
+
+## 6) Inspect the gate state (optional)
+
+```bash
+curl -fsS "http://127.0.0.1:3000/x402/gate/$GATE_ID" \
+  -H "x-proxy-tenant-id: tenant_default" \
+  -H "authorization: Bearer $SETTLD_API_KEY" \
+  -H "x-settld-protocol: 1.0"
+```
+
+You can also inspect the gateway signing keyset used for `SettldPay` verification:
+
+```bash
+curl -fsS "http://127.0.0.1:3000/.well-known/settld-keys.json"
+```
+
+## Troubleshooting
+
+- If the gateway never returns `x-settld-gate-id`, your upstream likely isn’t returning `402` with `x-payment-required`.
+- If `/x402/gate/verify` fails with insufficient funds, you forgot `X402_AUTOFUND=1` (local demo) or you need a real funding path wired in.
+- Linux + Docker: if the gateway container can’t reach `http://host.docker.internal:3000` / `:9402`, use `--add-host=host.docker.internal:host-gateway` or `--network host` (and point `SETTLD_API_URL`/`UPSTREAM_URL` at `http://127.0.0.1:...`).
+- If you see `EADDRINUSE` (port already in use), pick different ports (the one-command quickstart supports `SETTLD_QUICKSTART_API_PORT`, `SETTLD_QUICKSTART_UPSTREAM_PORT`, and `SETTLD_QUICKSTART_GATEWAY_PORT`).
+
+If you tried and failed:
+
+- Run `./scripts/collect-debug.sh` and attach the resulting `settld-debug-*.tar.gz` to a GitHub issue using the "Quickstart failure" template:
+  - https://github.com/aidenlippert/settld/issues/new?template=quickstart-failure.yml

package/docs/README.md

@@ -0,0 +1,15 @@
+# Settld Documentation Index
+
+This root docs index is for GitBook sync setups using project directory `docs`.
+
+For curated public docs, start here:
+
+- [Settld Docs home](./gitbook/README.md)
+- [Quickstart](./gitbook/quickstart.md)
+- [Core Primitives](./gitbook/core-primitives.md)
+- [API Reference](./gitbook/api-reference.md)
+- [Conformance](./gitbook/conformance.md)
+- [Closepacks](./gitbook/closepacks.md)
+- [Guides](./gitbook/guides.md)
+- [Security Model](./gitbook/security-model.md)
+- [FAQ](./gitbook/faq.md)

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,156 @@
+# Release Checklist (v1.0.0+)
+
+This checklist is the “no surprises” gate for shipping Settld as a product (not just a repo).
+
+## Preconditions
+
+- `npm test` is green on main.
+- `CHANGELOG.md` is updated and accurate.
+- Protocol v1 freeze gate is satisfied (no accidental v1 schema/vector drift).
+- Minimum production topology is defined for the target environment:
+  - `docs/ops/MINIMUM_PRODUCTION_TOPOLOGY.md`
+- Production deployment checklist is prepared for this release:
+  - `docs/ops/PRODUCTION_DEPLOYMENT_CHECKLIST.md`
+- Staging billing smoke secrets are configured for `.github/workflows/release.yml`:
+  - `SETTLD_STAGING_BASE_URL`
+  - `SETTLD_STAGING_OPS_TOKEN`
+- npm publish secret is configured for `.github/workflows/release.yml` if you want direct registry distribution:
+  - `NPM_TOKEN`
+- PyPI Trusted Publisher is configured for `.github/workflows/release.yml` and the `pypi` GitHub environment is allowed.
+- PyPI Trusted Publisher is configured for `.github/workflows/python-pypi.yml` and the `pypi` GitHub environment is allowed (if using the Python-only lane).
+- TestPyPI Trusted Publisher is configured for `.github/workflows/python-testpypi.yml` and the `testpypi` GitHub environment is allowed.
+
+## Required release artifacts
+
+For a v1 freeze release, the GitHub Release MUST include:
+
+- npm tarballs (`*.tgz`) + `npm-SHA256SUMS`
+  - includes `settld-*.tgz` (CLI distribution for `npx --package ... settld ...`)
+  - optional registry publish lane (if `NPM_TOKEN` present) publishes `settld`, `settld-api-sdk`, `@settld/provider-kit`, and `create-settld-paid-tool`
+- Python distributions (`*.whl`, `*.tar.gz`) + `python-SHA256SUMS`
+- `conformance-v1.tar.gz` + `conformance-v1-SHA256SUMS`
+- `settld-audit-packet-v1.zip` + `settld-audit-packet-v1.zip.sha256`
+- `release_index_v1.json` + `release_index_v1.sig` (signed release manifest)
+
+Release-gate evidence should also include:
+
+- `billing-smoke-prod.log`
+- `billing-smoke-status.json`
+- `npm-postpublish-smoke-<version>` artifact (when `NPM_TOKEN` is configured), containing:
+  - `provider-kit-npm-view-version.txt`
+  - `create-settld-paid-tool-npm-view-version.txt`
+  - `settld-npx-version.txt`
+  - `settld-kernel-cases.txt`
+  - `settld-help.txt`
+  - `create-settld-paid-tool-help.txt`
+  - `npm-postpublish-smoke.json`
+- `artifacts/throughput/10x-drill-summary.json`
+- `artifacts/gates/s13-go-live-gate.json`
+- `artifacts/gates/s13-launch-cutover-packet.json`
+
+See `docs/spec/SUPPLY_CHAIN.md` for the release-channel threat model and verification posture.
+
+## Local build + verification (recommended)
+
+Build all artifacts locally:
+
+```sh
+python3 -m pip install --disable-pip-version-check --no-input build
+node scripts/release/build-artifacts.mjs --out dist/release-artifacts
+```
+
+If you want to produce a locally-signed `ReleaseIndex.v1` too, provide a release signing key:
+
+```sh
+export SETTLD_RELEASE_SIGNING_PRIVATE_KEY_PEM="$(cat /path/to/release_ed25519_private_key.pem)"
+node scripts/release/build-artifacts.mjs --out dist/release-artifacts --sign-release-index
+```
+
+Verify release checksums:
+
+```sh
+(cd dist/release-artifacts && sha256sum -c SHA256SUMS)
+```
+
+Validate conformance from the produced artifacts:
+
+```sh
+(cd dist/release-artifacts && tar -xzf conformance-v1.tar.gz)
+node conformance-v1/run.mjs --node-bin packages/artifact-verify/bin/settld-verify.js
+```
+
+Validate release assets (checksums + archive contents):
+
+```sh
+node scripts/release/validate-release-assets.mjs --dir dist/release-artifacts
+```
+
+Verify release index signature + artifact hashes:
+
+```sh
+node scripts/release/verify-release.mjs --dir dist/release-artifacts --format json
+```
+
+Preferred operator CLI (same contract, packaged):
+
+```sh
+node packages/artifact-verify/bin/settld-release.js verify --dir dist/release-artifacts --trust-file trust/release-trust.json --format json --explain
+```
+
+## Release candidates
+
+Use SemVer pre-release tags for RCs (e.g. `v1.0.0-rc.1`). RCs must meet the same artifact completeness and conformance gates as final releases.
+
+Recommended Python dry-run before final tag release:
+
+- Trigger `.github/workflows/python-testpypi.yml` with the target `version`.
+- Confirm wheel/sdist publish succeeded on TestPyPI.
+- Smoke-install from TestPyPI in a clean environment.
+
+## Tag + release
+
+- Create and push a tag: `vX.Y.Z`.
+- The `release` workflow will:
+  - build and attach npm artifacts + checksums
+  - build and attach Python distribution artifacts + checksums
+  - publish Python distributions to PyPI (Trusted Publishing/OIDC)
+  - attach conformance pack + checksum
+  - attach audit packet zip + checksum
+
+## Kernel v0 ship gate
+
+Before any Kernel v0 release candidate or public OSS push, run:
+
+```sh
+node scripts/ci/run-kernel-v0-ship-gate.mjs
+```
+
+Required report:
+
+- `artifacts/gates/kernel-v0-ship-gate.json`
+
+Runbook:
+
+- `docs/ops/KERNEL_V0_SHIP_GATE.md`
+
+## S13 launch gate (pre-cutover)
+
+Before production cutover, run:
+
+```sh
+node scripts/ci/run-go-live-gate.mjs
+```
+
+Required gate reports:
+
+- `artifacts/throughput/10x-drill-summary.json`
+- `artifacts/throughput/10x-incident-rehearsal-summary.json`
+- `artifacts/gates/s13-go-live-gate.json`
+- `artifacts/gates/s13-launch-cutover-packet.json`
+
+Related runbooks:
+
+- `docs/ops/THROUGHPUT_DRILL_10X.md`
+- `docs/ops/GO_LIVE_GATE_S13.md`
+- `docs/ops/LIGHTHOUSE_PRODUCTION_CLOSE.md`
+- `docs/ops/MCP_COMPATIBILITY_MATRIX.md`