@runcofactor/cli 0.57.0 → 0.58.0

package/dist/{dev-D2HS5XXN.js → dev-MU45HWAN.js}

@@ -1,11 +1,14 @@
 import { createRequire as __cr } from "module"; import { fileURLToPath as __fup } from "url"; import { dirname as __dn } from "path"; const require = __cr(import.meta.url); const __filename = __fup(import.meta.url); const __dirname = __dn(__filename);
+import {
+  printServedGuide
+} from "./chunk-W43YGZOP.js";
 import {
   ProcessExitSignal
-} from "./chunk-K3MG2ZMH.js";
+} from "./chunk-RIBSXEAM.js";
 import {
   apiRequest,
   getPositionalArg
-} from "./chunk-72Y65NWI.js";
+} from "./chunk-WY4R4IL5.js";
 import "./chunk-W7CFLOEI.js";
 import "./chunk-S3Q7MDCS.js";
 import {
@@ -14,11 +17,11 @@ import {
   getArgValue,
   hasFlag,
   resolveConfig
-} from "./chunk-IIDQM4MY.js";
+} from "./chunk-BMFD4OPC.js";
 import {
   writeRawOutput
-} from "./chunk-T6ZNIMI4.js";
-import "./chunk-EYHJ5FIA.js";
+} from "./chunk-LRIP5IQD.js";
+import "./chunk-C6SNLHVE.js";
 import "./chunk-TOWZAG3I.js";
 
 // src/dev-aws.ts
@@ -424,6 +427,9 @@ if ! gh auth status --hostname github.com >/dev/null 2>&1; then
   exit 1
 fi
 
+# Persist the helper: the agent\u2019s ordinary git push must use the same HTTPS login.
+gh auth setup-git --hostname github.com
+
 template=/etc/cofactor/ade/template.json
 session=$(jq -er '.sessionId' /run/cofactor/ade/session.json)
 [[ $session =~ ^ades_([1-9A-HJ-NP-Za-km-z]{8}) ]] || { echo "ade-sync-repos: invalid session id" >&2; exit 2; }
@@ -887,6 +893,15 @@ import os2 from "os";
 import path2 from "path";
 import { createInterface as createInterface3 } from "readline/promises";
 import { stripVTControlCharacters } from "util";
