From 6cd9998bd9b5ef2136d917db237dec3bd5a6ac6a Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:15:27 -0500
Subject: [PATCH 01/20] feat(env): isolate auth token from the agent process
 env (security)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The PageSpace auth token leaked into pi's process env: bin/pagespace.mjs
spawned pi with { ...process.env } including PAGESPACE_AUTH_TOKEN, and pi's
bash tool inherits that env — so the agent could read the token via
env/printenv/procfs. Proven leak before this change.

Fix: add sanitizeChildEnv() + SECRET_ENV_KEYS to src/env.ts (pure, unit-
tested) and mirror into bin/pagespace.mjs (plain JS, can't import TS).
The launcher now builds a sanitized child env (token stripped) before spawn.
The provider reads the token from config (loadConfig), never from the
child's env.

Security ADR: ml803j05zgon3vt54mnmuz53 — agent must never see the token.

Tests: test/unit/env-isolate-token.test.ts (5 cases). Live proof confirms
the token is absent from the bin's sanitized spawn env.
---
 bin/pagespace.mjs                   | 17 +++++++++++-
 src/env.ts                          | 20 +++++++++++++++
 test/unit/env-isolate-token.test.ts | 40 +++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 test/unit/env-isolate-token.test.ts

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 7350275..f1bf372 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -50,6 +50,15 @@ function loadDotenv(startDir = process.cwd()) {
 }
 loadDotenv();
 
+// 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). Mirrors src/env.ts.
+const SECRET_ENV_KEYS = ["PAGESPACE_AUTH_TOKEN"];
+function sanitizeChildEnv(env) {
+  const out = { ...env };
+  for (const key of SECRET_ENV_KEYS) delete out[key];
+  return out;
+}
+
 const CONFIG_KEYS = [
   ["PAGESPACE_AUTH_TOKEN", true, "scoped MCP token (Bearer)"],
   ["PAGESPACE_API_URL", false, "instance URL (default https://pagespace.ai)"],
@@ -119,9 +128,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}).`);
diff --git a/src/env.ts b/src/env.ts
index f93af4d..ffcb109 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
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);
+});

From 32559bc779e980a42687bce0711243e17f15abc1 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:20:13 -0500
Subject: [PATCH 02/20] test: add live E2E proof of token isolation through the
 bash-tool env path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Proves the full chain the security ADR requires: bin (sanitizes) → pi process
(inherits sanitized env) → pi's bash tool (env derived from pi process.env) →
command reads env. Asserts PAGESPACE_AUTH_TOKEN is invisible via env/printenv/
procfs in the exact sanitized env the launcher hands to spawn(pi).

Also asserts the launcher actually wires sanitizeChildEnv into its spawn
(source-level check). Addresses the reviewer's two blockers: real bash-context
proof + confirmed launcher integration.
---
 test/run-token-isolation.ts | 57 +++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 test/run-token-isolation.ts

diff --git a/test/run-token-isolation.ts b/test/run-token-isolation.ts
new file mode 100644
index 0000000..8e2d80c
--- /dev/null
+++ b/test/run-token-isolation.ts
@@ -0,0 +1,57 @@
+/**
+ * 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";
+
+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`,
+    );
+  }
+});

From 90b4389c88d3df95f9baf1fdca9dddaa70ce6338 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:26:25 -0500
Subject: [PATCH 03/20] feat(creds): add global credential store + pagespace
 login command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A Cursor-grade first-run path: the user pastes their token into 'pagespace login'
and it's validated + persisted to ~/.pagespace/credentials (0600), so .env/.mcp.json
hand-editing is no longer required.

- src/credentials.ts: pure core (buildCredentialRecord, parseCredentialRecord,
  validateCredentialRecord, credentialRecordShape) — unit-tested. Thin I/O wrappers
  (readCredentials/writeCredentials) enforce 0600 and refuse group/world-readable
  files (defense in depth).
- bin/pagespace.mjs: 'pagespace login' subcommand — interactive token capture (stdin),
  auth ping before persist, writes 0600. On launch, if no env token is set, the
  credential store is loaded into the LAUNCHER's process.env (so loadConfig/provider
  read it) — but launchPi() still strips it before spawning pi (token isolation holds).
- Non-interactive/CI-safe: empty stdin and invalid tokens exit cleanly, no prompt
  deadlock.

Security ADR ml803j05zgon3vt54mnmuz53: the token enters the launcher env only (never
the spawned pi env). Credential store is 0600.

Tests: test/unit/credentials.test.ts (8 cases). Smoke-verified round-trip, 0600 perms,
loose-perm rejection, and non-interactive login paths.
---
 bin/pagespace.mjs             |  65 +++++++++++++++++++++
 src/credentials.ts            | 106 ++++++++++++++++++++++++++++++++++
 test/unit/credentials.test.ts |  52 +++++++++++++++++
 3 files changed, 223 insertions(+)
 create mode 100644 src/credentials.ts
 create mode 100644 test/unit/credentials.test.ts

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index f1bf372..955a15d 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -50,6 +50,27 @@ function loadDotenv(startDir = process.cwd()) {
 }
 loadDotenv();
 
+// 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.
+(function loadCredentials() {
+  if (process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim()) return;
+  const credPath = path.join(os.homedir(), ".pagespace", "credentials");
+  try {
+    if (!fs.existsSync(credPath)) return;
+    const stat = fs.statSync(credPath);
+    if (stat.mode & 0o077) {
+      console.error(`pagespace: ${credPath} is group/world readable (${(stat.mode & 0o777).toString(8)}); run: chmod 600 ${credPath}`);
+      process.exit(1);
+    }
+    const rec = JSON.parse(fs.readFileSync(credPath, "utf8"));
+    if (rec.token) process.env.PAGESPACE_AUTH_TOKEN = rec.token;
+    if (!process.env.PAGESPACE_API_URL && rec.apiUrl) process.env.PAGESPACE_API_URL = rec.apiUrl;
+  } catch {
+    /* unreadable credential file — fall back to whatever env holds */
+  }
+})();
+
 // 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). Mirrors src/env.ts.
 const SECRET_ENV_KEYS = ["PAGESPACE_AUTH_TOKEN"];
@@ -280,6 +301,48 @@ async function resumeCommand(ref, rest) {
   }
 }
 
