settld 0.1.2 → 0.2.0

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,33 @@
+# 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)
+- [Quickstart: Profiles CLI](./QUICKSTART_PROFILES.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)
+
+## Fastest onboarding path
+
+1. Run `settld setup` (or `./bin/settld.js setup`) with your host, tenant, and API key.
+2. Activate your host and run `npm run mcp:probe`.
+3. Run `npm run demo:mcp-paid-exa`.
+4. Verify the first receipt:
+
+```bash
+jq -c 'first' artifacts/mcp-paid-exa/*/x402-receipts.export.jsonl > /tmp/settld-first-receipt.json
+settld x402 receipt verify /tmp/settld-first-receipt.json --format json --json-out /tmp/settld-first-receipt.verify.json
+```
+
+Reference docs:
+
+- `docs/QUICKSTART_MCP_HOSTS.md`
+- `docs/QUICKSTART_MCP.md`

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,182 @@
+# 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.
+- Main-branch release gate jobs are green in `.github/workflows/tests.yml` for the release commit:
+  - `noo_44_47_48_regressions` (NOO-44/47/48 fail-closed regression lane)
+  - `kernel_v0_ship_gate`
+  - `production_cutover_gate`
+  - `offline_verification_parity_gate` (NOO-50)
+  - `onboarding_host_success_gate`
+- Public package smoke for OpenClaw onboarding is green:
+  - `npm run test:ci:public-openclaw-npx-smoke`
+- `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`
+- Optional launch cutover packet signing inputs are configured for `.github/workflows/go-live-gate.yml` if signed packets are required:
+  - secret: `LAUNCH_CUTOVER_PACKET_SIGNING_PRIVATE_KEY_PEM`
+  - variable: `LAUNCH_CUTOVER_PACKET_SIGNATURE_KEY_ID`
+- 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-promotion-guard.json` (NOO-65 promotion guard report)
+
+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`
+- when signing is configured, packet includes `signature` with `schemaVersion=LaunchCutoverPacketSignature.v1`
+- `artifacts/gates/production-cutover-gate.json`
+- `artifacts/gates/offline-verification-parity-gate.json` (NOO-50)
+- `artifacts/gates/onboarding-host-success-gate.json`
+- `artifacts/gates/release-promotion-guard.json` (NOO-65)
+
+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/production-cutover-gate.json`
+- `artifacts/gates/s13-go-live-gate.json`
+- `artifacts/gates/s13-launch-cutover-packet.json`
+- Live deploy readiness run (manual workflow): `artifacts/gates/production-cutover-gate-prod.json`
+
+Promotion guard order (fail-closed):
+
+1. NOO-50 parity gate report is generated on main (`artifacts/gates/offline-verification-parity-gate.json`).
+2. S13 go-live workflow report set is generated for the same release commit (`s13-go-live-gate.json` + `s13-launch-cutover-packet.json`).
+3. Release workflow binds all required gate artifacts (kernel, production cutover, NOO-50 parity, onboarding host success, S13 go-live, S13 launch packet, hosted baseline evidence) into NOO-65.
+4. Release workflow must emit `artifacts/gates/release-promotion-guard.json` with `verdict.ok=true` before artifact publish jobs execute.
+
+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`

package/docs/RELEASING.md

