settld 0.1.5 → 0.2.0

package/README.md

@@ -67,6 +67,31 @@ The core mental model in this repo:
 
 ## Quick start
 
+Agent host onboarding (Codex / Claude / Cursor / OpenClaw), with guided wallet + policy setup:
+
+```sh
+npx -y settld setup
+```
+
+Preflight-only check (no host config write), with JSON report:
+
+```sh
+npx -y settld setup --preflight-only --report-path ./.tmp/setup-preflight.json
+```
+
+If you prefer global install:
+
+```sh
+npm install -g settld
+settld setup
+```
+
+Legacy setup wizard (advanced / old flags):
+
+```sh
+settld setup legacy
+```
+
 Start the API:
 
 ```sh
@@ -157,6 +182,12 @@ Run conformance (kernel control plane, disputes + holdback):
 ./bin/settld.js conformance kernel --ops-token tok_ops
 ```
 
+Run local MCP host compatibility checks:
+
+```sh
+./bin/settld.js doctor
+```
+
 No-clone registry flow:
 
 ```sh
@@ -194,6 +225,7 @@ Ops workspaces (HTML):
 - `docs/QUICKSTART_PRODUCE.md`
 - `docs/QUICKSTART_SDK.md`
 - `docs/QUICKSTART_SDK_PYTHON.md`
+- `docs/QUICKSTART_POLICY_PACKS.md`
 - `docs/QUICKSTART_MCP.md`
 - `docs/QUICKSTART_MCP_HOSTS.md`
 - `docs/ADOPTION_CHECKLIST.md`

package/SETTLD_VERSION

@@ -1 +1 @@
-0.1.5
+0.2.0

package/bin/settld.js

@@ -8,6 +8,12 @@ function usage() {
   // eslint-disable-next-line no-console
   console.error("usage:");
   console.error("  settld --version");
+  console.error("  settld onboard [--help]");
+  console.error("  settld setup [--help]");
+  console.error("  settld setup legacy [--help]");
+  console.error("  settld setup circle [--help]");
+  console.error("  settld setup openclaw [--help]");
+  console.error("  settld doctor [--help] [--report <path>]");
   console.error("  settld conformance test [--case <id>] [--bin settld-verify] [--node-bin <path/to/settld-verify.js>] [--keep-temp]");
   console.error("  settld conformance list");
   console.error("  settld conformance kernel --ops-token <tok_opsw> [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0] [--case <id>]");
@@ -15,12 +21,34 @@ function usage() {
   console.error("  settld closepack export --agreement-hash <sha256> --out <path.zip> [--ops-token tok_ops] [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0]");
   console.error("  settld closepack verify <path.zip> [--json-out <path.json>]");
   console.error("  settld x402 receipt verify <receipt.json|-> [--strict] [--format json|text] [--json-out <path>]");
+  console.error("  settld profile list [--format json|text] [--json-out <path>]");
+  console.error("  settld profile init <profile-id> [--out <path>] [--force] [--format json|text] [--json-out <path>]");
+  console.error(
+    "  settld profile wizard [--template <profile-id>] [--non-interactive] [--profile-id <id>] [--name <text>] [--vertical <text>] [--description <text>] [--currency <code>] [--per-request-usd-cents <int>] [--monthly-usd-cents <int>] [--providers <csv>] [--tools <csv>] [--out <path>] [--force] [--format json|text] [--json-out <path>]"
+  );
+  console.error("  settld profile validate <profile.json|-> [--format json|text] [--json-out <path>]");
+  console.error(
+    "  settld profile simulate <profile.json|-> [--scenario <scenario.json|->|--scenario-json <json>] [--format json|text] [--json-out <path>]"
+  );
+  console.error("  settld policy init <pack-id> [--out <path>] [--force] [--format json|text] [--json-out <path>]");
+  console.error(
+    "  settld policy simulate <policy-pack.json|-> [--scenario <scenario.json|->|--scenario-json <json>] [--format json|text] [--json-out <path>]"
+  );
+  console.error(
+    "  settld policy publish <policy-pack.json|-> [--out <path>] [--force] [--channel <name>] [--owner <id>] [--format json|text] [--json-out <path>]"
+  );
   console.error("  settld dev up [--no-build] [--foreground]");
   console.error("  settld dev down [--wipe]");
   console.error("  settld dev ps");
   console.error("  settld dev logs [--follow] [--service api]");
   console.error("  settld dev info");
   console.error("  settld init capability <name> [--out <dir>] [--force]");
+  console.error("");
+  console.error("onboarding:");
+  console.error("  settld onboard");
+  console.error("  settld setup");
+  console.error("  settld setup --help");
+  console.error("  settld dev up");
 }
 
 function repoRoot() {
@@ -92,6 +120,28 @@ function main() {
     process.exit(0);
   }
 
+  if (cmd === "setup") {
+    const setupSubcommand = String(argv[1] ?? "").trim();
+    if (setupSubcommand === "openclaw") {
+      return runNodeScript("scripts/setup/openclaw-onboard.mjs", argv.slice(2));
+    }
+    if (setupSubcommand === "circle") {
+      return runNodeScript("scripts/setup/circle-bootstrap.mjs", argv.slice(2));
+    }
+    if (setupSubcommand === "legacy") {
+      return runNodeScript("scripts/setup/wizard.mjs", argv.slice(2));
+    }
+    return runNodeScript("scripts/setup/onboard.mjs", argv.slice(1));
+  }
+
+  if (cmd === "onboard") {
+    return runNodeScript("scripts/setup/onboard.mjs", argv.slice(1));
+  }
+
+  if (cmd === "doctor") {
+    return runNodeScript("scripts/doctor/mcp-host.mjs", argv.slice(1));
+  }
+
   if (cmd === "conformance") {
     const sub = argv[1] ? String(argv[1]) : "test";
     if (sub === "test") return runNodeScript("conformance/v1/run.mjs", argv.slice(2));
@@ -216,6 +266,14 @@ function main() {
     process.exit(1);
   }
 
+  if (cmd === "profile") {
+    return runNodeScript("scripts/profile/cli.mjs", argv.slice(1));
+  }
+
+  if (cmd === "policy") {
+    return runNodeScript("scripts/policy/cli.mjs", argv.slice(1));
+  }
+
   usage();
   // eslint-disable-next-line no-console
   console.error(`unknown command: ${cmd}`);

package/docs/CIRCLE_SANDBOX_E2E.md

@@ -34,6 +34,18 @@ Set these for sandbox runs:
 - `CIRCLE_WALLET_ID_ESCROW`
 - `CIRCLE_TOKEN_ID_USDC`
 
+Fastest way to generate these from your Circle account:
+
+```bash
+settld setup circle --api-key 'TEST_API_KEY:...' --mode auto --out-env ./.tmp/circle.env
+```
+
+Then load them:
+
+```bash
+set -a; source ./.tmp/circle.env; set +a
+```
+
 If your environment uses a different naming convention, map these into the adapter config before running tests.
 
 ## Suggested test flow

package/docs/QUICKSTART_MCP.md

@@ -10,6 +10,22 @@ For host-specific setup (Claude, Cursor, Codex, OpenClaw), see `docs/QUICKSTART_
 - A Settld API key with appropriate scopes (`keyId.secret` format)
 - Settld API reachable (local `npm run dev:api` or hosted)
 