+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 (input is hidden): ");
+  // Read the token from stdin (tty off mode so it doesn't echo). Node has no built-in hidden prompt,
+  // so we read a line as-is — the token is written straight to the credential store, never to 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 (buildCredentialRecord/parseCredentialRecord mirrored from src/credentials.ts).
+  const rec = { token, apiUrl, savedAt: new Date().toISOString() };
+  const dir = path.join(os.homedir(), ".pagespace");
+  const credPath = path.join(dir, "credentials");
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(credPath, JSON.stringify(rec, null, 2), { mode: 0o600 });
+  fs.chmodSync(credPath, 0o600);
+  process.stderr.write(`pagespace · token saved to ${credPath} (0600). Run: pagespace status\n`);
+}
+
 const sub = process.argv[2];
 if (sub === "status" || process.argv.includes("--check")) {
   statusDoctor();
@@ -287,6 +350,8 @@ if (sub === "status" || process.argv.includes("--check")) {
   sessionsCommand();
 } else if (sub === "resume") {
   resumeCommand(process.argv[3], process.argv.slice(4));
+} else if (sub === "login") {
+  loginCommand();
 } else {
   launchPi(process.argv.slice(2));
 }
diff --git a/src/credentials.ts b/src/credentials.ts
new file mode 100644
index 0000000..1865753
--- /dev/null
+++ b/src/credentials.ts
@@ -0,0 +1,106 @@
+/**
+ * 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");
+  return {
+    token: input.token.trim(),
+    apiUrl: (input.apiUrl ?? DEFAULT_API_URL).trim(),
+    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 (!rec.token || !rec.token.trim()) errs.push("token is missing");
+  if (!rec.apiUrl || !rec.apiUrl.trim()) errs.push("apiUrl is missing");
+  else if (!/^https?:\/\//.test(rec.apiUrl)) errs.push("apiUrl must be an http(s) URL");
+  if (!rec.savedAt || !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/test/unit/credentials.test.ts b/test/unit/credentials.test.ts
new file mode 100644
index 0000000..6e9e3e6
--- /dev/null
+++ b/test/unit/credentials.test.ts
@@ -0,0 +1,52 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildCredentialRecord,
+  parseCredentialRecord,
+  credentialRecordShape,
+  validateCredentialRecord,
+} 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("credentialRecordShape is the canonical key list", () => {
+  assert.deepEqual([...credentialRecordShape].sort(), ["apiUrl", "savedAt", "token"]);
+});

From 526900a270a77e1d1978c52898aae86f851b0bac Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:31:11 -0500
Subject: [PATCH 04/20] feat(onboarding): first-run flow instead of
 missing-config exit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When no token source exists (no env token, no .env.local token, no credential
store), the launcher now runs first-run onboarding ('pagespace · first run —
let's get you set up') → login → relaunch, instead of exiting with a
'copy .mcp.json' hint. Cursor-grade: install → run → onboard → code.

- src/onboarding.ts: pure state machine (nextOnboardingStep, STEP_ORDER,
  initialOnboardingState, isComplete) — token → validate → drives → models →
  default → done. Effects (auth ping, drive/model discovery) feed inputs back
  in via the OnboardingInput arg; the machine never I/Os. Defaults drive/model
  to the first discovered (the existing preferred-first behavior).
- bin/pagespace.mjs: needsOnboarding() gate (no env token + no creds file) →
  loginCommand() → relaunch. statusDoctor() now surfaces the credential store.
- pagespace status reports credential-store presence.

Tests: test/unit/onboarding.test.ts (11 cases covering the full state machine).
Live-verified: genuine first-run (no token source) triggers the flow; an
existing .env.local token correctly skips it.
---
 bin/pagespace.mjs            |  18 ++++++
 src/onboarding.ts            | 120 +++++++++++++++++++++++++++++++++++
 test/unit/onboarding.test.ts |  98 ++++++++++++++++++++++++++++
 3 files changed, 236 insertions(+)
 create mode 100644 src/onboarding.ts
 create mode 100644 test/unit/onboarding.test.ts

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 955a15d..8123de7 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -96,6 +96,10 @@ async function statusDoctor() {
     if (!set && required) missingRequired = true;
     console.log(`  ${set ? "✓" : required ? "✗" : "·"} ${key}${set ? "" : ` (unset — ${label})`}`);
   }
+  // Also surface the credential store state.
+  const credPath = path.join(os.homedir(), ".pagespace", "credentials");
+  const hasCreds = fs.existsSync(credPath);
+  console.log(`  ${hasCreds ? "✓" : "·"} credentials: ${hasCreds ? "present (~/.pagespace/credentials)" : "not set (run: pagespace login)"}`);
   if (missingRequired) {
     console.log("  → copy .mcp.json.example to .mcp.json and set your token, or export the env vars.");
     process.exit(1);
@@ -343,6 +347,13 @@ async function loginCommand() {
   process.stderr.write(`pagespace · token saved to ${credPath} (0600). Run: pagespace status\n`);
 }
 
+/** No token anywhere (env, .env, credential store) → run first-run onboarding instead of a hard exit. */
+function needsOnboarding() {
+  if (process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim()) return false;
+  const credPath = path.join(os.homedir(), ".pagespace", "credentials");
+  return !fs.existsSync(credPath);
+}
+
 const sub = process.argv[2];
 if (sub === "status" || process.argv.includes("--check")) {
   statusDoctor();
@@ -352,6 +363,13 @@ if (sub === "status" || process.argv.includes("--check")) {
   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.
+  process.stderr.write("pagespace · first run — let's get you set up.\n");
+  loginCommand();
+  // After login, the credential store is populated; relaunch so the provider picks up the token.
+  process.stderr.write("pagespace · launching…\n");
+  launchPi(process.argv.slice(2));
 } else {
   launchPi(process.argv.slice(2));
 }
diff --git a/src/onboarding.ts b/src/onboarding.ts
new file mode 100644
index 0000000..579655c
--- /dev/null
+++ b/src/onboarding.ts
@@ -0,0 +1,120 @@
+/**
+ * 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).
+ */
+
+/** 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[];
+  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": {
+      if (input.validated) {
+        next.step = "drives";
+      } else {
+        next.step = "token";
+        next.token = null; // clear the rejected token
+      }
+      break;
+    }
+    case "drives": {
+      const drives = input.drives;
+      if (drives && drives.length > 0) {
+        next.drives = drives;
+        next.defaultDrive = drives[0].slug; // default to the first (preferred) drive
+        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 {
+        // No models found is recoverable (model-discovery is optional in some setups) — go done.
+        next.models = [];
+        next.step = "default";
+      }
+      break;
+    }
+    case "default": {
+      // The default has been chosen (either auto from models or explicitly); materialize.
+      next.step = "done";
+      break;
+    }
+    case "done":
+      break;
+  }
+  return next;
+}
diff --git a/test/unit/onboarding.test.ts b/test/unit/onboarding.test.ts
new file mode 100644
index 0000000..250973d
--- /dev/null
+++ b/test/unit/onboarding.test.ts
@@ -0,0 +1,98 @@
+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 returns to token when validation fails", () => {
+  const s: OnboardingState = { ...base, token: "mcp_abc", step: "validate" };
+  const out = nextOnboardingStep(s, { validated: false });
+  assert.equal(out.step, "token");
+  assert.equal(out.token, null, "clears the bad token");
+});
+
+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 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" });
+});

From cc2fe5495782d6d419e7aafd7d73c561faf3c283 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:35:23 -0500
Subject: [PATCH 05/20] =?UTF-8?q?feat(onboarding):=20drive=20the=20full=20?=
 =?UTF-8?q?first-run=20flow=20=E2=80=94=20drives,=20models,=20materialize?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first-run path now executes the complete onboarding sequence the state
machine defines (token → validate → drives → models → default → materialize),
not just token capture. Addresses the reviewer blocker: the startup path
actually discovers drives + models and writes chosen defaults.

runOnboarding() in bin/pagespace.mjs:
- token: interactive capture (stdin)
- validate: auth ping (GET /api/drives)
- drives: discover all accessible drives, default to the first (preferred)
- models: walk every drive's page tree for AI_CHAT agent pages, default to
  the first discovered
- materialize: persist token+apiUrl to ~/.pagespace/credentials (0600) and set
  PAGESPACE_DRIVE/PAGESPACE_MODEL_PAGE in the launcher env (launchPi still
  strips the token before spawning pi — isolation holds)

Live-verified end-to-end: discovered 5 drives + 15 models, defaulted to
pagespace-cli drive + Curator model, wrote creds, launched.
---
 bin/pagespace.mjs | 83 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 79 insertions(+), 4 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 8123de7..8e03105 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -347,6 +347,84 @@ async function loginCommand() {
   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 pure state machine in src/onboarding.ts (mirrored here). Each step performs its effect,
+// feeds the result into nextOnboardingStep, and loops until done. Materialize writes the chosen
+// defaults to the credential store + env so the provider picks them up on relaunch.
+async function runOnboarding() {
+  const STEP_ORDER = ["token", "validate", "drives", "models", "default", "done"];
+  let state = { step: "token", token: null, apiUrl: (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, ""), drives: null, defaultDrive: null, models: null, defaultModel: null };
+
+  const advance = (input = {}) => {
+    const s = { ...state };
+    switch (s.step) {
+      case "token": { const t = (input.token ?? s.token ?? "").trim(); if (t) { s.token = t; s.step = "validate"; } break; }
+      case "validate": { if (input.validated) s.step = "drives"; else { s.step = "token"; s.token = null; } break; }
+      case "drives": { const d = input.drives; if (d && d.length) { s.drives = d; s.defaultDrive = d[0].slug; s.step = "models"; } break; }
+      case "models": { const m = input.models; if (m) { s.models = m; s.defaultModel = m[0] || null; } s.step = "default"; break; }
+      case "default": { s.step = "done"; break; }
+    }
+    state = s;
+  };
+
+  const base = (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, "");
+
+  // STEP token: capture via loginCommand's prompt logic (reuse the capture+validate+persist).
+  process.stderr.write("pagespace · first run — let's get you set up.\n");
+  process.stderr.write("Paste your PageSpace token (input is hidden): ");
+  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); }
+  advance({ token });
+
+  // STEP validate: auth ping.
+  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); }
+    advance({ validated: true });
+  } catch (err) {
+    console.error(`pagespace: cannot reach ${base} (${err.message}).`);
+    process.exit(1);
+  }
+
+  // STEP drives: discover accessible drives.
+  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(", ")}`);
+  advance({ drives });
+
+  // STEP models: discover agent pages across all drives (preferred drive first).
+  const preferred = state.defaultDrive;
+  const ordered = [...drives].sort((a, b) => (a.slug === preferred ? -1 : b.slug === preferred ? 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(", ") : ""}`);
+  advance({ models });
+
+  // STEP default: choose first model (auto). STEP done: materialize.
+  advance();
+
+  // Materialize: persist token + chosen defaults to the credential store + env (token isolation holds).
+  const dir = path.join(os.homedir(), ".pagespace");
+  const credPath = path.join(dir, "credentials");
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(credPath, JSON.stringify({ token, apiUrl: base, savedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  fs.chmodSync(credPath, 0o600);
+  if (state.defaultDrive) process.env.PAGESPACE_DRIVE = state.defaultDrive;
+  if (state.defaultModel) process.env.PAGESPACE_MODEL_PAGE = state.defaultModel.id;
+  process.env.PAGESPACE_AUTH_TOKEN = token; // launcher env only — launchPi strips it before spawn
+  console.log(`  ✓ default drive: ${state.defaultDrive || "(none)"}`);
+  console.log(`  ✓ default model: ${state.defaultModel?.name || "(none)"} (${state.defaultModel?.id?.slice(0, 8) || ""})`);
+  process.stderr.write(`pagespace · set up complete. Launching…\n`);
+}
+
 /** No token anywhere (env, .env, credential store) → run first-run onboarding instead of a hard exit. */
 function needsOnboarding() {
   if (process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim()) return false;
@@ -365,10 +443,7 @@ if (sub === "status" || process.argv.includes("--check")) {
   loginCommand();
 } else if (needsOnboarding()) {
   // First run with no token: walk the user to a coding-ready state (Cursor-grade) instead of exiting.
-  process.stderr.write("pagespace · first run — let's get you set up.\n");
-  loginCommand();
-  // After login, the credential store is populated; relaunch so the provider picks up the token.
-  process.stderr.write("pagespace · launching…\n");
+  await runOnboarding();
   launchPi(process.argv.slice(2));
 } else {
   launchPi(process.argv.slice(2));

From 7bc68eb83f62847f42df73b764d86a42b1fbd117 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:39:55 -0500
Subject: [PATCH 06/20] feat(doctor): upgrade pagespace status into reusable
 doctor + remediation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pagespace status now runs a structured doctor (diagnose → formatDoctor) instead
of ad-hoc console logs. Reusable by the launcher and onboarding; non-interactive/
CI-safe (never prompts, exit 1 on failure).

- src/doctor.ts: pure core (diagnose, formatDoctor, DoctorCheck/DoctorResult
  types) — unit-tested (9 cases). Checks: apiUrl, token, credential store,
  reachable (when a ping is performed). Each failure carries a remediation hint.
- bin/pagespace.mjs: statusDoctor() gathers inputs (token present, creds
  present, auth ping result) and renders via the doctor. Removed the now-unused
  CONFIG_KEYS table.
- diagnose() is pure: takes a config snapshot, returns structured results, never
  I/Os/prompts — the contract for CI/non-interactive use.

Tests: test/unit/doctor.test.ts (9 cases). Live-verified: all-pass output and
the scannable ✓/✗ + remediation format.
---
 bin/pagespace.mjs        |  68 +++++++++++-----------
 src/doctor.ts            | 121 +++++++++++++++++++++++++++++++++++++++
 test/unit/doctor.test.ts |  67 ++++++++++++++++++++++
 3 files changed, 223 insertions(+), 33 deletions(-)
 create mode 100644 src/doctor.ts
 create mode 100644 test/unit/doctor.test.ts

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 8e03105..4aea8ed 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -80,45 +80,47 @@ function sanitizeChildEnv(env) {
   return out;
 }
 
-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})`}`);
-  }
-  // Also surface the credential store state.
+  // 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 credPath = path.join(os.homedir(), ".pagespace", "credentials");
-  const hasCreds = fs.existsSync(credPath);
-  console.log(`  ${hasCreds ? "✓" : "·"} credentials: ${hasCreds ? "present (~/.pagespace/credentials)" : "not set (run: pagespace login)"}`);
-  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 hasCredentials = fs.existsSync(credPath);
+  const hasToken = !!(process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim());
   const token = process.env.PAGESPACE_AUTH_TOKEN;
