@openscaffold/cli 0.1.2 → 0.1.3

package/README.md

@@ -7,7 +7,7 @@ start, in any repo, loads the right customer deployment's briefing, and the Open
 ```sh
 npx @openscaffold/cli setup acme.com ./customer-docs   # sign in if needed, create the deployment, upload the folder, print the cited plan
 npx @openscaffold/cli login    # opens your browser: click Approve. That's it.
-npx @openscaffold/cli review --title "…" --req req_1   # review this folder's change against the customer's plan (agents run it)
+npx @openscaffold/cli review --req req_1             # review this folder's change against the customer's plan (agents run it)
 npx @openscaffold/cli status   # what's set up and the next step (--json for coding agents)
 npx @openscaffold/cli logout   # removes everything it installed and revokes the login
 npx @openscaffold/cli help     # commands and environment variables
@@ -29,7 +29,9 @@ MCP server and `/openscaffold:*` commands).
 - a SessionStart hook in `~/.claude/settings.json` that prints the briefing
 - two guardrail hooks in the same file: before a `git commit`, the customer's rules and must-haves as context; at Stop,
   once per session, if Claude edited files without a review, it's asked to run `openscaffold review` (or `request_review`) and then
-  call `report_session`
+  call `report_session`; and after Claude switches or creates a customer (`use_deployment`, `create_deployment`), a hook that makes `review` and the guardrails follow it
+
+Logged in before 2026-10-29? Run `npx @openscaffold/cli login` again to add the customer-switch hook (`status` says so).
 - `/os-requirements`, `/os-what-changed`, `/os-check-plan`, `/os-demo-check` in `~/.claude/skills/`
 
 Requires Node 22+ and Claude Code. Set `OPENSCAFFOLD_URL` to point at a self-hosted OpenScaffold. Set

package/dist/index.js

@@ -4,7 +4,7 @@ import { execFileSync, spawn } from "node:child_process";
 import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { briefingFacts, briefingStatus, browserCommand, collectDiff, gitInfo, hasOpenScaffoldPlugin, hookBase, HOSTED, installedHooks, loadedEntry, loginResultLine, MCP_NAME, mcpText, nameFromDomain, parseReviewArgs, parseSetupArgs, planSummary, pluginServes, preCommitOutput, selectFiles, SETUP_EXTENSIONS, setupPrompt, setupResultLine, skillFile, statusReport, stopOutput, transcriptActivity, windowsCommandLine, withHooks, withoutHooks, withSession, } from "./install.js";
+import { briefingFacts, briefingStatus, browserCommand, collectDiff, gitInfo, hasOpenScaffoldPlugin, hookBase, HOSTED, installedHooks, loadedEntry, loginResultLine, MCP_NAME, mcpText, nameFromDomain, callerSession, commandLine, rememberedCache, DEFAULT_REVIEW_TITLE, parseReviewArgs, parseSetupArgs, planSummary, pluginServes, preCommitOutput, REVIEW_HELP, REVIEW_WAIT, reviewTitle, selectFiles, SETUP_EXTENSIONS, setupPrompt, setupResultLine, skillFile, statusReport, stopOutput, switchAllowed, switchedTo, transcriptActivity, whichCustomerError, windowsCommandLine, withHooks, withoutHooks, } from "./install.js";
 const CONFIG = join(homedir(), ".config", "openscaffold");
 const CREDENTIALS = join(CONFIG, "credentials.json");
 const CACHE = join(CONFIG, "cache");
@@ -336,6 +336,17 @@ const git = (cwd, args) => {
         return null;
     }
 };
+/** Caches a deployment's briefing as this folder's (and this Claude session's) deployment, for the guardrail hooks and review. */
+function remember(creds, deployment, briefing, cwd, sessionId, switching = false) {
+    mkdirSync(CACHE, { recursive: true });
+    writeFileSync(join(CACHE, `${deployment}.md`), briefing);
+    const entry = { deployment, at: new Date().toISOString(), login: loginKey(creds) };
+    // Per Claude session too: two sessions in one folder on different customers each keep their own guardrails.
+    const next = rememberedCache(readJson(join(CACHE, "index.json"), {}), readJson(SESSIONS, {}), cwd, sessionId, entry, switching);
+    writeJson(join(CACHE, "index.json"), next.index);
+    if (sessionId)
+        writeJson(SESSIONS, next.sessions);
+}
 /** Prints the briefing. Never breaks a session: on any problem, a cached briefing or one line, exit 0. */
 async function sessionStart() {
     let hook = {};
@@ -357,15 +368,8 @@ async function sessionStart() {
         const briefing = String(r.body.briefing);
         console.log(briefing);
         const dep = r.body.deployment?.id;
-        if (dep) {
-            mkdirSync(CACHE, { recursive: true });
-            writeFileSync(join(CACHE, `${dep}.md`), briefing);
-            const entry = { deployment: dep, at: new Date().toISOString(), login: loginKey(creds) };
-            writeJson(join(CACHE, "index.json"), { ...index, [cwd]: entry });
-            // Per Claude session too: two sessions in one folder on different customers each keep their own guardrails.
-            if (hook.session_id)
-                writeJson(SESSIONS, withSession(readJson(SESSIONS, {}), hook.session_id, entry));
-        }
+        if (dep)
+            remember(creds, dep, briefing, cwd, hook.session_id);
     }
     catch {
         const last = index[cwd]?.login === loginKey(creds) ? index[cwd] : undefined; // a session started before a re-login may write late
@@ -411,28 +415,60 @@ async function stop() {
     writeFileSync(marker, new Date().toISOString());
     console.log(out);
 }
+/** The deployments this login has cached (session-start or an earlier switch), newest first, with their names when cached. */
+const knownDeployments = (creds) => {
+    const entries = [...Object.values(readJson(SESSIONS, {})), ...Object.values(readJson(join(CACHE, "index.json"), {}))];
+    const ids = [...new Set(entries.filter((e) => e.login === loginKey(creds)).sort((a, b) => b.at.localeCompare(a.at)).map((e) => e.deployment))];
+    return ids.map((id) => {
+        const file = join(CACHE, `${id}.md`);
+        return { id, name: existsSync(file) ? /^# OpenScaffold — (.+)$/m.exec(readFileSync(file, "utf8"))?.[1]?.trim() ?? null : null };
+    });
+};
+/**
+ * PostToolUse after use_deployment / create_deployment: the new deployment becomes this session's and folder's, so review
+ * and the hooks follow it; only when it is this login's server and workspace (switchAllowed), never a foreign id.
+ */
+async function useDeployment() {
+    const hook = await hookInput();
+    const creds = credentials();
+    const got = switchedTo(hook.tool_response);
+    if (!creds || !got || !switchAllowed(hook.tool_name, got.deployment, creds.api_url, knownDeployments(creds).map((d) => d.id)))
+        return;
+    remember(creds, got.deployment, got.briefing, hook.cwd ?? process.cwd(), hook.session_id, true);
+}
 // --- review -------------------------------------------------------------------------------------
 /**
- * `review --title "…" [--req ids] [--deployment dep_…] [files…]`: the coding agent's one command for a review. It
+ * `review [--req ids] [--title "…"] [--deployment dep_…] [files…]`: the coding agent's one command for a review. It
  * collects the change itself (git, or the listed files where git sees none), calls request_review, waits on
  * get_review (which holds up to 50 s per call) and prints the verdict. Nothing to paste, nothing to poll.
  */
 async function review() {
-    const args = parseReviewArgs(process.argv.slice(3));
+    const args = parseReviewArgs(process.argv.slice(3), existsSync);
+    if ("help" in args)
+        return console.log(REVIEW_HELP);
     if ("error" in args)
         throw new Error(args.error);
     const creds = credentials();
+    const again = process.argv.slice(2);
     if (!creds)
-        throw new Error("Not signed in here: run `npx -y @openscaffold/cli@latest login` (one click), or send the diff with the request_review tool.");
-    const deployment = args.deployment ?? loadedHere(undefined, process.cwd())?.deployment;
+        throw new Error(`Not signed in here. Run ${commandLine(["login"])} (one click in the browser), then ${commandLine(again)}. With the plugin or OAuth only, send the diff with the request_review tool instead.`);
+    // The calling Claude session's deployment first (another session in this folder may have switched), else the folder's.
+    const deployment = args.deployment ?? loadedHere(callerSession(process.env), process.cwd())?.deployment;
     if (!deployment)
-        throw new Error("Which customer? Add --deployment dep_… (the id in the OpenScaffold briefing).");
+        throw new Error(whichCustomerError(again, knownDeployments(creds)));
     const git = (a) => execFileSync("git", a, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
     const got = collectDiff(args.files, git, (f) => (lstatSync(f).isSymbolicLink() ? { link: readlinkSync(f) } : readFileSync(f, "utf8")));
     if ("error" in got)
         throw new Error(got.error);
+    const cached = join(CACHE, `${deployment}.md`);
+    const briefing = existsSync(cached) ? readFileSync(cached, "utf8") : null;
+    const name = briefing && /^# OpenScaffold — (.+)$/m.exec(briefing)?.[1]?.trim();
+    const title = args.title === DEFAULT_REVIEW_TITLE ? reviewTitle(args.reqs, briefing) : args.title;
+    // No --deployment and no Claude session id in this shell: the folder's default, said out loud.
+    const which = !args.deployment && !callerSession(process.env) ? " (this folder's default customer; pass --deployment to choose)" : "";
+    console.log(`Reviewing "${title}" for ${name ? `${name} (${deployment})` : deployment}${which}. ${REVIEW_WAIT}`);
     try {
-        const queued = JSON.parse(await tool(creds, "request_review", { deployment_id: deployment, title: args.title, requirement_ids: args.reqs, diff: got.diff }, 60_000));
+        const queued = JSON.parse(await tool(creds, "request_review", { deployment_id: deployment, title, requirement_ids: args.reqs, diff: got.diff }, 60_000));
         if (!queued.review_id)
             return console.log(queued.note ?? "Nothing to review.");
         let out = "";
@@ -475,7 +511,7 @@ async function status() {
         server,
         mcp,
         hook: hooks.includes("session-start"),
-        guardrails: hooks.includes("pre-commit") && hooks.includes("stop"),
+        guardrails: hooks.includes("pre-commit") && hooks.includes("stop") && hooks.includes("use-deployment"),
         skills: names.filter((n) => onDisk.includes(n)).length,
         skillsExpected: names.length,
         plugin: mcp === null ? false : pluginInstalled() && pluginServes(creds?.api_url),
@@ -508,13 +544,13 @@ Usage: npx @openscaffold/cli@latest <command>
                    Everything in one go: sign in if needed, create the customer's deployment, upload
                    every .vtt .srt .txt .md .csv .json in the folder (default .), wait for the plan, print it
   login            Sign in (one browser click on Approve) and connect Claude Code
-  review --title "<what it does>" [--req req_1,req_2] [--deployment dep_…] [files…]
+  review [--req req_1,req_2] [--title "…"] [--deployment dep_…] [files…]
                    Review this folder's change against the customer's plan and rules: sends the git diff
-                   (or the listed files, where git sees no change) and prints the verdict
+                   (or the listed files, where git sees no change) and prints the verdict. review --help for more
   status [--json]  What's set up on this machine, and the next step
   logout           Remove everything login added and revoke this machine's login
   help             This text
-  (session-start, pre-commit and stop are run by Claude Code's hooks)
+  (session-start, pre-commit, stop and use-deployment are run by Claude Code's hooks)
 
 Environment:
   OPENSCAFFOLD_URL         Server to sign in to (default ${DEFAULT_URL}; e.g. http://localhost:3000)
@@ -522,7 +558,7 @@ Environment:
                            (SSH and headless Linux are detected and skip the browser by themselves)`;
 const [cmd] = process.argv.slice(2);
 /** Run by a hook: must never break the session or block a tool, so any problem exits 0 quietly. */