+## Fast Path (Recommended)
+
+Run guided setup first:
+
+```bash
+npx -y settld setup
+```
+
+Then run a smoke probe:
+
+```bash
+npm run mcp:probe
+```
+
+If you prefer to wire everything manually, use the fallback steps in `Run The MCP Server` below.
+
 ## One-Command Local Demo (Paid MCP Exa Flow)
 
 Boots local API + provider wrapper + x402 gateway, runs MCP `settld.exa_search_paid`, verifies signatures/tokens, and writes an artifact bundle.
@@ -91,6 +107,23 @@ Artifact bundle includes:
 - `batch-worker-state.json` (when `SETTLD_DEMO_RUN_BATCH_SETTLEMENT=1`)
 - `batch-settlement.json` (when `SETTLD_DEMO_RUN_BATCH_SETTLEMENT=1`)
 
+## First verified receipt (keep this artifact)
+
+The demo exports receipts to:
+
+- `<artifactDir>/x402-receipts.export.jsonl`
+- `<artifactDir>/x402-receipts.sample-verification.json`
+
+Convert the first exported receipt row into a standalone JSON file and verify it:
+
+```bash
+jq -c 'first' <artifactDir>/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
+```
+
+Keep `/tmp/settld-first-receipt.verify.json` (or check in an equivalent artifact path in CI). This is the deterministic
+proof packet for the first paid action.
+
 ## Authority + Pinning Notes
 
 - Authority enforcement in this flow is API key scope + tenant-bound policy checks at Settld API/gateway surfaces.