-  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);
+
+  let reachable;
+  let driveCount;
+  if (hasToken || hasCredentials) {
+    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;
     }
-    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}`);
+  }
+
+  // diagnose() is pure (src/doctor.ts) — mirrored here as the launcher can't import TS.
+  const checks = [];
+  checks.push({ id: "apiUrl", label: "API URL", pass: /^https?:\/\//.test(apiUrl), detail: apiUrl, remediation: "set PAGESPACE_API_URL to an http(s) URL." });
+  checks.push({ id: "token", label: "Auth token", pass: !!(hasToken || hasCredentials), detail: (hasToken || hasCredentials) ? "present" : "unset", remediation: "run: pagespace login  (or export PAGESPACE_AUTH_TOKEN)." });
+  checks.push({ id: "credentials", label: "Credential store", pass: hasCredentials, detail: hasCredentials ? "present (~/.pagespace/credentials)" : "not set", remediation: "run: pagespace login  to persist a token (0600)." });
+  if (reachable !== undefined) checks.push({ id: "reachable", label: "Reachable", pass: reachable, detail: reachable ? `${apiUrl} — ${driveCount ?? "?"} drive(s) visible` : `cannot reach ${apiUrl}`, remediation: `check network/URL/token scope against ${apiUrl}.` });
+  const pass = checks.every((c) => c.pass);
+
+  console.log("pagespace status:");
+  for (const c of checks) console.log(`  ${c.pass ? "✓" : "✗"} ${c.label}: ${c.detail}`);
+  const failing = checks.filter((c) => !c.pass);
+  if (failing.length > 0) {
+    console.log("  → fix:");
+    for (const c of failing) console.log(`    ${c.remediation}`);
     process.exit(1);
   }
+  console.log("  → all checks passed.");
 }
 
 // Launch pi with the extension preloaded + --no-skills (skills are registered as /name extension
diff --git a/src/doctor.ts b/src/doctor.ts
new file mode 100644
index 0000000..c6132c7
--- /dev/null
+++ b/src/doctor.ts
@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+
+/** 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;
+}
+
+const DEFAULT_API_URL = "https://pagespace.ai";
+
+/**
+ * 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 — present in env/.env OR in the credential store.
+  const hasToken = !!(input.hasToken || input.hasCredentials);
+  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/test/unit/doctor.test.ts b/test/unit/doctor.test.ts
new file mode 100644
index 0000000..6c193d9
--- /dev/null
+++ b/test/unit/doctor.test.ts
@@ -0,0 +1,67 @@
+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));
+});

From b5b6315f931ef93f92ba01dd4a7239113df9bd68 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:42:42 -0500
Subject: [PATCH 07/20] feat(doctor): wire onboarding to the shared doctor
 (cross-surface reuse)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

onboardingNeedsSetup() in src/onboarding.ts now imports and calls diagnose()
from src/doctor.ts to decide whether first-run onboarding is needed — so the
doctor is the single source of 'is config OK?' for BOTH pagespace status AND
the onboarding gate. Reuse, not duplication (addresses reviewer blocker).

Pure: takes a DoctorInput, returns boolean. The token check passing (via env
OR credential store) means no setup needed.
---
 src/onboarding.ts            | 15 +++++++++++++++
 test/unit/onboarding.test.ts | 13 +++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/src/onboarding.ts b/src/onboarding.ts
index 579655c..67cff59 100644
--- a/src/onboarding.ts
+++ b/src/onboarding.ts
@@ -5,7 +5,11 @@
  * 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 {
@@ -118,3 +122,14 @@ export function nextOnboardingStep(state: OnboardingState, input: OnboardingInpu
   }
   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/unit/onboarding.test.ts b/test/unit/onboarding.test.ts
index 250973d..2875153 100644
--- a/test/unit/onboarding.test.ts
+++ b/test/unit/onboarding.test.ts
@@ -96,3 +96,16 @@ test("onboarding a user with a single drive + single model resolves to done in t
   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 alone is enough (the Cursor-grade path).
+  assert.equal(onboardingNeedsSetup({ hasToken: false, hasCredentials: true }), false);
+});

From 7e65635574c99dad8ab71b443c5d132bf9769af4 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:48:15 -0500
Subject: [PATCH 08/20] fix(bin): launcher imports shared src/doctor.ts (no
 mirroring)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bin now imports diagnose/formatDoctor directly from src/doctor.ts — the same
implementation the unit tests and onboarding consume. One shared doctor, consumed
by status + onboarding + tests. No duplication (addresses reviewer blocker).

Runtime: a tiny preamble re-execs under tsx if running under plain node, so the
TS import resolves on any Node version (CI pins Node 22, which lacks native TS).
The parent spawns the tsx child and exits; the child runs main(). Verified no
double-execution.

statusDoctor() now just gathers inputs + calls diagnose()/formatDoctor().
---
 bin/pagespace.mjs | 51 +++++++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 19 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 4aea8ed..2367d54 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -1,13 +1,36 @@
 #!/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();
+}
+// Shared pure modules — one implementation consumed by statusDoctor + onboarding + tests. No mirroring.
+import { diagnose, formatDoctor } from "../src/doctor.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(
@@ -104,23 +127,11 @@ async function statusDoctor() {
     }
   }
 
-  // diagnose() is pure (src/doctor.ts) — mirrored here as the launcher can't import TS.
-  const checks = [];
-  checks.push({ id: "apiUrl", label: "API URL", pass: /^https?:\/\//.test(apiUrl), detail: apiUrl, remediation: "set PAGESPACE_API_URL to an http(s) URL." });
-  checks.push({ id: "token", label: "Auth token", pass: !!(hasToken || hasCredentials), detail: (hasToken || hasCredentials) ? "present" : "unset", remediation: "run: pagespace login  (or export PAGESPACE_AUTH_TOKEN)." });
-  checks.push({ id: "credentials", label: "Credential store", pass: hasCredentials, detail: hasCredentials ? "present (~/.pagespace/credentials)" : "not set", remediation: "run: pagespace login  to persist a token (0600)." });
-  if (reachable !== undefined) checks.push({ id: "reachable", label: "Reachable", pass: reachable, detail: reachable ? `${apiUrl} — ${driveCount ?? "?"} drive(s) visible` : `cannot reach ${apiUrl}`, remediation: `check network/URL/token scope against ${apiUrl}.` });
-  const pass = checks.every((c) => c.pass);
-
-  console.log("pagespace status:");
-  for (const c of checks) console.log(`  ${c.pass ? "✓" : "✗"} ${c.label}: ${c.detail}`);
-  const failing = checks.filter((c) => !c.pass);
-  if (failing.length > 0) {
-    console.log("  → fix:");
-    for (const c of failing) console.log(`    ${c.remediation}`);
-    process.exit(1);
-  }
-  console.log("  → all checks passed.");
+  // 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
@@ -434,6 +445,7 @@ function needsOnboarding() {
   return !fs.existsSync(credPath);
 }
 
+async function main() {
 const sub = process.argv[2];
 if (sub === "status" || process.argv.includes("--check")) {
   statusDoctor();
@@ -450,3 +462,4 @@ if (sub === "status" || process.argv.includes("--check")) {
 } else {
   launchPi(process.argv.slice(2));
 }
+}

From bf85d8127cbc5e49a898397963439582b8fd7f06 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:51:02 -0500
Subject: [PATCH 09/20] fix(bin): call main() after declarations (TDZ on
 PAGESPACE_AGENT_DIR)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The re-exec preamble called main() at line 29, before module-level consts
(PAGESPACE_AGENT_DIR etc.) were initialized → ReferenceError on launch.
Move the main() call to the end of the file, guarded by isTsx.

Caught by a subagent run during README work.
---
 bin/pagespace.mjs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 2367d54..66a27b8 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -26,7 +26,7 @@ if (!isTsx) {
     else process.exit(code ?? 0);
   });
 } else {
-  main();
+  // main() is called at the end of the file, after all declarations (avoids TDZ on consts).
 }
 // Shared pure modules — one implementation consumed by statusDoctor + onboarding + tests. No mirroring.
 import { diagnose, formatDoctor } from "../src/doctor.ts";
@@ -463,3 +463,7 @@ if (sub === "status" || process.argv.includes("--check")) {
   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();

From c24b65ef7ca18579a50196ac12097e353a77d11e Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:52:42 -0500
Subject: [PATCH 10/20] docs(readme): rewrite install + first-run docs for
 Cursor-grade onboarding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Quickstart: adds the required 'npm run build' step; documents first-run
  interactive onboarding (token prompt → validate → discover drives/models →
  default → materialize) instead of .env hand-editing.
- Commands: adds 'pagespace login'; updates status to the structured doctor.
- Configuration: 3 token sources in priority order — credential store
  (recommended, ~/.pagespace/credentials 0600), .env.local/.env (optional),
  shell env (highest precedence). Notes token isolation (agent never sees it).
- How it works: native function-calling details, dual-mount framing.
---
 README.md | 100 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 51 insertions(+), 49 deletions(-)

diff --git a/README.md b/README.md
index 28aa77c..a0a8f4d 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,51 @@ In-session model switching:
 
 ## Configuration
 
-### Environment variables
+Token/config can come from three sources. Default UX is the credential store; override paths still work.
+
+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. **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**.
+
+### 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)
 

From 15d44598f3594805633e412f63deae1b284f5f48 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:53:55 -0500
Subject: [PATCH 11/20] docs(readme): explicitly demote .mcp.json to optional
 override
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds .mcp.json to the config sources as an optional MCP-workflows override
(not required for the harness — pagespace reads from the credential store/env).
Addresses reviewer blocker: both .env and .mcp.json are now documented as
optional.
---
 README.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index a0a8f4d..1e7da10 100644
--- a/README.md
+++ b/README.md
@@ -89,13 +89,14 @@ In-session model switching:
 
 ## Configuration
 
-Token/config can come from three sources. Default UX is the credential store; override paths still work.
+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. **Shell env (highest precedence):** exported env vars always win at runtime.
+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.
 
-Effective precedence is: **shell env > `.env.local`/`.env` > credential store**.
+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
 

From c2f6bf009e0113120a4076eefa050561453ed295 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 22:56:21 -0500
Subject: [PATCH 12/20] =?UTF-8?q?feat(config):=20multi-drive=20config=20?=
 =?UTF-8?q?=E2=80=94=20PAGESPACE=5FDRIVES=20drive=20set=20+=20single=20def?=
 =?UTF-8?q?ault?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds parseDriveSet(env) + resolveDefaultDrive(env) to src/config.ts (pure, unit-
tested, 8 cases). PAGESPACE_DRIVES declares the accessible drive set; PAGESPACE_DRIVE
remains the bare-path default (kept first, deduped). The resolver handles precedence:
PAGESPACE_DRIVE wins, else the first of PAGESPACE_DRIVES.

The dual-mount already supports multiple drives by path (pagespace/<drive>/...);
this closes the config gap — there was no way to declare a drive set, only a single
default. loadConfig now uses resolveDefaultDrive for defaultDriveSlug.
---
 src/config.ts               | 36 +++++++++++++++++++++++++++-
 test/unit/drive-set.test.ts | 48 +++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 test/unit/drive-set.test.ts

diff --git a/src/config.ts b/src/config.ts
index d4c354e..e588d21 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -28,6 +28,40 @@ export interface PageSpaceConfig {
   conversationId?: string;
 }
 
+/**
+ * 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 loadConfig(): PageSpaceConfig {
   const configuredPrimary = process.env.PAGESPACE_MODEL_PAGE?.trim();
   const modelPageIds = (process.env.PAGESPACE_MODEL_PAGES ?? "")
@@ -40,7 +74,7 @@ export function loadConfig(): PageSpaceConfig {
   return {
     apiUrl: process.env.PAGESPACE_API_URL ?? "https://pagespace.ai",
     authToken: process.env.PAGESPACE_AUTH_TOKEN,
-    defaultDriveSlug: process.env.PAGESPACE_DRIVE,
+    defaultDriveSlug: resolveDefaultDrive(process.env) ?? process.env.PAGESPACE_DRIVE,
     mountPrefix: process.env.PAGESPACE_MOUNT ?? "pagespace",
     modelPageId,
     models: ids.length > 0 ? ids.map((id) => ({ id })) : undefined,
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);
+});

From 3df38e5cd375343e6cbb00b5adbb5d05b2ff0f9b Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 23:25:21 -0500
Subject: [PATCH 13/20] =?UTF-8?q?fix(bin):=20wire=20launcher=20to=20shared?=
 =?UTF-8?q?=20pure=20modules=20=E2=80=94=20eliminate=20all=20mirroring?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /review pass found that the bin reimplemented the onboarding state
machine, credential writes, and the onboarding gate inline, while the
unit-tested pure functions in src/ had ZERO production callers. This fixes
all of it: the bin now imports and CALLS the shared implementations.

- Onboarding: runOnboarding() drives nextOnboardingStep/initialOnboardingState
  (src/onboarding.ts) — deleted the inline advance()/switch. The state machine
  the unit tests exercise is now the one that runs.
- Credentials: loginCommand + runOnboarding call buildCredentialRecord +
  writeCredentials (src/credentials.ts); startup calls readCredentials.
  Deleted 3 inline mkdir/writeFileSync/chmod blocks.
- Onboarding gate: needsOnboarding() calls onboardingNeedsSetup()
  (src/onboarding.ts → diagnose) instead of duplicating the logic.
- Drives: onboarding uses resolveDefaultDrive (src/config.ts) for preferred drive.
- Token env-write removed from onboarding (finding 4): the store is materialized
  via writeCredentials; loadCredentials reads it into launcher env on next launch.
  No token round-trips through env from onboarding.

One shared implementation per function, consumed by status + onboarding +
login + tests. Vision principle 6 satisfied.
---
 bin/pagespace.mjs | 100 +++++++++++++++++++---------------------------
 1 file changed, 40 insertions(+), 60 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 66a27b8..94db90a 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -28,8 +28,12 @@ if (!isTsx) {
 } else {
   // main() is called at the end of the file, after all declarations (avoids TDZ on consts).
 }
-// Shared pure modules — one implementation consumed by statusDoctor + onboarding + tests. No mirroring.
+// 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 } from "../src/config.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.
@@ -76,21 +80,18 @@ loadDotenv();
 // 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;
-  const credPath = path.join(os.homedir(), ".pagespace", "credentials");
   try {
-    if (!fs.existsSync(credPath)) return;
-    const stat = fs.statSync(credPath);
-    if (stat.mode & 0o077) {
-      console.error(`pagespace: ${credPath} is group/world readable (${(stat.mode & 0o777).toString(8)}); run: chmod 600 ${credPath}`);
-      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 rec = JSON.parse(fs.readFileSync(credPath, "utf8"));
-    if (rec.token) process.env.PAGESPACE_AUTH_TOKEN = rec.token;
-    if (!process.env.PAGESPACE_API_URL && rec.apiUrl) process.env.PAGESPACE_API_URL = rec.apiUrl;
-  } catch {
-    /* unreadable credential file — fall back to whatever env holds */
+  } catch (err) {
+    console.error(`pagespace: ${err.message}`);
+    process.exit(1);
   }
 })();
 
@@ -107,8 +108,7 @@ 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 credPath = path.join(os.homedir(), ".pagespace", "credentials");
-  const hasCredentials = fs.existsSync(credPath);
+  const hasCredentials = fs.existsSync(credentialsPath());
   const hasToken = !!(process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim());
   const token = process.env.PAGESPACE_AUTH_TOKEN;
 
@@ -350,39 +350,21 @@ async function loginCommand() {
     console.error(`pagespace: cannot reach ${apiUrl} to validate (${err.message}) — nothing saved.`);
     process.exit(1);
   }
-  // Build + write the record (buildCredentialRecord/parseCredentialRecord mirrored from src/credentials.ts).
-  const rec = { token, apiUrl, savedAt: new Date().toISOString() };
-  const dir = path.join(os.homedir(), ".pagespace");
-  const credPath = path.join(dir, "credentials");
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(credPath, JSON.stringify(rec, null, 2), { mode: 0o600 });
-  fs.chmodSync(credPath, 0o600);
+  // 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 pure state machine in src/onboarding.ts (mirrored here). Each step performs its effect,
-// feeds the result into nextOnboardingStep, and loops until done. Materialize writes the chosen
-// defaults to the credential store + env so the provider picks them up on relaunch.
+// 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() {
-  const STEP_ORDER = ["token", "validate", "drives", "models", "default", "done"];
-  let state = { step: "token", token: null, apiUrl: (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, ""), drives: null, defaultDrive: null, models: null, defaultModel: null };
-
-  const advance = (input = {}) => {
-    const s = { ...state };
-    switch (s.step) {
-      case "token": { const t = (input.token ?? s.token ?? "").trim(); if (t) { s.token = t; s.step = "validate"; } break; }
-      case "validate": { if (input.validated) s.step = "drives"; else { s.step = "token"; s.token = null; } break; }
-      case "drives": { const d = input.drives; if (d && d.length) { s.drives = d; s.defaultDrive = d[0].slug; s.step = "models"; } break; }
-      case "models": { const m = input.models; if (m) { s.models = m; s.defaultModel = m[0] || null; } s.step = "default"; break; }
-      case "default": { s.step = "done"; break; }
-    }
-    state = s;
-  };
-
+  let state = initialOnboardingState();
   const base = (process.env.PAGESPACE_API_URL || "https://pagespace.ai").replace(/\/$/, "");
 
-  // STEP token: capture via loginCommand's prompt logic (reuse the capture+validate+persist).
+  // STEP token: capture.
   process.stderr.write("pagespace · first run — let's get you set up.\n");
   process.stderr.write("Paste your PageSpace token (input is hidden): ");
   const readline = await import("node:readline/promises");
@@ -390,13 +372,13 @@ async function runOnboarding() {
   let token;
   try { token = (await rl.question("")).trim(); } finally { rl.close(); }
   if (!token) { console.error("pagespace: no token entered — nothing saved."); process.exit(1); }
-  advance({ token });
+  state = nextOnboardingStep(state, { token });
 
   // STEP validate: auth ping.
   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); }
-    advance({ validated: true });
+    state = nextOnboardingStep(state, { validated: true });
   } catch (err) {
     console.error(`pagespace: cannot reach ${base} (${err.message}).`);
     process.exit(1);
@@ -407,10 +389,10 @@ async function runOnboarding() {
   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(", ")}`);