-const HOOKS = new Set(["session-start", "pre-commit", "stop"]);
+const HOOKS = new Set(["session-start", "pre-commit", "stop", "use-deployment"]);
 if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     console.log(HELP);
     process.exit(0);
@@ -536,7 +572,7 @@ if (Number(process.versions.node.split(".")[0]) < 22) {
         console.log(msg);
     process.exit(HOOKS.has(cmd ?? "") ? 0 : 1);
 }
-const commands = { setup, login: () => login(), review, status, "session-start": sessionStart, "pre-commit": preCommit, stop, logout };
+const commands = { setup, login: () => login(), review, status, "session-start": sessionStart, "pre-commit": preCommit, stop, "use-deployment": useDeployment, logout };
 const run = commands[cmd ?? ""];
 if (!run) {
     console.error(HELP);

package/dist/install.js

@@ -2,19 +2,21 @@
 // Formats checked against code.claude.com docs (hooks, mcp, skills), 2026-10-23.
 export const MCP_NAME = "openscaffold";
 /** Our hook commands mention openscaffold and end in one of our subcommands (npx form or a local build path). */
-const isOurCommand = (cmd) => /openscaffold/.test(cmd) && /\b(session-start|pre-commit|stop)"?$/.test(cmd.trim());
+const isOurCommand = (cmd) => /openscaffold/.test(cmd) && /\b(session-start|pre-commit|stop|use-deployment)"?$/.test(cmd.trim());
 const HOOK_MATCHER = "startup|resume|clear|compact";
 const isOurs = (h) => typeof h.command === "string" && isOurCommand(h.command);
 /**
  * The hooks login installs (Claude Code docs, hooks, 2026-10-27): the briefing at session start; before a
  * `git commit` (the handler's `if` is one permission rule, `Bash(git commit *)` also matches a bare `git commit`),
- * the deployment's constraints and must-haves as context; at Stop, a one-time ask to review the changes (request_review) and report_session.
+ * the deployment's constraints and must-haves as context; at Stop, a one-time ask to review the changes (request_review) and report_session;
+ * after the agent's use_deployment or create_deployment, the local cache follows the switch (so review, pre-commit and Stop use the new customer).
  * Timeouts are seconds. None ever blocks a tool call.
  */
 export const OUR_HOOKS = [
     { event: "SessionStart", sub: "session-start", matcher: HOOK_MATCHER, handler: { timeout: 10 } },
     { event: "PreToolUse", sub: "pre-commit", matcher: "Bash", handler: { if: "Bash(git commit *)", timeout: 2 } },
     { event: "Stop", sub: "stop", matcher: undefined, handler: { timeout: 5 } },
+    { event: "PostToolUse", sub: "use-deployment", matcher: "mcp__.*openscaffold.*__(use|create)_deployment", handler: { timeout: 2 } },
 ];
 const withoutOurs = (groups = []) => groups.map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) })).filter((g) => g.hooks.length > 0);
 /** Adds (or replaces) our hooks, `<base> <subcommand>` each; leaves everything else in settings.json as it was. */