+var FILE_GROUPS = [
+  "claude-settings",
+  "claude-skills",
+  "claude-memory",
+  "codex-config",
+  "shell"
+];
+var configDir = () => path2.join(os2.homedir(), ".config/cofactor/ade");
+var capture = (command2, args) => spawnSync3(command2, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 function readJson(file) {
   try {
     return JSON.parse(readFileSync3(file, "utf8"));
@@ -894,8 +909,11 @@ function readJson(file) {
     throw new Error(`Could not read ADE setup JSON at ${file}`);
   }
 }
-var configDir = () => path2.join(os2.homedir(), ".config/cofactor/ade");
-var capture = (command2, args) => spawnSync3(command2, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+function privateJson(file, value) {
+  mkdirSync2(path2.dirname(file), { recursive: true, mode: 448 });
+  if (existsSync2(file)) chmodSync(file, 384);
+  writeFileSync3(file, JSON.stringify(value), { mode: 384 });
+}
 async function ask(question, yes) {
   const input = createInterface3({ input: process.stdin, output: process.stdout });
   try {
@@ -905,11 +923,6 @@ async function ask(question, yes) {
     input.close();
   }
 }
-function privateJson(file, value) {
-  mkdirSync2(path2.dirname(file), { recursive: true, mode: 448 });
-  if (existsSync2(file)) chmodSync(file, 384);
-  writeFileSync3(file, JSON.stringify(value), { mode: 384 });
-}
 function collect(relative, destination = relative) {
   let ancestor = os2.homedir();
   for (const part of relative.split("/")) {
@@ -925,6 +938,212 @@ function collect(relative, destination = relative) {
   const stat = lstatSync2(file);
   return stat.isFile() && stat.nlink === 1 ? [{ source: relative, path: destination, size: stat.size }] : [];
 }
+function fileGroups() {
+  const repo = capture("git", ["worktree", "list", "--porcelain"]).stdout.split("\n").find((line) => line.startsWith("worktree "))?.slice(9);
+  const remote = capture("git", ["remote", "get-url", "origin"]).stdout.trim();
+  const repoName = remote.match(/\/([^/]+?)(?:\.git)?$/)?.[1];
+  return {
+    "claude-settings": collect(".claude/settings.json"),
+    "claude-skills": collect(".claude/skills"),
+    "claude-memory": repo && repoName ? collect(
+      `.claude/projects/${repo.replace(/[^a-zA-Z0-9]/g, "-")}/memory`,
+      `.claude/projects/-workspace-${repoName}/memory`
+    ) : [],
+    "codex-config": [...collect(".codex/config.toml"), ...collect(".codex/AGENTS.md")],
+    shell: [".bashrc", ".bash_profile", ".zshrc", ".profile", ".inputrc"].flatMap(
+      (file) => collect(file)
+    )
+  };
+}
+function claudeToken() {
+  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) return process.env.CLAUDE_CODE_OAUTH_TOKEN;
+  const file = path2.join(configDir(), "claude-setup-token.json");
+  if (!existsSync2(file)) return null;
+  const cached = readJson(file);
+  return typeof cached === "object" && cached !== null && "token" in cached && typeof cached.token === "string" && cached.token ? cached.token : null;
+}
+function gitIdentity() {
+  const name = capture("git", ["config", "--global", "user.name"]).stdout.trim();
+  const email = capture("git", ["config", "--global", "user.email"]).stdout.trim();
+  return name && email ? { name, email } : null;
+}
+function inspectLaptopSetup(template) {
+  const saved = savedChoices();
+  const github = capture("gh", ["auth", "status", "--hostname", "github.com"]).status === 0;
+  const claude = Boolean(claudeToken());
+  const identity = Boolean(gitIdentity());
+  const groups = fileGroups();
+  const option = (value, flag, consequence) => ({
+    value,
+    flag,
+    consequence
+  });
+  const plan = {
+    template,
+    decisions: [
+      {
+        id: "github",
+        current: saved?.github ?? null,
+        question: "Use your existing GitHub login to clone and push repositories in the ADE?",
+        found: [
+          github ? "GitHub CLI is signed in on this laptop (credential hidden)." : "No usable GitHub CLI login found."
+        ],
+        recommendedDefault: github ? "token" : "none",
+        options: [
+          option(
+            "token",
+            "--github=token",
+            "Send the existing gh token privately to ~/.config/gh/hosts.yml. Clone and push over HTTPS with gh auth git-credential; no new GitHub key or deploy key is created."
+          ),
+          option(
+            "none",
+            "--github=none",
+            "Send no GitHub token. Sign in with a browser inside the ADE before private repositories can clone or push."
+          )
+        ]
+      },
+      {
+        id: "claude",
+        current: saved?.claude ?? null,
+        question: "Use a dedicated Claude token to avoid signing in again inside the ADE?",
+        found: [
+          claude ? "Dedicated Claude token found in CLAUDE_CODE_OAUTH_TOKEN or the local ADE cache (value hidden)." : "No dedicated Claude token found in the environment or ADE cache."
+        ],
+        recommendedDefault: claude ? "token" : "in-box",
+        options: [
+          option(
+            "token",
+            "--claude=token",
+            "Send the dedicated token privately to ~/.config/cofactor/ade-env.sh. Browser approval is needed on the laptop if no token is available. Laptop OAuth refresh credentials are excluded."
+          ),
+          option(
+            "in-box",
+            "--claude=in-box",
+            "Send no Claude token. Complete browser sign-in from the attached ADE when Claude needs it."
+          )
+        ]
+      },
+      {
+        id: "codex-key",
+        current: saved ? saved.codexKey ? "yes" : "no" : null,
+        question: "Send the explicit OpenAI API key for Codex API billing?",
+        found: [
+          process.env.OPENAI_API_KEY ? "OPENAI_API_KEY is present (value hidden)." : "OPENAI_API_KEY is absent."
+        ],
+        recommendedDefault: "no",
+        options: [
+          option(
+            "yes",
+            "--codex-key=yes",
+            "Send OPENAI_API_KEY privately to ~/.config/cofactor/ade-env.sh. Codex uses API billing; requires the key in this command\u2019s environment."
+          ),
+          option(
+            "no",
+            "--codex-key=no",
+            "Send no API key. Use browser sign-in inside the ADE if Codex is selected. Codex OAuth auth.json is never copied."
+          )
+        ]
+      },
+      {
+        id: "git-identity",
+        current: saved ? saved.gitIdentity ? "yes" : "no" : null,
+        question: "Use the laptop\u2019s global git author name and email for commits in the ADE?",
+        found: [
+          identity ? "Both global git user.name and user.email are configured." : "Global git user.name or user.email is missing."
+        ],
+        recommendedDefault: identity ? "yes" : "no",
+        options: [
+          option(
+            "yes",
+            "--git-identity=yes",
+            "Write the global author name and email to the guest ~/.gitconfig. This does not authenticate GitHub or create a key."
+          ),
+          option(
+            "no",
+            "--git-identity=no",
+            "Send no identity. Configure git user.name and user.email inside the ADE before committing."
+          )
+        ]
+      },
+      {
+        id: "include",
+        current: saved ? saved.include.join(",") || "none" : null,
+        question: "Which optional settings and dotfiles should be copied to each new ADE home?",
+        found: FILE_GROUPS.map(
+          (group) => `${group}: ${groups[group].length ? groups[group].map((file) => `~/${file.source} \u2192 guest ~/${file.path} (${file.size} bytes)`).join("; ") : "no eligible files found"}`
+        ),
+        recommendedDefault: "none",
+        options: [
+          option("none", "--include=none", "Copy no optional files; use the template defaults."),
+          ...FILE_GROUPS.map(
+            (group) => option(
+              group,
+              `--include=${group}`,
+              `Copy ${group} files listed above (combine groups with commas). Review their contents locally first: they may contain secrets or machine-specific commands. Claude settings.env is removed; symlinks and hardlinks are excluded.`
+            )
+          )
+        ]
+      }
+    ],
+    needsYou: [
+      ...!github ? [
+        {
+          id: "github",
+          reason: "Browser required only if you choose --github=token; otherwise sign in inside the ADE.",
+          command: "!gh auth login --hostname github.com --git-protocol https --web"
+        }
+      ] : [],
+      ...!claude ? [
+        {
+          id: "claude",
+          reason: "Browser required only if you choose --claude=token. Run locally, then export the dedicated token as CLAUDE_CODE_OAUTH_TOKEN in the setup command\u2019s environment. Keep the value out of chat and logs.",
+          command: "!claude setup-token"
+        }
+      ] : []
+    ]
+  };
+  return {
+    ...plan,
+    suggestedCommand: `cofactor dev setup --yes ${plan.decisions.map((decision) => `--${decision.id}=${decision.current ?? decision.recommendedDefault}`).join(" ")}`
+  };
+}
+function savedChoices() {
+  const file = path2.join(configDir(), "setup-answers.json");
+  if (!existsSync2(file)) return null;
+  const saved = readJson(file);
+  if (typeof saved !== "object" || saved === null || Array.isArray(saved))
+    throw new Error("Invalid saved ADE choices; run `cofactor dev setup --plan`.");
+  const s = saved;
+  if (typeof s.github === "boolean" && typeof s.claude === "boolean") {
+    const oldGroups = {
+      claudeSettings: "claude-settings",
+      claudeSkills: "claude-skills",
+      claudeMemory: "claude-memory",
+      codexConfig: "codex-config",
+      shell: "shell"
+    };
+    return {
+      github: s.github ? "token" : "none",
+      claude: s.claude ? "token" : "in-box",
+      codexKey: s.codexKey === true,
+      gitIdentity: s.identity === true,
+      include: Object.entries(oldGroups).flatMap(
+        ([key, group]) => s[key] === true ? [group] : []
+      )
+    };
+  }
+  if (s.github !== "token" && s.github !== "none" || s.claude !== "token" && s.claude !== "in-box" || typeof s.codexKey !== "boolean" || typeof s.gitIdentity !== "boolean" || !Array.isArray(s.include) || !s.include.every(
+    (group) => typeof group === "string" && FILE_GROUPS.some((allowed) => allowed === group)
+  ))
+    throw new Error("Invalid saved ADE choices; run `cofactor dev setup --plan`.");
+  return {
+    github: s.github,
+    claude: s.claude,
+    codexKey: s.codexKey,
+    gitIdentity: s.gitIdentity,
+    include: s.include
+  };
+}
 async function setupToken() {
   console.log(
     "Creating a dedicated Claude token on this laptop. Complete the browser approval locally."
@@ -970,169 +1189,111 @@ async function setupToken() {
     });
   });
 }
-async function prepareLaptopSetup(edit = false) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    if (edit)
-      throw new Error("ADE setup needs a laptop terminal. Run `cofactor dev setup` interactively.");
-    console.log("ADE: no laptop terminal for setup; attach will offer the in-box sign-in flow.");
-    return null;
-  }
-  const answersFile = path2.join(configDir(), "setup-answers.json");
-  const saved = existsSync2(answersFile) ? readJson(answersFile) : {};
-  if (typeof saved !== "object" || saved === null || Array.isArray(saved))
-    throw new Error("Invalid saved ADE choices; run `cofactor dev setup`.");
-  const choices = {};
-  for (const [key, value] of Object.entries(saved))
-    if (typeof value === "boolean") choices[key] = value;
-  const choose = async (key, label, preview, defaultYes) => {
+async function prepareLaptopSetup(options = {}) {
+  let choices = options.choices ?? (!options.edit ? savedChoices() : null);
+  const interactive = !choices;
+  if (!choices) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      if (options.edit)
+        throw new Error(
+          "No terminal: run `cofactor dev setup --plan`, then `cofactor dev setup --yes` with every decision flag."
+        );
+      console.log(
+        "ADE: no saved laptop choices; run `cofactor dev setup --plan` to prepare unattended. Attach will offer browser sign-in inside the ADE."
+      );
+      return null;
+    }
+    const plan = inspectLaptopSetup({ name: "claim", repos: [] });
+    const saved = savedChoices();
+    const answers = {};
+    for (const decision of plan.decisions.filter((d) => d.id !== "include")) {
+      console.log(`
+${decision.question}`);
+      for (const found of decision.found) console.log(`  ${found}`);
+      for (const option of decision.options) console.log(`  ${option.flag}: ${option.consequence}`);
+      const prior = decision.id === "github" ? saved ? saved.github === "token" : void 0 : decision.id === "claude" ? saved ? saved.claude === "token" : void 0 : decision.id === "codex-key" ? saved?.codexKey : saved?.gitIdentity;
+      answers[decision.id] = await ask(
+        `Choose ${decision.options[0].flag}?`,
+        prior ?? decision.recommendedDefault === decision.options[0].value
+      );
+    }
+    const include = [];
+    const files = plan.decisions.find((d) => d.id === "include");
     console.log(`
-${label}:`);
-    for (const item of preview) console.log(`  ${item}`);
-    if (!edit && key in choices) {
-      console.log(`  Cached choice: ${choices[key] ? "include" : "skip"}`);
-      return choices[key];
+${files.question}`);
+    for (const group of FILE_GROUPS) {
+      console.log(`  ${files.found.find((found) => found.startsWith(`${group}:`))}`);
+      if (await ask(
+        `${files.options.find((option) => option.value === group).consequence} Include ${group}?`,
+        saved?.include.includes(group) ?? false
+      ))
+        include.push(group);
     }
-    choices[key] = await ask(`Include ${label.toLowerCase()}?`, choices[key] ?? defaultYes);
-    return choices[key];
-  };
+    choices = {
+      github: answers.github ? "token" : "none",
+      claude: answers.claude ? "token" : "in-box",
+      codexKey: answers["codex-key"],
+      gitIdentity: answers["git-identity"],
+      include
+    };
+  }
   const result = { files: [], env: {}, githubToken: null, git: null };
-  console.log(
-    "Prepare your ADE from this laptop. Secret values are hidden. Nothing is copied until the final preview is confirmed."
-  );
-  if (await choose(
-    "github",
-    "GitHub login",
-    ["Current gh login \u2192 ~/.config/gh/hosts.yml (token hidden)"],
-    true
-  )) {
+  if (choices.github === "token") {
     let status = capture("gh", ["auth", "status", "--hostname", "github.com"]);
-    if (status.status !== 0 && await ask("Sign in to GitHub on this laptop now?", true)) {
+    if (interactive && status.status !== 0 && await ask("Browser required: sign in to GitHub on this laptop now?", true))
       status = spawnSync3(
         "gh",
         ["auth", "login", "--hostname", "github.com", "--git-protocol", "https", "--web"],
         { encoding: "utf8", stdio: "inherit" }
       );
-    }
-    if (status.status === 0) {
-      const token = capture("gh", ["auth", "token", "--hostname", "github.com"]);
-      if (token.status === 0) result.githubToken = token.stdout.trim();
-    }
-    if (!result.githubToken)
-      console.log(
-        "GitHub login unavailable locally; the box will offer browser-forwarded sign-in."
+    const token = status.status === 0 ? capture("gh", ["auth", "token", "--hostname", "github.com"]) : null;
+    if (token?.status !== 0 || !token.stdout.trim())
+      throw new Error(
+        "GitHub token unavailable. Run `cofactor dev setup --plan` for the browser sign-in command or choose --github=none."
       );
+    result.githubToken = token.stdout.trim();
   }
-  const name = capture("git", ["config", "--global", "user.name"]).stdout.trim();
-  const email = capture("git", ["config", "--global", "user.email"]).stdout.trim();
-  if (name && email && await choose("identity", "Git identity", [`${name} <${email}> \u2192 ~/.gitconfig`], true))
-    result.git = { name, email };
-  const tokenFile = path2.join(configDir(), "claude-setup-token.json");
-  if (await choose(
-    "claude",
-    "Claude dedicated token",
-    [
-      "Dedicated setup-token \u2192 ~/.config/cofactor/ade-env.sh",
-      "Laptop OAuth refresh credentials are excluded"
-    ],
-    true
-  )) {
-    let token = process.env.CLAUDE_CODE_OAUTH_TOKEN ?? null;
-    if (!token && existsSync2(tokenFile)) {
-      const cached = readJson(tokenFile);
-      if (typeof cached === "object" && cached !== null && "token" in cached && typeof cached.token === "string")
-        token = cached.token;
-    }
-    if (!token && await ask("Create and cache a dedicated Claude token on this laptop?", true)) {
+  if (choices.claude === "token") {
+    let token = claudeToken();
+    if (!token && interactive && await ask(
+      "Browser required: create and cache a dedicated Claude token on this laptop?",
+      true
+    )) {
       token = await setupToken();
-      if (token) privateJson(tokenFile, { token });
+      if (token) privateJson(path2.join(configDir(), "claude-setup-token.json"), { token });
     }
-    if (token) result.env.CLAUDE_CODE_OAUTH_TOKEN = token;
-    else
-      console.log(
-        "Claude token unavailable locally; the box will offer browser-forwarded sign-in."
+    if (!token)
+      throw new Error(
+        "Claude dedicated token unavailable. Run `cofactor dev setup --plan` for browser approval instructions or choose --claude=in-box."
       );
+    result.env.CLAUDE_CODE_OAUTH_TOKEN = token;
   }
-  if (process.env.OPENAI_API_KEY && await choose(
-    "codexKey",
-    "Codex API key",
-    [
-      "OPENAI_API_KEY \u2192 ~/.config/cofactor/ade-env.sh (value hidden)",
-      "Codex OAuth auth.json is excluded"
-    ],
-    false
-  ))
+  if (choices.codexKey) {
+    if (!process.env.OPENAI_API_KEY)
+      throw new Error(
+        "OPENAI_API_KEY is missing. Run `cofactor dev setup --plan`, supply it privately in the environment or choose --codex-key=no."
+      );
     result.env.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
-  else if (!process.env.OPENAI_API_KEY)
-    console.log(
-      "Codex: no explicit OPENAI_API_KEY is available; subscription refresh credentials will not be copied."
-    );
-  const repo = capture("git", ["worktree", "list", "--porcelain"]).stdout.split("\n").find((line) => line.startsWith("worktree "))?.slice(9) ?? "";
-  const remote = capture("git", ["remote", "get-url", "origin"]).stdout.trim();
-  const repoName = remote.match(/\/([^/]+?)(?:\.git)?$/)?.[1];
-  const groups = [
-    {
-      key: "claudeSettings",
-      label: "Claude settings",
-      files: collect(".claude/settings.json"),
-      yes: false
-    },
-    { key: "claudeSkills", label: "Claude skills", files: collect(".claude/skills"), yes: false },
-    {
-      key: "claudeMemory",
-      label: "Claude repo memory",
-      files: repo && repoName ? collect(
-        `.claude/projects/${repo.replace(/[^a-zA-Z0-9]/g, "-")}/memory`,
-        `.claude/projects/-workspace-${repoName}/memory`
-      ) : [],
-      yes: false
-    },
-    {
-      key: "codexConfig",
-      label: "Codex config",
-      files: [...collect(".codex/config.toml"), ...collect(".codex/AGENTS.md")],
-      yes: false
-    },
-    {
-      key: "shell",
-      label: "Shell dotfiles",
-      files: [".bashrc", ".bash_profile", ".zshrc", ".profile", ".inputrc"].flatMap(
-        (file) => collect(file)
-      ),
-      yes: false
-    },
-    {
-      key: "ssh",
-      label: "SSH keys and config",
-      files: collect(".ssh").filter(
-        (file) => /^\.ssh\/(config|config\.d\/.+|id_[a-zA-Z0-9_.-]+)$/.test(file.path)
-      ),
-      yes: false
-    }
-  ];
-  const selected = [];
-  for (const group of groups) {
-    if (!group.files.length) continue;
-    if (await choose(
-      group.key,
-      group.label,
-      group.files.map((file) => `~/${file.source} \u2192 guest ~/${file.path}`),
-      group.yes
-    ))
-      selected.push(...group.files);
   }
+  if (choices.gitIdentity) {
+    result.git = gitIdentity();
+    if (!result.git)
+      throw new Error(
+        "Global git identity is incomplete. Run `cofactor dev setup --plan`, configure git user.name and user.email or choose --git-identity=no."
+      );
+  }
+  const groups = fileGroups();
+  const selected = choices.include.flatMap((group) => groups[group]);
   console.log("\nTransfer preview (your own new session only; files mode 0600):");
-  if (result.githubToken) console.log("  ~/.config/gh/hosts.yml: selected GitHub token (hidden)");
-  if (result.git) console.log("  ~/.gitconfig: selected identity");
+  if (result.githubToken)
+    console.log("  gh login \u2192 guest ~/.config/gh/hosts.yml (token hidden; HTTPS clone and push)");
+  if (result.git) console.log("  global git author \u2192 guest ~/.gitconfig");
   for (const key of Object.keys(result.env))
-    console.log(`  ~/.config/cofactor/ade-env.sh: ${key} (hidden)`);
+    console.log(`  ${key} \u2192 guest ~/.config/cofactor/ade-env.sh (value hidden)`);
   for (const file of selected)
-    console.log(
-      `  ~/${file.path} (${file.size} bytes${file.path === ".claude/settings.json" ? "; credential environment excluded" : ""})`
-    );
-  console.log(
-    "  Managed ADE startup/browser helpers \u2192 ~/.local/share/cofactor/bin/ (executables mode 0700)"
-  );
-  if (!await ask("Send these items to each new ADE session using these choices?", true))
+    console.log(`  ~/${file.source} \u2192 guest ~/${file.path} (${file.size} bytes)`);
+  console.log("  Managed startup/browser helpers \u2192 guest ~/.local/share/cofactor/bin/ (0700)");
+  if (interactive && !await ask("Send these items to each new ADE session using these choices?", true))
     return null;
   for (const file of selected) {
     let content = readFileSync3(path2.join(os2.homedir(), file.source));
@@ -1145,10 +1306,106 @@ ${label}:`);
     }
     result.files.push({ path: file.path, content: content.toString("base64") });
   }
-  privateJson(answersFile, choices);
+  privateJson(path2.join(configDir(), "setup-answers.json"), choices);
   return result;
 }
 