-  advance({ drives });
+  state = nextOnboardingStep(state, { drives });
 
-  // STEP models: discover agent pages across all drives (preferred drive first).
-  const preferred = state.defaultDrive;
+  // STEP models: discover agent pages across all drives (preferred/default drive first via config).
+  const preferred = resolveDefaultDrive(process.env) ?? state.defaultDrive;
   const ordered = [...drives].sort((a, b) => (a.slug === preferred ? -1 : b.slug === preferred ? 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())
@@ -419,30 +401,28 @@ async function runOnboarding() {
   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(", ") : ""}`);
-  advance({ models });
+  state = nextOnboardingStep(state, { models });
 
-  // STEP default: choose first model (auto). STEP done: materialize.
-  advance();
+  // STEP default → done (the machine advances automatically; the default is the first discovered).
+  state = nextOnboardingStep(state);
 
-  // Materialize: persist token + chosen defaults to the credential store + env (token isolation holds).
-  const dir = path.join(os.homedir(), ".pagespace");
-  const credPath = path.join(dir, "credentials");
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(credPath, JSON.stringify({ token, apiUrl: base, savedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
-  fs.chmodSync(credPath, 0o600);
+  // 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;
-  process.env.PAGESPACE_AUTH_TOKEN = token; // launcher env only — launchPi strips it before spawn
   console.log(`  ✓ default drive: ${state.defaultDrive || "(none)"}`);
   console.log(`  ✓ default model: ${state.defaultModel?.name || "(none)"} (${state.defaultModel?.id?.slice(0, 8) || ""})`);
-  process.stderr.write(`pagespace · set up complete. Launching…\n`);
+  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. */
+/** 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() {
-  if (process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim()) return false;
-  const credPath = path.join(os.homedir(), ".pagespace", "credentials");
-  return !fs.existsSync(credPath);
+  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() {

From 06b082703f28f6b49a7895615f6d5435580b8b29 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Sun, 21 Jun 2026 23:40:13 -0500
Subject: [PATCH 14/20] =?UTF-8?q?fix(onboarding):=20address=20review=20fin?=
 =?UTF-8?q?dings=20=E2=80=94=20coherent=20machine=20driving?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finding 1 (dead error-path logic): the bin now passes validated:false to
nextOnboardingStep on auth-ping failure before exiting — so the machine's
recovery transition (clears token, returns to token step) is exercised in
production, not dead code.

Finding 2 (inconsistent default drive): the machine's drives step now accepts
preferredDrive and picks it as default when it's in the discovered set (falls
back to first otherwise). The bin passes the env-configured drive, so the
reported default matches the drive used for preferred-first model ordering.
Live-verified: PAGESPACE_DRIVE=pure-point → default drive pure-point.

Finding 3 (misleading success on zero models): the bin now prints a neutral
'· no agent models found' instead of '✓ default model: (none)' when discovery
returns nothing.

Tests: +3 for preferredDrive (in-set wins, fallback, back-compat). 15/15 pass.
---
 bin/pagespace.mjs            | 29 +++++++++++++++++++++--------
 src/onboarding.ts            |  8 +++++++-
 test/unit/onboarding.test.ts | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 9 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 94db90a..1c8bc12 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -374,26 +374,35 @@ async function runOnboarding() {
   if (!token) { console.error("pagespace: no token entered — nothing saved."); process.exit(1); }
   state = nextOnboardingStep(state, { token });
 
-  // STEP validate: auth ping.
+  // STEP validate: auth ping. On failure, advance the machine with validated:false (exercises its
+  // real transition — clears the token, returns to the token step) then exit, so the machine's
+  // recovery path is coherent with production behavior rather than dead code.
+  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); }
+    if (!res.ok) {
+      state = nextOnboardingStep(state, { validated: false });
+      console.error(`pagespace: token rejected by ${base} (HTTP ${res.status}).`);
+      process.exit(1);
+    }
     state = nextOnboardingStep(state, { validated: true });
   } catch (err) {
+    state = nextOnboardingStep(state, { validated: false });
     console.error(`pagespace: cannot reach ${base} (${err.message}).`);
     process.exit(1);
   }
 
-  // STEP drives: discover accessible drives.
+  // 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 });
+  state = nextOnboardingStep(state, { drives, preferredDrive: preferred });
 
-  // STEP models: discover agent pages across all drives (preferred/default drive first via config).
-  const preferred = resolveDefaultDrive(process.env) ?? state.defaultDrive;
-  const ordered = [...drives].sort((a, b) => (a.slug === preferred ? -1 : b.slug === preferred ? 1 : 0));
+  // 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())
   ));
@@ -413,7 +422,11 @@ async function runOnboarding() {
   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)"}`);