@@ -107,7 +140,14 @@ Reference specs:
 
 ## Run The MCP Server
 
-Set environment variables:
+Primary path:
+
+```bash
+settld setup
+npm run mcp:server
+```
+
+Manual fallback (if you skip setup):
 
 ```bash
 export SETTLD_BASE_URL='https://api.settld.work'   # or http://127.0.0.1:3000

package/docs/QUICKSTART_MCP_HOSTS.md

@@ -1,143 +1,210 @@
-# Quickstart: MCP Host Integrations (Claude, Cursor, Codex, OpenClaw)
+# Quickstart: MCP Host Integrations (Codex, Claude, Cursor, OpenClaw)
 
-Use this when you want to connect a real agent host to Settld MCP in under 5 minutes.
+This guide is the fastest path to wire Settld into an agent host and confirm a first verified paid action.
 
-For core MCP flow details and paid-tool artifacts, see `docs/QUICKSTART_MCP.md`.
+Target outcome:
 
-## 0) Prerequisites
+1. Host can call `settld.*` MCP tools.
+2. Wallet mode is configured (`managed`, `byo`, or `none`).
+3. Policy profile is applied.
+4. Smoke call and first paid receipt are green.
 
+For deeper tool-level examples, see `docs/QUICKSTART_MCP.md`.
+
+## 1) Before you run `settld setup`
+
+Required inputs:
+
+- `SETTLD_BASE_URL` (local or hosted API URL)
+- `SETTLD_TENANT_ID`
+- `SETTLD_API_KEY` (`keyId.secret`)
 - Node.js 20+
-- Settld API reachable (`http://127.0.0.1:3000` for local or your hosted API)
-- A tenant-scoped Settld API key (`keyId.secret` format)
 
-Export env once in your shell:
+Recommended non-interactive pattern:
 
 ```bash
-export SETTLD_BASE_URL='http://127.0.0.1:3000'
-export SETTLD_TENANT_ID='tenant_default'
-export SETTLD_API_KEY='sk_live_xxx.yyy'
-export SETTLD_PAID_TOOLS_BASE_URL='http://127.0.0.1:8402'
+settld setup --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --settld-api-key 'sk_live_xxx.yyy' \
+  --wallet-mode managed \
+  --wallet-bootstrap remote \
+  --profile-id engineering-spend \
+  --smoke \
+  --out-env ./.tmp/settld-openclaw.env
 ```
 
-Sanity check the server before wiring any host:
+If you want validation only (no config writes):
 
 ```bash
-npm run mcp:probe
+settld setup --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --settld-api-key 'sk_live_xxx.yyy' \
+  --wallet-mode none \
+  --preflight-only \
+  --report-path ./.tmp/setup-preflight.json \
+  --format json
 ```
 