@@ -94,7 +96,7 @@ export function statusReport(s) {
         `Signed in:    ${s.workspace ? `yes, workspace "${s.workspace}" (${s.apiUrl}${s.server === "down" ? ", not answering" : s.server === "revoked" ? ", login revoked" : ""})` : "no"}`,
         `MCP server:   ${s.plugin ? "from the openscaffold plugin" : s.mcp === null ? "unknown (Claude Code not on PATH)" : s.mcp ? "added" : "missing"}`,
         `Session hook: ${s.hook ? "installed" : "missing"}`,
-        ...(s.guardrails === undefined ? [] : [`Guardrails:   ${s.guardrails ? "pre-commit plan check and end-of-session report reminder" : "missing"}`]),
+        ...(s.guardrails === undefined ? [] : [`Guardrails:   ${s.guardrails ? "pre-commit plan check and end-of-session report reminder" : "missing or out of date (logins before 2026-10-29 lack the customer-switch hook): re-run npx @openscaffold/cli login"}`]),
         `Commands:     ${s.plugin ? "/openscaffold:* from the plugin" : commandsOk ? `${s.skills} /os-* commands` : s.skills ? `${s.skills} of ${s.skillsExpected || "?"} /os-* commands` : "missing"}`,
     ];
     const next = !s.workspace || s.server === "revoked" || mcpOk === false || !s.hook || s.guardrails === false || !commandsOk
