diff --git a/README.md b/README.md
index 28aa77c..1e7da10 100644
--- a/README.md
+++ b/README.md
@@ -38,41 +38,48 @@
 ```bash
 git clone https://github.com/2witstudios/pagespace-cli.git
 cd pagespace-cli
-npm install
+npm install          # resolves vendored pi workspaces in packages/
+npm run build        # required: builds workspace pi packages to dist/ (~3s)
 ```
 
-`npm install` resolves the vendored pi workspaces in this monorepo (`packages/pi-agent-core`, `packages/pi-ai`, `packages/pi-coding-agent`, `packages/pi-tui`). You do **not** need a global `@earendil-works/pi-coding-agent` install.
-
-Create local config (recommended):
-
-```bash
-cp .env.example .env.local
-# then edit .env.local and set at least PAGESPACE_AUTH_TOKEN
-```
+This repo vendors pi via npm workspaces (`packages/`), so you do **not** need a global pi install.
 
 Launch either way:
 
 ```bash
-npm link
+npm link             # optional: puts `pagespace` on your PATH
 pagespace
 
 # or without linking
 node bin/pagespace.mjs
 ```
 
-Run the doctor:
+### First run (Cursor-grade onboarding)
 
-```bash
-pagespace status
-```
+If no token is configured, `pagespace` now runs an interactive onboarding flow instead of exiting:
+
+- prompts you to paste a token
+- validates auth (`GET /api/drives`)
+- discovers accessible drives (preferred drive first)
+- discovers available AI_CHAT agent models across drives
+- defaults drive/model to the first discovered option
+- writes credentials + selection, then launches
+
+Materialized config on successful onboarding:
+
+- `~/.pagespace/credentials` (token, mode `0600`)
+- chosen default drive/model
+
+Happy path is now: **install → run → onboard → code**.
 
 ## Commands
 
 ```bash
-pagespace                    # start the harness
-pagespace status             # env + connectivity doctor
-pagespace sessions           # list conversations for PAGESPACE_MODEL_PAGE
-pagespace resume <id>        # resume by exact id or unique prefix
+pagespace              # start (runs onboarding on first run if no token)
+pagespace status       # config + auth doctor (credential store + structured ✓/✗)
+pagespace login        # capture/refresh token into ~/.pagespace/credentials (0600)
+pagespace sessions     # list synced conversations
+pagespace resume <id>  # resume a conversation
 ```
 
 In-session model switching:
@@ -82,56 +89,52 @@ In-session model switching:
 
 ## Configuration
 
-### Environment variables
+Token/config can come from several sources. Default UX is the credential store; override paths still work for those who need them.
+
+1. **Credential store (recommended):** `~/.pagespace/credentials` (mode `0600`). Written by first-run onboarding or `pagespace login`. Global across projects.
+2. **Project env files (optional override):** `.env.local` then `.env`, auto-loaded by the launcher.
+3. **`.mcp.json` (optional override, MCP workflows):** holds the token for MCP-server workflows (see `.mcp.json.example`). Not required for the harness itself — `pagespace` reads from the credential store / env, not `.mcp.json`.
+4. **Shell env (highest precedence):** exported env vars always win at runtime.
 
