settld 0.2.0 → 0.2.1

package/SETTLD_VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

package/bin/settld.js

@@ -9,6 +9,7 @@ function usage() {
   console.error("usage:");
   console.error("  settld --version");
   console.error("  settld onboard [--help]");
+  console.error("  settld login [--help]");
   console.error("  settld setup [--help]");
   console.error("  settld setup legacy [--help]");
   console.error("  settld setup circle [--help]");
@@ -138,6 +139,10 @@ function main() {
     return runNodeScript("scripts/setup/onboard.mjs", argv.slice(1));
   }
 
+  if (cmd === "login") {
+    return runNodeScript("scripts/setup/login.mjs", argv.slice(1));
+  }
+
   if (cmd === "doctor") {
     return runNodeScript("scripts/doctor/mcp-host.mjs", argv.slice(1));
   }

package/docs/QUICKSTART_MCP_HOSTS.md

@@ -17,7 +17,9 @@ Required inputs:
 
 - `SETTLD_BASE_URL` (local or hosted API URL)
 - `SETTLD_TENANT_ID`
-- `SETTLD_API_KEY` (`keyId.secret`)
+- 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+
 
 Recommended non-interactive pattern:
@@ -35,6 +37,20 @@ settld setup --non-interactive \
   --out-env ./.tmp/settld-openclaw.env
 ```
 
+If you want setup to generate the tenant API key for you:
+
+```bash
+settld setup --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --bootstrap-api-key 'ml_admin_xxx' \
+  --wallet-mode managed \
+  --wallet-bootstrap remote \
+  --profile-id engineering-spend \
+  --smoke
+```
+
 If you want validation only (no config writes):
 
 ```bash

package/docs/integrations/openclaw/PUBLIC_QUICKSTART.md

@@ -53,6 +53,19 @@ npx -y settld@latest setup \
   --smoke
 ```
 
+If you do not have a tenant `sk_*` yet, let setup mint one:
+
+```bash
+npx -y settld@latest setup \
+  --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --bootstrap-api-key 'ml_admin_xxx' \
+  --wallet-mode managed \
+  --wallet-bootstrap remote
+```
+
 ## 3) Verify OpenClaw + Settld are wired
 
 Run:

package/docs/ops/VERCEL_MONOREPO_DEPLOY.md

@@ -0,0 +1,42 @@
+# Vercel Monorepo Deploy (Docs + Website)
+
+Use **two separate Vercel projects** pointing at the same GitHub repo:
+
+1. `settld-docs` (MkDocs)
+2. `settld-site` (Dashboard website)
+
+## Project 1: `settld-docs` (MkDocs)
+
+- Root Directory: repo root (`.`)
+- Production Branch: `main`
+- Build/Output config comes from `/vercel.json`:
+  - `installCommand`: `bash scripts/vercel/install-mkdocs.sh`
+  - `buildCommand`: `bash scripts/vercel/build-mkdocs.sh`
+  - `ignoreCommand`: `bash scripts/vercel/ignore-mkdocs.sh`
+  - `outputDirectory`: `mkdocs/site`
+
+Deploy will run when docs-relevant files change (including `mkdocs/docs/**`).
+
+## Project 2: `settld-site` (Website)
+
+- Root Directory: `dashboard`
+- Production Branch: `main`
+- Build/Output config comes from `/dashboard/vercel.json`:
+  - `installCommand`: `npm install`
+  - `buildCommand`: `npm run build`
+  - `ignoreCommand`: `bash ../scripts/vercel/ignore-dashboard.sh`
+  - `outputDirectory`: `dist`
+
+Deploy will run when website-relevant files change (`dashboard/**` + deploy scripts/workflows).
+
+## Push Flow
+
+1. Commit and push changes to `main`.
+2. Verify both Vercel projects are connected to this repo and track `main`.
+3. Check the commit SHA in each Vercel deployment detail page matches the pushed commit.
+
+## Quick Troubleshooting
+
+- Docs didn’t deploy: confirm changes touched `mkdocs/docs/**` or another path matched by `scripts/vercel/ignore-mkdocs.sh`.
+- Website didn’t deploy: confirm changes touched `dashboard/**` or another path matched by `scripts/vercel/ignore-dashboard.sh`.
+- Wrong commit deployed: confirm Vercel project production branch is `main`, not a feature branch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "settld",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",

package/scripts/setup/login.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+import { cookieHeaderFromSetCookie, defaultSessionPath, writeSavedSession } from "./session-store.mjs";
+
+const FORMAT_OPTIONS = new Set(["text", "json"]);
+
+function usage() {
+  const text = [
+    "usage:",
+    "  settld login [flags]",
+    "  node scripts/setup/login.mjs [flags]",
+    "",
+    "flags:",
+    "  --base-url <url>                Settld onboarding base URL (default: https://api.settld.work)",
+    "  --tenant-id <id>                Existing tenant ID (omit to create via public signup)",
+    "  --email <email>                 Login email",
+    "  --company <name>                Company name (required when --tenant-id omitted)",
+    "  --otp <code>                    OTP code (otherwise prompted)",
+    "  --non-interactive               Disable prompts; require explicit flags",
+    "  --session-file <path>           Session output path (default: ~/.settld/session.json)",
+    "  --format <text|json>            Output format (default: text)",
+    "  --help                          Show this help"
+  ].join("\n");
+  process.stderr.write(`${text}\n`);
+}
+
+function readArgValue(argv, index, rawArg) {
+  const arg = String(rawArg ?? "");
+  const eq = arg.indexOf("=");
+  if (eq >= 0) return { value: arg.slice(eq + 1), nextIndex: index };
+  return { value: String(argv[index + 1] ?? ""), nextIndex: index + 1 };
+}
+
+function parseArgs(argv) {
+  const out = {
+    baseUrl: "https://api.settld.work",
+    tenantId: "",
+    email: "",
+    company: "",
+    otp: "",
+    nonInteractive: false,
+    sessionFile: defaultSessionPath(),
+    format: "text",
+    help: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i] ?? "");
+    if (!arg) continue;
+
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (arg === "--non-interactive" || arg === "--yes") {
+      out.nonInteractive = true;
+      continue;
+    }
+    if (arg === "--base-url" || arg.startsWith("--base-url=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.baseUrl = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--tenant-id" || arg.startsWith("--tenant-id=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.tenantId = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--email" || arg.startsWith("--email=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.email = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--company" || arg.startsWith("--company=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.company = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--otp" || arg.startsWith("--otp=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.otp = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--session-file" || arg.startsWith("--session-file=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.sessionFile = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--format" || arg.startsWith("--format=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.format = String(parsed.value ?? "").trim().toLowerCase();
+      i = parsed.nextIndex;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+
+  if (!FORMAT_OPTIONS.has(out.format)) throw new Error("--format must be text|json");
+  out.baseUrl = String(out.baseUrl ?? "").trim().replace(/\/+$/, "");
+  out.tenantId = String(out.tenantId ?? "").trim();
+  out.email = String(out.email ?? "").trim().toLowerCase();
+  out.company = String(out.company ?? "").trim();
+  out.otp = String(out.otp ?? "").trim();
+  out.sessionFile = path.resolve(process.cwd(), String(out.sessionFile ?? "").trim() || defaultSessionPath());
+  return out;
+}
+
+function mustHttpUrl(value, label) {
+  const raw = String(value ?? "").trim();
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${label} must be a valid URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${label} must use http/https`);
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+async function requestJson(url, { method, body, headers = {}, fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(url, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      ...headers
+    },
+    body: body === undefined ? undefined : JSON.stringify(body)
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  return { res, text, json };
+}
+
+async function promptLine(rl, label, { defaultValue = "", required = true } = {}) {
+  const suffix = defaultValue ? ` [${defaultValue}]` : "";
+  const value = String(await rl.question(`${label}${suffix}: `) ?? "").trim() || String(defaultValue ?? "").trim();
+  if (value || !required) return value;
+  throw new Error(`${label} is required`);
+}
+
+function printBanner(stdout = process.stdout) {
+  stdout.write("Settld login\n");
+  stdout.write("============\n");
+  stdout.write("Sign in with OTP and save local session for one-command setup.\n\n");
+}
+
+export async function runLogin({
+  argv = process.argv.slice(2),
+  stdin = process.stdin,
+  stdout = process.stdout,
+  fetchImpl = fetch,
+  writeSavedSessionImpl = writeSavedSession
+} = {}) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    usage();
+    return { ok: true, code: 0 };
+  }
+
+  const interactive = !args.nonInteractive;
+  const state = {
+    baseUrl: args.baseUrl,
+    tenantId: args.tenantId,
+    email: args.email,
+    company: args.company,
+    otp: args.otp,
+    sessionFile: args.sessionFile,
+    format: args.format
+  };
+
+  if (interactive) printBanner(stdout);
+  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 });
+      state.email = (await promptLine(rl, "Email", { defaultValue: state.email })).toLowerCase();
+      if (!state.tenantId) {
+        state.company = await promptLine(rl, "Company name", { defaultValue: state.company });
+      }
+    }
+
+    const baseUrl = mustHttpUrl(state.baseUrl, "base URL");
+    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");
+
+    let tenantId = state.tenantId;
+    if (!tenantId) {
+      const signup = await requestJson(`${baseUrl}/v1/public/signup`, {
+        method: "POST",
+        body: { email: state.email, company: state.company },
+        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;
+        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"}`);
+      }
+      tenantId = String(signup.json?.tenantId ?? "").trim();
+      if (!tenantId) throw new Error("public signup response missing tenantId");
+      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 (!state.otp && interactive) {
+      state.otp = await promptLine(rl, "OTP code", { required: true });
+    }
+    if (!state.otp) throw new Error("otp code is required (pass --otp in non-interactive mode)");
+
+    const login = await requestJson(`${baseUrl}/v1/tenants/${encodeURIComponent(tenantId)}/buyer/login`, {
+      method: "POST",
+      body: { email: state.email, code: state.otp },
+      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 setCookie = login.res.headers.get("set-cookie") ?? "";
+    const cookie = cookieHeaderFromSetCookie(setCookie);
+    if (!cookie) throw new Error("login response missing session cookie");
+
+    const session = await writeSavedSessionImpl({
+      sessionPath: state.sessionFile,
+      session: {
+        baseUrl,
+        tenantId,
+        email: state.email,
+        cookie,
+        expiresAt: typeof login.json?.expiresAt === "string" ? login.json.expiresAt : null
+      }
+    });
+
+    const payload = {
+      ok: true,
+      schemaVersion: "SettldLoginResult.v1",
+      baseUrl: session.baseUrl,
+      tenantId: session.tenantId,
+      email: session.email,
+      sessionFile: state.sessionFile,
+      expiresAt: session.expiresAt ?? null
+    };
+
+    if (state.format === "json") {
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      stdout.write(`Login saved.\n`);
+      stdout.write(`Tenant: ${session.tenantId}\n`);
+      stdout.write(`Session file: ${state.sessionFile}\n`);
+      stdout.write(`Next: run \`settld setup\`.\n`);
+    }
+    return payload;
+  } finally {
+    if (rl) rl.close();
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  try {
+    await runLogin({ argv });
+  } catch (err) {
+    process.stderr.write(`${err?.message ?? String(err)}\n`);
+    process.exit(1);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/scripts/setup/onboard.mjs

@@ -10,8 +10,9 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import { bootstrapWalletProvider } from "../../src/core/wallet-provider-bootstrap.js";
-import { loadHostConfigHelper, runWizard } from "./wizard.mjs";
+import { extractBootstrapMcpEnv, loadHostConfigHelper, runWizard } from "./wizard.mjs";
 import { SUPPORTED_HOSTS } from "./host-config.mjs";
+import { defaultSessionPath, readSavedSession } from "./session-store.mjs";
 
 const WALLET_MODES = new Set(["managed", "byo", "none"]);
 const WALLET_PROVIDERS = new Set(["circle"]);
@@ -37,6 +38,12 @@ 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 ANSI_RESET = "\u001b[0m";
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_DIM = "\u001b[2m";
+const ANSI_CYAN = "\u001b[36m";
+const ANSI_GREEN = "\u001b[32m";
+const ANSI_MAGENTA = "\u001b[35m";
 
 function usage() {
   const text = [
@@ -51,6 +58,11 @@ function usage() {
     "  --base-url <url>                Settld API base URL (or SETTLD_BASE_URL)",
     "  --tenant-id <id>                Settld tenant ID (or SETTLD_TENANT_ID)",
     "  --settld-api-key <key>          Settld tenant API key (or SETTLD_API_KEY)",
+    "  --bootstrap-api-key <key>       Onboarding bootstrap API key used to mint tenant API key",
+    "  --magic-link-api-key <key>      Alias for --bootstrap-api-key",
+    "  --session-file <path>           Saved login session path (default: ~/.settld/session.json)",
+    "  --bootstrap-key-id <id>         Optional API key ID hint for runtime bootstrap",
+    "  --bootstrap-scopes <csv>        Optional scopes for generated tenant API key",
     "  --wallet-mode <managed|byo|none> Wallet setup mode (default: managed)",
     "  --wallet-provider <name>        Wallet provider (circle; default: circle)",
     "  --wallet-bootstrap <auto|local|remote> Managed wallet setup path (default: auto)",
@@ -101,6 +113,10 @@ function parseArgs(argv) {
     baseUrl: null,
     tenantId: null,
     settldApiKey: null,
+    bootstrapApiKey: null,
+    sessionFile: defaultSessionPath(),
+    bootstrapKeyId: null,
+    bootstrapScopes: null,
     walletMode: "managed",
     walletProvider: "circle",
     walletBootstrap: "auto",
@@ -186,6 +202,35 @@ function parseArgs(argv) {
       i = parsed.nextIndex;
       continue;
     }
+    if (
+      arg === "--bootstrap-api-key" ||
+      arg === "--magic-link-api-key" ||
+      arg.startsWith("--bootstrap-api-key=") ||
+      arg.startsWith("--magic-link-api-key=")
+    ) {
+      const parsed = readArgValue(argv, i, arg);
+      out.bootstrapApiKey = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--session-file" || arg.startsWith("--session-file=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.sessionFile = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--bootstrap-key-id" || arg.startsWith("--bootstrap-key-id=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.bootstrapKeyId = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    if (arg === "--bootstrap-scopes" || arg.startsWith("--bootstrap-scopes=")) {
+      const parsed = readArgValue(argv, i, arg);
+      out.bootstrapScopes = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
     if (arg === "--wallet-mode" || arg.startsWith("--wallet-mode=")) {
       const parsed = readArgValue(argv, i, arg);
       out.walletMode = String(parsed.value ?? "").trim().toLowerCase();
@@ -272,6 +317,7 @@ function parseArgs(argv) {
   if (out.preflightOnly && out.preflight === false) {
     throw new Error("--preflight-only cannot be combined with --no-preflight");
   }
+  out.sessionFile = path.resolve(process.cwd(), String(out.sessionFile ?? "").trim() || defaultSessionPath());
   if (out.outEnv) out.outEnv = path.resolve(process.cwd(), out.outEnv);
   if (out.reportPath) out.reportPath = path.resolve(process.cwd(), out.reportPath);
   return out;
@@ -290,6 +336,19 @@ function normalizeHttpUrl(value) {
   return parsed.toString().replace(/\/+$/, "");
 }
 
+function supportsColor(output = process.stdout, env = process.env) {
+  if (!output?.isTTY) return false;
+  if (String(env.NO_COLOR ?? "").trim()) return false;
+  if (String(env.FORCE_COLOR ?? "").trim() === "0") return false;
+  return true;
+}
+
+function tint(enabled, code, value) {
+  const text = String(value ?? "");
+  if (!enabled) return text;
+  return `${code}${text}${ANSI_RESET}`;
+}
+
 function commandExists(command, { platform = process.platform } = {}) {
   const lookupCmd = platform === "win32" ? "where" : "which";
   const probe = spawnSync(lookupCmd, [command], { stdio: "ignore" });
@@ -582,7 +641,7 @@ async function promptSelect(
   stdout,
   label,
   options,
-  { defaultValue = null, hint = null } = {}
+  { defaultValue = null, hint = null, color = false } = {}
 ) {
   if (!Array.isArray(options) || options.length === 0) {
     throw new Error(`${label} requires at least one option`);
@@ -614,14 +673,14 @@ async function promptSelect(
 
   const render = () => {
     const lines = [];
-    lines.push(`${label} (arrow keys + Enter)`);
+    lines.push(tint(color, ANSI_CYAN, `${label} (arrow keys + Enter)`));
     for (let i = 0; i < normalizedOptions.length; i += 1) {
       const option = normalizedOptions[i];
-      const prefix = i === index ? ">" : " ";
+      const prefix = i === index ? tint(color, ANSI_GREEN, "●") : tint(color, ANSI_DIM, "○");
       const detail = option.hint ? ` - ${option.hint}` : "";
-      lines.push(`  ${prefix} ${option.label}${detail}`);
+      lines.push(`  ${prefix} ${i === index ? tint(color, ANSI_BOLD, option.label) : option.label}${tint(color, ANSI_DIM, detail)}`);
     }
-    if (hint) lines.push(`  ${hint}`);
+    if (hint) lines.push(`  ${tint(color, ANSI_DIM, hint)}`);
     if (renderedLines > 0) {
       stdout.write(`\u001b[${renderedLines}A`);
     }
@@ -648,7 +707,7 @@ async function promptSelect(
     const resolveWithSelection = () => {
       const selected = normalizedOptions[index];
       cleanup();
-      stdout.write(`\u001b[2K\r${label}: ${selected.label}\n`);
+      stdout.write(`\u001b[2K\r${tint(color, ANSI_CYAN, label)}: ${tint(color, ANSI_GREEN, selected.label)}\n`);
       resolve(selected.value);
     };
 
@@ -679,7 +738,14 @@ async function promptSelect(
   });
 }
 
-async function promptBooleanChoice(rl, stdin, stdout, label, defaultValue, { trueLabel = "Yes", falseLabel = "No", hint = null } = {}) {
+async function promptBooleanChoice(
+  rl,
+  stdin,
+  stdout,
+  label,
+  defaultValue,
+  { trueLabel = "Yes", falseLabel = "No", hint = null, color = false } = {}
+) {
   const selected = await promptSelect(
     rl,
     stdin,
@@ -689,7 +755,7 @@ async function promptBooleanChoice(rl, stdin, stdout, label, defaultValue, { tru
       { value: "yes", label: trueLabel },
       { value: "no", label: falseLabel }
     ],
-    { defaultValue: defaultValue ? "yes" : "no", hint }
+    { defaultValue: defaultValue ? "yes" : "no", hint, color }
   );
   return selected === "yes";
 }
@@ -824,6 +890,81 @@ function resolveByoWalletEnv({ walletProvider, walletEnvRows, runtimeEnv }) {
   return env;
 }
 
+function parseScopes(raw) {
+  if (!raw || !String(raw).trim()) return [];
+  const seen = new Set();
+  const out = [];
+  for (const part of String(raw).split(",")) {
+    const scope = String(part ?? "").trim();
+    if (!scope || seen.has(scope)) continue;
+    seen.add(scope);
+    out.push(scope);
+  }
+  return out;
+}
+
+async function requestRuntimeBootstrapMcpEnv({
+  baseUrl,
+  tenantId,
+  bootstrapApiKey,
+  sessionCookie,
+  bootstrapKeyId = null,
+  bootstrapScopes = [],
+  idempotencyKey = null,
+  fetchImpl = fetch
+} = {}) {
+  const normalizedBaseUrl = normalizeHttpUrl(baseUrl);
+  if (!normalizedBaseUrl) throw new Error(`invalid runtime bootstrap base URL: ${baseUrl}`);
+  const apiKey = String(bootstrapApiKey ?? "").trim();
+  const cookie = String(sessionCookie ?? "").trim();
+  if (!apiKey && !cookie) {
+    throw new Error("runtime bootstrap requires bootstrap API key or saved login session");
+  }
+
+  const headers = {
+    "content-type": "application/json"
+  };
+  if (apiKey) headers["x-api-key"] = apiKey;
+  if (cookie) headers.cookie = cookie;
+  if (idempotencyKey) headers["x-idempotency-key"] = String(idempotencyKey);
+
+  const body = {
+    apiKey: {
+      create: true,
+      description: "settld setup runtime bootstrap"
+    }
+  };
+  if (bootstrapKeyId) body.apiKey.keyId = String(bootstrapKeyId);
+  if (Array.isArray(bootstrapScopes) && bootstrapScopes.length > 0) {
+    body.apiKey.scopes = bootstrapScopes;
+  }
+
+  const url = new URL(
+    `/v1/tenants/${encodeURIComponent(String(tenantId ?? ""))}/onboarding/runtime-bootstrap`,
+    normalizedBaseUrl
+  );
+  const res = await fetchImpl(url.toString(), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  if (!res.ok) {
+    const message =
+      json && typeof json === "object"
+        ? json?.message ?? json?.error ?? `HTTP ${res.status}`
+        : text || `HTTP ${res.status}`;
+    throw new Error(`runtime bootstrap request failed (${res.status}): ${String(message)}`);
+  }
+  return extractBootstrapMcpEnv(json);
+}
+
 async function requestRemoteWalletBootstrap({
   baseUrl,
   tenantId,
@@ -889,6 +1030,8 @@ async function resolveRuntimeConfig({
   stdout = process.stdout,
   detectInstalledHostsImpl = detectInstalledHosts
 }) {
+  const sessionFile = String(args.sessionFile ?? runtimeEnv.SETTLD_SESSION_FILE ?? defaultSessionPath()).trim();
+  const savedSession = await readSavedSession({ sessionPath: sessionFile });
   const installedHosts = detectInstalledHostsImpl();
   const defaultHost = selectDefaultHost({
     explicitHost: args.host ? String(args.host).toLowerCase() : "",
@@ -900,6 +1043,13 @@ async function resolveRuntimeConfig({
     baseUrl: String(args.baseUrl ?? runtimeEnv.SETTLD_BASE_URL ?? "").trim(),
     tenantId: String(args.tenantId ?? runtimeEnv.SETTLD_TENANT_ID ?? "").trim(),
     settldApiKey: String(args.settldApiKey ?? runtimeEnv.SETTLD_API_KEY ?? "").trim(),
+    bootstrapApiKey: String(
+      args.bootstrapApiKey ?? runtimeEnv.SETTLD_BOOTSTRAP_API_KEY ?? runtimeEnv.MAGIC_LINK_API_KEY ?? ""
+    ).trim(),
+    sessionFile,
+    sessionCookie: String(runtimeEnv.SETTLD_SESSION_COOKIE ?? "").trim(),
+    bootstrapKeyId: String(args.bootstrapKeyId ?? runtimeEnv.SETTLD_BOOTSTRAP_KEY_ID ?? "").trim(),
+    bootstrapScopes: String(args.bootstrapScopes ?? runtimeEnv.SETTLD_BOOTSTRAP_SCOPES ?? "").trim(),
     walletProvider: args.walletProvider,
     walletBootstrap: args.walletBootstrap,
     circleApiKey: String(args.circleApiKey ?? runtimeEnv.CIRCLE_API_KEY ?? "").trim(),
@@ -914,12 +1064,19 @@ async function resolveRuntimeConfig({
     dryRun: Boolean(args.dryRun),
     installedHosts
   };
+  if (savedSession) {
+    if (!out.baseUrl) out.baseUrl = String(savedSession.baseUrl ?? "").trim();
+    if (!out.tenantId) out.tenantId = String(savedSession.tenantId ?? "").trim();
+    if (!out.sessionCookie) out.sessionCookie = String(savedSession.cookie ?? "").trim();
+  }
 
   if (args.nonInteractive) {
     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");
-    if (!out.settldApiKey) throw new Error("--settld-api-key is required");
+    if (!out.settldApiKey && !out.bootstrapApiKey && !out.sessionCookie) {
+      throw new Error("--settld-api-key, --bootstrap-api-key, or saved login session is required");
+    }
     if (out.walletMode === "managed" && out.walletBootstrap === "local" && !out.circleApiKey) {
       throw new Error("--circle-api-key is required for --wallet-mode managed --wallet-bootstrap local");
     }
@@ -929,15 +1086,22 @@ async function resolveRuntimeConfig({
   if (!stdin.isTTY || !stdout.isTTY) {
     throw new Error("interactive mode requires a TTY. Re-run with --non-interactive and explicit flags.");
   }
+  const color = supportsColor(stdout, runtimeEnv);
   const mutableOutput = createMutableOutput(stdout);
   const rl = createInterface({ input: stdin, output: mutableOutput });
   try {
-    stdout.write("Settld guided setup\n");
-    stdout.write("===================\n");
+    const title = tint(color, ANSI_BOLD, "Settld guided setup");
+    const subtitle = tint(color, ANSI_DIM, "Deterministic onboarding for trusted agent spend");
+    stdout.write(`${title}\n`);
+    stdout.write(`${tint(color, ANSI_MAGENTA, "===================")}\n`);
+    stdout.write(`${subtitle}\n`);
     if (installedHosts.length > 0) {
-      stdout.write(`Detected hosts: ${installedHosts.join(", ")}\n`);
+      stdout.write(`${tint(color, ANSI_CYAN, "Detected hosts")}: ${installedHosts.join(", ")}\n`);
     } else {
-      stdout.write("Detected hosts: none (will still write config files)\n");
+      stdout.write(`${tint(color, ANSI_CYAN, "Detected hosts")}: none (will still write config files)\n`);
+    }
+    if (savedSession?.tenantId) {
+      stdout.write(`${tint(color, ANSI_GREEN, "Saved login session")}: tenant ${savedSession.tenantId}\n`);
     }
     stdout.write("\n");
 
@@ -952,7 +1116,7 @@ async function resolveRuntimeConfig({
       stdout,
       "Select host",
       hostOptions,
-      { defaultValue: hostPromptDefault, hint: "Up/Down arrows change selection" }
+      { defaultValue: hostPromptDefault, hint: "Up/Down arrows change selection", color }
     );
 
     if (!out.walletMode) out.walletMode = "managed";
@@ -966,7 +1130,7 @@ async function resolveRuntimeConfig({
         { value: "byo", label: "byo", hint: "Use your existing wallet IDs and secrets" },
         { value: "none", label: "none", hint: "No payment rail wiring during setup" }
       ],
-      { defaultValue: out.walletMode }
+      { defaultValue: out.walletMode, color }
     );
 
     if (!out.baseUrl) {
@@ -975,7 +1139,48 @@ async function resolveRuntimeConfig({
     if (!out.tenantId) {
       out.tenantId = await promptLine(rl, "Tenant ID", { defaultValue: "tenant_default" });
     }
-    if (!out.settldApiKey) out.settldApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Settld API key");
+    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");
+        }
+        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 });
+        }
+      } else if (keyMode === "manual") {
+        out.settldApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Settld API key");
+      } else {
+        out.bootstrapApiKey = "";
+      }
+    }
 
     if (out.walletMode === "managed") {
       out.walletBootstrap = await promptSelect(
@@ -988,7 +1193,7 @@ async function resolveRuntimeConfig({
           { 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" }
+        { defaultValue: out.walletBootstrap || "auto", color }
       );
       if (out.walletBootstrap === "local" && !out.circleApiKey) {
         out.circleApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Circle API key");
@@ -1024,7 +1229,8 @@ async function resolveRuntimeConfig({
         out.preflight,
         {
           trueLabel: "Yes - validate API/auth/paths",
-          falseLabel: "No - skip preflight"
+          falseLabel: "No - skip preflight",
+          color
         }
       );
       out.smoke = await promptBooleanChoice(
@@ -1035,7 +1241,8 @@ async function resolveRuntimeConfig({
         out.smoke,
         {
           trueLabel: "Yes - run settld.about probe",
-          falseLabel: "No - skip smoke"
+          falseLabel: "No - skip smoke",
+          color
         }
       );
 
@@ -1047,7 +1254,8 @@ async function resolveRuntimeConfig({
         !out.skipProfileApply,
         {
           trueLabel: "Yes - apply profile now",
-          falseLabel: "No - skip profile apply"
+          falseLabel: "No - skip profile apply",
+          color
         }
       );
       out.skipProfileApply = !applyProfile;
@@ -1065,7 +1273,8 @@ async function resolveRuntimeConfig({
         out.dryRun,
         {
           trueLabel: "Yes - preview only",
-          falseLabel: "No - write config"
+          falseLabel: "No - write config",
+          color
         }
       );
     }
@@ -1084,6 +1293,7 @@ export async function runOnboard({
   runWizardImpl = runWizard,
   loadHostConfigHelperImpl = loadHostConfigHelper,
   bootstrapWalletProviderImpl = bootstrapWalletProvider,
+  requestRuntimeBootstrapMcpEnvImpl = requestRuntimeBootstrapMcpEnv,
   requestRemoteWalletBootstrapImpl = requestRemoteWalletBootstrap,
   runPreflightChecksImpl = runPreflightChecks,
   detectInstalledHostsImpl = detectInstalledHosts
@@ -1110,7 +1320,28 @@ export async function runOnboard({
   const normalizedBaseUrl = normalizeHttpUrl(mustString(config.baseUrl, "SETTLD_BASE_URL / --base-url"));
   if (!normalizedBaseUrl) throw new Error(`invalid Settld base URL: ${config.baseUrl}`);
   const tenantId = mustString(config.tenantId, "SETTLD_TENANT_ID / --tenant-id");
-  const settldApiKey = mustString(config.settldApiKey, "SETTLD_API_KEY / --settld-api-key");
+  let settldApiKey = String(config.settldApiKey ?? "").trim();
+  let runtimeBootstrapEnv = null;
+  if (!settldApiKey) {
+    if (showSteps) stdout.write("Generating tenant runtime API key via onboarding bootstrap/session...\n");
+    runtimeBootstrapEnv = await requestRuntimeBootstrapMcpEnvImpl({
+      baseUrl: normalizedBaseUrl,
+      tenantId,
+      bootstrapApiKey: config.bootstrapApiKey,
+      sessionCookie: config.sessionCookie,
+      bootstrapKeyId: config.bootstrapKeyId || null,
+      bootstrapScopes: parseScopes(config.bootstrapScopes),
+      fetchImpl
+    });
+    settldApiKey = mustString(runtimeBootstrapEnv?.SETTLD_API_KEY ?? "", "runtime bootstrap SETTLD_API_KEY");
+  }
+  const runtimeBootstrapOptionalEnv = {};
+  if (runtimeBootstrapEnv?.SETTLD_PAID_TOOLS_BASE_URL) {
+    runtimeBootstrapOptionalEnv.SETTLD_PAID_TOOLS_BASE_URL = String(runtimeBootstrapEnv.SETTLD_PAID_TOOLS_BASE_URL);
+  }
+  if (runtimeBootstrapEnv?.SETTLD_PAID_TOOLS_AGENT_PASSPORT) {
+    runtimeBootstrapOptionalEnv.SETTLD_PAID_TOOLS_AGENT_PASSPORT = String(runtimeBootstrapEnv.SETTLD_PAID_TOOLS_AGENT_PASSPORT);
+  }
 
   if (showSteps) printStep(stdout, step, totalSteps, "Resolve wallet configuration");
   let walletBootstrapMode = "none";
@@ -1198,13 +1429,19 @@ export async function runOnboard({
       preflight,
       hostInstallDetected: Array.isArray(config.installedHosts) && config.installedHosts.includes(config.host),
       installedHosts: config.installedHosts,
-      env: walletEnv,
+      env: {
+        SETTLD_BASE_URL: normalizedBaseUrl,
+        SETTLD_TENANT_ID: tenantId,
+        SETTLD_API_KEY: settldApiKey,
+        ...runtimeBootstrapOptionalEnv,
+        ...walletEnv
+      },
       outEnv: args.outEnv ?? null,
       reportPath: args.reportPath ?? null
     };
     if (args.outEnv) {
       await fs.mkdir(path.dirname(args.outEnv), { recursive: true });
-      await fs.writeFile(args.outEnv, toEnvFileText(walletEnv), "utf8");
+      await fs.writeFile(args.outEnv, toEnvFileText(payload.env), "utf8");
     }
     await writeJsonReport(args.reportPath, payload);
     if (args.format === "json") {
@@ -1251,11 +1488,15 @@ export async function runOnboard({
     argv: wizardArgv,
     fetchImpl,
     stdout,
-    extraEnv: walletEnv
+    extraEnv: {
+      ...runtimeBootstrapOptionalEnv,
+      ...walletEnv
+    }
   });
   step += 1;
 
   const mergedEnv = {
+    ...runtimeBootstrapOptionalEnv,
     ...(walletEnv ?? {}),
     ...(wizardResult?.env && typeof wizardResult.env === "object" ? wizardResult.env : {})
   };

package/scripts/setup/session-store.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const SESSION_SCHEMA_VERSION = "SettldCliSession.v1";
+
+function normalizeCookieHeader(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return null;
+  const firstSegment = raw.split(";")[0]?.trim() ?? "";
+  if (!firstSegment) return null;
+  const eq = firstSegment.indexOf("=");
+  if (eq <= 0) return null;
+  const name = firstSegment.slice(0, eq).trim();
+  const token = firstSegment.slice(eq + 1).trim();
+  if (!name || !token) return null;
+  return `${name}=${token}`;
+}
+
+export function defaultSessionPath({ homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, ".settld", "session.json");
+}
+
+export function normalizeSession(input) {
+  const row = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const baseUrl = typeof row.baseUrl === "string" ? row.baseUrl.trim().replace(/\/+$/, "") : "";
+  const tenantId = typeof row.tenantId === "string" ? row.tenantId.trim() : "";
+  const email = typeof row.email === "string" ? row.email.trim().toLowerCase() : "";
+  const cookie = normalizeCookieHeader(row.cookie);
+  if (!baseUrl || !tenantId || !cookie) return null;
+  const out = {
+    schemaVersion: SESSION_SCHEMA_VERSION,
+    savedAt: typeof row.savedAt === "string" && row.savedAt.trim() ? row.savedAt.trim() : new Date().toISOString(),
+    baseUrl,
+    tenantId,
+    cookie,
+    email: email || null
+  };
+  if (typeof row.expiresAt === "string" && row.expiresAt.trim()) out.expiresAt = row.expiresAt.trim();
+  return out;
+}
+
+export async function readSavedSession({ sessionPath = defaultSessionPath() } = {}) {
+  try {
+    const raw = await fs.readFile(sessionPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return normalizeSession(parsed);
+  } catch {
+    return null;
+  }
+}
+
+export async function writeSavedSession({ session, sessionPath = defaultSessionPath() } = {}) {
+  const normalized = normalizeSession(session);
+  if (!normalized) throw new Error("invalid session payload");
+  await fs.mkdir(path.dirname(sessionPath), { recursive: true });
+  await fs.writeFile(sessionPath, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  return normalized;
+}
+
+export function cookieHeaderFromSetCookie(value) {
+  return normalizeCookieHeader(value);
+}

package/scripts/vercel/ignore-dashboard.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Vercel "ignoreCommand" contract:
+# - exit 0 => skip deployment
+# - exit 1 => continue with deployment
+
+if ! git rev-parse --verify HEAD^ >/dev/null 2>&1; then
+  # No parent commit context available; build to stay safe.
+  exit 1
+fi
+
+if git diff --quiet HEAD^ HEAD -- \
+  dashboard/ \
+  scripts/vercel/ignore-dashboard.sh \
+  .github/workflows/release.yml \
+  .github/workflows/tests.yml; then
+  # No website changes; skip dashboard deployment.
+  exit 0
+fi
+
+# Relevant website/deploy files changed; run deployment.
+exit 1

package/scripts/vercel/ignore-mkdocs.sh

@@ -11,6 +11,8 @@ if ! git rev-parse --verify HEAD^ >/dev/null 2>&1; then
 fi
 
 if git diff --quiet HEAD^ HEAD -- \
+  mkdocs/docs/ \
+  mkdocs/ \
   docs/ \
   mkdocs.yml \
   scripts/vercel/ \