settld 0.2.2 → 0.2.4

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
@@ -89,6 +99,7 @@ settld setup
 Check wallet wiring and funding path:
 
 ```sh
+settld login
 settld wallet status
 settld wallet fund --open
 settld wallet fund --method transfer

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:
+
+```bash
+settld setup
+```
 
-Recommended non-interactive pattern:
+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
@@ -177,6 +192,12 @@ Check wallet assignment after setup:
 settld wallet status
 ```
 
+If wallet commands return auth errors, run:
+
+```bash
+settld login
+```
+
 Funding paths:
 
 ```bash

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:
 
@@ -54,6 +60,7 @@ Then restart your host app (Codex/Claude/Cursor/OpenClaw) so it reloads MCP conf
 ## 2) Check wallet and fund it
 
 ```bash
+settld login
 settld wallet status
 settld wallet fund --method transfer
 settld wallet balance --watch --min-usdc 1

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.2",
+  "version": "0.2.4",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",

package/scripts/setup/login.mjs

@@ -39,6 +39,7 @@ function readArgValue(argv, index, rawArg) {
 function parseArgs(argv) {
   const out = {
     baseUrl: "https://api.settld.work",
+    baseUrlProvided: false,
     tenantId: "",
     email: "",
     company: "",
@@ -64,6 +65,7 @@ function parseArgs(argv) {
     if (arg === "--base-url" || arg.startsWith("--base-url=")) {
       const parsed = readArgValue(argv, i, arg);
       out.baseUrl = parsed.value;
+      out.baseUrlProvided = true;
       i = parsed.nextIndex;
       continue;
     }
@@ -149,6 +151,20 @@ async function requestJson(url, { method, body, headers = {}, fetchImpl = fetch
   return { res, text, json };
 }
 
+function responseCode({ json }) {
+  const direct = typeof json?.code === "string" ? json.code : "";
+  if (direct) return direct;
+  const error = typeof json?.error === "string" ? json.error : "";
+  return error ? error.toUpperCase() : "";
+}
+
+function responseMessage({ json, text }, fallback = "unknown error") {
+  if (typeof json?.message === "string" && json.message.trim()) return json.message.trim();
+  if (typeof json?.error === "string" && json.error.trim()) return json.error.trim();
+  const raw = String(text ?? "").trim();
+  return raw || fallback;
+}
+
 async function promptLine(rl, label, { defaultValue = "", required = true } = {}) {
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
   const value = String(await rl.question(`${label}${suffix}: `) ?? "").trim() || String(defaultValue ?? "").trim();
@@ -190,11 +206,16 @@ export async function runLogin({
   const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
   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 });
+      if (!args.baseUrlProvided) {
+        state.baseUrl = await promptLine(rl, "Settld base URL", { defaultValue: state.baseUrl || "https://api.settld.work" });
+      }
+      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 });
       }
     }
 
@@ -202,7 +223,20 @@ export async function runLogin({
     if (!state.email) throw new Error("email is required");
     if (!state.tenantId && !state.company) throw new Error("company is required when tenant ID is omitted");
 
+    const requestTenantOtp = async (tenantId) => {
+      const otpRequest = await requestJson(`${baseUrl}/v1/tenants/${encodeURIComponent(String(tenantId ?? ""))}/buyer/login/otp`, {
+        method: "POST",
+        body: { email: state.email },
+        fetchImpl
+      });
+      if (!otpRequest.res.ok) {
+        const message = responseMessage(otpRequest);
+        throw new Error(`otp request failed (${otpRequest.res.status}): ${message}`);
+      }
+    };
+
     let tenantId = state.tenantId;
+    let otpAlreadyIssued = false;
     if (!tenantId) {
       const signup = await requestJson(`${baseUrl}/v1/public/signup`, {
         method: "POST",
@@ -210,27 +244,24 @@ export async function runLogin({
         fetchImpl
       });
       if (!signup.res.ok) {
-        const code = typeof signup.json?.code === "string" ? signup.json.code : "";
-        const message = typeof signup.json?.message === "string" ? signup.json.message : signup.text;
+        const code = responseCode(signup);
+        const message = responseMessage(signup);
         if (code === "SIGNUP_DISABLED") {
           throw new Error("Public signup is disabled for this environment. Use an existing tenant ID or bootstrap key flow.");
         }
-        throw new Error(`public signup failed (${signup.res.status}): ${message || "unknown error"}`);
+        if (signup.res.status === 403 && code === "FORBIDDEN") {
+          throw new Error(
+            "Public signup is unavailable on this base URL. Retry with --tenant-id <existing_tenant>, or in `settld setup` choose `Generate during setup` and provide an onboarding bootstrap API key."
+          );
+        }
+        throw new Error(`public signup failed (${signup.res.status}): ${message}`);
       }
       tenantId = String(signup.json?.tenantId ?? "").trim();
       if (!tenantId) throw new Error("public signup response missing tenantId");
+      otpAlreadyIssued = Boolean(signup.json?.otpIssued);
       if (interactive) stdout.write(`Created tenant: ${tenantId}\n`);
-    } else {
-      const otpRequest = await requestJson(`${baseUrl}/v1/tenants/${encodeURIComponent(tenantId)}/buyer/login/otp`, {
-        method: "POST",
-        body: { email: state.email },
-        fetchImpl
-      });
-      if (!otpRequest.res.ok) {
-        const message = typeof otpRequest.json?.message === "string" ? otpRequest.json.message : otpRequest.text;
-        throw new Error(`otp request failed (${otpRequest.res.status}): ${message || "unknown error"}`);
-      }
     }
+    if (!otpAlreadyIssued) await requestTenantOtp(tenantId);
 
     if (!state.otp && interactive) {
       state.otp = await promptLine(rl, "OTP code", { required: true });
@@ -243,8 +274,8 @@ export async function runLogin({
       fetchImpl
     });
     if (!login.res.ok) {
-      const message = typeof login.json?.message === "string" ? login.json.message : login.text;
-      throw new Error(`login failed (${login.res.status}): ${message || "unknown error"}`);
+      const message = responseMessage(login);
+      throw new Error(`login failed (${login.res.status}): ${message}`);
     }
     const setCookie = login.res.headers.get("set-cookie") ?? "";
     const cookie = cookieHeaderFromSetCookie(setCookie);

package/scripts/setup/onboard.mjs

@@ -13,10 +13,13 @@ import { bootstrapWalletProvider } from "../../src/core/wallet-provider-bootstra
 import { extractBootstrapMcpEnv, loadHostConfigHelper, runWizard } from "./wizard.mjs";
 import { SUPPORTED_HOSTS } from "./host-config.mjs";
 import { defaultSessionPath, readSavedSession } from "./session-store.mjs";
+import { runLogin } from "./login.mjs";
+import { runWalletCli } from "../wallet/cli.mjs";
 
 const WALLET_MODES = new Set(["managed", "byo", "none"]);
 const WALLET_PROVIDERS = new Set(["circle"]);
 const WALLET_BOOTSTRAP_MODES = new Set(["auto", "local", "remote"]);
+const SETUP_MODES = new Set(["quick", "advanced"]);
 const FORMAT_OPTIONS = new Set(["text", "json"]);
 const HOST_BINARY_HINTS = Object.freeze({
   codex: "codex",
@@ -38,6 +41,7 @@ const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(SCRIPT_DIR, "..", "..");
 const SETTLD_BIN = path.join(REPO_ROOT, "bin", "settld.js");
 const PROFILE_FINGERPRINT_REGEX = /^[0-9a-f]{64}$/;
+const DEFAULT_PUBLIC_BASE_URL = "https://api.settld.work";
 const ANSI_RESET = "\u001b[0m";
 const ANSI_BOLD = "\u001b[1m";
 const ANSI_DIM = "\u001b[2m";
@@ -54,6 +58,10 @@ function usage() {
     "",
     "flags:",
     "  --non-interactive               Disable prompts; require explicit flags",
+    "  --quick                         Quick setup mode (default for interactive)",
+    "  --advanced                      Advanced setup mode (shows all prompts)",
+    "  --guided-next                   Run guided fund + first paid check after setup (default in quick mode)",
+    "  --skip-guided-next              Skip guided post-setup actions",
     `  --host <${SUPPORTED_HOSTS.join("|")}>      Host target (default: auto-detect, fallback openclaw)`,
     "  --base-url <url>                Settld API base URL (or SETTLD_BASE_URL)",
     "  --tenant-id <id>                Settld tenant ID (or SETTLD_TENANT_ID)",
@@ -109,6 +117,8 @@ function parseWalletEnvAssignment(raw) {
 function parseArgs(argv) {
   const out = {
     nonInteractive: false,
+    setupMode: null,
+    guidedNext: null,
     host: null,
     baseUrl: null,
     tenantId: null,
@@ -149,6 +159,22 @@ function parseArgs(argv) {
       out.nonInteractive = true;
       continue;
     }
+    if (arg === "--quick") {
+      out.setupMode = "quick";
+      continue;
+    }
+    if (arg === "--advanced") {
+      out.setupMode = "advanced";
+      continue;
+    }
+    if (arg === "--guided-next") {
+      out.guidedNext = true;
+      continue;
+    }
+    if (arg === "--skip-guided-next") {
+      out.guidedNext = false;
+      continue;
+    }
     if (arg === "--skip-profile-apply") {
       out.skipProfileApply = true;
       continue;
@@ -310,6 +336,9 @@ function parseArgs(argv) {
   if (out.host && !SUPPORTED_HOSTS.includes(out.host)) {
     throw new Error(`--host must be one of: ${SUPPORTED_HOSTS.join(", ")}`);
   }
+  if (out.setupMode && !SETUP_MODES.has(out.setupMode)) {
+    throw new Error("--quick or --advanced are the supported setup modes");
+  }
   if (!WALLET_MODES.has(out.walletMode)) throw new Error("--wallet-mode must be managed|byo|none");
   if (!WALLET_PROVIDERS.has(out.walletProvider)) throw new Error(`--wallet-provider must be one of: ${[...WALLET_PROVIDERS].join(", ")}`);
   if (!WALLET_BOOTSTRAP_MODES.has(out.walletBootstrap)) throw new Error("--wallet-bootstrap must be auto|local|remote");
@@ -865,6 +894,144 @@ function buildHostNextSteps({ host, installedHosts }) {
   return steps;
 }
 
+function runMcpPaidCallProbe({ env, timeoutMs = 45_000 } = {}) {
+  const args = [
+    path.join("scripts", "mcp", "probe.mjs"),
+    "--call",
+    "settld.weather_current_paid",
+    JSON.stringify({ city: "Chicago", unit: "f" }),
+    "--timeout-ms",
+    String(timeoutMs)
+  ];
+  const result = spawnSync(process.execPath, args, {
+    cwd: REPO_ROOT,
+    env: { ...process.env, ...(env ?? {}) },
+    encoding: "utf8",
+    timeout: timeoutMs + 5000,
+    maxBuffer: 4 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const stdoutText = String(result.stdout ?? "");
+  const stderrText = String(result.stderr ?? "");
+  const sawToolError = /"isError"\s*:\s*true/.test(stdoutText);
+  const sawToolSuccess = /"isError"\s*:\s*false/.test(stdoutText);
+  const ok = Number(result.status) === 0 && sawToolSuccess && !sawToolError;
+  return {
+    ok,
+    exitCode: typeof result.status === "number" ? result.status : 1,
+    stdout: stdoutText,
+    stderr: stderrText
+  };
+}
+
+async function runGuidedQuickFlow({
+  enabled = false,
+  walletMode = "none",
+  normalizedBaseUrl,
+  tenantId,
+  sessionFile,
+  sessionCookie = "",
+  mergedEnv = {},
+  runtimeEnv = process.env,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  runWalletCliImpl = runWalletCli
+} = {}) {
+  const summary = {
+    enabled: Boolean(enabled),
+    ran: false,
+    walletFund: null,
+    walletBalanceWatch: null,
+    firstPaidCall: null,
+    warnings: []
+  };
+  if (!summary.enabled) return summary;
+  if (!stdin?.isTTY || !stdout?.isTTY) {
+    summary.warnings.push("guided quick flow skipped (non-interactive terminal)");
+    return summary;
+  }
+
+  const actionEnv = {
+    ...runtimeEnv,
+    ...mergedEnv,
+    SETTLD_BASE_URL: normalizedBaseUrl,
+    SETTLD_TENANT_ID: tenantId,
+    ...(sessionCookie ? { SETTLD_SESSION_COOKIE: sessionCookie } : {})
+  };
+  summary.ran = true;
+
+  if (walletMode !== "none") {
+    try {
+      const fundResult = await runWalletCliImpl({
+        argv: ["fund", "--open", "--base-url", normalizedBaseUrl, "--tenant-id", tenantId, "--session-file", sessionFile, "--format", "json"],
+        env: actionEnv,
+        stdin,
+        stdout
+      });
+      summary.walletFund = {
+        ok: true,
+        method: String(fundResult?.method ?? "").trim() || null
+      };
+    } catch (err) {
+      summary.walletFund = {
+        ok: false,
+        error: err?.message ?? String(err ?? "")
+      };
+      summary.warnings.push("wallet funding did not complete during guided flow");
+    }
+
+    try {
+      const watchResult = await runWalletCliImpl({
+        argv: [
+          "balance",
+          "--watch",
+          "--min-usdc",
+          "1",
+          "--timeout-seconds",
+          "300",
+          "--interval-seconds",
+          "5",
+          "--base-url",
+          normalizedBaseUrl,
+          "--tenant-id",
+          tenantId,
+          "--session-file",
+          sessionFile,
+          "--format",
+          "json"
+        ],
+        env: actionEnv,
+        stdin,
+        stdout
+      });
+      summary.walletBalanceWatch = {
+        ok: Boolean(watchResult?.ok),
+        satisfied: Boolean(watchResult?.watch?.satisfied)
+      };
+    } catch (err) {
+      summary.walletBalanceWatch = {
+        ok: false,
+        error: err?.message ?? String(err ?? "")
+      };
+      summary.warnings.push("wallet balance watch did not reach target within timeout");
+    }
+  }
+
+  const paidProbe = runMcpPaidCallProbe({ env: actionEnv });
+  if (paidProbe.ok) {
+    summary.firstPaidCall = { ok: true };
+  } else {
+    summary.firstPaidCall = {
+      ok: false,
+      exitCode: paidProbe.exitCode,
+      error: paidProbe.stderr || "paid call returned tool error"
+    };
+    summary.warnings.push("first paid call probe failed");
+  }
+
+  return summary;
+}
+
 function resolveByoWalletEnv({ walletProvider, walletEnvRows, runtimeEnv }) {
   const env = {};
   for (const row of walletEnvRows ?? []) env[row.key] = row.value;
@@ -1028,16 +1195,21 @@ async function resolveRuntimeConfig({
   runtimeEnv,
   stdin = process.stdin,
   stdout = process.stdout,
-  detectInstalledHostsImpl = detectInstalledHosts
+  detectInstalledHostsImpl = detectInstalledHosts,
+  fetchImpl = fetch,
+  runLoginImpl = runLogin,
+  readSavedSessionImpl = readSavedSession
 }) {
   const sessionFile = String(args.sessionFile ?? runtimeEnv.SETTLD_SESSION_FILE ?? defaultSessionPath()).trim();
-  const savedSession = await readSavedSession({ sessionPath: sessionFile });
+  const savedSession = await readSavedSessionImpl({ sessionPath: sessionFile });
   const installedHosts = detectInstalledHostsImpl();
   const defaultHost = selectDefaultHost({
     explicitHost: args.host ? String(args.host).toLowerCase() : "",
     installedHosts
   });
   const out = {
+    setupMode: args.setupMode ?? "quick",
+    guidedNext: args.guidedNext,
     host: args.host ?? defaultHost,
     walletMode: args.walletMode,
     baseUrl: String(args.baseUrl ?? runtimeEnv.SETTLD_BASE_URL ?? "").trim(),
@@ -1071,6 +1243,9 @@ async function resolveRuntimeConfig({
   }
 
   if (args.nonInteractive) {
+    if (!out.setupMode) out.setupMode = "quick";
+    if (!SETUP_MODES.has(out.setupMode)) throw new Error("--quick or --advanced are the supported setup modes");
+    if (out.guidedNext === null || out.guidedNext === undefined) out.guidedNext = false;
     if (!SUPPORTED_HOSTS.includes(out.host)) throw new Error(`--host must be one of: ${SUPPORTED_HOSTS.join(", ")}`);
     if (!out.baseUrl) throw new Error("--base-url is required");
     if (!out.tenantId) throw new Error("--tenant-id is required");
@@ -1105,6 +1280,24 @@ async function resolveRuntimeConfig({
     }
     stdout.write("\n");
 
+    if (!out.setupMode || !SETUP_MODES.has(out.setupMode)) {
+      out.setupMode = "quick";
+    }
+    out.setupMode = await promptSelect(
+      rl,
+      stdin,
+      stdout,
+      "Setup mode",
+      [
+        { value: "quick", label: "quick", hint: "Recommended: minimal prompts and guided next steps" },
+        { value: "advanced", label: "advanced", hint: "Full control over all setup options" }
+      ],
+      { defaultValue: out.setupMode, color }
+    );
+    if (out.guidedNext === null || out.guidedNext === undefined) {
+      out.guidedNext = out.setupMode === "quick";
+    }
+
     const hostPromptDefault = out.host && SUPPORTED_HOSTS.includes(out.host) ? out.host : defaultHost;
     const hostOptions = SUPPORTED_HOSTS.map((host) => ({
       value: host,
@@ -1133,68 +1326,105 @@ async function resolveRuntimeConfig({
       { defaultValue: out.walletMode, color }
     );
 
-    if (!out.baseUrl) {
-      out.baseUrl = await promptLine(rl, "Settld base URL", { defaultValue: "https://api.settld.work" });
-    }
-    if (!out.tenantId) {
-      out.tenantId = await promptLine(rl, "Tenant ID", { defaultValue: "tenant_default" });
-    }
+    if (!out.baseUrl) out.baseUrl = DEFAULT_PUBLIC_BASE_URL;
     if (!out.settldApiKey) {
-      const canUseSavedSession =
-        Boolean(out.sessionCookie) &&
-        (!savedSession ||
-          (normalizeHttpUrl(out.baseUrl) === normalizeHttpUrl(savedSession?.baseUrl) &&
-            String(out.tenantId ?? "").trim() === String(savedSession?.tenantId ?? "").trim()));
-      const keyOptions = [];
-      if (canUseSavedSession) {
-        keyOptions.push({
-          value: "session",
-          label: "Use saved login session",
-          hint: `Reuse ${out.sessionFile} to mint runtime key`
-        });
-      }
-      keyOptions.push(
-        { value: "bootstrap", label: "Generate during setup", hint: "Use onboarding bootstrap API key" },
-        { value: "manual", label: "Paste existing key", hint: "Use an existing tenant API key" }
-      );
-      const keyMode = await promptSelect(
-        rl,
-        stdin,
-        stdout,
-        "How should setup get your Settld API key?",
-        keyOptions,
-        { defaultValue: canUseSavedSession ? "session" : "bootstrap", color }
-      );
-      if (keyMode === "bootstrap") {
-        if (!out.bootstrapApiKey) {
-          out.bootstrapApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Onboarding bootstrap API key");
+      while (!out.settldApiKey) {
+        const canUseSavedSession =
+          Boolean(out.sessionCookie) &&
+          (!savedSession ||
+            (normalizeHttpUrl(out.baseUrl) === normalizeHttpUrl(savedSession?.baseUrl) &&
+              (!out.tenantId || String(out.tenantId ?? "").trim() === String(savedSession?.tenantId ?? "").trim())));
+        const keyOptions = [];
+        if (canUseSavedSession) {
+          keyOptions.push({
+            value: "session",
+            label: "Use saved login session",
+            hint: `Reuse ${out.sessionFile} to mint runtime key`
+          });
+        } else {
+          keyOptions.push({
+            value: "login",
+            label: "Login / create tenant (recommended)",
+            hint: "OTP sign-in; no API key required"
+          });
         }
-        if (!out.bootstrapKeyId) {
-          out.bootstrapKeyId = await promptLine(rl, "Generated key ID (optional)", { required: false });
+        keyOptions.push(
+          { value: "bootstrap", label: "Generate during setup", hint: "Use onboarding bootstrap API key" },
+          { value: "manual", label: "Paste existing key", hint: "Use an existing tenant API key" }
+        );
+        const keyMode = await promptSelect(
+          rl,
+          stdin,
+          stdout,
+          "How should setup get your Settld API key?",
+          keyOptions,
+          { defaultValue: canUseSavedSession ? "session" : "login", color }
+        );
+        if (keyMode === "login") {
+          try {
+            await runLoginImpl({
+              argv: ["--base-url", out.baseUrl, "--session-file", out.sessionFile],
+              stdin,
+              stdout,
+              fetchImpl
+            });
+            const refreshedSession = await readSavedSessionImpl({ sessionPath: out.sessionFile });
+            if (!refreshedSession) throw new Error("login did not produce a saved session");
+            out.baseUrl = String(refreshedSession.baseUrl ?? out.baseUrl).trim() || out.baseUrl;
+            out.tenantId = String(refreshedSession.tenantId ?? out.tenantId).trim();
+            out.sessionCookie = String(refreshedSession.cookie ?? out.sessionCookie).trim();
+            if (savedSession) {
+              savedSession.baseUrl = refreshedSession.baseUrl;
+              savedSession.tenantId = refreshedSession.tenantId;
+              savedSession.cookie = refreshedSession.cookie;
+            }
+          } catch (err) {
+            stdout.write(`Login failed: ${err?.message ?? "unknown error"}\n`);
+            stdout.write("Choose `Generate during setup` if your deployment does not expose public signup/login.\n");
+          }
+          continue;
         }
-        if (!out.bootstrapScopes) {
-          out.bootstrapScopes = await promptLine(rl, "Generated key scopes CSV (optional)", { required: false });
+        if (keyMode === "bootstrap") {
+          if (!out.bootstrapApiKey) {
+            out.bootstrapApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Onboarding bootstrap API key");
+          }
+          if (!out.bootstrapKeyId) {
+            out.bootstrapKeyId = await promptLine(rl, "Generated key ID (optional)", { required: false });
+          }
+          if (!out.bootstrapScopes) {
+            out.bootstrapScopes = await promptLine(rl, "Generated key scopes CSV (optional)", { required: false });
+          }
+          break;
+        }
+        if (keyMode === "manual") {
+          out.settldApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Settld API key");
+          break;
         }
-      } else if (keyMode === "manual") {
-        out.settldApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Settld API key");
-      } else {
         out.bootstrapApiKey = "";
+        break;
       }
     }
+    if (!out.tenantId) {
+      out.tenantId = await promptLine(rl, "Tenant ID", { defaultValue: "tenant_default" });
+    }
 
     if (out.walletMode === "managed") {
-      out.walletBootstrap = await promptSelect(
-        rl,
-        stdin,
-        stdout,
-        "Managed wallet bootstrap",
-        [
-          { value: "auto", label: "auto", hint: "Use local Circle key when present, else remote bootstrap" },
-          { value: "local", label: "local", hint: "Always use local Circle API key flow" },
-          { value: "remote", label: "remote", hint: "Always use tenant onboarding endpoint" }
-        ],
-        { defaultValue: out.walletBootstrap || "auto", color }
-      );
+      if (out.setupMode === "quick") {
+        out.walletBootstrap = out.walletBootstrap || "auto";
+      } else {
+        out.walletBootstrap = await promptSelect(
+          rl,
+          stdin,
+          stdout,
+          "Managed wallet bootstrap",
+          [
+            { value: "auto", label: "auto", hint: "Use local Circle key when present, else remote bootstrap" },
+            { value: "local", label: "local", hint: "Always use local Circle API key flow" },
+            { value: "remote", label: "remote", hint: "Always use tenant onboarding endpoint" }
+          ],
+          { defaultValue: out.walletBootstrap || "auto", color }
+        );
+      }
       if (out.walletBootstrap === "local" && !out.circleApiKey) {
         out.circleApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Circle API key");
       }
@@ -1220,6 +1450,9 @@ async function resolveRuntimeConfig({
       out.smoke = false;
       out.skipProfileApply = true;
       out.dryRun = true;
+      out.guidedNext = false;
+    } else if (out.setupMode === "quick") {
+      out.profileId = out.profileId || "engineering-spend";
     } else {
       out.preflight = await promptBooleanChoice(
         rl,
@@ -1296,7 +1529,10 @@ export async function runOnboard({
   requestRuntimeBootstrapMcpEnvImpl = requestRuntimeBootstrapMcpEnv,
   requestRemoteWalletBootstrapImpl = requestRemoteWalletBootstrap,
   runPreflightChecksImpl = runPreflightChecks,
-  detectInstalledHostsImpl = detectInstalledHosts
+  detectInstalledHostsImpl = detectInstalledHosts,
+  runLoginImpl = runLogin,
+  readSavedSessionImpl = readSavedSession,
+  runWalletCliImpl = runWalletCli
 } = {}) {
   const args = parseArgs(argv);
   if (args.help) {
@@ -1305,7 +1541,7 @@ export async function runOnboard({
   }
 
   const showSteps = args.format !== "json";
-  const totalSteps = args.preflightOnly ? 4 : 5;
+  const totalSteps = args.preflightOnly ? 4 : 6;
   let step = 1;
 
   if (showSteps) printStep(stdout, step, totalSteps, "Resolve setup configuration");
@@ -1314,7 +1550,10 @@ export async function runOnboard({
     runtimeEnv,
     stdin,
     stdout,
-    detectInstalledHostsImpl
+    detectInstalledHostsImpl,
+    fetchImpl,
+    runLoginImpl,
+    readSavedSessionImpl
   });
   step += 1;
   const normalizedBaseUrl = normalizeHttpUrl(mustString(config.baseUrl, "SETTLD_BASE_URL / --base-url"));
@@ -1512,9 +1751,27 @@ export async function runOnboard({
     await fs.writeFile(args.outEnv, toEnvFileText(mergedEnv), "utf8");
   }
 
+  if (showSteps) printStep(stdout, step, totalSteps, "Guided next steps");
+  const guided = await runGuidedQuickFlow({
+    enabled: Boolean(config.setupMode === "quick" && config.guidedNext),
+    walletMode: config.walletMode,
+    normalizedBaseUrl,
+    tenantId,
+    sessionFile: config.sessionFile,
+    sessionCookie: config.sessionCookie,
+    mergedEnv,
+    runtimeEnv,
+    stdin,
+    stdout,
+    runWalletCliImpl
+  });
+  step += 1;
+
   if (showSteps) printStep(stdout, step, totalSteps, "Finalize output");
   const payload = {
     ok: true,
+    setupMode: config.setupMode,
+    guided,
     host: config.host,
     wallet: {
       mode: config.walletMode,
@@ -1546,6 +1803,7 @@ export async function runOnboard({
     lines.push("Settld onboard complete.");
     lines.push(`Host: ${config.host}`);
     lines.push(`Settld: ${normalizedBaseUrl} (tenant=${tenantId})`);
+    lines.push(`Setup mode: ${config.setupMode}`);
     lines.push(`Preflight: ${config.preflight ? "passed" : "skipped"}`);
     lines.push(`Wallet mode: ${config.walletMode}`);
     lines.push(`Wallet bootstrap mode: ${walletBootstrapMode}`);
@@ -1553,6 +1811,18 @@ export async function runOnboard({
     if (wallet?.wallets?.escrow?.walletId) lines.push(`Escrow wallet: ${wallet.wallets.escrow.walletId}`);
     if (wallet?.tokenIdUsdc) lines.push(`USDC token id: ${wallet.tokenIdUsdc}`);
     if (args.outEnv) lines.push(`Wrote env file: ${args.outEnv}`);
+    if (guided?.enabled) {
+      lines.push("");
+      lines.push("Guided quick flow:");
+      if (guided.ran) {
+        lines.push(`- wallet fund: ${guided.walletFund?.ok ? "ok" : "not completed"}`);
+        lines.push(`- wallet balance watch: ${guided.walletBalanceWatch?.ok ? "ok" : "not completed"}`);
+        lines.push(`- first paid call: ${guided.firstPaidCall?.ok ? "ok" : "failed"}`);
+      } else {
+        lines.push("- skipped");
+      }
+      for (const warning of guided.warnings ?? []) lines.push(`- warning: ${warning}`);
+    }
     lines.push("");
     lines.push("Combined exports:");
     lines.push(toExportText(mergedEnv));