@@ -163,11 +165,53 @@ export function deploymentForCwd(index, cwd) {
         dir = up;
     }
 }
+/** A tool's output as text: a string, MCP content blocks, or `{content}` / `{text}` objects (transcripts, hook input). */
+const textOf = (r) => typeof r === "string" ? r : Array.isArray(r) ? r.map(textOf).join("\n") : r && typeof r === "object" ? textOf(r.text ?? r.content) : "";
+/**
+ * A use_deployment or create_deployment result (PostToolUse `tool_response`) → the deployment it switched to and a briefing
+ * to cache: use_deployment's own, or for create_deployment (JSON `{deployment: {id, name}}`, no briefing yet) just its name line.
+ */
+export function switchedTo(response) {
+    const briefing = textOf(response);
+    const deployment = /^Deployment id: (dep_\w+)/m.exec(briefing)?.[1];
+    if (deployment)
+        return { deployment, briefing };
+    try {
+        const created = JSON.parse(briefing).deployment;
+        if (typeof created?.id === "string" && /^dep_\w+$/.test(created.id))
+            return { deployment: created.id, briefing: `# OpenScaffold — ${String(created.name ?? created.id)}\n` };
+    }
+    catch { }
+    return null;
+}
+/**
+ * Whether a switch seen by the use-deployment hook may replace the CLI's cache. The user-scope server (`mcp__openscaffold__…`)
+ * is the one login added with this CLI's token: same server and workspace. The plugin's server is the hosted app signed in
+ * by its own OAuth, maybe another workspace: only a deployment this login already cached (`known`) on the hosted app. Else no.
+ */
+export function switchAllowed(toolName, deployment, apiUrl, known) {
+    if (toolName?.startsWith(`mcp__${MCP_NAME}__`))
+        return true;
+    return Boolean(toolName?.startsWith("mcp__plugin_")) && pluginServes(apiUrl) && new Set(known).has(deployment);
+}
+/** The Claude Code session a CLI command runs in, when Claude Code says (env), so `review` follows that session's deployment. */
+export const callerSession = (env) => env.CLAUDE_SESSION_ID || env.CLAUDE_CODE_SESSION_ID || undefined;
 /** session-start's per-Claude-session record (cache sessions.json): this session's entry added, only the newest `keep` kept. */
 export function withSession(sessions, sessionId, entry, keep = 200) {
     const all = Object.entries({ ...sessions, [sessionId]: entry }).sort(([, a], [, b]) => b.at.localeCompare(a.at));
     return Object.fromEntries(all.slice(0, keep));
 }
