settld 0.2.1 → 0.2.3

package/README.md

@@ -73,6 +73,16 @@ Agent host onboarding (Codex / Claude / Cursor / OpenClaw), with guided wallet +
 npx -y settld setup
 ```
 
+Default interactive flow is now login-first:
+
+1. pick host + wallet mode
+2. choose `quick` setup (recommended)
+3. login with OTP (creates tenant if needed)
+4. setup mints runtime API key automatically
+5. guided wallet fund + first paid call check runs
+
+Advanced mode is still available in setup when you need explicit base URL/bootstrap/API-key control.
+
 Preflight-only check (no host config write), with JSON report:
 
 ```sh
@@ -86,6 +96,28 @@ npm install -g settld
 settld setup
 ```
 
+Check wallet wiring and funding path:
+
+```sh
+settld login
+settld wallet status
+settld wallet fund --open
+settld wallet fund --method transfer
+settld wallet balance --watch --min-usdc 1
+```
+
+Hosted top-up (recommended): configure Coinbase Hosted Onramp on the backend so `settld wallet fund --open` launches funding directly:
+
+```sh
+export MAGIC_LINK_WALLET_FUND_PROVIDER='coinbase'
+export MAGIC_LINK_COINBASE_API_KEY_VALUE='organizations/<org_id>/apiKeys/<key_id>'
+export MAGIC_LINK_COINBASE_API_SECRET_KEY='-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----'
+export MAGIC_LINK_COINBASE_PROJECT_ID='<project_id>'
+export MAGIC_LINK_COINBASE_DESTINATION_NETWORK='base'
+export MAGIC_LINK_COINBASE_ASSET='USDC'
+export MAGIC_LINK_COINBASE_FIAT_CURRENCY='USD'
+```
+
 Legacy setup wizard (advanced / old flags):
 
 ```sh

package/bin/settld.js