-By default, launcher/extension load `.env.local` then `.env` (shell env still wins). Configure with:
+Effective precedence is: **shell env > `.env.local`/`.env` > credential store**. (`.mcp.json` is consumed by MCP clients, not the launcher's token resolution.)
+
+### Environment variables
 
 | Variable | Required | Purpose |
 |---|---|---|
-| `PAGESPACE_AUTH_TOKEN` | **Yes** | Scoped PageSpace token for API access. |
+| `PAGESPACE_AUTH_TOKEN` | No | Scoped token. **Now optional** (recommended to set via `pagespace login` / onboarding). |
 | `PAGESPACE_API_URL` | No | PageSpace base URL. Default: `https://pagespace.ai`. |
-| `PAGESPACE_DRIVE` | No | Default drive slug used for mount + memory grounding order. |
+| `PAGESPACE_DRIVE` | No | Default drive slug for bare mount paths. |
 | `PAGESPACE_MOUNT` | No | Mount prefix in your cwd. Default: `pagespace`. |
-| `PAGESPACE_MODEL_PAGE` | No | Optional primary brain agent page id (pin first model). |
-| `PAGESPACE_MODEL_PAGES` | No | Optional comma-separated additional agent page ids. |
+| `PAGESPACE_MODEL_PAGE` | No | Optional primary model page pin. |
+| `PAGESPACE_MODEL_PAGES` | No | Optional comma-separated model page pins. |
 | `PAGESPACE_READONLY` | No | Optional comma-separated mounted prefixes to protect from write/edit (e.g. `Specs,Epics`). |
 
-### Auto-discovery first, pinning optional
+### Models: auto-discovery by default
 
-If `PAGESPACE_MODEL_PAGES` is not set, the extension auto-discovers model agents across all accessible drives and registers them under provider `pagespace`.
+If model pins are not set, `pagespace` auto-discovers AI_CHAT agent models across all drives accessible to your token (preferred drive first).
 
-Use `PAGESPACE_MODEL_PAGE` / `PAGESPACE_MODEL_PAGES` only when you want to pin or extend the model list explicitly.
+Use `PAGESPACE_MODEL_PAGE` / `PAGESPACE_MODEL_PAGES` only when you want explicit pinning.
 
-### `.env.local` vs `.mcp.json`
+### Security note
 
-These are separate configuration paths:
-
-- **`.env.local` / `.env`**: consumed directly by `pagespace` launcher + extension runtime.
-- **`.mcp.json`** (gitignored): MCP server config format (see `.mcp.json.example`) that can also hold the same token for MCP workflows.
-
-`pagespace status` will suggest `.mcp.json.example` when required env is missing, but runtime behavior is still based on process env.
+The launcher strips auth token env before spawning pi. That means the agent's `bash` tool cannot read your token via `env`, `printenv`, or `/proc/self/environ`. Provider auth reads from config/credential storage, not child process env.
 
 ## How it works
 
-### 1) Dual-mount files
-
-`extensions/pagespace.ts` replaces file tools with path-aware routers:
-
-- under mounted PageSpace path: operate on PageSpace pages via API
-- outside mount: use local filesystem tools
-- `grep` on mounted paths uses server-side regex search
-- `bash` remains local-only
+### 1) Dual-mount filesystem
 
-### 2) PageSpace as model brain
+- Paths under `pagespace/<drive>/...` route to PageSpace pages.
+- Everything outside that mount stays on your local filesystem.
+- `bash` always runs locally.
 
-`src/provider.ts` registers provider `pagespace` and calls:
+### 2) PageSpace brain
 
-- `POST /api/v1/chat/completions`
-- `model: ps-agent://<pageId>`
-- includes pi-native `tools`
-- `disable_server_tools: true`
+- Uses native function-calling via `POST /api/v1/chat/completions`.
+- Targets `model: ps-agent://<pageId>`.
+- Sends pi tools with `disable_server_tools: true`, keeping the tool loop in pi.
 
-The model streams native `tool_calls`; pi executes those tools locally and returns tool results in the next turn. No text tool shim.
+This keeps the two axes explicit: **PageSpace-backed mounted memory/files + local code execution**.
 
 ## Architecture (condensed)
 
diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 7350275..619d8ac 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -1,13 +1,41 @@
 #!/usr/bin/env node
 // Branded `pagespace` launcher. `pagespace status` runs a config/auth doctor; anything else starts
-// pi with this package's extension preloaded and passes args through. Mirrors src/cli.ts
-// (buildPiLaunchArgs/resolveExtensionPath/checkConfig — kept in TS for unit tests).
+// pi with this package's extension preloaded and passes args through.
+//
+// Runtime: re-exec under tsx so the bin can import the shared TS source (src/doctor.ts etc.) —
+// one implementation consumed by status, onboarding, and the unit tests (no mirroring). The preamble
+// below detects plain node and re-spawns under tsx transparently.
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+// Re-exec under tsx if running under plain node (so TS imports resolve on any Node version).
+// The parent spawns the child under tsx and exits; the child (PAGESPACE_UNDER_TSX=1) runs main().
+const isTsx = process.execArgv.some((a) => a.includes("tsx")) || !!process.env.PAGESPACE_UNDER_TSX;
+if (!isTsx) {
+  const bin = fileURLToPath(import.meta.url);
+  const tsxPath = path.join(path.dirname(bin), "..", "node_modules", ".bin", "tsx");
+  const child = spawn(process.execPath, [tsxPath, bin, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env: { ...process.env, PAGESPACE_UNDER_TSX: "1" },
+  });
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+} else {
+  // main() is called at the end of the file, after all declarations (avoids TDZ on consts).
+}
+// Shared pure modules — ONE implementation consumed by status + onboarding + login + tests.
+// No mirroring: every function below calls these, not a local copy.
+import { diagnose, formatDoctor } from "../src/doctor.ts";
+import { nextOnboardingStep, initialOnboardingState, onboardingNeedsSetup } from "../src/onboarding.ts";
+import { buildCredentialRecord, writeCredentials, readCredentials, credentialsPath } from "../src/credentials.ts";
+import { resolveDefaultDrive, resolveAuthToken } from "../src/config.ts";
+import { sanitizeChildEnv, SECRET_ENV_KEYS } from "../src/env.ts";
+
 // Resolve the pi CLI from the local workspace package rather than a global install.
 // Using a path-relative URL since dist/cli.js isn't in the package's exports map.
 const PI_CLI = fileURLToPath(
@@ -50,41 +78,60 @@ function loadDotenv(startDir = process.cwd()) {
 }
 loadDotenv();
 
-const CONFIG_KEYS = [
-  ["PAGESPACE_AUTH_TOKEN", true, "scoped MCP token (Bearer)"],
-  ["PAGESPACE_API_URL", false, "instance URL (default https://pagespace.ai)"],
-  ["PAGESPACE_DRIVE", false, "default drive slug (mount + memory)"],
-  ["PAGESPACE_MODEL_PAGE", false, "brain agent page id (ps-agent://<id>)"],
-  ["PAGESPACE_MODEL_PAGES", false, "comma-separated brain agent ids for /model toggling"],
-];
-
-async function statusDoctor() {
-  console.log("pagespace config:");
-  let missingRequired = false;
-  for (const [key, required, label] of CONFIG_KEYS) {
-    const set = !!(process.env[key] && process.env[key].trim());
-    if (!set && required) missingRequired = true;
-    console.log(`  ${set ? "✓" : required ? "✗" : "·"} ${key}${set ? "" : ` (unset — ${label})`}`);
-  }
-  if (missingRequired) {
-    console.log("  → copy .mcp.json.example to .mcp.json and set your token, or export the env vars.");
-    process.exit(1);
-  }
-  const url = (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, "");
-  const token = process.env.PAGESPACE_AUTH_TOKEN;
+// Load credentials from the store (~/.pagespace/credentials, 0600) if no token is set via env/.env.
+// The token enters the LAUNCHER's process.env here so loadConfig()/the provider can read it — but
+// launchPi() strips it before spawning pi (token isolation). So the agent never sees it.
+// Uses the shared readCredentials() from src/credentials.ts (enforces 0600, validates the record).
+(function loadCredentials() {
+  if (process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim()) return;
   try {
-    const res = await fetch(`${url}/api/drives`, { headers: { authorization: `Bearer ${token}` } });
-    if (!res.ok) {
-      console.log(`  ✗ auth ping ${url}: HTTP ${res.status} — check the token/permissions.`);
-      process.exit(1);
+    const rec = readCredentials();
+    if (rec) {
+      process.env.PAGESPACE_AUTH_TOKEN = rec.token;
+      if (!process.env.PAGESPACE_API_URL) process.env.PAGESPACE_API_URL = rec.apiUrl;
     }
-    const data = await res.json().catch(() => []);
-    const n = Array.isArray(data) ? data.length : Array.isArray(data?.drives) ? data.drives.length : "?";
-    console.log(`  ✓ reachable: ${url} — ${n} drive(s) visible to this token.`);
   } catch (err) {
-    console.log(`  ✗ cannot reach ${url}: ${err.message}`);
+    console.error(`pagespace: ${err.message}`);
     process.exit(1);
   }
+})();
+
+// Secret env keys stripped from the spawned pi process so pi's bash tool can never read them
+// (token isolation — the agent must never see the PageSpace auth token). Shared via src/env.ts.
+async function statusDoctor() {
+  // Reusable doctor (src/doctor.ts): gathers inputs, calls diagnose(), prints structured results.
+  // Non-interactive/CI-safe: never prompts; exit 1 on any failing check.
+  const apiUrl = (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, "");
+  const hasCredentials = fs.existsSync(credentialsPath());
+  const token = resolveAuthToken(process.env, () => {
+    try {
+      return readCredentials();
+    } catch {
+      return null;
+    }
+  });
+  const hasToken = !!(token && token.trim());
+
+  let reachable;
+  let driveCount;
+  if (hasToken) {
+    try {
+      const res = await fetch(`${apiUrl}/api/drives`, { headers: { authorization: `Bearer ${token}` } });
+      reachable = res.ok;
+      if (res.ok) {
+        const data = await res.json().catch(() => []);
+        driveCount = Array.isArray(data) ? data.length : Array.isArray(data?.drives) ? data.drives.length : 0;
+      }
+    } catch {
+      reachable = false;
+    }
+  }
+
+  // diagnose() + formatDoctor() are the shared pure doctor (src/doctor.ts) — same impl the unit
+  // tests and onboarding consume. No mirroring. Non-interactive/CI-safe: exit 1 on any failing check.
+  const result = diagnose({ apiUrl, hasToken, hasCredentials, reachable, driveCount });
+  console.log(formatDoctor(result));
+  if (!result.pass) process.exit(1);
 }
 
 // Launch pi with the extension preloaded + --no-skills (skills are registered as /name extension
@@ -119,9 +166,15 @@ function launchPi(passthrough) {
     passthrough.includes("--no-skills") || passthrough.includes("-ns") || passthrough.includes("--skill")
       ? []
       : ["--no-skills"];
+  // Spawn pi with a SANITIZED env: strip secret keys (PAGESPACE_AUTH_TOKEN) so pi's bash tool and
+  // any subprocess can NEVER read them via env/printenv/procfs. The provider reads the token from
+  // config (not the child env) — token isolation (security ADR: agent must never see the token).
+  const childEnv = sanitizeChildEnv(process.env);
+  childEnv.PI_SKIP_VERSION_CHECK = "1";
+  childEnv.PI_CODING_AGENT_DIR = PAGESPACE_AGENT_DIR;
   const child = spawn(process.execPath, [PI_CLI, "-e", extensionPath, ...noSkillsFlag, ...passthrough], {
     stdio: "inherit",
-    env: { ...process.env, PI_SKIP_VERSION_CHECK: "1", PI_CODING_AGENT_DIR: PAGESPACE_AGENT_DIR },
+    env: childEnv,
   });
   child.on("error", (err) => {
     console.error(`pagespace: failed to launch (${err.message}).`);
@@ -265,13 +318,143 @@ async function resumeCommand(ref, rest) {
   }
 }
 
-const sub = process.argv[2];
-if (sub === "status" || process.argv.includes("--check")) {
-  statusDoctor();
-} else if (sub === "sessions") {
-  sessionsCommand();
-} else if (sub === "resume") {
-  resumeCommand(process.argv[3], process.argv.slice(4));
-} else {
-  launchPi(process.argv.slice(2));
+async function loginCommand() {
+  // pagespace login — interactive token capture → validate → persist to ~/.pagespace/credentials (0600).
+  // The token never round-trips through .env or the shell env the agent sees (security ADR).
+  process.stderr.write("pagespace · login\n");
+  process.stderr.write("Paste your PageSpace token: ");
+  // Read the token from stdin as a normal line; it is written straight to the credential store,
+  // never to .env and never to the spawned pi env.
+  const readline = await import("node:readline/promises");
+  const { stdin, stdout } = process;
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  let token;
+  try {
+    token = (await rl.question("")).trim();
+  } finally {
+    rl.close();
+  }
+  if (!token) {
+    console.error("pagespace: no token entered — nothing saved.");
+    process.exit(1);
+  }
+  const apiUrl = (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, "");
+  // Validate via an auth ping before persisting.
+  try {
+    const res = await fetch(`${apiUrl}/api/drives`, { headers: { authorization: `Bearer ${token}` } });
+    if (!res.ok) {
+      console.error(`pagespace: token rejected by ${apiUrl} (HTTP ${res.status}) — nothing saved.`);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`pagespace: cannot reach ${apiUrl} to validate (${err.message}) — nothing saved.`);
+    process.exit(1);
+  }
+  // Build + write the record via the shared helpers (src/credentials.ts) — one impl, 0600 enforced.
+  const rec = buildCredentialRecord({ token, apiUrl });
+  const credPath = writeCredentials(rec);
+  process.stderr.write(`pagespace · token saved to ${credPath} (0600). Run: pagespace status\n`);
 }
+
+// Drive the full first-run onboarding flow (token → validate → drives → models → default → materialize)
+// using the shared pure state machine (src/onboarding.ts nextOnboardingStep). Each step performs its
+// effect, feeds the result into nextOnboardingStep, and loops until done. No local state logic —
+// the machine is the single implementation the unit tests exercise. Materialize via shared helpers.
+async function runOnboarding() {
+  let state = initialOnboardingState();
+  const base = (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, "");
+
+  // STEP token: capture.
+  process.stderr.write("pagespace · first run — let's get you set up.\n");
+  process.stderr.write("Paste your PageSpace token: ");
+  const readline = await import("node:readline/promises");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let token;
+  try { token = (await rl.question("")).trim(); } finally { rl.close(); }
+  if (!token) { console.error("pagespace: no token entered — nothing saved."); process.exit(1); }
+  state = nextOnboardingStep(state, { token });
+
+  // STEP validate: auth ping. On failure this is a terminal condition — the caller exits. (The
+  // machine only advances validate→drives on success; there is no recovery branch, so we don't
+  // call nextOnboardingStep with validated:false.)
+  const preferred = resolveDefaultDrive(process.env);
+  try {
+    const res = await fetch(`${base}/api/drives`, { headers: { authorization: `Bearer ${token}` } });
+    if (!res.ok) {
+      console.error(`pagespace: token rejected by ${base} (HTTP ${res.status}).`);
+      process.exit(1);
+    }
+    state = nextOnboardingStep(state, { validated: true });
+  } catch (err) {
+    console.error(`pagespace: cannot reach ${base} (${err.message}).`);
+    process.exit(1);
+  }
+
+  // STEP drives: discover accessible drives. Pass preferredDrive so the machine picks a default
+  // consistent with the drive used for preferred-first model ordering.
+  const drivesRaw = await fetch(`${base}/api/drives`, { headers: { authorization: `Bearer ${token}` } }).then((r) => r.json()).catch(() => []);
+  const drives = (Array.isArray(drivesRaw) ? drivesRaw : drivesRaw?.drives || []).map((d) => ({ id: d.id, name: d.name, slug: d.slug }));
+  if (drives.length === 0) { console.error("pagespace: no drives accessible to this token."); process.exit(1); }
+  console.log(`  ✓ discovered ${drives.length} drive(s): ${drives.map((d) => d.slug).join(", ")}`);
+  state = nextOnboardingStep(state, { drives, preferredDrive: preferred });
+
+  // STEP models: discover agent pages across all drives (preferred/default drive first).
+  const orderPreferred = state.defaultDrive ?? drives[0].slug;
+  const ordered = [...drives].sort((a, b) => (a.slug === orderPreferred ? -1 : b.slug === orderPreferred ? 1 : 0));
+  const modelRes = await Promise.allSettled(ordered.map((d) =>
+    fetch(`${base}/api/drives/${d.id}/pages`, { headers: { authorization: `Bearer ${token}` } }).then((r) => r.json())
+  ));
+  const models = [];
+  const walk = (nodes) => { for (const n of nodes) { if (n.type === "AI_CHAT") models.push({ id: n.id, name: n.title }); if (n.children) walk(n.children); } };
+  for (const r of modelRes) if (r.status === "fulfilled" && Array.isArray(r.value)) walk(r.value);
+  console.log(`  ✓ discovered ${models.length} agent model(s)${models.length ? ": " + models.map((m) => m.name).join(", ") : ""}`);
+  state = nextOnboardingStep(state, { models });
+
+  // STEP default → done (the machine advances automatically; the default is the first discovered).
+  state = nextOnboardingStep(state);
+
+  // Materialize: persist token to the credential store (shared writeCredentials). Set non-secret
+  // drive/model defaults in the launcher env. The token does NOT go into env here — loadCredentials()
+  // will read it from the store on the next launch (token isolation holds: no env round-trip).
+  const credPath = writeCredentials(buildCredentialRecord({ token, apiUrl: base }));
+  if (state.defaultDrive) process.env.PAGESPACE_DRIVE = state.defaultDrive;
+  if (state.defaultModel) process.env.PAGESPACE_MODEL_PAGE = state.defaultModel.id;
+  console.log(`  ✓ default drive: ${state.defaultDrive || "(none)"}`);
+  if (state.defaultModel) {
+    console.log(`  ✓ default model: ${state.defaultModel.name} (${state.defaultModel.id.slice(0, 8)})`);
+  } else {
+    console.log("  · no agent models found — set PAGESPACE_MODEL_PAGE manually if needed.");
+  }
+  process.stderr.write(`pagespace · set up complete (${credPath}, 0600). Launching…\n`);
+}
+
+/** No token anywhere (env, .env, credential store) → run first-run onboarding instead of a hard exit.
+ * Uses the shared onboardingNeedsSetup() (src/onboarding.ts → diagnose()) — single decision path. */
+function needsOnboarding() {
+  const hasToken = !!(process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim());
+  const hasCredentials = fs.existsSync(credentialsPath());
+  return onboardingNeedsSetup({ hasToken, hasCredentials });
+}
+
+async function main() {
+  const sub = process.argv[2];
+  if (sub === "status" || process.argv.includes("--check")) {
+    statusDoctor();
+  } else if (sub === "sessions") {
+    sessionsCommand();
+  } else if (sub === "resume") {
+    resumeCommand(process.argv[3], process.argv.slice(4));
+  } else if (sub === "login") {
+    loginCommand();
+  } else if (needsOnboarding()) {
+    // First run with no token: walk the user to a coding-ready state (Cursor-grade) instead of exiting.
+    await runOnboarding();
+    launchPi(process.argv.slice(2));
+  } else {
+    launchPi(process.argv.slice(2));
+  }
+}
+
+// Entry point — run after all declarations are initialized (avoids TDZ on module-level consts).
+// Only the tsx child reaches here (PAGESPACE_UNDER_TSX=1); the plain-node parent spawns + exits above.
+if (isTsx) main();
diff --git a/src/config.ts b/src/config.ts
index d4c354e..fa8828b 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,3 +1,5 @@
+import { readCredentials, type CredentialRecord, DEFAULT_API_URL } from "./credentials.ts";
+
 /** Runtime configuration for the PageSpace companion, resolved from env. */
 export interface PageSpaceConfig {
   /** Base URL of the PageSpace instance, e.g. https://pagespace.ai */
@@ -28,9 +30,55 @@ export interface PageSpaceConfig {
   conversationId?: string;
 }
 
-export function loadConfig(): PageSpaceConfig {
-  const configuredPrimary = process.env.PAGESPACE_MODEL_PAGE?.trim();
-  const modelPageIds = (process.env.PAGESPACE_MODEL_PAGES ?? "")
+/**
+ * Parse a drive set from env: PAGESPACE_DRIVES (comma-separated, the accessible drives) merged with
+ * PAGESPACE_DRIVE (the bare-path default, kept first + deduped). Returns {drives, default}. Pure.
+ *
+ * `default` is what the dual-mount uses for bare paths (pagespace/... with no drive segment);
+ * `drives` is the declared set the harness is aware of. A single PAGESPACE_DRIVE still works (the
+ * common case) — it becomes a one-element set with itself as the default.
+ */
+export function parseDriveSet(env: {
+  PAGESPACE_DRIVE?: string;
+  PAGESPACE_DRIVES?: string;
+}): { drives: string[]; default: string | undefined } {
+  const single = env.PAGESPACE_DRIVE?.trim();
+  const list = (env.PAGESPACE_DRIVES ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const drives = [...new Set([...(single ? [single] : []), ...list])];
+  return { drives, default: resolveDefaultDrive(env) };
+}
+
+/** Resolve the bare-path default drive: PAGESPACE_DRIVE wins, else the first of PAGESPACE_DRIVES. Pure. */
+export function resolveDefaultDrive(env: {
+  PAGESPACE_DRIVE?: string;
+  PAGESPACE_DRIVES?: string;
+}): string | undefined {
+  const single = env.PAGESPACE_DRIVE?.trim();
+  if (single) return single;
+  return (env.PAGESPACE_DRIVES ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .find(Boolean);
+}
+
+export function resolveAuthToken(
+  env: NodeJS.ProcessEnv,
+  readCredential: () => CredentialRecord | null = readCredentials,
+): string | undefined {
+  const envToken = env.PAGESPACE_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  return readCredential()?.token;
+}
+
+export function loadConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  readCredential: () => CredentialRecord | null = readCredentials,
+): PageSpaceConfig {
+  const configuredPrimary = env.PAGESPACE_MODEL_PAGE?.trim();
+  const modelPageIds = (env.PAGESPACE_MODEL_PAGES ?? "")
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean);
@@ -38,13 +86,13 @@ export function loadConfig(): PageSpaceConfig {
   const modelPageId = ids[0];
 
   return {
-    apiUrl: process.env.PAGESPACE_API_URL ?? "https://pagespace.ai",
-    authToken: process.env.PAGESPACE_AUTH_TOKEN,
-    defaultDriveSlug: process.env.PAGESPACE_DRIVE,
-    mountPrefix: process.env.PAGESPACE_MOUNT ?? "pagespace",
+    apiUrl: env.PAGESPACE_API_URL ?? DEFAULT_API_URL,
+    authToken: resolveAuthToken(env, readCredential),
+    defaultDriveSlug: resolveDefaultDrive(env),
+    mountPrefix: env.PAGESPACE_MOUNT ?? "pagespace",
     modelPageId,
     models: ids.length > 0 ? ids.map((id) => ({ id })) : undefined,
-    readOnlyPrefixes: (process.env.PAGESPACE_READONLY ?? "")
+    readOnlyPrefixes: (env.PAGESPACE_READONLY ?? "")
       .split(",")
       .map((s) => s.trim())
       .filter(Boolean),
diff --git a/src/credentials.ts b/src/credentials.ts
new file mode 100644
index 0000000..c95e49f
--- /dev/null
+++ b/src/credentials.ts
@@ -0,0 +1,108 @@
+/**
+ * Global credential store for the pagespace launcher — a token + API URL persisted under
+ * `~/.pagespace/credentials` (0600) so the user never has to hand-edit `.env`/`.mcp.json`.
+ *
+ * Security (ADR ml803j05zgon3vt54mnmuz53): the token is isolated from the agent's process env
+ * (the launcher scrubs it before spawn). The credential store is the source the provider reads
+ * from. This module holds the PURE shaping/validation/parsing (unit-tested); the file I/O +
+ * permission enforcement live in a thin wrapper and the `pagespace login` command in the launcher.
+ */
+
+/** The shape persisted to ~/.pagespace/credentials. */
+export interface CredentialRecord {
+  /** The scoped PageSpace MCP token (Bearer). */
+  token: string;
+  /** The instance URL this token is for. */
+  apiUrl: string;
+  /** ISO timestamp the credential was saved (for rotation prompts). */
+  savedAt: string;
+}
+
+/** Canonical API URL when none is specified. */
+export const DEFAULT_API_URL = "https://pagespace.ai";
+
+/** The sorted list of keys a credential record carries. Pure. */
+export const credentialRecordShape = ["token", "apiUrl", "savedAt"] as const;
+
+/** Build a credential record from a captured token + optional metadata. Pure. */
+export function buildCredentialRecord(input: {
+  token: string;
+  apiUrl?: string;
+  now?: () => Date;
+}): CredentialRecord {
+  if (!input.token || !input.token.trim()) throw new Error("token is required");
+  const apiUrl = (input.apiUrl ?? DEFAULT_API_URL).trim();
+  if (!apiUrl) throw new Error("apiUrl is empty");
+  return {
+    token: input.token.trim(),
+    apiUrl,
+    savedAt: (input.now ?? (() => new Date()))().toISOString(),
+  };
+}
+
+/** Parse a JSON credential-record body back into typed shape. Pure; throws on malformed input. */
+export function parseCredentialRecord(body: string): CredentialRecord {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error("credential file is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("credential file is not a JSON object");
+  }
+  const rec = parsed as Partial<CredentialRecord>;
+  const errs = validateCredentialRecord(rec);
+  if (errs.length > 0) throw new Error(`invalid credential record: ${errs.join("; ")}`);
+  return { token: rec.token!, apiUrl: rec.apiUrl!, savedAt: rec.savedAt! };
+}
+
+/** Validate a candidate credential record; returns a list of human-readable errors. Pure. */
+export function validateCredentialRecord(rec: Partial<CredentialRecord>): string[] {
+  const errs: string[] = [];
+  if (typeof rec.token !== "string" || !rec.token.trim()) errs.push("token is missing");
+  if (typeof rec.apiUrl !== "string" || !rec.apiUrl.trim()) errs.push("apiUrl is missing");
+  else if (!/^https?:\/\//.test(rec.apiUrl)) errs.push("apiUrl must be an http(s) URL");
+  if (typeof rec.savedAt !== "string" || !rec.savedAt.trim()) errs.push("savedAt is missing");
+  return errs;
+}
+
+/** File-path + permission helpers for the credential store. Thin I/O wrappers over the pure core. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The pagespace config directory (~/.pagespace). */
+export function pagespaceDir(): string {
+  return path.join(os.homedir(), ".pagespace");
+}
+
+/** Path to the credential file (~/.pagespace/credentials). */
+export function credentialsPath(): string {
+  return path.join(pagespaceDir(), "credentials");
+}
+
+/**
+ * Read the saved credential record, or null if none. Enforces 0600 on the file (refuses to load a
+ * world/group-readable credential — defense in depth). Throws on a corrupt/unreadable file.
+ */
+export function readCredentials(path_ = credentialsPath()): CredentialRecord | null {
+  if (!fs.existsSync(path_)) return null;
+  const stat = fs.statSync(path_);
+  const mode = stat.mode & 0o777;
+  if (mode & 0o077) {
+    throw new Error(
+      `credential file is too permissive (${mode.toString(8)}); expected 0600. Run: chmod 600 ${path_}`,
+    );
+  }
+  return parseCredentialRecord(fs.readFileSync(path_, "utf8"));
+}
+
+/** Write a credential record to disk with 0600 perms, creating the dir. Returns the path written. */
+export function writeCredentials(rec: CredentialRecord, path_ = credentialsPath()): string {
+  fs.mkdirSync(path.dirname(path_), { recursive: true });
+  fs.writeFileSync(path_, JSON.stringify(rec, null, 2), { mode: 0o600 });
+  // chmod in case the file already existed with looser perms (writeFile respects umask on create only)
+  fs.chmodSync(path_, 0o600);
+  return path_;
+}
diff --git a/src/doctor.ts b/src/doctor.ts
new file mode 100644
index 0000000..bdbb446
--- /dev/null
+++ b/src/doctor.ts
@@ -0,0 +1,122 @@
+/**
+ * The `pagespace status` doctor — a reusable diagnostic + remediation layer.
+ *
+ * The pure core (`diagnose`) takes a config snapshot and returns structured checks (each with a
+ * pass/fail + remediation hint); `formatDoctor` renders them. The launcher gathers the inputs
+ * (token present? credential store present? reachable?) and calls these. Non-interactive/CI-safe:
+ * `diagnose` is pure — it never prompts or blocks, just reports.
+ */
+import { DEFAULT_API_URL } from "./credentials.ts";
+
+/** A single diagnostic check. */
+export interface DoctorCheck {
+  /** Stable id for the check (e.g. "token", "credentials", "apiUrl"). */
+  id: string;
+  /** Human label. */
+  label: string;
+  pass: boolean;
+  /** Status detail (what was found). */
+  detail: string;
+  /** What to do when it fails (never empty on failure). */
+  remediation: string;
+}
+
+/** Inputs to the doctor — a snapshot of the environment, gathered by the launcher. */
+export interface DoctorInput {
+  hasToken?: boolean;
+  hasCredentials?: boolean;
+  /** Instance URL (defaults to the canonical pagespace.ai). */
+  apiUrl?: string;
+  /** Result of a live auth ping (optional; when absent, that check is skipped). */
+  reachable?: boolean;
+  /** Count of drives the token can see (optional; for a reachable report). */
+  driveCount?: number;
+}
+
+/** The resolved config the doctor normalized. */
+export interface DoctorConfig {
+  apiUrl: string;
+}
+
+/** A full doctor result. */
+export interface DoctorResult {
+  checks: DoctorCheck[];
+  pass: boolean;
+  config: DoctorConfig;
+  /** Top-level remediation summary (the first failing check's action, or "" when all pass). */
+  remediation: string;
+}
+
+/**
+ * Run the diagnostic checks against a config snapshot. Pure: decides pass/fail + remediation per
+ * check, aggregates, and returns structured results — never I/Os, never prompts.
+ */
+export function diagnose(input: DoctorInput): DoctorResult {
+  const apiUrl = (input.apiUrl ?? DEFAULT_API_URL).trim() || DEFAULT_API_URL;
+  const checks: DoctorCheck[] = [];
+
+  // apiUrl check.
+  const urlOk = /^https?:\/\//.test(apiUrl);
+  checks.push({
+    id: "apiUrl",
+    label: "API URL",
+    pass: urlOk,
+    detail: apiUrl,
+    remediation: "set PAGESPACE_API_URL to an http(s) URL (default: https://pagespace.ai).",
+  });
+
+  // token check — effective token resolved by the caller (env or credential store).
+  // Uses input.hasToken only; the credential-store check is a separate check below so that a
+  // credential file that exists but is corrupt/unreadable can't produce a false-green here.
+  const hasToken = !!input.hasToken;
+  checks.push({
+    id: "token",
+    label: "Auth token",
+    pass: hasToken,
+    detail: hasToken ? "present" : "unset",
+    remediation: "run: pagespace login  (or export PAGESPACE_AUTH_TOKEN).",
+  });
+
+  // credentials check — credential-store presence (the Cursor-grade path).
+  checks.push({
+    id: "credentials",
+    label: "Credential store",
+    pass: !!input.hasCredentials,
+    detail: input.hasCredentials ? "present (~/.pagespace/credentials)" : "not set",
+    remediation: "run: pagespace login  to persist a token (0600).",
+  });
+
+  // reachable check — only when a ping was performed.
+  if (input.reachable !== undefined) {
+    checks.push({
+      id: "reachable",
+      label: "Reachable",
+      pass: input.reachable,
+      detail: input.reachable
+        ? `${apiUrl} — ${input.driveCount ?? "?"} drive(s) visible`
+        : `cannot reach ${apiUrl}`,
+      remediation: `check the network, the URL, and the token scope against ${apiUrl}.`,
+    });
+  }
+
+  const pass = checks.every((c) => c.pass);
+  const firstFail = checks.find((c) => !c.pass);
+  return { checks, pass, config: { apiUrl }, remediation: firstFail?.remediation ?? "" };
+}
+
+/** Render a doctor result as scannable text (✓/✗ per check + remediation on failure). Pure. */
+export function formatDoctor(r: DoctorResult): string {
+  const lines = ["pagespace status:"];
+  for (const c of r.checks) {
+    const mark = c.pass ? "✓" : "✗";
+    lines.push(`  ${mark} ${c.label}: ${c.detail}`);
+  }
+  const failing = r.checks.filter((c) => !c.pass);
+  if (failing.length > 0) {
+    lines.push("  → fix:");
+    for (const c of failing) lines.push(`    ${c.remediation}`);
+  } else {
+    lines.push("  → all checks passed.");
+  }
+  return lines.join("\n");
+}
diff --git a/src/env.ts b/src/env.ts
index f93af4d..0b22ede 100644
--- a/src/env.ts
+++ b/src/env.ts
@@ -14,6 +14,26 @@
 import fs from "node:fs";
 import path from "node:path";
 
+/**
+ * Env keys that carry a secret and must NEVER be inherited by a spawned child (e.g. pi) whose
+ * tools (bash) could otherwise read them via `env`/`printenv`/`/proc/self/environ`. Token
+ * isolation: the agent must never see the PageSpace auth token. The provider reads the token
+ * from config, not from the child's process env.
+ */
+export const SECRET_ENV_KEYS = ["PAGESPACE_AUTH_TOKEN"] as const;
+
+/**
+ * Return a copy of `env` with all secret-bearing keys removed — safe to pass to `spawn` so a child
+ * process (and its tools) cannot exfiltrate the auth token. Non-mutating. Pure.
+ */
+export function sanitizeChildEnv(
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = { ...env };
+  for (const key of SECRET_ENV_KEYS) delete out[key];
+  return out;
+}
+
 /**
  * Parse a dotenv-style file body into key/value pairs. Pure.
  * Skips blanks and `#` comments, tolerates a leading `export `, strips one layer of matching
@@ -47,6 +67,7 @@ export function parseEnvFile(body: string): Record<string, string> {
 export function applyEnv(parsed: Record<string, string>, env: NodeJS.ProcessEnv = process.env): string[] {
   const applied: string[] = [];
   for (const [k, v] of Object.entries(parsed)) {
+    if (SECRET_ENV_KEYS.includes(k as (typeof SECRET_ENV_KEYS)[number])) continue;
     if (env[k] === undefined || env[k] === "") {
       env[k] = v;
       applied.push(k);
diff --git a/src/onboarding.ts b/src/onboarding.ts
new file mode 100644
index 0000000..4771946
--- /dev/null
+++ b/src/onboarding.ts
@@ -0,0 +1,140 @@
+/**
+ * First-run onboarding flow — when no token/config exists, the launcher walks the user from a blank
+ * slate to a coding-ready state instead of exiting with a "copy .mcp.json" hint.
+ *
+ * The flow is a pure state machine (unit-tested): token → validate → drives → models → default → done.
+ * Effects (auth ping, drive/model discovery) live in the launcher and feed results back in via the
+ * `input` argument. Token capture writes straight to the credential store (never .env/agent env).
+ *
+ * Reuses the doctor (src/doctor.ts) for the setup-needed decision — one shared diagnostic layer
+ * consumed by both the launcher's `pagespace status` and the onboarding gate.
+ */
+import { diagnose, type DoctorInput } from "./doctor.ts";
+
+/** A drive discovered during onboarding. */
+export interface OnboardingDrive {
+  id: string;
+  name: string;
+  slug: string;
+}
+
+/** A model (agent page) discovered during onboarding. */
+export interface OnboardingModel {
+  id: string;
+  name: string;
+}
+
+/** The onboarding step names, in order. */
+export const STEP_ORDER = ["token", "validate", "drives", "models", "default", "done"] as const;
+export type OnboardingStep = (typeof STEP_ORDER)[number];
+
+/** Mutable state threaded through the flow. */
+export interface OnboardingState {
+  step: OnboardingStep;
+  token: string | null;
+  apiUrl: string;
+  drives: OnboardingDrive[] | null;
+  defaultDrive: string | null;
+  models: OnboardingModel[] | null;
+  defaultModel: OnboardingModel | null;
+}
+
+/** The inputs an effect provides back to advance the state machine. */
+export interface OnboardingInput {
+  token?: string;
+  validated?: boolean;
+  drives?: OnboardingDrive[];
+  /** The env/configured preferred drive — used to pick the default when it's in the discovered set. */
+  preferredDrive?: string;
+  models?: OnboardingModel[];
+}
+
+/** Fresh onboarding state, starting at the token step. Pure. */
+export function initialOnboardingState(apiUrl = "https://pagespace.ai"): OnboardingState {
+  return {
+    step: "token",
+    token: null,
+    apiUrl,
+    drives: null,
+    defaultDrive: null,
+    models: null,
+    defaultModel: null,
+  };
+}
+
+/** True only when the flow has reached `done`. Pure. */
+export function isComplete(state: OnboardingState): boolean {
+  return state.step === "done";
+}
+
+/**
+ * Advance one step given the current state + any inputs from effects. Pure: decides the next step,
+ * applies the input (capture token, default the drive/model to the first discovered), and never I/Os.
+ * When a precondition for advancing isn't met (e.g. no token), the state is held/rewound.
+ */
+export function nextOnboardingStep(state: OnboardingState, input: OnboardingInput = {}): OnboardingState {
+  const next: OnboardingState = { ...state };
+  switch (state.step) {
+    case "token": {
+      const token = (input.token ?? state.token)?.trim();
+      if (token) {
+        next.token = token;
+        next.step = "validate";
+      }
+      break;
+    }
+    case "validate": {
+      // Validate is one-shot: advance to drives only on success. A failed auth ping is a terminal
+      // condition the caller handles (exit) — the machine never receives validated:false, so there
+      // is no recovery branch to go stale. (Onboarding is one-shot-and-exit-on-failure by design.)
+      if (input.validated) next.step = "drives";
+      break;
+    }
+    case "drives": {
+      const drives = input.drives;
+      if (drives && drives.length > 0) {
+        next.drives = drives;
+        // Default drive: the preferred/configured drive if it's in the discovered set, else the first.
+        // This keeps the reported default consistent with the drive used for preferred-first ordering.
+        const preferred = input.preferredDrive;
+        const inSet = preferred && drives.some((d) => d.slug === preferred);
+        next.defaultDrive = inSet ? preferred : drives[0].slug;
+        next.step = "models";
+      }
+      break;
+    }
+    case "models": {
+      const models = input.models;
+      if (models && models.length > 0) {
+        next.models = models;
+        next.defaultModel = models[0]; // default to the first discovered model
+        next.step = "default";
+      } else if (models !== undefined) {
+        // Explicit empty discovery is recoverable (model-discovery is optional in some setups) — go default.
+        next.models = [];
+        next.step = "default";
+      }
+      // models === undefined: hold — discovery hasn't run yet; wait for a real result.
+      break;
+    }
+    case "default": {
+      // The default has been chosen (either auto from models or explicitly); materialize.
+      next.step = "done";
+      break;
+    }
+    case "done":
+      break;
+  }
+  return next;
+}
+
+/**
+ * Decide whether first-run onboarding is needed, by running the shared doctor and checking the
+ * token + credential-store checks. Pure; consumes diagnose() so the doctor is the single source of
+ * "is config OK?" for both `pagespace status` and the onboarding gate. Reuse, not duplication.
+ */
+export function onboardingNeedsSetup(input: DoctorInput): boolean {
+  const result = diagnose(input);
+  const tokenOk = result.checks.find((c) => c.id === "token")?.pass ?? false;
+  return !tokenOk;
+}
diff --git a/test/run-token-isolation.ts b/test/run-token-isolation.ts
new file mode 100644
index 0000000..0d3ea9a
--- /dev/null
+++ b/test/run-token-isolation.ts
@@ -0,0 +1,79 @@
+/**
+ * Live E2E proof of token isolation THROUGH the agent's bash-tool env path.
+ *
+ * Chain proven: bin/pagespace.mjs (sanitizes spawn env) → pi process (inherits sanitized env) →
+ * pi's bash tool (packages/pi-coding-agent/.../bash.ts: `env: env ?? getShellEnv()` /
+ * `{ ...getShellEnv() }`, i.e. pi's process.env-derived) → command reads env.
+ *
+ * We run `env` / `printenv` / procfs in the exact sanitized env the launcher hands to `spawn(pi)`.
+ * That is the same env pi's bash tool derives its command env from. If the token is absent here, it
+ * is absent from anything the agent's bash tool can surface. Deterministic, no model/network needed.
+ *
+ * Two assertions: (1) the launcher actually wires sanitization into its spawn (source-level), and
+ * (2) the sanitized env survives all three exfil vectors the agent could use.
+ */
+import { readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { sanitizeChildEnv } from "../src/env.ts";
+import { loadConfig } from "../src/config.ts";
+
+test("the launcher sanitizes its spawn env (bin/pagespace.mjs wires sanitizeChildEnv)", () => {
+  const binSrc = readFileSync(new URL("../bin/pagespace.mjs", import.meta.url), "utf8");
+  assert.ok(
+    binSrc.includes("sanitizeChildEnv"),
+    "bin/pagespace.mjs must call sanitizeChildEnv before spawning pi",
+  );
+  assert.match(binSrc, /sanitizeChildEnv\(process\.env\)/, "sanitize process.env before spawn");
+});
+
+test("token is invisible through the bash-tool env path (env / printenv / procfs)", async () => {
+  // Reproduce the launcher's spawn-env construction with a live token present.
+  const childEnv = sanitizeChildEnv({ ...process.env, PAGESPACE_AUTH_TOKEN: "mcp_PROOF_LEAK" });
+  childEnv.PI_SKIP_VERSION_CHECK = "1";
+
+  const vectors: Array<{ name: string; cmd: string }> = [
+    { name: "env", cmd: "env" },
+    { name: "printenv", cmd: "printenv" },
+    { name: "procfs", cmd: "cat /proc/self/environ 2>/dev/null || true" },
+  ];
+
+  for (const v of vectors) {
+    const r = spawn("sh", ["-c", v.cmd], { env: childEnv });
+    let out = "";
+    r.stdout.on("data", (d) => (out += d.toString()));
+    r.stderr.on("data", () => {});
+    const code = await new Promise<number>((resolve) => r.on("close", resolve));
+    assert.equal(code, 0, `${v.name} exited cleanly`);
+    assert.ok(
+      !out.includes("mcp_PROOF_LEAK"),
+      `${v.name}: PAGESPACE_AUTH_TOKEN leaked through the bash-tool env path`,
+    );
+    assert.ok(
+      !out.includes("PAGESPACE_AUTH_TOKEN"),
+      `${v.name}: the token's env-key name leaked through the bash-tool env path`,
+    );
+  }
+});
+
+test("isolation AND auth path: sanitized child env + credential-store fallback yields authToken", () => {
+  const childEnv = sanitizeChildEnv({ ...process.env, PAGESPACE_AUTH_TOKEN: "mcp_PROOF_LEAK" });
+  assert.equal(childEnv.PAGESPACE_AUTH_TOKEN, undefined, "token must not reach spawned pi env");
+
+  const config = loadConfig(
+    {
+      ...childEnv,
+      PAGESPACE_AUTH_TOKEN: undefined,
+      PAGESPACE_API_URL: "https://pagespace.ai",
+    },
+    () => ({
+      token: "mcp_from_store",
+      apiUrl: "https://pagespace.ai",
+      savedAt: "2026-06-22T00:00:00.000Z",
+    }),
+  );
+
+  assert.ok(config.authToken, "auth token should still resolve via credential store");
+  assert.equal(config.authToken, "mcp_from_store");
+});
diff --git a/test/unit/config.test.ts b/test/unit/config.test.ts
new file mode 100644
index 0000000..90bca18
--- /dev/null
+++ b/test/unit/config.test.ts
@@ -0,0 +1,47 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { loadConfig } from "../../src/config.ts";
+
+test("loadConfig: falls back to credential store token when env token is unset", () => {
+  const config = loadConfig(
+    {
+      PAGESPACE_API_URL: "https://pagespace.ai",
+      PAGESPACE_AUTH_TOKEN: undefined,
+    },
+    () => ({
+      token: "mcp_from_store",
+      apiUrl: "https://pagespace.ai",
+      savedAt: "2026-06-22T00:00:00.000Z",
+    }),
+  );
+  assert.equal(config.authToken, "mcp_from_store");
+});
+
+test("loadConfig: authToken is undefined when env and credential store are both unset", () => {
+  const config = loadConfig(
+    {
+      PAGESPACE_AUTH_TOKEN: undefined,
+    },
+    () => null,
+  );
+  assert.equal(config.authToken, undefined);
+});
+
+test("loadConfig: env token wins over credential store token", () => {
+  const config = loadConfig(
+    {
+      PAGESPACE_AUTH_TOKEN: "mcp_env_token",
+    },
+    () => ({
+      token: "mcp_store_token",
+      apiUrl: "https://pagespace.ai",
+      savedAt: "2026-06-22T00:00:00.000Z",
+    }),
+  );
+  assert.equal(config.authToken, "mcp_env_token");
+});
+
+test("loadConfig: whitespace-only PAGESPACE_DRIVE does not leak into defaultDriveSlug", () => {
+  const config = loadConfig({ PAGESPACE_DRIVE: "   " }, () => null);
+  assert.equal(config.defaultDriveSlug, undefined);
+});
diff --git a/test/unit/credentials.test.ts b/test/unit/credentials.test.ts
new file mode 100644
index 0000000..be6e441
--- /dev/null
+++ b/test/unit/credentials.test.ts
@@ -0,0 +1,79 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildCredentialRecord,
+  parseCredentialRecord,
+  credentialRecordShape,
+  validateCredentialRecord,
+  type CredentialRecord,
+} from "../../src/credentials.ts";
+
+test("buildCredentialRecord shapes a token + metadata into the stored record", () => {
+  const rec = buildCredentialRecord({ token: "mcp_abc", apiUrl: "https://pagespace.ai" });
+  assert.equal(rec.token, "mcp_abc");
+  assert.equal(rec.apiUrl, "https://pagespace.ai");
+  assert.ok(rec.savedAt, "savedAt timestamp present");
+  assert.match(rec.savedAt, /^\d{4}-\d{2}-\d{2}T/);
+});
+
+test("buildCredentialRecord defaults apiUrl to the canonical instance", () => {
+  const rec = buildCredentialRecord({ token: "mcp_abc" });
+  assert.equal(rec.apiUrl, "https://pagespace.ai");
+});
+
+test("parseCredentialRecord round-trips with buildCredentialRecord (JSON)", () => {
+  const rec = buildCredentialRecord({ token: "mcp_abc", apiUrl: "https://custom.example" });
+  const json = JSON.stringify(rec);
+  const back = parseCredentialRecord(json);
+  assert.deepEqual(back, rec);
+});
+
+test("parseCredentialRecord rejects malformed JSON", () => {
+  assert.throws(() => parseCredentialRecord("not json"), /credential file/);
+});
+
+test("validateCredentialRecord accepts a well-formed record", () => {
+  const rec = buildCredentialRecord({ token: "mcp_abc" });
+  const errs = validateCredentialRecord(rec);
+  assert.deepEqual(errs, []);
+});
+
+test("validateCredentialRecord flags a missing token", () => {
+  const errs = validateCredentialRecord({ apiUrl: "https://pagespace.ai", savedAt: "x" });
+  assert.ok(errs.some((e) => /token/i.test(e)));
+});
+
+test("validateCredentialRecord flags a missing apiUrl", () => {
+  const errs = validateCredentialRecord({ token: "mcp_abc", savedAt: "x" });
+  assert.ok(errs.some((e) => /apiUrl|api url|url/i.test(e)));
+});
+
+test("validateCredentialRecord rejects non-string field values (e.g. numeric token)", () => {
+  const rec = {
+    token: 123,
+    apiUrl: "https://pagespace.ai",
+    savedAt: "x",
+  } as unknown as Partial<CredentialRecord>;
+  const errs = validateCredentialRecord(rec);
+  assert.ok(
+    errs.some((e) => /token/i.test(e)),
+    "numeric token should be flagged, not crash",
+  );
+});
+
+test("validateCredentialRecord rejects non-string apiUrl", () => {
+  const rec = { token: "mcp_abc", apiUrl: 42, savedAt: "x" } as unknown as Partial<CredentialRecord>;
+  const errs = validateCredentialRecord(rec);
+  assert.ok(
+    errs.some((e) => /apiUrl|api url|url/i.test(e)),
+    "numeric apiUrl should be flagged",
+  );
+});
+
+test("buildCredentialRecord rejects whitespace-only apiUrl", () => {
+  assert.throws(() => buildCredentialRecord({ token: "mcp_abc", apiUrl: "   " }), /apiUrl|url/i);
+});
+
+test("credentialRecordShape is the canonical key list", () => {
+  assert.deepEqual([...credentialRecordShape].sort(), ["apiUrl", "savedAt", "token"]);
+});
diff --git a/test/unit/doctor.test.ts b/test/unit/doctor.test.ts
new file mode 100644
index 0000000..a7585c7
--- /dev/null
+++ b/test/unit/doctor.test.ts
@@ -0,0 +1,80 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { diagnose, type DoctorCheck, formatDoctor } from "../../src/doctor.ts";
+
+test("diagnose flags a missing token", () => {
+  const r = diagnose({ apiUrl: "https://pagespace.ai", hasToken: false, hasCredentials: false });
+  assert.equal(r.pass, false);
+  const tokenCheck = r.checks.find((c) => c.id === "token");
+  assert.ok(tokenCheck);
+  assert.equal(tokenCheck?.pass, false);
+  assert.ok(/token|login/i.test(tokenCheck?.remediation ?? ""), "remediation points to login");
+});
+
+test("diagnose passes when a token is present", () => {
+  const r = diagnose({ apiUrl: "https://pagespace.ai", hasToken: true, hasCredentials: true });
+  const tokenCheck = r.checks.find((c) => c.id === "token");
+  assert.equal(tokenCheck?.pass, true);
+});
+
+test("diagnose reports credential-store presence", () => {
+  const withStore = diagnose({ apiUrl: "https://pagespace.ai", hasToken: true, hasCredentials: true });
+  const withoutStore = diagnose({ apiUrl: "https://pagespace.ai", hasToken: true, hasCredentials: false });
+  assert.equal(withStore.checks.find((c) => c.id === "credentials")?.pass, true);
+  assert.equal(withoutStore.checks.find((c) => c.id === "credentials")?.pass, false);
+});
+
+test("diagnose flags an invalid apiUrl", () => {
+  const r = diagnose({ apiUrl: "not-a-url", hasToken: true });
+  const urlCheck = r.checks.find((c) => c.id === "apiUrl");
+  assert.equal(urlCheck?.pass, false);
+});
+
+test("diagnose defaults apiUrl to the canonical instance when omitted", () => {
+  const r = diagnose({ hasToken: true });
+  assert.equal(r.checks.find((c) => c.id === "apiUrl")?.pass, true);
+  assert.equal(r.config.apiUrl, "https://pagespace.ai");
+});
+
+test("diagnose pass is true only when all checks pass", () => {
+  const allPass = diagnose({ apiUrl: "https://pagespace.ai", hasToken: true, hasCredentials: true });
+  assert.equal(allPass.pass, true);
+  const oneFail = diagnose({ apiUrl: "https://pagespace.ai", hasToken: false, hasCredentials: false });
+  assert.equal(oneFail.pass, false);
+});
+
+test("formatDoctor produces scannable output with ✓/✗ and remediation", () => {
+  const r = diagnose({ apiUrl: "https://pagespace.ai", hasToken: false, hasCredentials: false });
+  const out = formatDoctor(r);
+  assert.match(out, /✗/);
+  assert.match(out, /✓|·/);
+  assert.match(out, /pagespace login|token/i);
+});
+
+test("formatDoctor reports all-pass cleanly", () => {
+  const r = diagnose({ apiUrl: "https://pagespace.ai", hasToken: true, hasCredentials: true });
+  const out = formatDoctor(r);
+  assert.match(out, /✓/);
+  assert.ok(!out.includes("✗"), "no failures when all pass");
+});
+
+test("non-interactive mode: diagnose never prompts (pure, returns results only)", () => {
+  // The contract: diagnose() is pure and returns structured results; it never blocks on stdin.
+  const r = diagnose({ apiUrl: "https://pagespace.ai", hasToken: false });
+  assert.ok(Array.isArray(r.checks));
+  assert.equal(r.pass, false);
+  assert.ok(r.remediation.length > 0 || r.checks.some((c) => c.remediation));
+});
+
+test("diagnose token check does not false-green when credential file exists but token is unusable", () => {
+  // hasCredentials=true (file exists) but hasToken=false (token unreadable/corrupt) must FAIL the
+  // token check — credential-store presence is a separate check; it must not rescue the token check.
+  const r = diagnose({ apiUrl: "https://pagespace.ai", hasToken: false, hasCredentials: true });
+  const tokenCheck = r.checks.find((c) => c.id === "token");
+  assert.equal(
+    tokenCheck?.pass,
+    false,
+    "token check must fail when hasToken is false, even with credentials present",
+  );
+  assert.equal(r.pass, false, "overall pass must be false");
+});
diff --git a/test/unit/drive-set.test.ts b/test/unit/drive-set.test.ts
new file mode 100644
index 0000000..cc98a91
--- /dev/null
+++ b/test/unit/drive-set.test.ts
@@ -0,0 +1,48 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseDriveSet, resolveDefaultDrive } from "../../src/config.ts";
+
+test("parseDriveSet returns empty when neither PAGESPACE_DRIVE nor PAGESPACE_DRIVES is set", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVE: undefined, PAGESPACE_DRIVES: undefined });
+  assert.deepEqual(r.drives, []);
+  assert.equal(r.default, undefined);
+});
+
+test("parseDriveSet reads a single PAGESPACE_DRIVE", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVE: "pagespace-cli" });
+  assert.deepEqual(r.drives, ["pagespace-cli"]);
+  assert.equal(r.default, "pagespace-cli");
+});
+
+test("parseDriveSet reads a comma-separated PAGESPACE_DRIVES", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVES: "pagespace-cli,pure-point,pagespace" });
+  assert.deepEqual(r.drives, ["pagespace-cli", "pure-point", "pagespace"]);
+  assert.equal(r.default, "pagespace-cli", "first drive is the default");
+});
+
+test("parseDriveSet dedupes drives (case-preserving)", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVES: "a,b,a" });
+  assert.deepEqual(r.drives, ["a", "b"]);
+});
+
+test("parseDriveSet trims whitespace and drops empties", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVES: " a , , b " });
+  assert.deepEqual(r.drives, ["a", "b"]);
+});
+
+test("parseDriveSet merges PAGESPACE_DRIVE into PAGESPACE_DRIVES (drive first, deduped)", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVE: "pagespace-cli", PAGESPACE_DRIVES: "pure-point,pagespace-cli" });
+  assert.deepEqual(r.drives, ["pagespace-cli", "pure-point"]);
+  assert.equal(r.default, "pagespace-cli");
+});
+
+test("parseDriveSet: when only PAGESPACE_DRIVES is set, its first entry is the default", () => {
+  const r = parseDriveSet({ PAGESPACE_DRIVES: "pure-point,pagespace-cli" });
+  assert.equal(r.default, "pure-point");
+});
+
+test("resolveDefaultDrive prefers PAGESPACE_DRIVE, falls back to first of DRIVES, else undefined", () => {
+  assert.equal(resolveDefaultDrive({ PAGESPACE_DRIVE: "a", PAGESPACE_DRIVES: "b,c" }), "a");
+  assert.equal(resolveDefaultDrive({ PAGESPACE_DRIVE: undefined, PAGESPACE_DRIVES: "b,c" }), "b");
+  assert.equal(resolveDefaultDrive({ PAGESPACE_DRIVE: undefined, PAGESPACE_DRIVES: undefined }), undefined);
+});
diff --git a/test/unit/env-isolate-token.test.ts b/test/unit/env-isolate-token.test.ts
new file mode 100644
index 0000000..5a65434
--- /dev/null
+++ b/test/unit/env-isolate-token.test.ts
@@ -0,0 +1,40 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { sanitizeChildEnv, SECRET_ENV_KEYS } from "../../src/env.ts";
+
+test("SECRET_ENV_KEYS includes the auth token", () => {
+  assert.ok(SECRET_ENV_KEYS.includes("PAGESPACE_AUTH_TOKEN"));
+});
+
+test("sanitizeChildEnv removes secret keys", () => {
+  const env = {
+    PATH: "/usr/bin",
+    PAGESPACE_AUTH_TOKEN: "mcp_secret_here",
+    PAGESPACE_API_URL: "https://pagespace.ai",
+    HOME: "/home/user",
+  };
+  const out = sanitizeChildEnv(env);
+  assert.equal(out.PAGESPACE_AUTH_TOKEN, undefined, "token must be stripped");
+  assert.equal(out.PAGESPACE_API_URL, "https://pagespace.ai", "non-secret kept");
+  assert.equal(out.PATH, "/usr/bin");
+  assert.equal(out.HOME, "/home/user");
+});
+
+test("sanitizeChildEnv does not mutate the input env", () => {
+  const env = { PAGESPACE_AUTH_TOKEN: "mcp_secret", PATH: "/usr/bin" };
+  sanitizeChildEnv(env);
+  assert.equal(env.PAGESPACE_AUTH_TOKEN, "mcp_secret", "input untouched");
+});
+
+test("sanitizeChildEnv on env without secrets is a clean copy", () => {
+  const env = { PATH: "/usr/bin" };
+  const out = sanitizeChildEnv(env);
+  assert.deepEqual(out, env);
+  assert.notEqual(out, env, "returns a new object");
+});
+
+test("sanitizeChildEnv with PAGESPACE_AUTH_TOKEN empty still strips it (defense in depth)", () => {
+  const env = { PAGESPACE_AUTH_TOKEN: "", PATH: "/usr/bin" };
+  const out = sanitizeChildEnv(env);
+  assert.equal(out.PAGESPACE_AUTH_TOKEN, undefined);
+});
diff --git a/test/unit/env.test.ts b/test/unit/env.test.ts
index c63d8a7..ee04fcc 100644
--- a/test/unit/env.test.ts
+++ b/test/unit/env.test.ts
@@ -42,3 +42,15 @@ test("applyEnv: sets only unset/empty keys — the live shell env wins", () => {
   assert.equal(env.PAGESPACE_MOUNT, "pagespace"); // unset → filled
   assert.deepEqual(applied.sort(), ["PAGESPACE_DRIVE", "PAGESPACE_MOUNT"]);
 });