@@ -0,0 +1,82 @@
+# Releasing Settld
+
+This repo treats the **protocol** (docs + schemas + vectors + fixtures) as an API. Releases must be repeatable and reviewable.
+
+See `docs/spec/VERSIONING.md` for “what requires a bump”.
+
+## Release checklist
+
+See `docs/RELEASE_CHECKLIST.md` for the definitive artifact completeness requirements.
+
+1. Ensure `npm test` is green.
+2. Ensure fixture determinism gate passes (it’s part of `npm test`).
+3. Update `CHANGELOG.md`:
+   - Add a new version section (Keep a Changelog format).
+   - Call out any protocol-surface changes explicitly.
+4. Bump tool version(s) you ship:
+   - `packages/artifact-verify/package.json` `version`
+   - `packages/api-sdk-python/pyproject.toml` `project.version` (when shipping Python SDK changes)
+   - `SETTLD_VERSION` (repo/service version stamp)
+5. Run packaging smoke test:
+   - `node scripts/ci/npm-pack-smoke.mjs`
+   - `node scripts/ci/cli-pack-smoke.mjs`
+   - `node scripts/ci/run-public-openclaw-npx-smoke.mjs`
+   - `python3 -m build packages/api-sdk-python --sdist --wheel --outdir /tmp/settld-python-dist-smoke`
+   - Optionally generate full release artifacts locally: `npm run release:artifacts`
+6. Create a tag and push it:
+   - Tag format: `vX.Y.Z`
+   - `git tag -a vX.Y.Z -m "vX.Y.Z"`
+   - `git push origin vX.Y.Z`
+
+On tag push, GitHub Actions builds and publishes release artifacts (Docker image, Helm chart, npm tarballs, Python wheel/sdist artifacts, SHA256SUMS).
+If `NPM_TOKEN` is configured in repo secrets, the release lane also publishes:
+
+- `settld` (CLI, so `npx settld ...` works directly),
+- `settld-api-sdk` (JS SDK used by starter templates),
+- `@settld/provider-kit` (provider middleware package),
+- `create-settld-paid-tool` (scaffold CLI package).
+  After publish, the workflow runs registry smoke checks and uploads `npm-postpublish-smoke-<version>` artifacts with command outputs + JSON summary evidence.
+The `release_gate` job also runs a staging billing smoke (`dev:billing:smoke:prod`) and uploads `billing-smoke-prod.log` + `billing-smoke-status.json` as gate artifacts.
+
+Python package publishing uses PyPI Trusted Publishing (OIDC) via either:
+
+- the `python_publish` job in `.github/workflows/release.yml` (full release lane), or
+- `.github/workflows/python-pypi.yml` (Python-only publish lane).
+
+Before the first publish, configure a PyPI trusted publisher for this repo/workflow and allow the `pypi` GitHub environment.
+
+## TestPyPI dry-run lane
+
+Use `.github/workflows/python-testpypi.yml` as a manual pre-production lane:
+
+1. Ensure `packages/api-sdk-python/pyproject.toml` `project.version` matches the version you plan to publish.
+2. Run the `python-testpypi` workflow via `workflow_dispatch` and pass `version`.
+3. The workflow builds wheel+sdist, asserts versioned filenames, and publishes to TestPyPI using OIDC (`testpypi` environment).
+4. Validate installability from TestPyPI before running a production tag release.
+
+## Python-only PyPI lane
+
+Use `.github/workflows/python-pypi.yml` when you want to publish just the Python SDK to PyPI without waiting for other release jobs (Docker/Helm/conformance/audit).
+
+1. Set `packages/api-sdk-python/pyproject.toml` `project.version` to the target version.
+2. Ensure PyPI trusted publishing is configured for workflow `python-pypi.yml` and environment `pypi`.
+3. Run the `python-pypi` workflow via `workflow_dispatch`.
+4. Confirm wheel/sdist publish completed on PyPI and smoke-install in a clean venv.
+
+## Release authenticity
+
+Releases also publish a signed `ReleaseIndex.v1` (`release_index_v1.json` + `release_index_v1.sig`) to make artifact authenticity verifiable.
+
+See `docs/spec/ReleaseIndex.v1.md` and `docs/spec/SUPPLY_CHAIN.md`.
+
+The release workflow expects a repo secret named `SETTLD_RELEASE_SIGNING_PRIVATE_KEY_PEM` containing an Ed25519 private key PEM used only for signing release indexes.
+
+The corresponding public key (and quorum policy, if used) is pinned in `trust/release-trust.json` and should be treated as a security-sensitive change (PR + review).
+
+## Protocol vectors / fixtures rotation
+
+If a change *intentionally* changes protocol meaning (schemas/spec semantics/strictness/canonicalization/hashing), do not “let it drift”:
+
+- Update specs and schemas together.
+- Rotate vectors and/or add fixtures deliberately.
+- Add a clear “Protocol change” entry to `CHANGELOG.md`.

package/docs/REPO_SETTINGS.md

@@ -0,0 +1,37 @@
+# Repo Settings (Recommended)
+
+These are GitHub-side settings we expect for a fail-closed kernel repo.
+
+## Branch Protection (main)
+
+- Require a pull request before merging.
+- Require status checks to pass before merging:
+  - `tests / pr_issue_link_guard`
+  - `tests / changelog_guard`
+  - `tests / unit_tests`
+  - `tests / openapi_drift`
+  - `tests / npm_pack_smoke (ubuntu-latest)`
+  - `tests / npm_pack_smoke (macos-latest)`
+  - `tests / npm_pack_smoke (windows-latest)`
+  - `tests / cli_cross_platform (ubuntu-latest)`
+  - `tests / cli_cross_platform (macos-latest)`
+  - `tests / cli_cross_platform (windows-latest)`
+  - `tests / python_verifier_conformance`
+  - `tests / github_action_settld_verify (jobproof)`
+  - `tests / github_action_settld_verify (monthproof)`
+  - `tests / github_action_settld_verify (financepack)`
+- Dismiss stale PR approvals when new commits are pushed.
+- Require linear history.
+- Block force pushes and deletions.
+- Require conversation resolution.
+
+Optional:
+
+- Require signed commits.
+- Require CODEOWNERS review (if/when CODEOWNERS exists).
+
+## Actions
+
+- Keep secrets scoped to environments (staging/prod).
+- Require manual approval for production deployments (if/when added).
+