@@ -22,6 +22,15 @@ 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 wallet status [--base-url <url>] [--tenant-id <id>] [--session-file <path>] [--cookie <cookie>] [--magic-link-api-key <key>] [--format text|json] [--json-out <path>]"
+  );
+  console.error(
+    "  settld wallet fund [--method card|bank|transfer|faucet] [--open] [--hosted-url <url>] [--non-interactive] [--base-url <url>] [--tenant-id <id>] [--session-file <path>] [--cookie <cookie>] [--magic-link-api-key <key>] [--format text|json] [--json-out <path>]"
+  );
+  console.error(
+    "  settld wallet balance [--watch] [--min-usdc <amount>] [--interval-seconds <n>] [--timeout-seconds <n>] [--base-url <url>] [--tenant-id <id>] [--session-file <path>] [--cookie <cookie>] [--magic-link-api-key <key>] [--format text|json] [--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(
@@ -271,6 +280,10 @@ function main() {
     process.exit(1);
   }
 
+  if (cmd === "wallet") {
+    return runNodeScript("scripts/wallet/cli.mjs", argv.slice(1));
+  }
+
   if (cmd === "profile") {
     return runNodeScript("scripts/profile/cli.mjs", argv.slice(1));
   }

package/docs/QUICKSTART_MCP_HOSTS.md

@@ -13,16 +13,27 @@ For deeper tool-level examples, see `docs/QUICKSTART_MCP.md`.
 
 ## 1) Before you run `settld setup`
 
-Required inputs:
+Public default path (recommended):
 
-- `SETTLD_BASE_URL` (local or hosted API URL)
-- `SETTLD_TENANT_ID`
+- Node.js 20+
+- no API keys required up front
+- run `settld setup`, choose `quick`, then login with OTP
+- setup creates tenant (if needed), mints runtime key, and wires MCP
+
+Admin/operator path (advanced):
+
+- explicit `SETTLD_BASE_URL`, `SETTLD_TENANT_ID`
 - one of:
   - `SETTLD_API_KEY` (`keyId.secret`), or
-  - `SETTLD_BOOTSTRAP_API_KEY` (onboarding bootstrap key that mints `SETTLD_API_KEY` during setup)
-- Node.js 20+
+  - `SETTLD_BOOTSTRAP_API_KEY` (bootstrap key that mints runtime key)
+
+Recommended interactive pattern:
 
-Recommended non-interactive pattern:
+```bash
+settld setup
+```
+
+Recommended non-interactive pattern (automation/support):
 
 ```bash
 settld setup --non-interactive \
@@ -37,7 +48,7 @@ settld setup --non-interactive \
   --out-env ./.tmp/settld-openclaw.env
 ```
 
-If you want setup to generate the tenant API key for you:
+If you want non-interactive setup to generate the tenant API key:
 
 ```bash
 settld setup --non-interactive \
@@ -73,14 +84,18 @@ Unified setup command:
 settld setup
 ```
 
-The wizard handles:
+`quick` mode (default) handles:
 
 - host selection (`codex|claude|cursor|openclaw`)
 - wallet mode selection (`managed|byo|none`)
+- login/signup + OTP session flow (no manual key paste)
 - preflight checks (API health, tenant auth, profile baseline, host config path)
 - policy apply + optional smoke
+- guided wallet funding and first paid MCP check
 - interactive menus with arrow keys (Up/Down + Enter) for choice steps
 
+`advanced` mode exposes explicit key/bootstrap/base-url prompts and fine-grained setup toggles.
+
 Host-specific non-interactive examples:
 
 ```bash
@@ -169,7 +184,66 @@ Then activate host-side:
 - `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
+## 5) Fund and verify wallet state
+
+Check wallet assignment after setup:
+
+```bash
+settld wallet status
+```
+
+If wallet commands return auth errors, run:
+
+```bash
+settld login
+```
+
+Funding paths:
+
+```bash
+# Guided selector (recommended)
+settld wallet fund --open
+
+# Hosted flow (card/bank) - provider-hosted URL, add --open to launch browser
+settld wallet fund --method card --open
+settld wallet fund --method bank --open
+
+# Direct transfer path (prints chain + destination address)
+settld wallet fund --method transfer
+
+# Sandbox only: request faucet top-up
+settld wallet fund --method faucet
+```
+
+Provider-hosted card/bank links are configured on the control-plane backend.
+
+Option A (recommended): Coinbase Hosted Onramp:
+
+```bash
+export MAGIC_LINK_WALLET_FUND_PROVIDER='coinbase'
+export MAGIC_LINK_COINBASE_API_KEY_VALUE='organizations/<org_id>/apiKeys/<key_id>'
+export MAGIC_LINK_COINBASE_API_SECRET_KEY='-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----'
+export MAGIC_LINK_COINBASE_PROJECT_ID='<project_id>'
+export MAGIC_LINK_COINBASE_DESTINATION_NETWORK='base'
+export MAGIC_LINK_COINBASE_ASSET='USDC'
+export MAGIC_LINK_COINBASE_FIAT_CURRENCY='USD'
+```
+
+Option B: explicit card/bank URLs:
+
+```bash
+# backend env (magic-link service)
+export MAGIC_LINK_WALLET_FUND_CARD_URL='https://pay.example.com/topup?tenant={tenantId}&method=card&address={walletAddress}'
+export MAGIC_LINK_WALLET_FUND_BANK_URL='https://pay.example.com/topup?tenant={tenantId}&method=bank&address={walletAddress}'
+```
+
+After funding, wait until spend wallet has balance:
+
+```bash
+settld wallet balance --watch --min-usdc 1
+```
+
+## 6) How the agent uses Settld after activation
 
 After host activation, the agent interacts with Settld through MCP `settld.*` tools.
 
@@ -200,7 +274,7 @@ Verify first receipt from artifacts:
 settld x402 receipt verify <artifactDir>/x402-receipt.json --json-out /tmp/settld-first-receipt.json
 ```
 
-## 6) Host config helper customization
+## 7) Host config helper customization
 
 Default host configuration logic is in:
 
@@ -214,10 +288,15 @@ settld setup --host-config ./path/to/custom-host-config.mjs
 
 Your helper should provide resolver/setup exports compatible with `scripts/setup/wizard.mjs`.
 
-## 7) Troubleshooting
+## 8) Troubleshooting
 
 - `BYO wallet mode missing required env keys`
   - Provide all required Circle keys in section 3.
+- `auth required: pass --cookie/--magic-link-api-key or run settld login first`
+  - Run `settld login`, then retry `settld wallet status` / `settld wallet fund`.
+- `no hosted funding URL configured for card/bank`
+  - set backend Coinbase env (`MAGIC_LINK_WALLET_FUND_PROVIDER=coinbase`, `MAGIC_LINK_COINBASE_API_KEY_VALUE`, `MAGIC_LINK_COINBASE_API_SECRET_KEY`) or set explicit `MAGIC_LINK_WALLET_FUND_CARD_URL` / `MAGIC_LINK_WALLET_FUND_BANK_URL`.
+  - pass `--hosted-url` for an ad-hoc override.
 - `host config helper missing`
   - Add `scripts/setup/host-config.mjs` or pass `--host-config`.
 - `SETTLD_API_KEY must be a non-empty string`

package/docs/README.md

@@ -17,10 +17,11 @@ For curated public docs, start here:
 
 ## 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:
+1. Run `settld setup` (or `./bin/settld.js setup`), choose `quick`, and complete OTP login.
+2. Let guided wallet funding complete (or run `settld wallet fund` + `settld wallet balance --watch --min-usdc 1`).
+3. Activate your host and run `npm run mcp:probe`.
+4. Run `npm run demo:mcp-paid-exa`.
+5. Verify the first receipt:
 
 ```bash
 jq -c 'first' artifacts/mcp-paid-exa/*/x402-receipts.export.jsonl > /tmp/settld-first-receipt.json

package/docs/gitbook/README.md

@@ -19,9 +19,13 @@ Settld gives you a canonical economic loop:
 ## One-command onboarding
 
 ```bash
-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 managed --wallet-bootstrap remote --profile-id engineering-spend --smoke
+settld setup
 ```
 
+Recommended path: choose `quick`, complete OTP login, and let setup run guided funding + paid-call checks.
+
+Advanced/scripted path is still supported with explicit non-interactive flags.
+
 Then:
 
 1. `npm run mcp:probe -- --call settld.about '{}'`

package/docs/gitbook/quickstart.md

@@ -5,9 +5,8 @@ Get from zero to a verified paid agent action in minutes.
 ## Prerequisites
 
 - Node.js 20+
-- Settld API URL
-- Tenant ID
-- Tenant API key (`keyId.secret`)
+- Public flow: no API key required up front (`settld setup` handles login/session bootstrap)
+- Advanced flow: optional explicit `--base-url`, `--tenant-id`, and `--settld-api-key`
 
 ## 0) One-command setup
 
@@ -17,7 +16,14 @@ Run guided setup:
 settld setup
 ```
 
-The guided setup uses arrow-key menus for host/wallet/policy decisions, then asks only the next required fields.
+Recommended interactive choices:
+
+1. host
+2. `quick` setup mode
+3. wallet mode
+4. OTP login (creates tenant if needed)
+
+`quick` mode auto-runs preflight/smoke/profile apply, then starts guided wallet fund + first paid call checks.
 
 Non-interactive example:
 
@@ -51,7 +57,46 @@ source ./.tmp/settld.env
 
 Then restart your host app (Codex/Claude/Cursor/OpenClaw) so it reloads MCP config.
 
-## 2) Verify MCP connectivity
+## 2) Check wallet and fund it
+
+```bash
+settld login
+settld wallet status
+settld wallet fund --method transfer
+settld wallet balance --watch --min-usdc 1
+```
+
+Optional methods:
+
+```bash
+settld wallet fund --open
+settld wallet fund --method card --open
+settld wallet fund --method bank --open
+settld wallet fund --method faucet
+```
+
+For card/bank, configure one hosted provider URL strategy on the control-plane backend.
+
+Option A (recommended): Coinbase Hosted Onramp:
+
+```bash
+export MAGIC_LINK_WALLET_FUND_PROVIDER='coinbase'
+export MAGIC_LINK_COINBASE_API_KEY_VALUE='organizations/<org_id>/apiKeys/<key_id>'
+export MAGIC_LINK_COINBASE_API_SECRET_KEY='-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----'
+export MAGIC_LINK_COINBASE_PROJECT_ID='<project_id>'
+export MAGIC_LINK_COINBASE_DESTINATION_NETWORK='base'
+export MAGIC_LINK_COINBASE_ASSET='USDC'
+export MAGIC_LINK_COINBASE_FIAT_CURRENCY='USD'
+```
+
+Option B: explicit card/bank hosted templates:
+
+```bash
+export MAGIC_LINK_WALLET_FUND_CARD_URL='https://pay.example.com/topup?tenant={tenantId}&method=card&address={walletAddress}'
+export MAGIC_LINK_WALLET_FUND_BANK_URL='https://pay.example.com/topup?tenant={tenantId}&method=bank&address={walletAddress}'
+```
+
+## 3) Verify MCP connectivity
 
 ```bash
 npm run mcp:probe -- --call settld.about '{}'
@@ -62,7 +107,7 @@ Expected outcome:
 - `settld.about` succeeds
 - host can discover `settld.*` tools
 
-## 3) Run first paid call
+## 4) Run first paid call
 
 ```bash
 npm run demo:mcp-paid-exa
@@ -75,7 +120,7 @@ Expected output includes:
 - `decisionId=...`
 - `settlementReceiptId=...`
 
-## 4) Verify first receipt (proof packet)
+## 5) Verify first receipt (proof packet)
 
 ```bash
 jq -c 'first' <artifactDir>/x402-receipts.export.jsonl > /tmp/settld-first-receipt.json
@@ -84,7 +129,7 @@ settld x402 receipt verify /tmp/settld-first-receipt.json --format json --json-o
 
 `/tmp/settld-first-receipt.verify.json` is your deterministic verification artifact for audit/compliance.
 
-## 5) Optional: policy profile workflows
+## 6) Optional: policy profile workflows
 
 ```bash
 settld profile list
@@ -99,5 +144,10 @@ settld profile simulate ./profiles/engineering-spend.profile.json --format json
   - ensure key is present in setup flags or shell env.
 - `BYO wallet mode missing required env keys`
   - provide all required Circle keys in `docs/QUICKSTART_MCP_HOSTS.md`.
+- `auth required: pass --cookie/--magic-link-api-key or run settld login first`
+  - run `settld login`, then retry wallet commands.
+- `no hosted funding URL configured for card/bank`
+  - set backend Coinbase env (`MAGIC_LINK_WALLET_FUND_PROVIDER=coinbase`, `MAGIC_LINK_COINBASE_API_KEY_VALUE`, `MAGIC_LINK_COINBASE_API_SECRET_KEY`) or set explicit `MAGIC_LINK_WALLET_FUND_CARD_URL` / `MAGIC_LINK_WALLET_FUND_BANK_URL`.
+  - pass `--hosted-url` for an ad-hoc override.
 - Host cannot find MCP tools
   - rerun setup, restart host, then rerun `npm run mcp:probe`.

package/docs/integrations/README.md

@@ -5,7 +5,7 @@ Copy/paste adoption templates and guardrails:
 - `github-actions.md` — composite action usage and trust anchor wiring.
 - `github-actions-verify.yml` — pasteable workflow template.
 - `openclaw/PUBLIC_QUICKSTART.md` — public npm onboarding flow for OpenClaw (`npx settld@latest setup`).
-- `openclaw/settld-mcp-skill/SKILL.md` — OpenClaw skill payload for Settld MCP.
+- `openclaw/settld-mcp-skill/SKILL.md` + `openclaw/settld-mcp-skill/skill.json` — OpenClaw skill payload + manifest for Settld MCP.
 - `openclaw/CLAWHUB_PUBLISH_CHECKLIST.md` — publish + validation checklist for ClawHub.
 
 See also:

package/docs/integrations/openclaw/CLAWHUB_PUBLISH_CHECKLIST.md

@@ -15,6 +15,7 @@ Confirm required files exist:
 
 - `docs/integrations/openclaw/settld-mcp-skill/SKILL.md`
 - `docs/integrations/openclaw/settld-mcp-skill/mcp-server.example.json`
+- `docs/integrations/openclaw/settld-mcp-skill/skill.json`
 
 ## 2) Prepare Skill Metadata
 
@@ -62,4 +63,3 @@ Capture these fields each publish:
 - Added/changed tools
 - Known limitations
 - Validation run timestamp
-

package/docs/integrations/openclaw/PUBLIC_QUICKSTART.md

@@ -33,10 +33,10 @@ npx -y settld@latest setup
 Choose:
 
 1. `host`: `openclaw`
-2. wallet mode (`managed` recommended first)
-3. wallet bootstrap (`remote` recommended for first setup)
-4. keep preflight + smoke enabled
-5. apply a starter profile (`engineering-spend`)
+2. setup mode: `quick`
+3. wallet mode (`managed` recommended first)
+4. login with OTP (new tenant is created if needed)
+5. let setup run guided fund + first paid check
 
 Non-interactive path (automation/support):
 
@@ -53,7 +53,7 @@ npx -y settld@latest setup \
   --smoke
 ```
 
-If you do not have a tenant `sk_*` yet, let setup mint one:
+Advanced non-interactive key/bootstrap paths are still supported:
 
 ```bash
 npx -y settld@latest setup \
@@ -102,7 +102,9 @@ npx -y settld@latest x402 receipt verify ./receipt.json --format json
 ## Notes for operators
 
 - Public users do not need to clone the Settld repo.
+- Public users should not need bootstrap/admin keys in the default setup path.
 - Public path is valid only after publishing a package version that includes the current setup flow.
 - For OpenClaw skill packaging and publish flow, see:
   - `docs/integrations/openclaw/settld-mcp-skill/SKILL.md`
+  - `docs/integrations/openclaw/settld-mcp-skill/skill.json`
   - `docs/integrations/openclaw/CLAWHUB_PUBLISH_CHECKLIST.md`

package/docs/integrations/openclaw/settld-mcp-skill/SKILL.md

@@ -9,6 +9,14 @@ author: Settld
 
 This skill teaches OpenClaw agents to use Settld for paid MCP tool calls.
 
+It is designed for the public `quick` onboarding flow:
+
+1. `settld setup`
+2. pick `openclaw` + `quick`
+3. login via OTP
+4. fund wallet
+5. run paid tool call with deterministic receipt evidence
+
 ## What This Skill Enables
 
 - Discover Settld MCP tools (`settld.*`)
@@ -19,9 +27,7 @@ This skill teaches OpenClaw agents to use Settld for paid MCP tool calls.
 ## Prerequisites
 
 - Node.js 20+
-- Settld API key (`SETTLD_API_KEY`)
-- Settld API base URL (`SETTLD_BASE_URL`)
-- Tenant id (`SETTLD_TENANT_ID`)
+- Settld runtime env from setup (`SETTLD_API_KEY`, `SETTLD_BASE_URL`, `SETTLD_TENANT_ID`)
 - Optional paid tools base URL (`SETTLD_PAID_TOOLS_BASE_URL`)
 
 ## MCP Server Registration
@@ -61,9 +67,18 @@ Optional env vars:
 - "Call `settld.about` and return the result JSON."
 - "Run `settld.weather_current_paid` for Chicago in fahrenheit and include the `x-settld-*` headers."
 
+## Identity + Traceability
+
+Every paid call should be explainable and auditable:
+
+- tenant identity (who owns the runtime)
+- actor/session identity (who approved/triggered)
+- policy decision identity (`allow|challenge|deny|escalate` + reason codes)
+- settlement identity (`settlementReceiptId`)
+- evidence identity (hash-verifiable receipt/timeline artifacts)
+
 ## Safety Notes
 
 - Treat `SETTLD_API_KEY` as secret input.
 - Do not print full API keys in chat output.
 - Keep paid tools scoped to trusted providers and tenant policy.
-

package/docs/integrations/openclaw/settld-mcp-skill/mcp-server.example.json

@@ -3,10 +3,8 @@
   "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"
+    "SETTLD_BASE_URL": "https://api.settld.work",
+    "SETTLD_TENANT_ID": "tenant_xxx",
+    "SETTLD_API_KEY": "sk_live_xxx.yyy"
   }
 }
-

package/docs/integrations/openclaw/settld-mcp-skill/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "settld-mcp-payments",
+  "version": "0.2.0",
+  "description": "OpenClaw skill for Settld paid MCP tools with policy decisions and verifiable receipts.",
+  "author": "Settld",
+  "entry": "SKILL.md",
+  "files": [
+    "SKILL.md",
+    "mcp-server.example.json"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "settld",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",
@@ -136,6 +136,7 @@
   },
   "dependencies": {
     "@circle-fin/developer-controlled-wallets": "^10.1.0",
+    "@coinbase/cdp-sdk": "^1.44.1",
     "pg": "^8.11.5",
     "snarkjs": "^0.7.6"
   },

package/scripts/ci/run-mcp-host-smoke.mjs

@@ -11,6 +11,10 @@ function randomId(prefix) {
   return `${prefix}_${crypto.randomBytes(6).toString("hex")}`;
 }
 
+function buildScopedOpsToken(token) {
+  return `${String(token ?? "").trim()}:ops_read,ops_write,finance_read,finance_write,audit_read`;
+}
+
 function pickPort() {
   return new Promise((resolve, reject) => {
     const server = net.createServer();
@@ -243,6 +247,7 @@ function stopServer(server) {
 async function main() {
   const reportPath = path.resolve(process.cwd(), process.env.MCP_HOST_SMOKE_REPORT_PATH || "artifacts/ops/mcp-host-smoke.json");
   const opsToken = randomId("ops");
+  const scopedOpsToken = buildScopedOpsToken(opsToken);
   const magicLinkApiKey = randomId("ml_admin");
   const tenantId = randomId("tenant");
 
@@ -259,6 +264,7 @@ async function main() {
     env: {
       PORT: String(apiPort),
       PROXY_BIND_HOST: "127.0.0.1",
+      PROXY_OPS_TOKENS: scopedOpsToken,
       PROXY_OPS_TOKEN: opsToken,
       PROXY_AUTOTICK_INTERVAL_MS: "200"
     }

package/scripts/ci/run-production-cutover-gate.mjs

@@ -141,6 +141,10 @@ function randomId(prefix) {
   return `${prefix}_${crypto.randomBytes(6).toString("hex")}`;
 }
 
+function buildScopedOpsToken(token) {
+  return `${String(token ?? "").trim()}:ops_read,ops_write,finance_read,finance_write,audit_read`;
+}
+
 function pickPort() {
   return new Promise((resolve, reject) => {
     const server = net.createServer();
@@ -239,6 +243,7 @@ function startNodeProc({ name, scriptPath, env }) {
 async function startEphemeralApi(env = process.env) {
   const port = await pickPort();
   const opsToken = randomId("ops");
+  const scopedOpsToken = buildScopedOpsToken(opsToken);
   const baseUrl = `http://127.0.0.1:${port}`;
   const api = startNodeProc({
     name: "cutover-api",
@@ -247,6 +252,7 @@ async function startEphemeralApi(env = process.env) {
       ...env,
       PORT: String(port),
       PROXY_BIND_HOST: "127.0.0.1",
+      PROXY_OPS_TOKENS: scopedOpsToken,
       PROXY_OPS_TOKEN: opsToken,
       PROXY_AUTOTICK_INTERVAL_MS: "200"
     }

package/scripts/demo/mcp-paid-exa.mjs

@@ -192,6 +192,18 @@ function readEnvString(name, fallback = null) {
   return String(raw).trim();
 }
 
+function readFirstOpsTokenFromScopedList(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return null;
+  const firstEntry = text
+    .split(";")
+    .map((entry) => String(entry ?? "").trim())
+    .find(Boolean);
+  if (!firstEntry) return null;
+  const token = firstEntry.split(":")[0]?.trim() ?? "";
+  return token || null;
+}
+
 function assertCircleModeInputs({ mode }) {
   if (mode === "stub") return;
   const required = ["CIRCLE_API_KEY", "CIRCLE_WALLET_ID_SPEND", "CIRCLE_WALLET_ID_ESCROW", "CIRCLE_TOKEN_ID_USDC"];
@@ -646,7 +658,10 @@ async function main() {
   const workload = normalizeWorkload(cli.workload ?? readEnvString("SETTLD_DEMO_WORKLOAD", "exa"));
   const externalReserveRequired = circleMode !== "stub";
   assertCircleModeInputs({ mode: circleMode });
-  const opsToken = String(process.env.SETTLD_DEMO_OPS_TOKEN ?? "tok_ops").trim() || "tok_ops";
+  const inheritedOpsTokenList = readEnvString("PROXY_OPS_TOKENS", null);
+  const derivedOpsToken = readFirstOpsTokenFromScopedList(inheritedOpsTokenList);
+  const opsToken = String(process.env.SETTLD_DEMO_OPS_TOKEN ?? derivedOpsToken ?? "tok_ops").trim() || "tok_ops";
+  const scopedOpsToken = `${opsToken}:ops_read,ops_write,finance_read,finance_write,audit_read`;
   const tenantId = String(process.env.SETTLD_TENANT_ID ?? "tenant_default").trim() || "tenant_default";
 
   const workloadConfig = (() => {
@@ -733,6 +748,8 @@ async function main() {
       cmd: "node",
       args: ["src/api/server.js"],
       env: {
+        // Pin ops auth for this demo process so inherited deployment env can't cause token mismatch.
+        PROXY_OPS_TOKENS: scopedOpsToken,
         PROXY_OPS_TOKEN: opsToken,
         BIND_HOST: "127.0.0.1",
         PORT: String(apiPort),

package/scripts/setup/login.mjs

@@ -191,10 +191,13 @@ export async function runLogin({
   try {
     if (interactive) {
       state.baseUrl = await promptLine(rl, "Settld base URL", { defaultValue: state.baseUrl || "https://api.settld.work" });
-      state.tenantId = await promptLine(rl, "Tenant ID (optional for new signup)", { defaultValue: state.tenantId, required: false });
+      state.tenantId = await promptLine(rl, "Tenant ID (optional, leave blank to create new)", {
+        defaultValue: state.tenantId,
+        required: false
+      });
       state.email = (await promptLine(rl, "Email", { defaultValue: state.email })).toLowerCase();
       if (!state.tenantId) {
-        state.company = await promptLine(rl, "Company name", { defaultValue: state.company });
+        state.company = await promptLine(rl, "What should your tenant/company name be?", { defaultValue: state.company });
       }
     }