+
+test("applyEnv: never injects secret keys from .env into process env", () => {
+  const env: NodeJS.ProcessEnv = { PAGESPACE_DRIVE: "" };
+  const applied = applyEnv(
+    { PAGESPACE_AUTH_TOKEN: "file-token", PAGESPACE_DRIVE: "from-file", PAGESPACE_MOUNT: "pagespace" },
+    env,
+  );
+  assert.equal(env.PAGESPACE_AUTH_TOKEN, undefined, "secret key must be skipped");
+  assert.equal(env.PAGESPACE_DRIVE, "from-file");
+  assert.equal(env.PAGESPACE_MOUNT, "pagespace");
+  assert.deepEqual(applied.sort(), ["PAGESPACE_DRIVE", "PAGESPACE_MOUNT"]);
+});
diff --git a/test/unit/onboarding.test.ts b/test/unit/onboarding.test.ts
new file mode 100644
index 0000000..ceffebf
--- /dev/null
+++ b/test/unit/onboarding.test.ts
@@ -0,0 +1,159 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  nextOnboardingStep,
+  type OnboardingState,
+  STEP_ORDER,
+  isComplete,
+  initialOnboardingState,
+} from "../../src/onboarding.ts";
+
+const base: OnboardingState = {
+  step: "token",
+  token: null,
+  apiUrl: "https://pagespace.ai",
+  drives: null,
+  defaultDrive: null,
+  models: null,
+  defaultModel: null,
+};
+
+test("initialOnboardingState starts at the token step", () => {
+  assert.equal(initialOnboardingState().step, "token");
+});
+
+test("STEP_ORDER is the full onboarding sequence", () => {
+  assert.deepEqual(STEP_ORDER, ["token", "validate", "drives", "models", "default", "done"]);
+});
+
+test("nextOnboardingStep advances token→validate when a token is captured", () => {
+  const out = nextOnboardingStep({ ...base, token: "mcp_abc" });
+  assert.equal(out.step, "validate");
+});
+
+test("nextOnboardingStep holds at token when no token captured yet", () => {
+  const out = nextOnboardingStep(base);
+  assert.equal(out.step, "token", "can't advance without a token");
+});
+
+test("nextOnboardingStep advances validate→drives when token validates", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "validate" };
+  const out = nextOnboardingStep(s, { validated: true });
+  assert.equal(out.step, "drives");
+});
+
+test("nextOnboardingStep holds at validate when validated is not true (one-shot contract)", () => {
+  // Validate is one-shot-and-exit-on-failure by design: the caller exits on a failed auth ping and
+  // never calls the machine with validated:false. So the machine only advances on validated:true;
+  // without it, it holds (a terminal condition the caller owns, not a recovery the machine owns).
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "validate" };
+  const out = nextOnboardingStep(s, {});
+  assert.equal(out.step, "validate");
+  assert.equal(out.token, "mcp_abc", "token preserved when held");
+});
+
+test("nextOnboardingStep advances drives→models when drives discovered", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "drives" };
+  const out = nextOnboardingStep(s, {
+    drives: [
+      { slug: "a", id: "1", name: "A" },
+      { slug: "b", id: "2", name: "B" },
+    ],
+  });
+  assert.equal(out.step, "models");
+  assert.deepEqual(out.defaultDrive, "a", "defaults to first drive");
+});
+
+test("nextOnboardingStep advances models→default when models discovered", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", defaultDrive: "a", step: "models" };
+  const out = nextOnboardingStep(s, { models: [{ id: "m1", name: "Brain" }] });
+  assert.equal(out.step, "default");
+  assert.deepEqual(out.defaultModel, { id: "m1", name: "Brain" }, "defaults to first model");
+});
+
+test("nextOnboardingStep holds at models when input.models is undefined (no discovery yet)", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", defaultDrive: "a", step: "models" };
+  const out = nextOnboardingStep(s, {});
+  assert.equal(out.step, "models", "should hold when models discovery hasn't happened");
+});
+
+test("nextOnboardingStep advances models→default when discovery returns empty (recoverable)", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", defaultDrive: "a", step: "models" };
+  const out = nextOnboardingStep(s, { models: [] });
+  assert.equal(out.step, "default", "empty discovery is recoverable — advance");
+});
+
+test("nextOnboardingStep advances default→done when a default model is chosen", () => {
+  const s: OnboardingState = {
+    ...base,
+    token: "mcp_abc",
+    defaultDrive: "a",
+    defaultModel: { id: "m1", name: "Brain" },
+    step: "default",
+  };
+  const out = nextOnboardingStep(s);
+  assert.equal(out.step, "done");
+});
+
+test("isComplete is true only at done", () => {
+  assert.equal(isComplete(base), false);
+  assert.equal(isComplete({ ...base, step: "done" }), true);
+});
+
+test("onboarding a user with a single drive + single model resolves to done in the minimal steps", () => {
+  let s = initialOnboardingState();
+  s = nextOnboardingStep(s, { token: "mcp_abc" });
+  s = nextOnboardingStep(s, { validated: true });
+  s = nextOnboardingStep(s, { drives: [{ slug: "a", id: "1", name: "A" }] });
+  s = nextOnboardingStep(s, { models: [{ id: "m1", name: "Brain" }] });
+  s = nextOnboardingStep(s);
+  assert.equal(s.step, "done");
+  assert.equal(s.defaultDrive, "a");
+  assert.deepEqual(s.defaultModel, { id: "m1", name: "Brain" });
+});
+
+test("onboardingNeedsSetup uses the doctor to decide if onboarding is needed", async () => {
+  const { onboardingNeedsSetup } = await import("../../src/onboarding.ts");
+  // A failing doctor (no token) → onboarding needed.
+  assert.equal(onboardingNeedsSetup({ hasToken: false, hasCredentials: false }), true);
+  // A passing doctor (token present) → no onboarding needed.
+  assert.equal(
+    onboardingNeedsSetup({ hasToken: true, hasCredentials: true, apiUrl: "https://pagespace.ai" }),
+    false,
+  );
+  // Credential store path: the launcher's loadCredentials() IIFE copies the token into env
+  // before needsOnboarding() is called, so hasToken is always true when credentials are readable.
+  assert.equal(onboardingNeedsSetup({ hasToken: true, hasCredentials: true }), false);
+});
+
+test("nextOnboardingStep picks the preferred drive as default when it's in the discovered set", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "drives" };
+  const out = nextOnboardingStep(s, {
+    drives: [
+      { slug: "a", id: "1", name: "A" },
+      { slug: "b", id: "2", name: "B" },
+    ],
+    preferredDrive: "b",
+  });
+  assert.equal(out.defaultDrive, "b", "preferred drive wins when in the set");
+});
+
+test("nextOnboardingStep falls back to first drive when preferred is not in the discovered set", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "drives" };
+  const out = nextOnboardingStep(s, {
+    drives: [{ slug: "a", id: "1", name: "A" }],
+    preferredDrive: "nonexistent",
+  });
+  assert.equal(out.defaultDrive, "a", "falls back to first drive");
+});
+
+test("nextOnboardingStep without preferredDrive still defaults to first (back-compat)", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "drives" };
+  const out = nextOnboardingStep(s, {
+    drives: [
+      { slug: "a", id: "1", name: "A" },
+      { slug: "b", id: "2", name: "B" },
+    ],
+  });
+  assert.equal(out.defaultDrive, "a");
+});