settld 0.2.0 → 0.2.2

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") {
@@ -1216,6 +1453,12 @@ export async function runOnboard({
       lines.push(`Settld: ${normalizedBaseUrl} (tenant=${tenantId})`);
       lines.push(`Wallet mode: ${config.walletMode}`);
       lines.push(`Wallet bootstrap mode: ${walletBootstrapMode}`);
+      if (config.walletMode !== "none") {
+        lines.push("Wallet next steps:");
+        lines.push("- settld wallet status");
+        lines.push("- settld wallet fund --method transfer");
+        lines.push("- settld wallet balance --watch --min-usdc 1");
+      }
       if (args.outEnv) lines.push(`Wrote env file: ${args.outEnv}`);
       if (args.reportPath) lines.push(`Wrote report: ${args.reportPath}`);
       lines.push("");
@@ -1251,11 +1494,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 : {})
   };
@@ -1316,6 +1563,14 @@ export async function runOnboard({
       lines.push(`${step}. ${row}`);
       step += 1;
     }
+    if (config.walletMode !== "none") {
+      lines.push(`${step}. Run \`settld wallet status\` to confirm wallet wiring.`);
+      step += 1;
+      lines.push(`${step}. Fund with \`settld wallet fund --method transfer\` (or \`--method card --open\` if hosted links are configured).`);
+      step += 1;
+      lines.push(`${step}. Confirm funds: \`settld wallet balance --watch --min-usdc 1\`.`);
+      step += 1;
+    }
     lines.push(`${step}. Run \`npm run mcp:probe\` for an immediate health check.`);
     stdout.write(`${lines.join("\n")}\n`);
   }

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/build-mkdocs.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-if [ ! -x ".vercel-venv/bin/mkdocs" ]; then
-  echo "MkDocs venv not found; running install step first..."
+if ! python3 -m mkdocs --version >/dev/null 2>&1; then
+  echo "MkDocs not found; running install step first..."
   bash scripts/vercel/install-mkdocs.sh
 fi
 
-.vercel-venv/bin/mkdocs build --strict --config-file mkdocs.yml
+python3 -m mkdocs build --strict --config-file mkdocs.yml

package/scripts/vercel/ignore-dashboard.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Vercel "ignoreCommand" contract:
+# - exit 0 => skip deployment
+# - exit 1 => continue with deployment
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+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/ \

package/scripts/vercel/install-mkdocs.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-python3 -m venv .vercel-venv
-.vercel-venv/bin/python -m pip install --upgrade pip setuptools wheel
-.vercel-venv/bin/pip install mkdocs mkdocs-material
+python3 -m pip install --break-system-packages --upgrade pip setuptools wheel
+python3 -m pip install --break-system-packages mkdocs mkdocs-material