+// src/dev-setup.ts
+function parseSetupArgs(argv) {
+  const values = /* @__PURE__ */ new Map();
+  const switches = /* @__PURE__ */ new Set();
+  const decisionFlags = ["--github", "--claude", "--codex-key", "--git-identity", "--include"];
+  function invalid(reason) {
+    throw new Error(
+      `${reason} Run \`cofactor dev setup --plan\` to review decisions and exact flags.`
+    );
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const equals = arg.indexOf("=");
+    const flag = equals === -1 ? arg : arg.slice(0, equals);
+    if (["--plan", "--json", "--yes"].includes(flag)) {
+      if (equals !== -1 || switches.has(flag)) invalid("Invalid or duplicate setup switch.");
+      switches.add(flag);
+    } else if ([...GLOBAL_VALUE_FLAGS, "--template", ...decisionFlags].includes(flag)) {
+      if (values.has(flag)) invalid("Duplicate setup flag.");
+      const value = equals === -1 ? argv[++i] : arg.slice(equals + 1);
+      if (!value || value.startsWith("--")) invalid("A setup flag requires a value.");
+      values.set(flag, value);
+    } else invalid("Unknown setup option.");
+  }
+  const plan = switches.has("--plan");
+  const yes = switches.has("--yes");
+  if (plan && (yes || decisionFlags.some((flag) => values.has(flag))))
+    invalid("--plan cannot apply decisions.");
+  if (switches.has("--json") && !plan) invalid("--json requires --plan.");
+  if (!yes && decisionFlags.some((flag) => values.has(flag)))
+    invalid("Decision flags require --yes.");
+  if (!yes) return { plan, json: switches.has("--json") };
+  for (const flag of decisionFlags)
+    if (!values.has(flag)) invalid(`Missing required decision ${flag}.`);
+  const github = values.get("--github");
+  const claude = values.get("--claude");
+  const codexKey = values.get("--codex-key");
+  const identity = values.get("--git-identity");
+  if (github !== "token" && github !== "none") invalid("--github accepts token or none.");
+  if (claude !== "token" && claude !== "in-box") invalid("--claude accepts token or in-box.");
+  if (codexKey !== "yes" && codexKey !== "no") invalid("--codex-key accepts yes or no.");
+  if (identity !== "yes" && identity !== "no") invalid("--git-identity accepts yes or no.");
+  const include = values.get("--include") === "none" ? [] : values.get("--include").split(",");
+  if (!include.every(
+    (group) => FILE_GROUPS.some((allowed) => group === allowed)
+  ) || new Set(include).size !== include.length)
+    invalid(`--include accepts none or a comma-separated list of ${FILE_GROUPS.join(", ")}.`);
+  return {
+    plan,
+    json: false,
+    choices: {
+      github,
+      claude,
+      codexKey: codexKey === "yes",
+      gitIdentity: identity === "yes",
+      include
+    }
+  };
+}
+async function runLaptopSetup(args, template) {
+  if (args.plan) {
+    const plan = inspectLaptopSetup(template);
+    if (args.json) console.log(JSON.stringify(plan, null, 2));
+    else {
+      console.log(
+        `ADE setup plan for ${template.name} (read-only; no files sent or choices saved).`
+      );
+      console.log(`Repositories: ${template.repos.join(", ")} (HTTPS via GitHub login)`);
+      for (const decision of plan.decisions) {
+        console.log(`
+${decision.question} [${decision.id}]`);
+        for (const found of decision.found) console.log(`  Found: ${found}`);
+        console.log(`  Current: ${decision.current ?? "no saved choice"}`);
+        console.log(`  Recommended: ${decision.recommendedDefault}`);
+        for (const option of decision.options)
+          console.log(`  ${option.flag}: ${option.consequence}`);
+      }
+      for (const step of plan.needsYou)
+        console.log(`
+Needs you (${step.id}): ${step.reason}
+  ${step.command}`);
+      console.log(
+        `
+Suggested command (saved choices when present, otherwise recommended defaults):
+  ${plan.suggestedCommand}
+Ask the user to review and edit the choices before applying. Keep the same org, environment and template selectors. Read \`cofactor dev guide\` for the agent procedure.`
+      );
+    }
+    return;
+  }
+  const setup = await prepareLaptopSetup({ edit: true, choices: args.choices });
+  console.log(
+    setup ? "ADE laptop setup choices saved for new homes; subsequent claims use them without prompts. Prepared homes reuse their saved files." : "ADE setup cancelled; choices were not saved."
+  );
+}
+
 // src/dev-home-transfer.ts
 import { spawnSync as spawnSync4 } from "child_process";
 var RECEIVE = String.raw`
@@ -1158,7 +1415,7 @@ try { input = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { console.error('A
 process.umask(0o077);
 const home = os.homedir();
 function write(relative, bytes, mode = 0o600) {
-  if (typeof relative !== 'string' || relative.startsWith('/') || relative.split('/').some(x => !x || x === '.' || x === '..')) throw Error('invalid home destination');
+  if (typeof relative !== 'string' || relative.startsWith('/') || relative.split('/')[0] === '.ssh' || relative.split('/').some(x => !x || x === '.' || x === '..')) throw Error('invalid home destination');
   let current = home;
   for (const part of relative.split('/')) {
     current = path.join(current, part);
@@ -1205,13 +1462,24 @@ try {
 `;
 var quote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
 function deliverLaptopSetup(alias, setup) {
-  const stop = spawnSync4("ssh", ["-T", alias, "tmux kill-session -t ade 2>/dev/null || true"], { stdio: ["ignore", "ignore", "inherit"] });
-  if (stop.status !== 0) throw new Error("Could not prepare the new ADE terminal for laptop setup.");
+  const stop = spawnSync4("ssh", ["-T", alias, "tmux kill-session -t ade 2>/dev/null || true"], {
+    stdio: ["ignore", "ignore", "inherit"]
+  });
+  if (stop.status !== 0)
+    throw new Error("Could not prepare the new ADE terminal for laptop setup.");
   const received = spawnSync4("ssh", ["-T", alias, `node -e ${quote(RECEIVE)}`], {
-    input: JSON.stringify({ ...setup, browser: ADE_OPEN_SCRIPT, start: ADE_START_SCRIPT, sync: ADE_SYNC_SCRIPT }),
+    input: JSON.stringify({
+      ...setup,
+      browser: ADE_OPEN_SCRIPT,
+      start: ADE_START_SCRIPT,
+      sync: ADE_SYNC_SCRIPT
+    }),
     stdio: ["pipe", "inherit", "inherit"]
   });
-  if (received.status !== 0) console.error("ADE: laptop delivery is incomplete; continuing with browser-forwarded setup in the box.");
+  if (received.status !== 0)
+    console.error(
+      "ADE: laptop delivery is incomplete; continuing with browser-forwarded setup in the box."
+    );
   return received.status === 0;
 }
 