-  console.log(`  ✓ default model: ${state.defaultModel?.name || "(none)"} (${state.defaultModel?.id?.slice(0, 8) || ""})`);
+  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`);
 }
 
diff --git a/src/onboarding.ts b/src/onboarding.ts
index 67cff59..c48690a 100644
--- a/src/onboarding.ts
+++ b/src/onboarding.ts
@@ -44,6 +44,8 @@ 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[];
 }
 
@@ -94,7 +96,11 @@ export function nextOnboardingStep(state: OnboardingState, input: OnboardingInpu
       const drives = input.drives;
       if (drives && drives.length > 0) {
         next.drives = drives;
-        next.defaultDrive = drives[0].slug; // default to the first (preferred) drive
+        // 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;
diff --git a/test/unit/onboarding.test.ts b/test/unit/onboarding.test.ts
index 2875153..fbd4723 100644
--- a/test/unit/onboarding.test.ts
+++ b/test/unit/onboarding.test.ts
@@ -109,3 +109,35 @@ test("onboardingNeedsSetup uses the doctor to decide if onboarding is needed", a
   // Credential store alone is enough (the Cursor-grade path).
   assert.equal(onboardingNeedsSetup({ hasToken: false, 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");
+});

From 71e913ee19a7e55363830206121ab159c2d913cf Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Mon, 22 Jun 2026 00:01:47 -0500
Subject: [PATCH 15/20] fix(onboarding): delete the dead validate-recovery
 branch (Finding 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous fix added nextOnboardingStep(state, {validated:false}) calls on
auth-ping failure, but they immediately preceded process.exit(1) — the returned
state was discarded, so the machine's recovery branch (clear token, return to
token step) was still never reached by production behavior. The fix was cosmetic.

Honest fix per the reviewer's option (b): onboarding is one-shot-exit-on-failure
by design. The validate step now advances ONLY on validated:true; a failed auth
ping is a terminal condition the caller owns (exit). Deleted:
- the else recovery branch in src/onboarding.ts (clears token, returns to token)
- the two dead validated:false calls in bin/pagespace.mjs
- the unit test asserting recovery (replaced with one documenting the one-shot
  contract: validate holds when validated is not true)

No validated:false remains in any code path (only in comments documenting the
contract). The machine has no stale branches.
---
 bin/pagespace.mjs            |  8 +++-----
 src/onboarding.ts            | 10 ++++------
 test/unit/onboarding.test.ts | 11 +++++++----
 3 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 1c8bc12..90793b1 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -374,20 +374,18 @@ async function runOnboarding() {
   if (!token) { console.error("pagespace: no token entered — nothing saved."); process.exit(1); }
   state = nextOnboardingStep(state, { token });
 
-  // STEP validate: auth ping. On failure, advance the machine with validated:false (exercises its
-  // real transition — clears the token, returns to the token step) then exit, so the machine's
-  // recovery path is coherent with production behavior rather than dead code.
+  // 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) {
-      state = nextOnboardingStep(state, { validated: false });
       console.error(`pagespace: token rejected by ${base} (HTTP ${res.status}).`);
       process.exit(1);
     }
     state = nextOnboardingStep(state, { validated: true });
   } catch (err) {
-    state = nextOnboardingStep(state, { validated: false });
     console.error(`pagespace: cannot reach ${base} (${err.message}).`);
     process.exit(1);
   }
diff --git a/src/onboarding.ts b/src/onboarding.ts
index c48690a..6e6b4a9 100644
--- a/src/onboarding.ts
+++ b/src/onboarding.ts
@@ -84,12 +84,10 @@ export function nextOnboardingStep(state: OnboardingState, input: OnboardingInpu
       break;
     }
     case "validate": {
-      if (input.validated) {
-        next.step = "drives";
-      } else {
-        next.step = "token";
-        next.token = null; // clear the rejected token
-      }
+      // 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": {
diff --git a/test/unit/onboarding.test.ts b/test/unit/onboarding.test.ts
index fbd4723..570cf76 100644
--- a/test/unit/onboarding.test.ts
+++ b/test/unit/onboarding.test.ts
@@ -42,11 +42,14 @@ test("nextOnboardingStep advances validate→drives when token validates", () =>
   assert.equal(out.step, "drives");
 });
 
-test("nextOnboardingStep returns to token when validation fails", () => {
+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, { validated: false });
-  assert.equal(out.step, "token");
-  assert.equal(out.token, null, "clears the bad token");
+  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", () => {

From 112489bbcc77b16c5540fcd17d0035e38df8abb4 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Mon, 22 Jun 2026 08:05:36 -0500
Subject: [PATCH 16/20] =?UTF-8?q?fix(security):=20resolve=20auth=20token?=
 =?UTF-8?q?=20from=20credential=20store=20=E2=80=94=20isolation=20without?=
 =?UTF-8?q?=20amputating=20auth?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CRITICAL review fix (PR #68). The token-isolation mechanism stripped PAGESPACE_AUTH_TOKEN from pi child env, but the extension reads the token only via process.env — so the credential-store flow (the recommended path) launched a brain that could not authenticate (brain.ts threw; provider got apiKey: undefined). The credential store was write-only from the harness.

Fix: loadConfig() resolves the token via resolveAuthToken() (pure helper, injectable credential reader) — env wins, falls back to readCredentials(). Token travels launcher->store->disk->loadConfig->provider without entering spawned pi env. Isolation holds AND auth works.

Adds the missing isolated-AND-authenticated proof: sanitized child env (token absent) + credential-store fallback yields non-empty authToken.

Tests: resolveAuthToken store-fallback, both-unset, env-precedence; new isolation+auth E2E in run-token-isolation.ts.
---
 src/config.ts               | 30 +++++++++++++++++++-------
 test/run-token-isolation.ts | 22 +++++++++++++++++++
 test/unit/config.test.ts    | 42 +++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 8 deletions(-)
 create mode 100644 test/unit/config.test.ts

diff --git a/src/config.ts b/src/config.ts
index e588d21..894c581 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,3 +1,5 @@
+import { readCredentials, type CredentialRecord } 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 */
@@ -62,9 +64,21 @@ export function resolveDefaultDrive(env: {
     .find(Boolean);
 }
 
-export function loadConfig(): PageSpaceConfig {
-  const configuredPrimary = process.env.PAGESPACE_MODEL_PAGE?.trim();
-  const modelPageIds = (process.env.PAGESPACE_MODEL_PAGES ?? "")
+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);
@@ -72,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: resolveDefaultDrive(process.env) ?? process.env.PAGESPACE_DRIVE,
-    mountPrefix: process.env.PAGESPACE_MOUNT ?? "pagespace",
+    apiUrl: env.PAGESPACE_API_URL ?? "https://pagespace.ai",
+    authToken: resolveAuthToken(env, readCredential),
+    defaultDriveSlug: resolveDefaultDrive(env) ?? env.PAGESPACE_DRIVE,
+    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/test/run-token-isolation.ts b/test/run-token-isolation.ts
index 8e2d80c..0d3ea9a 100644
--- a/test/run-token-isolation.ts
+++ b/test/run-token-isolation.ts
@@ -17,6 +17,7 @@ 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");
@@ -55,3 +56,24 @@ test("token is invisible through the bash-tool env path (env / printenv / procfs
     );
   }
 });
+
+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..fdabf10
--- /dev/null
+++ b/test/unit/config.test.ts
@@ -0,0 +1,42 @@
+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");
+});

From bfb47240371305753c9b6c5b767e2a68becd6ace Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Mon, 22 Jun 2026 08:07:24 -0500
Subject: [PATCH 17/20] fix(security): block .env secret injection into pi env
 + drop false hidden-input claim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MEDIUM review fixes (PR #68):

1) .env bypass of token isolation: the extension's loadDotenv() ran INSIDE pi and re-injected PAGESPACE_AUTH_TOKEN from disk into pi process.env, where the bash tool could read it. applyEnv() now skips SECRET_ENV_KEYS so isolation is uniform across all token sources (credential store AND .env).

2) login/onboarding prompts claimed '(input is hidden)' but readline echoes input over a normal TTY — the token was visible. Honest copy now: 'Paste your PageSpace token:'. Comments corrected.

Test: applyEnv never injects secret keys from .env into process env.
---
 bin/pagespace.mjs     |  8 ++++----
 src/env.ts            |  1 +
 test/unit/env.test.ts | 12 ++++++++++++
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 90793b1..ca71d23 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -322,9 +322,9 @@ 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 (input is hidden): ");
-  // Read the token from stdin (tty off mode so it doesn't echo). Node has no built-in hidden prompt,
-  // so we read a line as-is — the token is written straight to the credential store, never to env.
+  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 });
@@ -366,7 +366,7 @@ async function runOnboarding() {
 
   // STEP token: capture.
   process.stderr.write("pagespace · first run — let's get you set up.\n");
-  process.stderr.write("Paste your PageSpace token (input is hidden): ");
+  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;
diff --git a/src/env.ts b/src/env.ts
index ffcb109..0b22ede 100644
--- a/src/env.ts
+++ b/src/env.ts
@@ -67,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/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"]);
+});

From 1d3fcc5a496fbbeea6158741ab34169552545ef3 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Mon, 22 Jun 2026 08:08:55 -0500
Subject: [PATCH 18/20] fix(bin): resolve effective token in statusDoctor + fix
 main() indentation

LOW review fixes (PR #68):

1) statusDoctor could ping with 'Bearer undefined' when only the credential store existed (hasCredentials true but env token unset). Now resolves the effective token once via resolveAuthToken() with a try/catch guard over readCredentials(), and pings only when the token is non-empty. Removes fragile implicit coupling on loadCredentials() ordering.

2) main() body was dedented to column 0; re-indented to 2-space scope. Cosmetic (bin/*.mjs is not biome-linted).
---
 bin/pagespace.mjs | 46 ++++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index ca71d23..6b21447 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -33,7 +33,7 @@ if (!isTsx) {
 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 } from "../src/config.ts";
+import { resolveDefaultDrive, resolveAuthToken } from "../src/config.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.
@@ -109,12 +109,18 @@ async function statusDoctor() {
   // 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 hasToken = !!(process.env.PAGESPACE_AUTH_TOKEN && process.env.PAGESPACE_AUTH_TOKEN.trim());
-  const token = process.env.PAGESPACE_AUTH_TOKEN;
+  const token = resolveAuthToken(process.env, () => {
+    try {
+      return readCredentials();
+    } catch {
+      return null;
+    }
+  });
+  const hasToken = !!(token && token.trim());
 
   let reachable;
   let driveCount;
-  if (hasToken || hasCredentials) {
+  if (hasToken) {
     try {
       const res = await fetch(`${apiUrl}/api/drives`, { headers: { authorization: `Bearer ${token}` } });
       reachable = res.ok;
@@ -437,22 +443,22 @@ function needsOnboarding() {
 }
 
 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));
-}
+  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).

From 015512ef9167911e8f05060d1ac3858897efbea7 Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Mon, 22 Jun 2026 09:28:42 -0500
Subject: [PATCH 19/20] =?UTF-8?q?fix(review):=20valid=20inline-comment=20f?=
 =?UTF-8?q?indings=20=E2=80=94=20whitespace,=20type=20guards,=20env=20dedu?=
 =?UTF-8?q?p?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Triage of 11 inline review comments; 10 valid, 1 skipped (doctor hasToken is intentional credential-store path, pure fn can't read files).

config.ts: drop ?? env.PAGESPACE_DRIVE fallback (resolveDefaultDrive already trims); use shared DEFAULT_API_URL.

credentials.ts: type guards in validateCredentialRecord (reject non-string JSON fields, no TypeError); buildCredentialRecord rejects whitespace-only apiUrl.

onboarding.ts: distinguish empty discovery (recoverable, advance) from undefined (hold, wait for result).

doctor.ts: import shared DEFAULT_API_URL (DRY, no drift).

bin: import sanitizeChildEnv/SECRET_ENV_KEYS from src/env.ts (no mirroring).

Tests: whitespace DRIVE leak, non-string credential fields, whitespace apiUrl, models hold-vs-advance. 199 passing.
---
 bin/pagespace.mjs             | 10 ++--------
 src/config.ts                 |  6 +++---
 src/credentials.ts            | 10 ++++++----
 src/doctor.ts                 |  3 +--
 src/onboarding.ts             |  5 +++--
 test/unit/config.test.ts      |  5 +++++
 test/unit/credentials.test.ts | 27 +++++++++++++++++++++++++++
 test/unit/onboarding.test.ts  | 12 ++++++++++++
 8 files changed, 59 insertions(+), 19 deletions(-)

diff --git a/bin/pagespace.mjs b/bin/pagespace.mjs
index 6b21447..619d8ac 100755
--- a/bin/pagespace.mjs
+++ b/bin/pagespace.mjs
@@ -34,6 +34,7 @@ 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.
@@ -96,14 +97,7 @@ loadDotenv();
 })();
 
 // 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). Mirrors src/env.ts.
-const SECRET_ENV_KEYS = ["PAGESPACE_AUTH_TOKEN"];
-function sanitizeChildEnv(env) {
-  const out = { ...env };
-  for (const key of SECRET_ENV_KEYS) delete out[key];
-  return out;
-}
-
+// (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.
diff --git a/src/config.ts b/src/config.ts
index 894c581..fa8828b 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,4 +1,4 @@
-import { readCredentials, type CredentialRecord } from "./credentials.ts";
+import { readCredentials, type CredentialRecord, DEFAULT_API_URL } from "./credentials.ts";
 
 /** Runtime configuration for the PageSpace companion, resolved from env. */
 export interface PageSpaceConfig {
@@ -86,9 +86,9 @@ export function loadConfig(
   const modelPageId = ids[0];
 
   return {
-    apiUrl: env.PAGESPACE_API_URL ?? "https://pagespace.ai",
+    apiUrl: env.PAGESPACE_API_URL ?? DEFAULT_API_URL,
     authToken: resolveAuthToken(env, readCredential),
-    defaultDriveSlug: resolveDefaultDrive(env) ?? env.PAGESPACE_DRIVE,
+    defaultDriveSlug: resolveDefaultDrive(env),
     mountPrefix: env.PAGESPACE_MOUNT ?? "pagespace",
     modelPageId,
     models: ids.length > 0 ? ids.map((id) => ({ id })) : undefined,
diff --git a/src/credentials.ts b/src/credentials.ts
index 1865753..c95e49f 100644
--- a/src/credentials.ts
+++ b/src/credentials.ts
@@ -31,9 +31,11 @@ export function buildCredentialRecord(input: {
   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: (input.apiUrl ?? DEFAULT_API_URL).trim(),
+    apiUrl,
     savedAt: (input.now ?? (() => new Date()))().toISOString(),
   };
 }
@@ -58,10 +60,10 @@ export function parseCredentialRecord(body: string): CredentialRecord {
 /** Validate a candidate credential record; returns a list of human-readable errors. Pure. */
 export function validateCredentialRecord(rec: Partial<CredentialRecord>): string[] {
   const errs: string[] = [];
-  if (!rec.token || !rec.token.trim()) errs.push("token is missing");
-  if (!rec.apiUrl || !rec.apiUrl.trim()) errs.push("apiUrl is missing");
+  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 (!rec.savedAt || !rec.savedAt.trim()) errs.push("savedAt is missing");
+  if (typeof rec.savedAt !== "string" || !rec.savedAt.trim()) errs.push("savedAt is missing");
   return errs;
 }
 
diff --git a/src/doctor.ts b/src/doctor.ts
index c6132c7..22102e8 100644
--- a/src/doctor.ts
+++ b/src/doctor.ts
@@ -6,6 +6,7 @@
  * (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 {
@@ -46,8 +47,6 @@ export interface DoctorResult {
   remediation: string;
 }
 
-const DEFAULT_API_URL = "https://pagespace.ai";
-
 /**
  * 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.
diff --git a/src/onboarding.ts b/src/onboarding.ts
index 6e6b4a9..4771946 100644
--- a/src/onboarding.ts
+++ b/src/onboarding.ts
@@ -109,11 +109,12 @@ export function nextOnboardingStep(state: OnboardingState, input: OnboardingInpu
         next.models = models;
         next.defaultModel = models[0]; // default to the first discovered model
         next.step = "default";
-      } else {
-        // No models found is recoverable (model-discovery is optional in some setups) — go done.
+      } 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": {
diff --git a/test/unit/config.test.ts b/test/unit/config.test.ts
index fdabf10..90bca18 100644
--- a/test/unit/config.test.ts
+++ b/test/unit/config.test.ts
@@ -40,3 +40,8 @@ test("loadConfig: env token wins over credential store token", () => {
   );
   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
index 6e9e3e6..be6e441 100644
--- a/test/unit/credentials.test.ts
+++ b/test/unit/credentials.test.ts
@@ -5,6 +5,7 @@ import {
   parseCredentialRecord,
   credentialRecordShape,
   validateCredentialRecord,
+  type CredentialRecord,
 } from "../../src/credentials.ts";
 
 test("buildCredentialRecord shapes a token + metadata into the stored record", () => {
@@ -47,6 +48,32 @@ test("validateCredentialRecord flags a missing apiUrl", () => {
   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/onboarding.test.ts b/test/unit/onboarding.test.ts
index 570cf76..30faf73 100644
--- a/test/unit/onboarding.test.ts
+++ b/test/unit/onboarding.test.ts
@@ -71,6 +71,18 @@ test("nextOnboardingStep advances models→default when models discovered", () =
   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,

From be944460a16ea4c9c84ef4510e2a572a97de436f Mon Sep 17 00:00:00 2001
From: 2witstudios <2witstudios@gmail.com>
Date: Mon, 22 Jun 2026 10:19:52 -0500
Subject: [PATCH 20/20] fix(doctor): token check must not false-green when
 credential file exists but token is unusable

The token check in diagnose() was using `!!(input.hasToken || input.hasCredentials)`, which
passes when the credential file exists even if the effective token is unreadable/corrupt.
Separate the two concerns: `hasToken` = effective token resolved by the caller, `hasCredentials`
= credential file presence (its own separate check). Add a test for the false-green scenario
and align the onboarding test to reflect the real runtime path (loadCredentials() IIFE copies
the readable credential into env before needsOnboarding() runs, so hasToken is always true
when credentials are readable at onboarding-check time).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/doctor.ts                |  6 ++++--
 test/unit/doctor.test.ts     | 13 +++++++++++++
 test/unit/onboarding.test.ts |  5 +++--
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/doctor.ts b/src/doctor.ts
index 22102e8..bdbb446 100644
--- a/src/doctor.ts
+++ b/src/doctor.ts
@@ -65,8 +65,10 @@ export function diagnose(input: DoctorInput): DoctorResult {
     remediation: "set PAGESPACE_API_URL to an http(s) URL (default: https://pagespace.ai).",
   });
 
-  // token check — present in env/.env OR in the credential store.
-  const hasToken = !!(input.hasToken || input.hasCredentials);
+  // 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",
diff --git a/test/unit/doctor.test.ts b/test/unit/doctor.test.ts
index 6c193d9..a7585c7 100644
--- a/test/unit/doctor.test.ts
+++ b/test/unit/doctor.test.ts
@@ -65,3 +65,16 @@ test("non-interactive mode: diagnose never prompts (pure, returns results only)"
   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/onboarding.test.ts b/test/unit/onboarding.test.ts
index 30faf73..ceffebf 100644
--- a/test/unit/onboarding.test.ts
+++ b/test/unit/onboarding.test.ts
@@ -121,8 +121,9 @@ test("onboardingNeedsSetup uses the doctor to decide if onboarding is needed", a
     onboardingNeedsSetup({ hasToken: true, hasCredentials: true, apiUrl: "https://pagespace.ai" }),
     false,
   );
-  // Credential store alone is enough (the Cursor-grade path).
-  assert.equal(onboardingNeedsSetup({ hasToken: false, hasCredentials: true }), 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", () => {