-## 1) Canonical MCP Server Definition
-
-Most hosts that support MCP stdio need a command, args, and env.
-Use this as your default server config:
-
-```json
-{
-  "name": "settld",
-  "command": "npx",
-  "args": ["-y", "settld-mcp"],
-  "env": {
-    "SETTLD_BASE_URL": "http://127.0.0.1:3000",
-    "SETTLD_TENANT_ID": "tenant_default",
-    "SETTLD_API_KEY": "sk_live_xxx.yyy",
-    "SETTLD_PAID_TOOLS_BASE_URL": "http://127.0.0.1:8402"
-  }
-}
+## 2) Host setup flows
+
+Unified setup command:
+
+```bash
+settld setup
 ```
 
-If your host cannot spawn stdio commands, use HTTP bridge:
+The wizard handles:
+
+- host selection (`codex|claude|cursor|openclaw`)
+- wallet mode selection (`managed|byo|none`)
+- preflight checks (API health, tenant auth, profile baseline, host config path)
+- policy apply + optional smoke
+- interactive menus with arrow keys (Up/Down + Enter) for choice steps
+
+Host-specific non-interactive examples:
 
 ```bash
-MCP_HTTP_PORT=8787 npm run mcp:http
+# Codex
+settld setup --non-interactive --host codex --base-url http://127.0.0.1:3000 --tenant-id tenant_default --settld-api-key sk_live_xxx.yyy --wallet-mode none --profile-id engineering-spend --smoke
+
+# Claude
+settld setup --non-interactive --host claude --base-url http://127.0.0.1:3000 --tenant-id tenant_default --settld-api-key sk_live_xxx.yyy --wallet-mode none --profile-id engineering-spend --smoke
+
+# Cursor
+settld setup --non-interactive --host cursor --base-url http://127.0.0.1:3000 --tenant-id tenant_default --settld-api-key sk_live_xxx.yyy --wallet-mode none --profile-id engineering-spend --smoke
+
+# OpenClaw
+settld setup --non-interactive --host openclaw --base-url http://127.0.0.1:3000 --tenant-id tenant_default --settld-api-key sk_live_xxx.yyy --wallet-mode none --profile-id engineering-spend --smoke
 ```
 
-Then point the host at:
+## 3) Wallet modes: managed vs BYO
 
-- MCP endpoint: `http://127.0.0.1:8787/rpc`
-- Health endpoint: `http://127.0.0.1:8787/healthz`
+### Managed (`--wallet-mode managed`)
 
-## 2) Claude
+Managed is the default and recommended first path.
 
-1. Open Claude MCP settings.
-2. Add a new MCP server using the canonical config above.
-3. Save and reconnect.
-4. Ask Claude to call:
-   - `settld.about`
-   - `settld.exa_search_paid` with `{"query":"dentist near me chicago","numResults":3}`
+`--wallet-bootstrap auto` behavior:
 
-Expected behavior:
+- If `--circle-api-key` (or `CIRCLE_API_KEY`) is present: local Circle bootstrap.
+- If not present: remote onboarding bootstrap (`/v1/tenants/{tenantId}/onboarding/wallet-bootstrap`).
 
-- First paid call triggers x402 challenge/authorize/retry automatically in the MCP wrapper.
-- Tool result includes Settld verification/settlement headers.
+Force the path explicitly when needed:
 
-## 3) Cursor
+```bash
+# force remote wallet creation
+settld setup --non-interactive --host openclaw --base-url https://api.settld.work --tenant-id tenant_default --settld-api-key 'sk_live_xxx.yyy' --wallet-mode managed --wallet-bootstrap remote --profile-id engineering-spend --smoke
 
-1. Open Cursor MCP settings.
-2. Add an MCP server using the same canonical stdio definition.
-3. Reconnect tools.
-4. Run:
-   - `settld.about`
-   - `settld.weather_current_paid` with `{"city":"Chicago","unit":"f"}`
+# force local wallet creation with Circle credentials
+settld setup --non-interactive --host openclaw --base-url https://api.settld.work --tenant-id tenant_default --settld-api-key 'sk_live_xxx.yyy' --wallet-mode managed --wallet-bootstrap local --circle-api-key 'TEST_API_KEY:...' --profile-id engineering-spend --smoke
+```
 
