@pipod/cli 0.1.5 → 0.1.7

package/dist/cli.js

@@ -6,8 +6,8 @@ import {
 } from "./chunk-GNKF75X7.js";
 
 // src/cli.ts
-import * as fs35 from "fs";
-import * as path33 from "path";
+import * as fs36 from "fs";
+import * as path34 from "path";
 
 // src/errors.ts
 var EXIT = {
@@ -4436,7 +4436,7 @@ function parseResourcePath(flag, value) {
 function sameResourceList(requested, echoed) {
   const want = requested ?? [];
   const got = echoed ?? [];
-  return want.length === got.length && want.every((path34, index) => got[index] === path34);
+  return want.length === got.length && want.every((path35, index) => got[index] === path35);
 }
 
 // src/account/launch-seed.ts
@@ -6275,7 +6275,7 @@ function splitPiArgs(piArgs) {
       if (key === "model" || key === "thinking") continue;
       const flag = PI_RESOURCE_FLAGS[key];
       if (!flag || !Array.isArray(paths)) continue;
-      for (const path34 of paths) managedArgs.push(flag, path34);
+      for (const path35 of paths) managedArgs.push(flag, path35);
     }
   }
   return {
@@ -7002,19 +7002,19 @@ function branchSessionStats(entries, state) {
 function branchUsageTotals(entries) {
   const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
   for (const entry of entries) {
-    let usage;
+    let usage2;
     if (entry.type === "message") {
       const message = entry.message;
-      if (message.role === "assistant" || message.role === "toolResult") usage = message.usage;
+      if (message.role === "assistant" || message.role === "toolResult") usage2 = message.usage;
     } else if (entry.type === "compaction" || entry.type === "branch_summary") {
-      usage = entry.usage;
+      usage2 = entry.usage;
     }
-    if (!usage) continue;
-    totals.input += usage.input ?? 0;
-    totals.output += usage.output ?? 0;
-    totals.cacheRead += usage.cacheRead ?? 0;
-    totals.cacheWrite += usage.cacheWrite ?? 0;
-    totals.cost += usage.cost?.total ?? 0;
+    if (!usage2) continue;
+    totals.input += usage2.input ?? 0;
+    totals.output += usage2.output ?? 0;
+    totals.cacheRead += usage2.cacheRead ?? 0;
+    totals.cacheWrite += usage2.cacheWrite ?? 0;
+    totals.cost += usage2.cost?.total ?? 0;
   }
   return totals;
 }
@@ -8632,11 +8632,11 @@ function extractAtPrefix(text) {
   const tokenStart = lastDelimiterIndex === -1 ? 0 : lastDelimiterIndex + 1;
   return text[tokenStart] === "@" ? text.slice(tokenStart) : null;
 }
-function buildCompletionValue(path34, isQuotedPrefix) {
-  return isQuotedPrefix || path34.includes(" ") ? `@"${path34}"` : `@${path34}`;
+function buildCompletionValue(path35, isQuotedPrefix) {
+  return isQuotedPrefix || path35.includes(" ") ? `@"${path35}"` : `@${path35}`;
 }
-function basename7(path34) {
-  const trimmed = path34.endsWith("/") ? path34.slice(0, -1) : path34;
+function basename7(path35) {
+  const trimmed = path35.endsWith("/") ? path35.slice(0, -1) : path35;
   const cut = trimmed.lastIndexOf("/");
   return cut === -1 ? trimmed : trimmed.slice(cut + 1);
 }
@@ -16560,8 +16560,8 @@ async function allJobs(client) {
     beforeId = last.id;
   }
 }
-function assertArgCount(args, expected, usage) {
-  if (args.length !== expected) throw new PiPodError(`usage: ${usage}`);
+function assertArgCount(args, expected, usage2) {
+  if (args.length !== expected) throw new PiPodError(`usage: ${usage2}`);
 }
 function shortSchedule(trigger) {
   if (trigger.type === "cron") return trigger.cron;
@@ -16747,8 +16747,8 @@ var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var CHANGE_USAGE = "pipod billing change --plan standard|pro [--yes]";
 var CHANGE_PREVIEW_USAGE = "pipod billing change preview --plan standard|pro";
 var CHANGE_CONFIRM_USAGE = "pipod billing change confirm --quote <quoteId> [--yes]";
-function usageError(message, usage) {
-  return new PiPodError(message, { hint: `usage: ${usage}`, exitCode: EXIT.USAGE });
+function usageError(message, usage2) {
+  return new PiPodError(message, { hint: `usage: ${usage2}`, exitCode: EXIT.USAGE });
 }
 function parseChangeArgs(args) {
   let form = "flow";
@@ -17945,11 +17945,11 @@ function formatStatus(status) {
   const expires = status.state === "ready" && status.expiresAt ? `  (expires ${status.expiresAt})` : "";
   return `${status.providerId}  ${status.state.replaceAll("_", " ")}${expires}`;
 }
-function rejectExtra(args, usage) {
-  if (args.length > 0) throw new PiPodError(usage);
+function rejectExtra(args, usage2) {
+  if (args.length > 0) throw new PiPodError(usage2);
 }
-function rejectProviderArgs(args, usage) {
-  if (args.length !== 1 || args[0].startsWith("-")) throw new PiPodError(usage);
+function rejectProviderArgs(args, usage2) {
+  if (args.length !== 1 || args[0].startsWith("-")) throw new PiPodError(usage2);
 }
 function terminalInteraction() {
   const controller = new AbortController();
@@ -18533,6 +18533,11 @@ async function showCmd(client, args) {
     info("bake script:");
     out(t.bakeScript);
   }
+  if (t.agentInstructions) {
+    out("");
+    info("agent instructions:");
+    out(t.agentInstructions);
+  }
   if (t.piSettings && Object.keys(t.piSettings).length > 0) {
     info(`Pi settings ${describePiSettings(flatPiSettings(t.piSettings))}`);
   }
@@ -18611,6 +18616,12 @@ function parseOpts(args) {
         opts.bakeScript = fs30.readFileSync(file, "utf8");
         break;
       }
+      case "--agent-instructions": {
+        const file = next();
+        if (!fs30.existsSync(file)) throw new PiPodError(`no such agent instructions file: ${file}`);
+        opts.agentInstructions = fs30.readFileSync(file, "utf8");
+        break;
+      }
       default:
         rest.push(arg);
     }
@@ -18664,6 +18675,7 @@ async function createCmd(client, args, flags) {
     ...opts.description ? { description: opts.description } : {},
     ...initScript ? { initScript } : {},
     ...bakeScript ? { bakeScript } : {},
+    ...opts.agentInstructions ? { agentInstructions: opts.agentInstructions } : {},
     // An explicit refresh is replacement, not merge: an empty project file set clears stale custody.
     ...opts.fromHere ? { piSettings: piSettings ?? {} } : {}
   });
@@ -18770,9 +18782,9 @@ async function editCmd(client, args) {
     });
   }
   const t = await findTemplate(client, rest[0]);
-  if (opts.name === void 0 && opts.description === void 0 && !opts.config && opts.initScript === void 0 && opts.bakeScript === void 0) {
+  if (opts.name === void 0 && opts.description === void 0 && !opts.config && opts.initScript === void 0 && opts.bakeScript === void 0 && opts.agentInstructions === void 0) {
     throw new PiPodError("nothing to change", {
-      hint: "pass --name, --description, --config <file>, --init-script <file> or --bake-script <file>"
+      hint: "pass --name, --description, --config <file>, --init-script <file>, --bake-script <file> or --agent-instructions <file>"
     });
   }
   const updated = await client.updateTemplate(t.id, {
@@ -18783,7 +18795,8 @@ async function editCmd(client, args) {
     ...opts.description !== void 0 ? { description: opts.description } : {},
     ...opts.config ? { config: opts.config } : {},
     ...opts.initScript !== void 0 ? { initScript: opts.initScript } : {},
-    ...opts.bakeScript !== void 0 ? { bakeScript: opts.bakeScript } : {}
+    ...opts.bakeScript !== void 0 ? { bakeScript: opts.bakeScript } : {},
+    ...opts.agentInstructions !== void 0 ? { agentInstructions: opts.agentInstructions } : {}
   });
   info(`updated template ${updated.name}`);
   await hintMissingCredentials(client);
@@ -19175,9 +19188,111 @@ function setDotPath(target, dotPath, value) {
   cursor[parts.at(-1)] = value;
 }
 
-// src/scaffold.ts
+// src/manual.ts
 import * as fs33 from "fs";
 import * as path31 from "path";
+var MAIN_PAGE = "pipod.1.md";
+var FENCE = "```";
+function usage(command) {
+  const entry = command === null ? section(mainPage(), 2, "SYNOPSIS") : commandEntry(command);
+  if (entry === null) throw new PiPodError(`the pipod manual has no entry for ${command}`);
+  const block = openingBlock(entry);
+  const more = command !== null && hasMoreThanBlock(entry) ? `
+More: pipod help ${command}
+` : "";
+  return `${block}${more}`;
+}
+function manualEntry(name) {
+  const entry = commandEntry(name) ?? topicSection(name) ?? topicPage(name);
+  if (entry === null) {
+    throw new PiPodError(`no manual entry for "${name}"`, {
+      hint: "`pipod help` lists the commands and topics",
+      exitCode: EXIT.USAGE
+    });
+  }
+  return plainText(entry);
+}
+function commandEntry(command) {
+  const commands = section(mainPage(), 2, "COMMANDS");
+  return commands === null ? null : section(commands, 3, `pipod ${command}`);
+}
+function topicSection(topic) {
+  return /^[a-z]+$/.test(topic) ? section(mainPage(), 2, topic.toUpperCase()) : null;
+}
+function topicPage(topic) {
+  const prefix = `pipod-${topic}.`;
+  const file = fs33.readdirSync(manDir()).find(
+    (name) => name.startsWith(prefix) && /^\d+\.md$/.test(name.slice(prefix.length))
+  );
+  return file === void 0 ? null : read(path31.join(manDir(), file));
+}
+function section(markdown, level, title) {
+  const lines = markdown.split("\n");
+  const heading = `${"#".repeat(level)} ${title}`;
+  let start = -1;
+  let fenced = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith(FENCE)) fenced = !fenced;
+    if (fenced) continue;
+    if (start < 0) {
+      if (line === heading) start = i;
+      continue;
+    }
+    const depth2 = /^(#+) /.exec(line)?.[1]?.length;
+    if (depth2 !== void 0 && depth2 <= level) return `${lines.slice(start, i).join("\n").trimEnd()}
+`;
+  }
+  return start < 0 ? null : `${lines.slice(start).join("\n").trimEnd()}
+`;
+}
+function openingBlock(entry) {
+  const lines = entry.split("\n");
+  const open = lines.findIndex((line) => line.startsWith(FENCE));
+  const close = lines.findIndex((line, i) => i > open && line.startsWith(FENCE));
+  if (open < 0 || close < 0) throw new PiPodError("a pipod manual entry does not open with a usage block");
+  return `${lines.slice(open + 1, close).join("\n")}
+`;
+}
+function hasMoreThanBlock(entry) {
+  const lines = entry.split("\n");
+  const fences = lines.flatMap((line, i) => line.startsWith(FENCE) ? [i] : []);
+  return lines.slice((fences[1] ?? lines.length) + 1).some((line) => line.trim() !== "");
+}
+function plainText(markdown) {
+  const out2 = [];
+  let fenced = false;
+  for (const line of markdown.split("\n")) {
+    if (line.startsWith(FENCE)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) out2.push(line === "" ? "" : `    ${line}`);
+    else out2.push(line.replace(/^#+ /, ""));
+  }
+  return `${out2.join("\n").trimEnd()}
+`;
+}
+function mainPage() {
+  return read(path31.join(manDir(), MAIN_PAGE));
+}
+function manDir() {
+  return path31.join(packageRoot(), "man");
+}
+function read(file) {
+  try {
+    return fs33.readFileSync(file, "utf8");
+  } catch (cause) {
+    throw new PiPodError(`the pipod manual is missing from this install (${file})`, {
+      hint: "reinstall pipod: `npm install -g @pipod/cli`, or `npm run build` in a checkout",
+      cause
+    });
+  }
+}
+
+// src/scaffold.ts
+import * as fs34 from "fs";
+import * as path32 from "path";
 function configTemplate() {
   return `{
   // .pi-pod/config.json \u2014 optional server-side launch overrides for this project.
@@ -19219,8 +19334,8 @@ set -euo pipefail
 echo "init complete"
 `;
 function scaffold(opts) {
-  const dir = path31.join(opts.projectRoot, CONFIG_DIR);
-  fs33.mkdirSync(dir, { recursive: true });
+  const dir = path32.join(opts.projectRoot, CONFIG_DIR);
+  fs34.mkdirSync(dir, { recursive: true });
   const files = [
     { name: "config.json", contents: configTemplate() },
     { name: "env.example", contents: ENV_EXAMPLE_TEMPLATE },
@@ -19229,32 +19344,32 @@ function scaffold(opts) {
   const created = [];
   const skipped = [];
   for (const file of files) {
-    const target = path31.join(dir, file.name);
-    if (fs33.existsSync(target) && !opts.force) {
-      skipped.push(path31.join(CONFIG_DIR, file.name));
+    const target = path32.join(dir, file.name);
+    if (fs34.existsSync(target) && !opts.force) {
+      skipped.push(path32.join(CONFIG_DIR, file.name));
       continue;
     }
-    fs33.writeFileSync(target, file.contents, file.mode ? { mode: file.mode } : void 0);
-    if (file.mode) fs33.chmodSync(target, file.mode);
-    created.push(path31.join(CONFIG_DIR, file.name));
+    fs34.writeFileSync(target, file.contents, file.mode ? { mode: file.mode } : void 0);
+    if (file.mode) fs34.chmodSync(target, file.mode);
+    created.push(path32.join(CONFIG_DIR, file.name));
   }
   const gitignoreUpdated = ensureGitignoreEntry(opts.projectRoot, `${CONFIG_DIR}/env`);
-  const envPath = path31.join(dir, "env");
-  const envCreated = !fs33.existsSync(envPath);
+  const envPath = path32.join(dir, "env");
+  const envCreated = !fs34.existsSync(envPath);
   if (envCreated) {
-    fs33.writeFileSync(envPath, ENV_TEMPLATE, { mode: 384 });
-    fs33.chmodSync(envPath, 384);
-    created.push(path31.join(CONFIG_DIR, "env"));
+    fs34.writeFileSync(envPath, ENV_TEMPLATE, { mode: 384 });
+    fs34.chmodSync(envPath, 384);
+    created.push(path32.join(CONFIG_DIR, "env"));
   }
   return { created, skipped, gitignoreUpdated, envCreated };
 }
 function ensureGitignoreEntry(projectRoot, entry) {
-  const gitignorePath = path31.join(projectRoot, ".gitignore");
-  const existing = fs33.existsSync(gitignorePath) ? fs33.readFileSync(gitignorePath, "utf8") : "";
+  const gitignorePath = path32.join(projectRoot, ".gitignore");
+  const existing = fs34.existsSync(gitignorePath) ? fs34.readFileSync(gitignorePath, "utf8") : "";
   const alreadyPresent = existing.split(/\r?\n/).map((line) => line.trim()).some((line) => line === entry || line === `/${entry}`);
   if (alreadyPresent) return false;
   const prefix = existing === "" || existing.endsWith("\n") ? "" : "\n";
-  fs33.appendFileSync(gitignorePath, `${prefix}
+  fs34.appendFileSync(gitignorePath, `${prefix}
 # pi pod secrets \u2014 never commit
 ${entry}
 `);
@@ -19268,7 +19383,7 @@ function printInitResult(result, projectRoot) {
   const steps = [
     [`edit ${CONFIG_DIR}/config.json and init.sh`, "what this project's pods get"],
     [`edit ${CONFIG_DIR}/env`, "this project's own keys"],
-    ["pipod", `launch a pod for ${path31.basename(projectRoot)}; the first launch offers to keep these in a template`]
+    ["pipod", `launch a pod for ${path32.basename(projectRoot)}; the first launch offers to keep these in a template`]
   ].map(([command, why]) => `${command.padEnd(40)} ${color.dim(`# ${why}`)}`);
   plain("");
   plain("Next steps:");
@@ -19278,8 +19393,8 @@ function printInitResult(result, projectRoot) {
 
 // src/update.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import * as fs34 from "fs";
-import * as path32 from "path";
+import * as fs35 from "fs";
+import * as path33 from "path";
 function run(cmd, args, cwd) {
   const r = spawnSync3(cmd, args, { cwd, encoding: "utf8" });
   return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
@@ -19288,13 +19403,13 @@ function runVisible(cmd, args, cwd) {
   return spawnSync3(cmd, args, { cwd, stdio: "inherit" }).status === 0;
 }
 function detectInstall(root = packageRoot()) {
-  if (fs34.existsSync(path32.join(root, ".git"))) return { kind: "git", root };
-  if (!root.split(path32.sep).includes("node_modules") && run("git", ["rev-parse", "--is-inside-work-tree"], root).out === "true") {
+  if (fs35.existsSync(path33.join(root, ".git"))) return { kind: "git", root };
+  if (!root.split(path33.sep).includes("node_modules") && run("git", ["rev-parse", "--is-inside-work-tree"], root).out === "true") {
     return { kind: "git", root };
   }
-  if (root.split(path32.sep).includes("node_modules")) {
+  if (root.split(path33.sep).includes("node_modules")) {
     try {
-      const pkg = JSON.parse(fs34.readFileSync(path32.join(root, "package.json"), "utf8"));
+      const pkg = JSON.parse(fs35.readFileSync(path33.join(root, "package.json"), "utf8"));
       if (pkg.name) return { kind: "npm", root, name: pkg.name };
     } catch {
     }
@@ -19303,7 +19418,7 @@ function detectInstall(root = packageRoot()) {
 }
 function versionAt(root) {
   try {
-    const pkg = JSON.parse(fs34.readFileSync(path32.join(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(fs35.readFileSync(path33.join(root, "package.json"), "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -19378,16 +19493,16 @@ async function updateCheckout(root, opts) {
   return rebuild(root, before);
 }
 function distIsStale(root) {
-  const srcDir = path32.join(root, "src");
-  if (!fs34.existsSync(srcDir)) return false;
-  const dist = path32.join(root, "dist", "cli.js");
-  if (!fs34.existsSync(dist)) return true;
-  const distTime = fs34.statSync(dist).mtimeMs;
+  const srcDir = path33.join(root, "src");
+  if (!fs35.existsSync(srcDir)) return false;
+  const dist = path33.join(root, "dist", "cli.js");
+  if (!fs35.existsSync(dist)) return true;
+  const distTime = fs35.statSync(dist).mtimeMs;
   const newest = (dir) => {
     let max = 0;
-    for (const entry of fs34.readdirSync(dir, { withFileTypes: true })) {
-      const p = path32.join(dir, entry.name);
-      max = Math.max(max, entry.isDirectory() ? newest(p) : fs34.statSync(p).mtimeMs);
+    for (const entry of fs35.readdirSync(dir, { withFileTypes: true })) {
+      const p = path33.join(dir, entry.name);
+      max = Math.max(max, entry.isDirectory() ? newest(p) : fs35.statSync(p).mtimeMs);
     }
     return max;
   };
@@ -19408,8 +19523,8 @@ function rebuild(root, before) {
   const head = run("git", ["rev-parse", "--short", "HEAD"], root).out;
   plain("");
   info(after === before ? `now at ${color.bold(after)} (${head})` : `updated ${before} \u2192 ${color.bold(after)} (${head})`);
-  const upgrade = path32.join(run("git", ["rev-parse", "--show-toplevel"], root).out, "selfhost", "upgrade");
-  if (fs34.existsSync(upgrade)) out(`if this checkout runs your server, upgrade it to match: ${upgrade}`);
+  const upgrade = path33.join(run("git", ["rev-parse", "--show-toplevel"], root).out, "selfhost", "upgrade");
+  if (fs35.existsSync(upgrade)) out(`if this checkout runs your server, upgrade it to match: ${upgrade}`);
   out("run `pipod doctor` to check the new version against this repo");
 }
 async function updateFromRegistry(root, name, opts) {
@@ -19477,461 +19592,6 @@ var ALIASES = {
   a: "attach",
   ls: "list"
 };
-var HELP = `pipod ${VERSION} \u2014 run pi sessions in server-managed pods
-
-Usage:
-  pipod [options]                   launch a pod for this project and start pi
-  pipod [options] -- <pi args\u2026>     launch and pass arguments to pi: prompt words,
-                                    --model <id>, --thinking <level>, --tui-mode <mode>,
-                                    -e/--extension <path>, --skill <path>,
-                                    --prompt-template <path> (each repeatable)
-  pipod <command> [options]         run a command
-  pipod help [command]              show help (same as --help)
-
-Sign in first with \`pipod login\`. A pod-scoped PI_POD_SERVER_TOKEN also counts as
-signed in. While signed out, only login, whoami, init, doctor, update, help, and
-version are available.
-
-Pod commands:
-  list [pod]             List pods; \`list <pod>\` shows one machine's group (ls)
-  attach [pod]           Reconnect to a pod session (a)
-  stop [pod\u2026]            Stop pods now (files kept; attach restarts them)
-  fork <pod>             Launch a new pod forked from a pod's session
-  rename <pod> <name>    Rename a pod
-  send [pod] <path>      Copy host files into a pod
-  receive [pod] <path>   Copy pod files into the current directory
-  archive [pod\u2026]         Hide pods from the list (files kept; restore brings them back)
-  restore [pod\u2026]         Bring archived pods back
-  gc                     Report retention state; --delete removes reclaimable pods
-
-Account commands:
-  login                  Sign in to a pi pod server via Zitadel
-  logout                 Revoke this session and delete the stored credentials
-  whoami                 Show the signed-in account
-  account                Open the Zitadel self-service console
-  org-admin              Open the Zitadel Console for this organization
-  billing                Open Stripe Checkout or the billing portal (authenticated)
-  credentials            Connect account model-provider sign-ins
-
-Configuration commands:
-  init                   Scaffold .pi-pod/ config, env, env.example, and init.sh
-  templates              Manage account templates
-  push                   Upload a local config layer to its server bundle
-  pull                   Write a server bundle into its local config layer
-  diff                   Show local vs server drift for a config layer
-  secrets                Manage server and project secret scopes
-  settings               Show or edit one server settings config directly
-  jobs                   Manage server-scheduled jobs
-
-Maintenance commands:
-  doctor                 Check auth, server, org, and launch-resolution layers
-  update                 Upgrade pi pod itself
-
-Launch options:
-  --template <name|id>   Launch from an account template
-  --on <pod|self>        Co-locate the new pod on an existing pod's machine
-  --reuse                Restart this project's newest stopped pod instead of creating one
-  --no-seed              Start the pod with an empty workspace (skip workspace seeding)
-  --dry-run              Resolve and print the launch plan; create nothing
-
-General options:
-  -y, --yes              Skip supported confirmations
-  -v, --verbose          Debug logging (secrets redacted)
-  --version              Print CLI, Node, and bundled Pi versions
-  -h, --help             Show help
-
-Settings resolve on the server: built-in \u2192 org \u2192 org-template \u2192 user \u2192 user-template
-\u2192 org policy. Each bundle has a local directory as its source of truth (see
-\`pipod push --help\`); local project settings apply after \`pipod push\`, and the
-first launch in a project offers to bootstrap a template.
-
-Per-launch Pi resources (--extension, --skill, --prompt-template) name files or
-directories inside the pod as absolute paths and add to the pod's configured Pi
-resources for that launch; anything else Pi-related belongs in the pi.args config.
-
-Workspace seeding: launching from a directory with no .pi-pod/config.json seeds the
-new pod from that directory (its git repository root when inside one). A clean,
-pushed checkout whose remote tip matches HEAD is cloned at that exact commit;
-anything else \u2014 dirty trees, unpushed commits, private remotes without usable
-credentials, plain directories \u2014 is streamed in as a tar archive (git-ignored
-paths, node_modules and .pi-pod/env excluded). Private-remote credentials are
-forwarded only after a prompt (\`--yes\` approves it) and are never stored.
-\`--dry-run\` prints the decision without prompting or creating a pod. Forks,
-reused pods, \`--on\` co-location and \`--no-seed\` never seed.
-
-Run \`pipod <command> --help\` for command-specific usage.
-`;
-var SUBCOMMAND_HELP = {
-  login: `Usage: pipod login [--server <url>] [--issuer <url>] [--org <alias>] [--device] [--token <jwt>]
-
-Sign this machine in to a pi pod server via Zitadel (authorization code + PKCE,
-in your browser). Where no browser can open here (over SSH, on a headless
-server), it prints a page and a code to confirm on any other device instead.
-The session is stored in ~/.pi-pod/auth.json.
-
-Options:
-  --server <url>   Server to sign in to (default: the previous session's server,
-                   $PI_POD_ACCOUNT_URL, or the production server)
-  --issuer <url>   OIDC issuer (default: $PI_POD_ISSUER, else the one the
-                   server publishes); needed only for a server too old to
-                   publish its own
-  --org <alias>    Only sign in to the organization with this primary domain;
-                   omit it to sign in to your own organization
-  --device         Sign in with a code on another device even if a browser
-                   could open here
-  --token <jwt>    Use an existing access token instead of the browser flow (dev/CI)
-`,
-  account: `Usage: pipod account
-
-Open the Zitadel self-service console in your browser to manage profile,
-password, MFA, and active sessions.
-`,
-  "org-admin": `Usage: pipod org-admin
-
-Open the Zitadel Console in your browser. Organization owners manage members
-and role grants there.
-`,
-  billing: `Usage: pipod billing checkout [--plan standard|pro] [--trial]
-       pipod billing portal
-       pipod billing change --plan standard|pro [--yes]
-       pipod billing change preview --plan standard|pro
-       pipod billing change confirm --quote <quoteId> [--yes]
-
-Authenticated Stripe Checkout and billing portal. Checkout sends trial:false
-(paid) unless --trial. Closed public trial refuses --trial with 402. Change
-previews a Standard<->Pro plan change and confirms it only after an explicit
-yes; stale quotes are never auto-confirmed. Return
-pages do not grant a plan. Public npm is not a supported install path; use a
-GitHub release tarball or git clone + npm run build.
-`,
-  logout: `Usage: pipod logout
-
-Revoke the current account session and delete ~/.pi-pod/auth.json. Pod
-operations are unavailable until the next \`pipod login\`.
-`,
-  whoami: `Usage: pipod whoami
-
-Show the signed-in server, user, permissions, active organization, and console
-links. Exits 1 when signed out.
-`,
-  init: `Usage: pipod init [--force]
-
-Scaffold project configuration under .pi-pod/ in the current directory:
-config.json, env.example, env (mode 600), and init.sh.
-
-Options:
-  --force                Overwrite scaffold files that already exist
-`,
-  doctor: `Usage: pipod doctor [--template <name|id>]
-
-Check each layer a launch depends on: account auth, server reachability and
-version, organization membership and roles, secret references, and the
-server-resolved settings bundle chain for this directory. Works while signed
-out to diagnose auth problems. Exits non-zero when a layer fails.
-
-Options:
-  --template <name|id>   Plan the checked launch with this template
-`,
-  list: `Usage: pipod list [pod] [--all] [--archived] [--template <name|id>] [--quiet]
-
-Alias: ls
-
-List pods on the signed-in server with stable short refs (p-\u2026). The project is
-the directory's git repository (or the directory, or its .pi-pod/ config): a
-listing shows that project's pods when it has any \u2014 its pinned template's when
-it pins one \u2014 and every pod otherwise. Co-located pods are grouped under the pod
-whose machine they share, with an ON column naming it.
-With a pod argument, show just that machine's group: the pod and everything
-co-located on it.
-
-Status says where a pod's files are: a stopped pod keeps them on disk and restarts on
-attach; an archived workspace is restored on next use, which takes longer the bigger it is.
-Pods you archive stay hidden unless --archived is passed.
-
-Options:
-  -a, --all              Every pod; ignore the current project and its template pin
-  --archived             Include logically archived pods
-  --template <name|id>   Only pods launched from that template (whole account)
-  -q, --quiet            Print pod ids only, one per line
-`,
-  attach: `Usage: pipod attach [pod] [--yes] [-- <prompt\u2026> [--tui-mode <mode>]]
-
-Alias: a
-
-Reconnect to a pod session through the server gateway. Name the pod by id,
-short ref (p-\u2026), or name; omit it when this project has exactly one pod.
-Quitting detaches: the pod keeps running until the server's idle policy reaps
-it or \`pipod stop\` stops it. Raw pod shells are not available.
-Attaching to an archived pod offers to restore it first.
-
-After --:
-  <prompt\u2026>              Words are sent to the session as a startup prompt
-  --tui-mode <mode>      Local TUI layout for this attach: regular or fullscreen
-
-Options:
-  -y, --yes              Restore an archived pod without asking
-`,
-  stop: `Usage: pipod stop [pod\u2026]
-
-Stop pods now by id, short ref (p-\u2026), or name; omit the argument when this
-project has exactly one pod. Stopped pods keep their files and \`pipod attach\`
-restarts them. Stopping a pod that hosts co-located pods stops those too.
-`,
-  fork: `Usage: pipod fork <pod> [--session <path>] [launch options] [-- <pi args\u2026>]
-
-Launch a new pod whose session starts as a fork of <pod>'s current session.
-<pod> is an id, short ref (p-\u2026), or name. The workspace is not copied \u2014
-commit and push first if the new pod needs those changes. --on is not
-supported: a fork launches a new sandbox, not a co-located pod.
-
-Options:
-  --session <path>       Fork a specific session file instead of the newest
-  --template <name|id>   Launch the new pod from an account template
-  --dry-run              Resolve and print the launch plan; create nothing
-  -y, --yes              Skip supported confirmations
-`,
-  rename: `Usage: pipod rename <pod> <name>
-
-Rename a server-managed pod. <pod> is an id, short ref (p-\u2026), or the current
-name.
-`,
-  send: `Usage: pipod send [pod] <path> [--yes]
-
-Copy a host file or directory into a pod through the server. Omit the pod when
-this project has exactly one. Sending to an archived pod offers to restore it
-first.
-
-Options:
-  -y, --yes   Restore an archived pod without asking
-`,
-  receive: `Usage: pipod receive [pod] <path> [--yes]
-
-Copy a file or directory from a pod into the current local directory. <path>
-may be a workdir-relative path or an absolute path inside that workdir, such
-as foo or /workspace/foo. The destination must not already exist. Omit the
-pod when this project has exactly one. Receiving from an archived pod offers
-to restore it first.
-
-Options:
-  -y, --yes   Restore an archived pod without asking
-`,
-  archive: `Usage: pipod archive [pod\u2026] [--all] [--template <name|id>] [--idle <duration>] [--dry-run] [--yes]
-
-Archive pods by id, short ref (p-\u2026), or name. Archiving hides pods from
-\`pipod list\` (\`pipod list --archived\` shows them); it never deletes work, and
-\`pipod restore\` brings them back. Archiving a pod that hosts co-located pods
-archives those too.
-
-Options:
-  -a, --all              Archive every pod (cannot be combined with pod refs)
-  --template <name|id>   Only pods launched from that template (whole account)
-  --idle <duration>      Only pods whose last activity is older than this (4h, 2d, 30m)
-  --dry-run              Print the matching pods; archive nothing
-  -y, --yes              Skip the bulk confirmation
-`,
-  restore: `Usage: pipod restore [pod\u2026] [--all] [--yes]
-
-Bring archived pods back by id, short ref (p-\u2026), or name. Restoring a host
-restores the co-located pods archived with it. \`pipod attach\` then starts the
-pod; a workspace in cold storage takes longer the bigger it is.
-
-Options:
-  -a, --all   Restore every archived pod (cannot be combined with pod refs)
-  -y, --yes   Skip the --all confirmation
-`,
-  gc: `Usage: pipod gc [--delete] [--yes]
-
-List the archived and failed pods that can be deleted for good; --delete deletes
-them. (The server stops idle pods and moves stopped workspaces to cold storage on
-its own schedule; that never deletes anything.)
-
-Options:
-  --delete    Permanently delete the reclaimable pods
-  -y, --yes   Delete without a confirmation prompt
-`,
-  jobs: `Usage: pipod jobs [action] [args] [--quiet] [--yes] [--project] [--org]
-
-Manage scheduled jobs the pi pod server runs for you: at each trigger it
-launches a pod from the job's template and sends the job's prompt. Local job
-files in .pi-pod/jobs/ (project) or ~/.pi-pod/jobs/ (user) are the reviewable
-source; \`jobs push\` promotes them to the server. <job> is an id, short ref
-(j-\u2026), or name.
-
-Actions:
-  list                 List server jobs (default)
-  show <job>           Show a job's schedule, template, model, and prompt
-  runs <job>           List a job's recent runs
-  run <job>            Run an active job once, now; its schedule is unchanged
-  activate <job>       Activate a job
-  pause <job>          Pause a job's schedule
-  resume <job>         Resume a paused job
-  rm <job>             Remove a job; its schedule stops firing
-  push [job\u2026]          Create or update server jobs from local job files
-  pull <job>           Write a server job to a local job file
-  diff [job\u2026]          Show local vs server drift; exits 1 when drifted
-
-Options:
-  --org        push: create org-scoped jobs or promote matching user jobs
-               (promotion is one-way)
-  --project    pull: write into this project's .pi-pod/jobs/ instead of
-               ~/.pi-pod/jobs/
-  -q, --quiet  list: print job ids only, one per line
-  -y, --yes    Skip confirmations; pull: overwrite an existing local file
-`,
-  credentials: `Usage: pipod credentials [action]
-
-Manage account-scoped model-provider sign-ins. Connected credentials apply to
-every pod you launch; OAuth refresh tokens stay in server custody and never
-reach pods or this machine.
-
-Actions:
-  list                       Saved credentials and connectable providers (default)
-  connect                    Connect every provider your local pi is signed in to:
-                             API keys are imported, everything else is a fresh
-                             account login; ready credentials are left alone
-  connect <provider>         Sign in to a provider (OAuth by default)
-  reconnect <provider>       Redo the sign-in for a saved credential
-  test <provider>            Verify a saved credential against the provider
-  remove <provider> [--yes]  Delete a saved credential (alias: rm)
-
-connect options:
-  --api-key            Enter an API key instead of the OAuth flow
-  --api-key --from-pi  Import the API key your local pi resolves for that
-                       provider (auth.json or env) instead of typing it.
-                       OAuth grants are never imported.
-`,
-  secrets: `Usage: pipod secrets [action]
-
-Manage the secret layers pods see. Requires account or pod-token auth. Server
-scopes are org, user, and template/<name>; project is this project's dotenv
-file, the highest-precedence layer for launches from the project.
-
-Actions:
-  list                          Every secret a pod launched here would see,
-                                which layer wins, and who set it (default)
-  set <scope> <NAME>            Store a secret, its value read from a hidden
-                                prompt or stdin (never the command line)
-  rm <scope> <NAME>             Remove a secret (aliases: remove, unset)
-  sync <scope>                  Upload a dotenv file to a server scope
-
-sync options (scope must be org, user, or template/<name>):
-  --file <path>   Dotenv file to upload (default: ~/.pi-pod/secrets/<scope>.env)
-  --prune         Also delete server secrets that are not in the file
-  --dry-run       Show what would change without writing
-
-Values may be op:// references; they resolve just-in-time (at upload for
-server scopes, at launch for the project file) and the references themselves
-are never stored on the server.
-`,
-  templates: `Usage: pipod templates [action]
-
-Manage pod templates on the pi pod server. A template stores config, init and
-bake scripts, Pi settings files, and named secrets. Templates are personal by
-default: only their owner sees and launches them. --org at creation or
-\`templates share\` makes one org-wide.
-
-Actions:
-  list             List templates with scope and key counts (default)
-  show <name|id>   Show config, scripts, Pi settings, and secret names
-  create <name>    Create a template
-  edit <name|id>   Update a template's name, description, config, or scripts
-  share <name|id>  Make a personal template org-wide (cannot be undone)
-  rm <name|id>     Delete a template (alias: delete)
-
-create/edit options:
-  --name <name>         New name (edit only)
-  --description <text>  Set the description
-  --config <file>       Store this config file (same shape as .pi-pod/config.json)
-  --from-here           create only: store this project's authored config,
-                        scripts, and sanitized Pi files (contradicts --config)
-  --init-script <file>  Store this init script
-  --bake-script <file>  Store this bake script
-  --org                 create only: make the template org-wide from the start
-  --with-secrets        With --from-here: also upload project env values as
-                        template secrets
-  -y, --yes             Skip confirmations (rm)
-`,
-  push: `Usage: pipod push [template [<name>] | user | org] [--dir <path>]
-                  [--with-secrets] [--yes]
-
-Replace a server config bundle with its local source, whole. The layer names
-both sides; edit the local files with any editor, then push. A diff preview
-precedes the confirmation.
-
-Layers and their local source:
-  template [<name>]  This project: .pi-pod/config.json, its init and bake
-                     scripts, Pi files under .pi/, and the project env file
-                     (secrets, with --with-secrets or a prompt). Without
-                     <name> the project's pinned template is used.
-  user               ~/.pi-pod/config.json and ~/.pi/agent/ (settings.json,
-                     models.json, mcporter.json, subagents.json, agents/)
-  org                ~/.pi-pod/org/: config.json, init.sh, bake.sh, pi/\u2026, and
-                     an optional env file whose values become org secrets
-
-Inside a project the layer defaults to template; elsewhere it is required.
-Provider credentials, hooks, mcpServers, and model credential values never
-leave this machine.
-
-Options:
-  --dir <path>     org only: read the org source from <path> instead
-  --with-secrets   Also upload the layer's env values as secrets
-  -y, --yes        Apply the replacement without the confirmation prompt
-`,
-  pull: `Usage: pipod pull [template [<name>] | user | org] [--dir <path>] [--yes]
-
-Write a server config bundle into its local source files (see
-\`pipod push --help\` for the layer \u2192 directory table). A diff preview
-precedes the confirmation; nothing is written when the two already match.
-
-What pull keeps from the local files:
-  config.json    client-only keys: $schema, template, secretResolver,
-                 pi.chords, pi.sessionNaming
-  settings.json  hooks and mcpServers (and packages when hostConfig.packages
-                 is off)
-  models.json    credential values the push had dropped
-  agents/        files the bundle no longer contains are removed
-
-Secrets stay on the server; their names are listed. The user layer has no
-local script files, so user bundle scripts are shown but not written.
-
-Options:
-  --dir <path>   org only: write the org source to <path> instead
-  -y, --yes      Apply the local changes without the confirmation prompt
-`,
-  diff: `Usage: pipod diff [template [<name>] | user | org] [--dir <path>]
-
-Compare a config layer's local source with its server bundle (see
-\`pipod push --help\` for the layer \u2192 directory table). Secrets compare by
-name only. Exits 1 when they differ, 0 when they match.
-
-Options:
-  --dir <path>   org only: read the org source from <path> instead
-`,
-  settings: `Usage: pipod settings <user|org> [show | edit | set <key> <value> | unset <key>]
-
-Show or edit a persistent settings bundle on the server: your own user bundle,
-or the org-wide defaults (org scope needs the org:manage permission). Edits
-change only the config; scripts and Pi files stay as they are \u2014 replace the
-whole bundle from local files with \`pipod push user\` or \`pipod push org\`.
-Edits use compare-and-swap on the bundle version, so concurrent changes fail
-cleanly instead of overwriting each other.
-
-Actions:
-  show                    Print the settings bundle as JSON (default)
-  edit                    Edit the config in $VISUAL/$EDITOR, then save
-  set <key> <value>       Set one dotted key to a JSON value, or to the text as
-                          a string: pipod settings user set pi.model provider/model
-  unset <key>             Remove one dotted key, so the layers below decide it
-`,
-  update: `Usage: pipod update [--dry-run]
-
-Upgrade pi pod itself: a registry install updates to the latest published
-version; a git checkout pulls its upstream and rebuilds.
-
-Options:
-  --dry-run   Report what an update would do without changing anything
-`
-};
 var SELF_PARSING_SUBCOMMANDS = /* @__PURE__ */ new Set(["credentials", "secrets", "templates", "push", "pull", "diff", "settings", "billing"]);
 var UNIVERSAL_FLAGS = /* @__PURE__ */ new Set(["--verbose", "--version", "--help"]);
 var FLAG_SCOPE = {
@@ -20107,15 +19767,22 @@ function parseArgs(argv) {
         });
     }
   }
-  let commandPositionals = positionals;
   if (positionals[0] === "help") {
     flags.help = true;
     seenFlags.add("--help");
-    commandPositionals = positionals.slice(1);
+    const name = positionals[1];
+    return {
+      subcommand: null,
+      subcommandArgs: [],
+      flags,
+      piArgs,
+      seenFlags,
+      ...name !== void 0 ? { helpEntry: resolveSubcommand(name) ?? name } : {}
+    };
   }
-  const subcommand = resolveSubcommand(commandPositionals[0]);
-  if (!subcommand && commandPositionals.length > 0) {
-    throw new PiPodError(`unknown pi pod command "${commandPositionals[0]}"`, {
+  const subcommand = resolveSubcommand(positionals[0]);
+  if (!subcommand && positionals.length > 0) {
+    throw new PiPodError(`unknown pi pod command "${positionals[0]}"`, {
       hint: 'pass all Pi arguments after `--`, for example: pipod -- "review this change"',
       exitCode: EXIT.USAGE
     });
@@ -20128,7 +19795,7 @@ function parseArgs(argv) {
   }
   return {
     subcommand,
-    subcommandArgs: subcommand ? commandPositionals.slice(1) : [],
+    subcommandArgs: subcommand ? positionals.slice(1) : [],
     flags,
     piArgs,
     seenFlags
@@ -20151,10 +19818,14 @@ function canonicalFlagName(name) {
   }
 }
 async function main(argv) {
-  const { subcommand, subcommandArgs, flags, piArgs, seenFlags } = parseArgs(argv);
+  const { subcommand, subcommandArgs, flags, piArgs, seenFlags, helpEntry } = parseArgs(argv);
   setVerbose(flags.verbose);
   if (flags.help) {
-    process.stdout.write(subcommand ? SUBCOMMAND_HELP[subcommand] : HELP);
+    if (helpEntry !== void 0) process.stdout.write(manualEntry(helpEntry));
+    else if (subcommand) process.stdout.write(usage(subcommand));
+    else process.stdout.write(`pipod ${VERSION} \u2014 run pi sessions in server-managed pods
+
+${usage(null)}`);
     return EXIT.OK;
   }
   for (const flag of checkFlagScope(subcommand, seenFlags)) {
@@ -20267,7 +19938,7 @@ function announceUserConfig() {
 function runInit(flags) {
   const cwd = process.cwd();
   const existing = findConfigPath(cwd);
-  if (existing !== null && path33.dirname(path33.dirname(existing)) !== fs35.realpathSync(cwd)) {
+  if (existing !== null && path34.dirname(path34.dirname(existing)) !== fs36.realpathSync(cwd)) {
     info(`note: ${color.bold(displayPath(existing))} defines an enclosing project; this scaffold shadows it here`);
   }
   const result = scaffold({ projectRoot: cwd, force: flags.force });
@@ -20295,7 +19966,7 @@ function reportError(errorValue) {
   if (errorValue instanceof Error && errorValue.stack) plain(color.dim(errorValue.stack));
   return EXIT.FAILURE;
 }
-var invokedDirectly = process.argv[1] !== void 0 && ["cli.js", "cli.ts", "pipod", "pi-pod", "pp"].includes(path33.basename(process.argv[1]));
+var invokedDirectly = process.argv[1] !== void 0 && ["cli.js", "cli.ts", "pipod", "pi-pod", "pp"].includes(path34.basename(process.argv[1]));
 if (invokedDirectly) {
   for (const stream of [process.stdout, process.stderr]) {
     stream.on("error", (failure) => {