@@ -1228,7 +1496,9 @@ function printHelp() {
       "",
       "Sub-commands:",
       "  (none) [--template <name>]  Claim a session and attach when its home is mounted (sign-in/setup may still need you). --template is required when the org has several",
-      "  setup                       Review laptop logins and files before sending them to new sessions",
+      "  setup [--plan [--json]]      Inspect laptop setup read-only; show decisions and browser-only steps",
+      "  setup --yes <decisions>      Save explicit choices without prompts (see --plan for exact flags)",
+      "  guide [section] [--json]     Agent guide: plan, ask the user, apply choices, then claim",
       "  attach [<id>]               SSH into a session (your only live one by default) from this machine. Makes",
       "                              ~/.config/cofactor/ade/id_ed25519 (no passphrase) once; each grant lasts 12 h",
       "  proxy <id>                  The SSH ProxyCommand `cofactor dev attach` writes; not run by hand",
@@ -1419,10 +1689,12 @@ function printSession(session) {
       `  ended: ${session.endReason}${session.endDetail ? ` (${session.endDetail})` : ""}`
     );
 }
-async function templateToClaim(argv, apiUrl, token) {
+async function templateToClaim(argv, apiUrl, token, templates) {
   const given = getArgValue(argv, "--template");
   if (given) return given;
-  const names = new Set((await allTemplates(apiUrl, token)).map((template) => template.name));
+  const names = new Set(
+    (templates ?? await allTemplates(apiUrl, token)).map((template) => template.name)
+  );
   if (names.size === 1) return [...names][0];
   if (names.size === 0)
     fail(
@@ -1574,17 +1846,31 @@ async function runDev(argv) {
     await awsCredentials(argv.slice(1));
     return;
   }
-  if (group === "setup") {
-    await prepareLaptopSetup(true);
-    console.log(
-      "ADE laptop setup choices saved for new homes; prepared homes reuse their saved files."
-    );
+  if (group === "guide") {
+    await printServedGuide("dev", argv.slice(1));
     return;
   }
   if (group === "help" || hasFlag(argv, "--help", "-h")) {
     printHelp();
     return;
   }
+  if (group === "setup") {
+    const args = argv.slice(1);
+    const setupArgs = parseSetupArgs(args);
+    const { apiUrl: apiUrl2, token: token2 } = await resolveConfig(args);
+    const templates = await allTemplates(apiUrl2, token2);
+    const name = await templateToClaim(args, apiUrl2, token2, templates);
+    const template = templates.find(
+      (template2) => template2.name === name && template2.status === "ready"
+    );
+    if (!template) fail("No ready version of the selected ADE template.");
+    if (!Array.isArray(template.repos))
+      fail(
+        "The ADE API must be updated to provide template repositories before setup can be planned."
+      );
+    await runLaptopSetup(setupArgs, { name, repos: template.repos });
+    return;
+  }
   if (group === void 0 || group.startsWith("--")) {
     const { apiUrl: apiUrl2, token: token2 } = await resolveConfig(argv);
     await claim(argv, apiUrl2, token2);
@@ -1627,4 +1913,4 @@ async function runDev(argv) {
 export {
   runDev
 };
-//# sourceMappingURL=dev-D2HS5XXN.js.map
+//# sourceMappingURL=dev-MU45HWAN.js.map