-Expected behavior:
+### BYO (`--wallet-mode byo`)
 
-- Paid tool returns response body plus `x-settld-*` headers captured by the tool bridge.
+Provide your own existing wallet values. Required keys:
 
-## 4) Codex
+- `CIRCLE_BASE_URL`
+- `CIRCLE_BLOCKCHAIN`
+- `CIRCLE_WALLET_ID_SPEND`
+- `CIRCLE_WALLET_ID_ESCROW`
+- `CIRCLE_TOKEN_ID_USDC`
+- `CIRCLE_ENTITY_SECRET_HEX`
 
-1. Open Codex MCP/tooling configuration.
-2. Register Settld with the canonical stdio definition.
-3. Reload tool discovery.
-4. Run:
-   - `settld.about`
-   - `settld.exa_search_paid`
+Pass as env or repeated `--wallet-env KEY=VALUE` flags:
 
-Expected behavior:
+```bash
+settld setup --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --settld-api-key 'sk_live_xxx.yyy' \
+  --wallet-mode byo \
+  --wallet-env CIRCLE_BASE_URL=https://api-sandbox.circle.com \
+  --wallet-env CIRCLE_BLOCKCHAIN=BASE-SEPOLIA \
+  --wallet-env CIRCLE_WALLET_ID_SPEND=wid_spend \
+  --wallet-env CIRCLE_WALLET_ID_ESCROW=wid_escrow \
+  --wallet-env CIRCLE_TOKEN_ID_USDC=token_usdc \
+  --wallet-env CIRCLE_ENTITY_SECRET_HEX=$(openssl rand -hex 32) \
+  --profile-id engineering-spend \
+  --smoke
+```
 
-- Paid call resolves through the same x402 autopay flow.
+### None (`--wallet-mode none`)
 
-## 5) OpenClaw
+Use this for policy/tooling setup without payment rails yet.
 
-For OpenClaw, package Settld as a skill that declares MCP setup instructions.
-Reference skill payload:
+## 4) Activation after setup
 
-- `docs/integrations/openclaw/settld-mcp-skill/SKILL.md`
-- `docs/integrations/openclaw/settld-mcp-skill/mcp-server.example.json`
-- `docs/integrations/openclaw/CLAWHUB_PUBLISH_CHECKLIST.md`
+`settld setup` writes host MCP config and prints `Combined exports`.
 
-Minimum skill payload should include:
+If you used `--out-env`, source it before running tools:
 
-- Name/description
-- MCP server command (`npx -y settld-mcp`)
-- Required env vars (`SETTLD_BASE_URL`, `SETTLD_TENANT_ID`, `SETTLD_API_KEY`, optional `SETTLD_PAID_TOOLS_BASE_URL`)
-- A smoke prompt using `settld.about`
+```bash
+source ./.tmp/settld-openclaw.env
+```
 
-You can test locally first with:
+Then activate host-side:
+
+- `codex`: restart Codex.
+- `claude`: restart Claude Desktop.
+- `cursor`: restart Cursor.
+- `openclaw`: run `openclaw doctor`, ensure OpenClaw onboarding is complete (`openclaw onboard --install-daemon`), then run `openclaw tui`.
+
+## 5) How the agent uses Settld after activation
+
+After host activation, the agent interacts with Settld through MCP `settld.*` tools.
+
+Typical flow:
+
+1. Connectivity check: `settld.about`
+2. Paid action: `settld.exa_search_paid` or `settld.weather_current_paid`
+3. Policy gate + authorization happen server-side in Settld.
+4. Settld records evidence/decision/receipt artifacts.
+5. You can verify receipts offline (`settld x402 receipt verify`).
+
+Quick local smoke:
 
 ```bash
 npm run mcp:probe -- --call settld.about '{}'
 ```
 