+/**
+ * The cache after loading a deployment: the Claude session's own entry, and the folder's default. A mid-session switch
+ * with a known session moves only that session's entry, so another session in the folder (or a `review` that can't tell
+ * which session called it) never picks it up; a session start, or a switch with no session, sets the folder default. Pure.
+ */
+export function rememberedCache(index, sessions, cwd, sessionId, entry, switching = false) {
+    return {
+        index: switching && sessionId ? index : { ...index, [cwd]: entry },
+        sessions: sessionId ? withSession(sessions, sessionId, entry) : sessions,
+    };
+}
 /** The deployment a hook's session loaded: by its Claude session_id first (two sessions can share a folder), else the folder's. */
 export const loadedEntry = (sessions, index, sessionId, cwd) => (sessionId ? sessions[sessionId] : undefined) ?? deploymentForCwd(index, cwd);
 /** A briefing section's list lines (§8.3), citations dropped: `- On-prem only` from `- On-prem only [Ticket · doc_… “…”]`. */
@@ -209,16 +253,23 @@ export function preCommitOutput(briefing, plugin) {
 const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
 /** Our report_session tool, from the user-scope server or the plugin's (`mcp__plugin_openscaffold_openscaffold__…`). */
 const REPORT = /^mcp__.*openscaffold.*__report_session$/;
-const REVIEW = /^mcp__.*openscaffold.*__request_review$/;
-/** `npx @openscaffold/cli review …` run through Bash counts as requesting a review. */
+/** The calls whose output can be a review: our get_review (user-scope or plugin), or the CLI's `review` through Bash. */
+const GET_REVIEW = /^mcp__.*openscaffold.*__get_review$/;
 const CLI_REVIEW = /(@openscaffold\/cli(@\S+)?|\bopenscaffold)\s+review\b/;
-/** From a session transcript (JSONL): did the agent edit files, call request_review, call report_session? */
+/** A finished review's verdict line (get_review's Markdown, which the CLI prints). Running and failed reviews have none. */
+const VERDICT = "\nVerdict: ";
+/**
+ * From a session transcript (JSONL): did the agent edit files, get a finished review back, call report_session? A review
+ * counts only as the tool_result of a get_review or Bash `… review` call (matched by tool_use_id) holding a verdict, so a
+ * failed or still-running review, or reading a file that contains one, doesn't.
+ */
 export function transcriptActivity(jsonl) {
     let edited = false;
     let reported = false;
     let reviewed = false;
+    const reviewCalls = new Set();
     for (const line of jsonl.split("\n")) {
-        if (!line.includes('"tool_use"'))
+        if (!line.includes('"tool_use"') && !(line.includes('"tool_result"') && line.includes("Verdict: ")))
             continue;
         let content;
         try {
@@ -230,23 +281,25 @@ export function transcriptActivity(jsonl) {
         if (!Array.isArray(content))
             continue;
         for (const c of content) {
+            if (c?.type === "tool_result" && c.tool_use_id && reviewCalls.has(c.tool_use_id) && textOf(c.content).includes(VERDICT))
+                reviewed = true;
             if (c?.type !== "tool_use" || typeof c.name !== "string")
                 continue;
             if (EDIT_TOOLS.has(c.name))
                 edited = true;
             if (REPORT.test(c.name))
                 reported = true;
-            if (REVIEW.test(c.name) || (c.name === "Bash" && typeof c.input?.command === "string" && CLI_REVIEW.test(c.input.command)))
-                reviewed = true;
+            if (c.id && (GET_REVIEW.test(c.name) || (c.name === "Bash" && typeof c.input?.command === "string" && CLI_REVIEW.test(c.input.command))))
+                reviewCalls.add(c.id);
         }
     }
     return { edited, reported, reviewed };
 }
 export const STOP_REASON = "Before you finish, call report_session with what you did.";
-export const STOP_REVIEW_REASON = "Before you finish, review your changes against the customer's plan: run `npx -y @openscaffold/cli@latest review --title \"<what the change does>\" --req <requirement ids>` (it sends the diff and prints the verdict), then report_session.";
+export const STOP_REVIEW_REASON = "Before you finish, review your changes against the customer's plan: run `npx -y @openscaffold/cli@latest review --req req_1,req_2` with the requirement ids you worked on (it sends the diff and prints the verdict; usually 30–90 s, up to ~7 min; don't wrap it in `timeout`), then report_session.";
 /**
  * The Stop hook's stdout: the documented block decision, once per session, when this session loaded a deployment and
- * edited files: first ask for a review (§8.4) if it never called request_review, else for report_session if it never
+ * edited files: first ask for a review (§8.4) if no review result came back, else for report_session if it never
  * reported; else "". Never twice, and never while Claude is already continuing for a stop hook.
  */
 export function stopOutput(s) {
@@ -355,28 +408,66 @@ export function mcpText(raw) {
 // --- review: send this folder's change to OpenScaffold's reviewer (SPEC §8.1 request_review) ------
 /** request_review's limit (web/lib/pipeline/review.ts MAX_DIFF_BYTES). */
 export const MAX_DIFF_BYTES = 400 * 1024;
-const REVIEW_USAGE = 'Usage: npx @openscaffold/cli@latest review --title "<what the change does>" [--req req_1,req_2] [--deployment dep_…] [files…]';
-/** `review` arguments; files are optional (git finds the change) and needed only where git sees none. */
-export function parseReviewArgs(args) {
+const REVIEW_CMD = "npx -y @openscaffold/cli@latest review";
+const REVIEW_USAGE = `Usage: ${REVIEW_CMD} [--req req_1,req_2] [--title "…"] [--deployment dep_…] [files…], e.g. ${REVIEW_CMD} --req req_1`;
+export const REVIEW_WAIT = "Usually 30–90 s, up to ~7 min; don't wrap it in `timeout`.";
+export const REVIEW_HELP = [
+    REVIEW_USAGE,
+    "",
+    "Reviews this folder's change against the customer's plan and rules: sends the git diff (or the listed files, where git",
+    "sees no change) and prints the verdict.",
+    "  --req ids          The plan's requirement ids this change works on (from the briefing or get_plan)",
+    '  --title "…"        One line: what the change does (default: those requirements\' titles); a bare phrase works too',
+    "  --deployment id    The customer (default: the one this folder's session loaded)",
+    "  files…             Narrow the change to these paths; outside git, the files to send whole",
+    REVIEW_WAIT,
+].join("\n");
+/** The title when none is given and the cached briefing names none of the claimed requirements. */
+export const DEFAULT_REVIEW_TITLE = "Review of current changes";
+/**
+ * `review` arguments; files are optional (git finds the change) and needed only where git sees none. A bare argument
+ * that isn't a file (`exists`) is the title, so `review "Fix X"` works. With no title, DEFAULT_REVIEW_TITLE (see reviewTitle).
+ */
+export function parseReviewArgs(args, exists = () => true) {
     const out = { title: "", reqs: [], deployment: undefined, files: [] };
     for (let i = 0; i < args.length; i++) {
         const eq = args[i].startsWith("--") ? args[i].indexOf("=") : -1;
         const [flag, inline] = eq < 0 ? [args[i], undefined] : [args[i].slice(0, eq), args[i].slice(eq + 1)];
         const value = () => inline ?? args[++i];
+        if (flag === "--help" || flag === "-h")
+            return { help: true };
         if (flag === "--title")
             out.title = value() ?? "";
         else if (flag === "--req" || flag === "--requirements")
             out.reqs.push(...(value() ?? "").split(/[,\s]+/).filter(Boolean));
         else if (flag === "--deployment")
             out.deployment = value();
-        else if (args[i].startsWith("--"))
+        else if (/^-./.test(args[i]))
             return { error: `Unknown option ${flag}. ${REVIEW_USAGE}` };
+        else if (/^req_\w+$/.test(args[i]) && !exists(args[i]))
+            out.reqs.push(args[i]); // `--req req_1 req_2`
+        // ponytail: a deleted file named alone reads as the title; then the whole change is reviewed, which still includes it.
+        else if (!out.title && !exists(args[i]))
+            out.title = args[i];
         else
             out.files.push(args[i]);
     }
-    if (!out.title.trim())
-        return { error: `Give the change a one-line title. ${REVIEW_USAGE}` };
-    return { ...out, title: out.title.trim(), reqs: [...new Set(out.reqs)] };
+    return { ...out, title: out.title.trim() || DEFAULT_REVIEW_TITLE, reqs: [...new Set(out.reqs)] };
+}
+/** A CLI command line to copy and run: `npx -y @openscaffold/cli@latest <args>`, quoting what a shell would split. */
+export const commandLine = (args) => ["npx -y @openscaffold/cli@latest", ...args.map((a) => (/^[\w./:@=,-]+$/.test(a) ? a : JSON.stringify(a)))].join(" ");
+/** `review` with no --deployment and none cached for this session or folder: the same command with each cached customer's id. */
+export function whichCustomerError(args, known) {
+    const head = "Which customer? This session has no OpenScaffold deployment cached here.";
+    if (!known.length)
+        return `${head} Add the id from the OpenScaffold briefing ("Deployment id: …", or call list_deployments), e.g. ${commandLine([...args, "--deployment", "dep_01EXAMPLE"])}`;
+    return [`${head} Run one of:`, ...known.map((d) => `  ${commandLine([...args, "--deployment", d.id])}${d.name ? `   # ${d.name}` : ""}`)].join("\n");
+}
+/** The default title: the claimed requirements' titles from the cached briefing's must-haves (`- req_1 Title — status`). */
+export function reviewTitle(reqs, briefing) {
+    const line = (id) => briefing?.split("\n").find((l) => l.startsWith(`- ${id} `));
+    const titles = reqs.map((id) => line(id)?.slice(id.length + 3).replace(/^\[[^\]]*\] /, "").replace(/ — \S+$/, "")).filter(Boolean);
+    return titles.length ? titles.join("; ").slice(0, 300) : DEFAULT_REVIEW_TITLE;
 }
 /**
  * A whole file as an added-file diff, as `git diff --no-index /dev/null <file>` prints it. Empty or binary: "". A
@@ -432,7 +523,7 @@ export function collectDiff(files, git, read) {
     if (!diff.trim()) {
         return { error: repo
                 ? `Nothing to review: git sees no change here. If your files are in a git-ignored folder, list them: ${REVIEW_USAGE}`
-                : `This folder isn't a git repo, so list the files you changed: ${REVIEW_USAGE}` };
+                : `This folder isn't a git repo, so list the files you changed (each is sent whole as a new file), e.g. ${REVIEW_CMD} --req req_1 src/report.py. Or send \`git diff --no-index /dev/null <file>\` for each file with the request_review tool.` };
     }
     if (Buffer.byteLength(diff) > MAX_DIFF_BYTES)
         return { error: `This change is ${Math.ceil(Buffer.byteLength(diff) / 1024)} KB; a review takes up to 400 KB. Review it in parts: list the files for one work item at a time.` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscaffold/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Connect Claude Code to your OpenScaffold workspace: each session loads the right customer deployment.",
   "type": "module",
   "bin": {