-## 6) 5-Minute Validation Checklist
+First paid run + artifacts:
+
+```bash
+npm run demo:mcp-paid-exa
+```
+
+Verify first receipt from artifacts:
+
+```bash
+# replace <artifactDir> with the printed directory from demo output
+settld x402 receipt verify <artifactDir>/x402-receipt.json --json-out /tmp/settld-first-receipt.json
+```
+
+## 6) Host config helper customization
+
+Default host configuration logic is in:
+
+- `scripts/setup/host-config.mjs`
 
-0. (CI/local gate) run hosted-style smoke once:
+If you need a custom resolver/writer, pass:
 
 ```bash
-npm run test:ci:mcp-host-smoke
+settld setup --host-config ./path/to/custom-host-config.mjs
 ```
 
-1. `npm run mcp:probe` passes locally.
-2. Host discovers Settld tools (`tools/list` includes `settld.*`).
-3. `settld.about` succeeds.
-4. One paid tool call succeeds (`settld.exa_search_paid` or `settld.weather_current_paid`).
-5. You can see a resulting artifact bundle from paid demo runs:
-   - `artifacts/mcp-paid-exa/.../summary.json`
-   - `artifacts/mcp-paid-weather/.../summary.json`
+Your helper should provide resolver/setup exports compatible with `scripts/setup/wizard.mjs`.
 
 ## 7) Troubleshooting
 
+- `BYO wallet mode missing required env keys`
+  - Provide all required Circle keys in section 3.
+- `host config helper missing`
+  - Add `scripts/setup/host-config.mjs` or pass `--host-config`.
 - `SETTLD_API_KEY must be a non-empty string`
-  - API key not injected into MCP server env.
+  - Ensure key is present in shell or setup flags.
 - Host cannot run `npx`
-  - Install Node 20+ and ensure `npx` is on PATH, or run HTTP bridge mode.
-- Paid tool returns gateway/connectivity errors
-  - Confirm `SETTLD_PAID_TOOLS_BASE_URL` points to a running gateway.
+  - Install Node.js 20+ and ensure `npx` is in `PATH`.

package/docs/QUICKSTART_POLICY_PACKS.md

@@ -0,0 +1,65 @@
+# Quickstart: Policy Packs CLI (v1)
+
+Goal: initialize, simulate, and publish deterministic local policy pack artifacts with `settld policy`.
+
+## Starter policy packs
+
+- `engineering-spend`
+- `procurement-enterprise`
+- `data-api-buyer`
+- `support-automation`
+- `finance-controls`
+
+## 1) Initialize a starter pack
+
+Installed CLI:
+
+```bash
+npx settld policy init engineering-spend --out ./policies/engineering.policy-pack.json
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js policy init engineering-spend --out ./policies/engineering.policy-pack.json
+```
+
+## 2) Simulate a decision
+
+Default scenario (first allowlisted provider/tool, zero spend):
+
+```bash
+./bin/settld.js policy simulate ./policies/engineering.policy-pack.json --format json
+```
+
+Explicit scenario:
+
+```bash
+./bin/settld.js policy simulate ./policies/engineering.policy-pack.json \
+  --scenario-json '{"providerId":"openai","toolId":"llm.inference","amountUsdCents":25000,"monthToDateSpendUsdCents":100000,"approvalsProvided":1,"receiptSigned":true,"toolManifestHashPresent":true,"toolVersionKnown":true}' \
+  --format json
+```
+
+## 3) Publish locally (deterministic report artifact)
+
+```bash
+./bin/settld.js policy publish ./policies/engineering.policy-pack.json --format json
+```
+
+`publish` has no remote dependency. It writes a local `SettldPolicyPublication.v1` artifact and returns a `SettldPolicyPublishReport.v1` with:
+
+- deterministic `policyFingerprint` (canonical JSON SHA-256)
+- deterministic `publicationRef` (`<channel>:<packId>:<fingerprint-prefix>`)
+- `artifactPath` + `artifactSha256`
+
+## Output modes
+
+All commands support:
+
+- `--format text|json` (default `text`)
+- `--json-out <path>` for machine output files
+
+`init` and `publish` also support:
+
+- `--out <path>`
+- `--force` to overwrite an existing path