@openscaffold/cli 0.1.1 → 0.1.2

package/README.md

@@ -5,16 +5,33 @@ start, in any repo, loads the right customer deployment's briefing, and the Open
 (search the customer's calls, tickets and emails; read the cited plan; propose plan changes).
 
 ```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 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
 ```
 
+Then start a new Claude Code session and say:
+
+```text
+Set up OpenScaffold for my customer <Name> (<domain>). Follow https://docs.openscaffold.ai/agent-quickstart.md. Use the files in ./customer-docs.
+```
+
+If the Claude Code plugin `openscaffold` is installed, `login` adds only the session hook (the plugin already brings the
+MCP server and `/openscaffold:*` commands).
+
 `login` writes only to your user config (never into a repo):
 
 - `~/.config/openscaffold/credentials.json` (your login, mode 0600)
 - the `openscaffold` MCP server in Claude Code (user scope)
 - 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`
 - `/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.
+Requires Node 22+ and Claude Code. Set `OPENSCAFFOLD_URL` to point at a self-hosted OpenScaffold. Set
+`OPENSCAFFOLD_NO_BROWSER=1` to not open a browser (SSH sessions and headless Linux skip it by themselves); open the
+printed link on any device. Docs: https://docs.openscaffold.ai/cli

package/dist/index.js

@@ -1,18 +1,23 @@
 #!/usr/bin/env node
-// `npx @openscaffold/cli login | status | session-start | logout` (SPEC §8.4). Node 22+, standard library only.
+// `npx @openscaffold/cli setup | login | status | session-start | logout` (SPEC §8.4). Node 22+, standard library only.
 import { execFileSync, spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
-import { dirname, join } from "node:path";
-import { gitInfo, hasSessionHook, hookCommand, MCP_NAME, skillFile, statusReport, withoutSessionHook, withSessionHook } from "./install.js";
+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";
 const CONFIG = join(homedir(), ".config", "openscaffold");
 const CREDENTIALS = join(CONFIG, "credentials.json");
 const CACHE = join(CONFIG, "cache");
+/** Which deployment each recent Claude Code session loaded (session-start writes it; the guardrail hooks read it). */
+const SESSIONS = join(CACHE, "sessions.json");
 const CLAUDE = join(homedir(), ".claude");
 const SETTINGS = join(CLAUDE, "settings.json");
 const SKILLS = join(CLAUDE, "skills");
+const PLUGINS = join(CLAUDE, "plugins", "installed_plugins.json");
+/** Run by a coding agent (Claude Code sets CLAUDECODE; others run us without a terminal): talk to it, never prompt. */
+const BY_AGENT = Boolean(process.env.CLAUDECODE) || !process.stdout.isTTY;
 // OPENSCAFFOLD_URL overrides (local dev: http://localhost:3000).
-const DEFAULT_URL = "https://app.openscaffold.ai";
+const DEFAULT_URL = HOSTED;
 const readJson = (path, fallback) => {
     try {
         return JSON.parse(readFileSync(path, "utf8"));
@@ -39,37 +44,86 @@ async function api(url, path, body, { token, timeoutMs = 15_000 } = {}) {
     });
     return { status: res.status, body: (await res.json().catch(() => ({}))) };
 }
+/** One file as raw text (not JSON), so the request is the file's own size and fits the 4.5 MB request limit. */
+async function uploadFile(creds, deploymentId, filename, text) {
+    const url = new URL("/api/upload", creds.api_url);
+    url.search = new URLSearchParams({ deployment_id: deploymentId, filename }).toString();
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "text/plain; charset=utf-8", authorization: `Bearer ${creds.token}` },
+        body: text,
+        signal: AbortSignal.timeout(120_000),
+    });
+    return { status: res.status, body: (await res.json().catch(() => ({}))) };
+}
+/** Opens the login page if there's a browser here; the URL is always printed too, so any device can open it. */
 function openBrowser(url) {
-    if (process.env.OPENSCAFFOLD_NO_BROWSER)
-        return; // tests and headless machines: the URL is printed
-    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    const cmd = browserCommand(url, process.platform, process.env);
+    const noBrowser = () => console.log(`No browser to open here. Open this link on any device where you can sign in:\n  ${url}`);
+    if (!cmd)
+        return noBrowser();
     try {
-        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+        // A missing opener (headless Linux, WSL, SSH) fails asynchronously: without this listener it would crash the login.
+        const child = spawn(cmd[0], cmd[1], { stdio: "ignore", detached: true });
+        child.on("error", noBrowser);
+        child.unref();
+    }
+    catch {
+        noBrowser();
     }
-    catch { }
 }
-/** Runs `claude …`; returns false if Claude Code isn't on PATH or the command failed. */
-function claude(args) {
+/**
+ * Runs `claude …`: "ok", "missing" (not on PATH) or "failed". On Windows an npm install is `claude.cmd`, which
+ * execFile can't start (ENOENT, or EINVAL on newer Node), so it falls back to a shell.
+ */
+function runClaude(args, { timeout = 30_000, capture = false } = {}) {
+    const opts = { stdio: (capture ? ["ignore", "pipe", "ignore"] : "ignore"), timeout, encoding: "utf8" };
+    try {
+        return { result: "ok", out: execFileSync("claude", args, opts) ?? undefined };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code !== "ENOENT" && code !== "EINVAL")
+            return { result: "failed" };
+        if (process.platform !== "win32")
+            return { result: "missing" };
+    }
+    try {
+        execFileSync("where", ["claude"], { stdio: "ignore", timeout: 5000 });
+    }
+    catch {
+        return { result: "missing" };
+    }
     try {
-        execFileSync("claude", args, { stdio: "ignore", timeout: 30_000 });
-        return true;
+        return { result: "ok", out: execFileSync(windowsCommandLine(["claude", ...args]), { ...opts, shell: true }) ?? undefined };
     }
     catch {
-        return false;
+        return { result: "failed" };
     }
 }
+const claude = (args) => runClaude(args).result === "ok";
+/** The Claude Code plugin "openscaffold" is installed: it already brings the MCP server and commands. */
+const pluginInstalled = () => hasOpenScaffoldPlugin(runClaude(["plugin", "list", "--json"], { capture: true, timeout: 15_000 }).out ?? null, existsSync(PLUGINS) ? readFileSync(PLUGINS, "utf8") : null);
 // --- login --------------------------------------------------------------------------------------
-async function login() {
+/** `next: false` (from setup): skip the "now say this to Claude Code" step, setup does it. */
+async function login({ next = true } = {}) {
     const url = (process.env.OPENSCAFFOLD_URL ?? credentials()?.api_url ?? DEFAULT_URL).replace(/\/$/, "");
     const start = await api(url, "/api/connect/start", { client_label: hostname() });
     if (start.status !== 200)
         throw new Error(`Couldn't reach OpenScaffold at ${url} (${start.status}).`);
     const { code, login_url, poll } = start.body;
-    console.log(`Opening ${login_url}\nClick Approve in your browser. The page should show the code ${code}.`);
+    console.log(BY_AGENT
+        ? `Tell the person: open ${login_url}, check the workspace on the page, then click Approve. The page shows the code ${code}. Signing up, if they need to, happens on that page too.`
+        : `Opening ${login_url}\nCheck the workspace on the page, then click Approve. The page should show the code ${code}.`);
     openBrowser(login_url);
     let creds = null;
-    for (const deadline = Date.now() + 10 * 60_000; Date.now() < deadline;) {
+    const deadline = Date.now() + 10 * 60_000;
+    for (let lastNote = Date.now(); Date.now() < deadline;) {
         await new Promise((r) => setTimeout(r, 2000));
+        if (Date.now() - lastNote >= 60_000) {
+            lastNote = Date.now();
+            console.log(`Waiting for you to click Approve at ${login_url} (code ${code})… ${Math.ceil((deadline - Date.now()) / 60_000)} min left.`);
+        }
         const r = await api(url, "/api/connect/exchange", { poll }).catch(() => null);
         if (r?.status === 200) {
             creds = { api_url: String(r.body.api_url ?? url), token: String(r.body.token), workspace: r.body.workspace };
@@ -78,25 +132,43 @@ async function login() {
         if (r && r.status !== 202)
             throw new Error(String(r.body.error ?? "Login failed. Run `npx @openscaffold/cli login` again."));
     }
-    if (!creds)
-        throw new Error("Timed out waiting for approval. Run `npx @openscaffold/cli login` again.");
+    if (!creds) {
+        // Not an error for an agent to retry blindly: nobody clicked. Exit 0 with what to do.
+        console.log("Nobody clicked Approve within 10 minutes, so nothing was changed. Run `npx @openscaffold/cli@latest login` again when you're at your browser.");
+        console.log(loginResultLine("timeout"));
+        return;
+    }
     writeJson(CREDENTIALS, creds, 0o600);
     // Offline fallback briefings belong to the previous login (maybe another server or workspace): start fresh.
     rmSync(CACHE, { recursive: true, force: true });
     const written = [`${CREDENTIALS} (your login, readable only by you)`];
+    // The plugin already brings the MCP server and /openscaffold:* commands: a second server or the os-* copies would
+    // show every tool and command twice. Then only the hook (which the plugin can't do: pick the customer) is added.
+    // The plugin always points at the hosted app: logged in elsewhere (local, self-hosted), the CLI's own server is kept,
+    // or tools would hit the hosted app while the hooks read this server.
+    const pluginHere = pluginInstalled();
+    const plugin = pluginHere && pluginServes(creds.api_url);
+    if (pluginHere && !plugin)
+        console.log(`\nThe Claude Code plugin "${MCP_NAME}" points at ${HOSTED}, not ${creds.api_url}, so login adds its own MCP server and /os-* commands for ${creds.api_url}.`);
     // 1. MCP server at user scope (replace any earlier login's).
     const mcpUrl = `${creds.api_url}/api/mcp/mcp`;
     const addArgs = ["mcp", "add", "--transport", "http", "--scope", "user", MCP_NAME, mcpUrl, "--header", `Authorization: Bearer ${creds.token}`];
     claude(["mcp", "remove", "--scope", "user", MCP_NAME]);
-    if (claude(addArgs))
+    if (plugin)
+        console.log(`\nThe Claude Code plugin "${MCP_NAME}" is installed, so it provides the MCP server and /openscaffold:* commands. Adding only the hooks: the one that loads the right customer, and the pre-commit and end-of-session guardrails.`);
+    else if (claude(addArgs))
         written.push(`Claude Code MCP server "${MCP_NAME}" (user scope)`);
     else
         console.log(`\nClaude Code wasn't found on PATH. Once it is, run:\n  claude ${addArgs.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")}\n`);
-    // 2. SessionStart hook: loads the right deployment's briefing in every session.
-    writeJson(SETTINGS, withSessionHook(readJson(SETTINGS, {}), hookCommand(process.argv[1], process.execPath)));
-    written.push(`${SETTINGS} (SessionStart hook)`);
+    // 2. Hooks: the SessionStart briefing in every session, plus the guardrails (pre-commit plan check, report reminder).
+    writeJson(SETTINGS, withHooks(readJson(SETTINGS, {}), hookBase(process.argv[1], process.execPath)));
+    written.push(`${SETTINGS} (hooks: SessionStart briefing, pre-commit plan check, end-of-session report reminder)`);
     // 3. Commands as personal skills: /os-requirements, /os-what-changed, /os-check-plan, /os-demo-check.
-    const commands = await fetch(`${creds.api_url}/api/commands`).then((r) => r.json()).catch(() => []);
+    const commands = plugin ? [] : await fetch(`${creds.api_url}/api/commands`).then((r) => r.json()).catch(() => []);
+    if (plugin && existsSync(SKILLS))
+        for (const d of readdirSync(SKILLS))
+            if (d.startsWith("os-"))
+                rmSync(join(SKILLS, d), { recursive: true, force: true });
     for (const c of commands) {
         const dir = join(SKILLS, `os-${c.name}`);
         mkdirSync(dir, { recursive: true });
@@ -104,10 +176,148 @@ async function login() {
     }
     if (commands.length)
         written.push(`${SKILLS}/os-* (${commands.map((c) => `/os-${c.name}`).join(", ")})`);
-    const self = hookCommand(process.argv[1], process.execPath).replace(/ session-start$/, "");
-    console.log(`\nLogged in to ${creds.workspace.name}.\nWrote:\n${written.map((w) => `  - ${w}`).join("\n")}\nNothing was written into any repo.\n\nStart Claude Code in any repo; it loads the right customer automatically.\nTo undo everything: ${self} logout\n`);
-    // End on the status report, so a person or agent needn't run (and download) status separately.
-    await status();
+    const self = hookBase(process.argv[1], process.execPath);
+    console.log(`\nLogged in to ${creds.workspace.name}.\nWrote:\n${written.map((w) => `  - ${w}`).join("\n")}\nNothing was written into any repo.\n` +
+        (next ? `\nStart a new Claude Code session (tools load when a session starts), then say:\n  ${setupPrompt()}\n` +
+            `(Already have the customer in OpenScaffold? Say "load <customer>" instead.)\n` : "") +
+        `To undo everything: ${self} logout\n`);
+    // End on the status report, so a person or agent needn't run (and download) status separately. Inside `setup`
+    // (next: false) setup carries on and ends on its own result, so login's status and "Next:" would only mislead.
+    if (!next)
+        return;
+    const ready = await status();
+    console.log(loginResultLine("ok", { workspace: creds.workspace.name, ready, restart_needed: true }));
+}
+// --- setup: login if needed, deployment, files, wait for the plan --------------------------------
+class LoggedOut extends Error {
+}
+/** One MCP tool call with the stored token: the same server and tools Claude Code uses. Throws the tool's error text. */
+async function tool(creds, name, args, timeoutMs = 30_000) {
+    const res = await fetch(new URL("/api/mcp/mcp", creds.api_url), {
+        method: "POST",
+        headers: { authorization: `Bearer ${creds.token}`, "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-protocol-version": "2025-06-18" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: Date.now(), method: "tools/call", params: { name, arguments: args } }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res.status === 401)
+        throw new LoggedOut("Your login expired or was revoked.");
+    const r = mcpText(await res.text());
+    if ("error" in r)
+        throw new Error(r.error);
+    return r.text;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * `setup <domain> [folder]`: one command from a folder of customer files to a cited plan. Logs in if needed (the login
+ * flow, which also connects Claude Code), creates the deployment (or reuses the one for that domain), uploads every
+ * supported file through the upload panel's path, waits for the plan (it starts on its own once the files are read,
+ * §7.1) and prints it with its quotes. Ends on one JSON line for agents.
+ */
+async function setup() {
+    const args = parseSetupArgs(process.argv.slice(3));
+    if ("error" in args)
+        throw new Error(args.error);
+    const folder = resolve(args.folder);
+    if (!existsSync(folder) || !statSync(folder).isDirectory())
+        throw new Error(`No folder at ${folder}.`);
+    const entries = readdirSync(folder, { withFileTypes: true }).map((d) => ({ name: d.name, file: d.isFile(), size: d.isFile() ? statSync(join(folder, d.name)).size : 0 }));
+    const { upload, skipped } = selectFiles(entries);
+    if (!upload.length)
+        throw new Error(`No customer files in ${folder} (looked for ${SETUP_EXTENSIONS.join(" ")}). Point setup at the folder with their calls, tickets and emails.`);
+    // 1. Logged in, with a token that still works? Else the login flow.
+    let creds = credentials();
+    let deps = null;
+    if (creds)
+        deps = await tool(creds, "list_deployments", {}).then((t) => JSON.parse(t), (e) => { if (e instanceof LoggedOut)
+            return null; throw e; });
+    if (!creds || !deps) {
+        await login({ next: false });
+        creds = credentials();
+        if (!creds)
+            return console.log(JSON.stringify({ openscaffold_setup: "not_logged_in" })); // login said what to do
+        deps = JSON.parse(await tool(creds, "list_deployments", {}));
+    }
+    // 2. The customer's deployment: the one with this domain, else a new one named from it.
+    let dep = deps.find((d) => d.customer_domains?.includes(args.domain));
+    if (dep)
+        console.log(`\nUsing ${dep.name} (already set up for ${args.domain}).`);
+    else {
+        const r = JSON.parse(await tool(creds, "create_deployment", { name: nameFromDomain(args.domain), customer_domains: [args.domain] }));
+        dep = { ...r.deployment, harness_version: null };
+        console.log(`\nCreated ${dep.name} in ${creds.workspace.name}.`);
+    }
+    // 3. Every file, one request each (the upload panel's parse path; a CSV's tickets stay one batch).
+    console.log(`Uploading ${upload.length} file${upload.length === 1 ? "" : "s"} from ${folder}`);
+    let added = 0;
+    const failed = []; // the rest still upload; the run ends "partial" naming these
+    for (const name of upload) {
+        const r = await uploadFile(creds, dep.id, name, readFileSync(join(folder, name), "utf8"))
+            .catch((e) => ({ status: 0, body: { error: e instanceof Error ? e.message : String(e) } }));
+        if (r.status === 200)
+            added += Number(r.body.added ?? 0);
+        else
+            failed.push(name);
+        console.log(`  ${name}: ${r.status === 200 ? (Number(r.body.added) ? `${r.body.added} source${Number(r.body.added) === 1 ? "" : "s"}` : "already uploaded") : `not uploaded: ${r.body.error ?? r.status}`}`);
+    }
+    for (const s of skipped)
+        console.log(`  ${s.name}: skipped, ${s.why}`);
+    if (failed.length === upload.length)
+        throw new Error(`None of the files uploaded (${failed.join(", ")}). Add them in ${dep.name}'s Sources in OpenScaffold (${creds.api_url}).`);
+    const { id: depId, name: depName } = dep;
+    const app = creds.api_url;
+    /** The last lines: failed uploads named (non-zero exit for a person; an agent reads the JSON line), then the result. */
+    const finish = (result, extra) => {
+        if (failed.length) {
+            console.log(`\nNot uploaded: ${failed.join(", ")}. Add ${failed.length === 1 ? "it" : "them"} in ${depName}'s Sources in OpenScaffold (${app}); a CSV whose columns weren't recognized can be mapped there.`);
+            if (!BY_AGENT)
+                process.exitCode = 1;
+        }
+        console.log(setupResultLine(result, failed, { deployment: depId, added, ...extra }));
+    };
+    if (dep.harness_version != null) {
+        console.log(`\n${dep.name} already has a plan. New sources become plan changes in its Inbox, for you to approve: ${creds.api_url}`);
+        return finish("ok", { plan: "existing" });
+    }
+    // 4. Wait for the plan; nudge it once if nothing is reading or building (e.g. the automatic build failed).
+    console.log("\nReading the sources, then writing the plan (usually 2–4 minutes).");
+    const deadline = Date.now() + 20 * 60_000;
+    let last = "";
+    const shown = new Set(); // facts already printed, so each prints once as it's found
+    let idle = 0;
+    let nudged = false;
+    for (;;) {
+        const briefing = await tool(creds, "get_briefing", { deployment_id: dep.id }, 20_000).catch(() => "");
+        const status = briefing && briefingStatus(briefing);
+        if (briefing && !status) {
+            // The cited plan and profile, not the briefing: it shortens the lists and leaves some quotes out.
+            const [plan, profile] = await Promise.all(["get_plan", "get_profile"].map((t) => tool(creds, t, { deployment_id: dep.id })));
+            console.log(`\nThe plan for ${dep.name} is ready. Every line is quoted from their sources:\n\n${planSummary(plan, profile) || "(No goal or must-haves in the sources yet.)"}\n`);
+            console.log(`Review it and mark what the customer agreed to: ${dep.url ?? creds.api_url}\nThen open Claude Code in your repo and say: load ${dep.name}`);
+            return finish("ok", { plan: "ready" });
+        }
+        if (status && status !== last)
+            console.log(`  ${(last = status)}`);
+        const facts = briefing ? briefingFacts(briefing).filter((f) => !shown.has(f)) : [];
+        if (facts.length && !shown.size)
+            console.log("  Found so far, quoted from their sources:");
+        for (const f of facts) {
+            console.log(`    ${f}`);
+            shown.add(f);
+        }
+        idle = status?.startsWith("No plan yet") ? idle + 1 : 0;
+        if (idle >= 2) {
+            if (nudged)
+                throw new Error(`The plan didn't build. Open ${dep.name} in OpenScaffold (${creds.api_url}) to see why, and Retry there.`);
+            nudged = true;
+            idle = 0;
+            await tool(creds, "generate_harness", { deployment_id: dep.id });
+        }
+        if (Date.now() > deadline) {
+            console.log(`Still going after 20 minutes; it keeps running without this window. See ${dep.name}'s Overview in OpenScaffold (${creds.api_url}).`);
+            return finish("waiting", {});
+        }
+        await sleep(10_000);
+    }
 }
 // --- session-start (the SessionStart hook) ------------------------------------------------------
 const readStdin = async () => {
@@ -150,7 +360,11 @@ async function sessionStart() {
         if (dep) {
             mkdirSync(CACHE, { recursive: true });
             writeFileSync(join(CACHE, `${dep}.md`), briefing);
-            writeJson(join(CACHE, "index.json"), { ...index, [cwd]: { deployment: dep, at: new Date().toISOString(), login: loginKey(creds) } });
+            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));
         }
     }
     catch {
@@ -159,18 +373,86 @@ async function sessionStart() {
         console.log(cached ? `${cached}\n\n(offline, from ${last?.at})` : "OpenScaffold: offline");
     }
 }
-// --- status -------------------------------------------------------------------------------------
-/** Read-only: what's set up on this machine and the next step. `--json` for agents. Always exits 0. */
-async function status() {
+// --- guardrail hooks (pre-commit, stop): local files only, no network, never block a tool --------
+const loadedHere = (sessionId, cwd) => {
     const creds = credentials();
-    let mcp = null;
+    const entry = creds ? loadedEntry(readJson(SESSIONS, {}), readJson(join(CACHE, "index.json"), {}), sessionId, cwd) : undefined;
+    return entry && entry.login === loginKey(creds) ? entry : undefined;
+};
+const hookInput = async () => {
     try {
-        execFileSync("claude", ["mcp", "get", MCP_NAME], { stdio: "ignore", timeout: 15_000 });
-        mcp = true;
+        return JSON.parse((await readStdin()) || "{}");
+    }
+    catch {
+        return {};
+    }
+};
+/** PreToolUse on `git commit`: the deployment's constraints and must-haves from the cached briefing, as context. */
+async function preCommit() {
+    const hook = await hookInput();
+    const entry = loadedHere(hook.session_id, hook.cwd ?? process.cwd());
+    const file = entry && join(CACHE, `${entry.deployment}.md`);
+    const out = preCommitOutput(file && existsSync(file) ? readFileSync(file, "utf8") : null, hasOpenScaffoldPlugin(null, existsSync(PLUGINS) ? readFileSync(PLUGINS, "utf8") : null));
+    if (out)
+        console.log(out);
+}
+/** Stop: once per session, if it edited files and never called request_review (or report_session), ask for it. */
+async function stop() {
+    const hook = await hookInput();
+    if (!hook.session_id || hook.stop_hook_active)
+        return;
+    const marker = join(CACHE, `reminded-${hook.session_id.replace(/[^\w-]/g, "")}`);
+    const transcript = hook.transcript_path?.replace(/^~(?=[\\/])/, homedir());
+    const activity = transcript && existsSync(transcript) ? transcriptActivity(readFileSync(transcript, "utf8")) : { edited: false, reported: false, reviewed: false };
+    const out = stopOutput({ stopHookActive: false, reminded: existsSync(marker), loaded: Boolean(loadedHere(hook.session_id, hook.cwd ?? process.cwd())), ...activity });
+    if (!out)
+        return;
+    mkdirSync(CACHE, { recursive: true });
+    writeFileSync(marker, new Date().toISOString());
+    console.log(out);
+}
+// --- review -------------------------------------------------------------------------------------
+/**
+ * `review --title "…" [--req ids] [--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));
+    if ("error" in args)
+        throw new Error(args.error);
+    const creds = credentials();
+    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;
+    if (!deployment)
+        throw new Error("Which customer? Add --deployment dep_… (the id in the OpenScaffold briefing).");
+    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);
+    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));
+        if (!queued.review_id)
+            return console.log(queued.note ?? "Nothing to review.");
+        let out = "";
+        // Each get_review waits up to 50 s on the server; a review that outlasts four of them is reported as still running.
+        for (let i = 0; i < 4 && (!out || out.includes("Still reviewing")); i++)
+            out = await tool(creds, "get_review", { deployment_id: deployment, review_id: queued.review_id }, 90_000);
+        console.log(out);
     }
     catch (e) {
-        mcp = e.code === "ENOENT" ? null : false;
+        if (e instanceof LoggedOut)
+            throw new Error(`${e.message} Run \`npx -y @openscaffold/cli@latest login\`, then review again.`);
+        throw e;
     }
+}
+// --- status -------------------------------------------------------------------------------------
+/** Read-only: what's set up on this machine and the next step. `--json` for agents. Always exits 0. */
+async function status() {
+    const creds = credentials();
+    const got = runClaude(["mcp", "get", MCP_NAME], { timeout: 15_000 }).result;
+    const mcp = got === "missing" ? null : got === "ok";
     // An authenticated request, so a revoked token isn't reported as ready: the MCP endpoint answers 401 to a bad token.
     const server = creds
         ? await fetch(new URL("/api/mcp/mcp", creds.api_url), {
@@ -186,17 +468,21 @@ async function status() {
         : null;
     const onDisk = existsSync(SKILLS) ? readdirSync(SKILLS).filter((d) => d.startsWith("os-") && existsSync(join(SKILLS, d, "SKILL.md"))) : [];
     const names = expected ?? onDisk;
+    const hooks = installedHooks(readJson(SETTINGS, {}));
     const state = {
         workspace: creds?.workspace.name ?? null,
         apiUrl: creds?.api_url ?? null,
         server,
         mcp,
-        hook: hasSessionHook(readJson(SETTINGS, {})),
+        hook: hooks.includes("session-start"),
+        guardrails: hooks.includes("pre-commit") && hooks.includes("stop"),
         skills: names.filter((n) => onDisk.includes(n)).length,
         skillsExpected: names.length,
+        plugin: mcp === null ? false : pluginInstalled() && pluginServes(creds?.api_url),
     };
     const report = statusReport(state);
     console.log(process.argv.includes("--json") ? JSON.stringify({ ...state, ready: report.ready, next: report.next }, null, 2) : report.text);
+    return report.ready;
 }
 // --- logout -------------------------------------------------------------------------------------
 async function logout() {
@@ -205,27 +491,68 @@ async function logout() {
         await api(creds.api_url, "/api/connect/revoke", {}, { token: creds.token, timeoutMs: 5000 }).catch(() => null);
     claude(["mcp", "remove", "--scope", "user", MCP_NAME]);
     if (existsSync(SETTINGS))
-        writeJson(SETTINGS, withoutSessionHook(readJson(SETTINGS, {})));
+        writeJson(SETTINGS, withoutHooks(readJson(SETTINGS, {})));
     if (existsSync(SKILLS))
         for (const d of readdirSync(SKILLS))
             if (d.startsWith("os-"))
                 rmSync(join(SKILLS, d), { recursive: true, force: true });
     rmSync(CONFIG, { recursive: true, force: true });
-    console.log("Logged out: token revoked, MCP server, hook, /os-* commands and local credentials removed.");
+    console.log("Logged out: token revoked, MCP server, hooks, /os-* commands and local credentials removed.");
 }
 // --- main ---------------------------------------------------------------------------------------
+const HELP = `OpenScaffold CLI: connect Claude Code to your OpenScaffold workspace. Docs: https://docs.openscaffold.ai/cli
+
+Usage: npx @openscaffold/cli@latest <command>
+
+  setup <domain> [folder]
+                   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 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
+  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)
+
+Environment:
+  OPENSCAFFOLD_URL         Server to sign in to (default ${DEFAULT_URL}; e.g. http://localhost:3000)
+  OPENSCAFFOLD_NO_BROWSER  Set to 1 to not open a browser; open the printed link on any device instead
+                           (SSH and headless Linux are detected and skip the browser by themselves)`;
 const [cmd] = process.argv.slice(2);
-const commands = { login, status, "session-start": sessionStart, logout };
+/** 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"]);
+if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    process.exit(0);
+}
+// npx doesn't enforce "engines": say it plainly instead of failing on a missing API later.
+if (Number(process.versions.node.split(".")[0]) < 22) {
+    const msg = `OpenScaffold CLI needs Node 22 or newer; this is Node ${process.versions.node}. Install it from https://nodejs.org (or \`nvm install 22\`), then run the command again.`;
+    if (cmd === "session-start")
+        console.log(`OpenScaffold: ${msg}`);
+    else if (!HOOKS.has(cmd ?? ""))
+        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 run = commands[cmd ?? ""];
 if (!run) {
-    console.error("Usage: npx @openscaffold/cli <login | status | logout>\n(session-start is run by Claude Code's SessionStart hook)");
+    console.error(HELP);
     process.exit(1);
 }
-run().then(() => process.exit(0), (e) => {
-    if (cmd === "session-start") {
-        console.log("OpenScaffold: offline"); // never break a session
+run().then(() => process.exit(), // process.exitCode, if a command set one (setup with failed uploads)
+(e) => {
+    if (HOOKS.has(cmd ?? "")) {
+        if (cmd === "session-start")
+            console.log("OpenScaffold: offline"); // never break a session
         process.exit(0);
     }
     console.error(e instanceof Error ? e.message : e);
+    if (cmd === "login")
+        console.log(loginResultLine("error", { message: e instanceof Error ? e.message : String(e) }));
+    if (cmd === "setup")
+        console.log(JSON.stringify({ openscaffold_setup: "error", message: e instanceof Error ? e.message : String(e) }));
     process.exit(1);
 });

package/dist/install.js

@@ -1,49 +1,65 @@
 // Pure helpers for what `openscaffold login`/`logout` write into Claude Code (SPEC §8.4).
 // Formats checked against code.claude.com docs (hooks, mcp, skills), 2026-10-23.
 export const MCP_NAME = "openscaffold";
-/** Our hook command mentions openscaffold and ends in `session-start` (npx form or a local build path). */
-const isOurCommand = (cmd) => /openscaffold/.test(cmd) && /\bsession-start"?$/.test(cmd.trim());
+/** 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 HOOK_MATCHER = "startup|resume|clear|compact";
 const isOurs = (h) => typeof h.command === "string" && isOurCommand(h.command);
-/** Adds (or replaces) our SessionStart hook; leaves everything else in settings.json as it was. */
-export function withSessionHook(settings, 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.
+ * 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 } },
+];
+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. */
+export function withHooks(settings, base) {
     const out = structuredClone(settings);
-    const groups = (out.hooks?.SessionStart ?? [])
-        .map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) }))
-        .filter((g) => g.hooks.length > 0);
-    groups.push({ matcher: HOOK_MATCHER, hooks: [{ type: "command", command, timeout: 10 }] });
-    out.hooks = { ...out.hooks, SessionStart: groups };
+    const hooks = { ...out.hooks };
+    for (const h of OUR_HOOKS) {
+        const group = { ...(h.matcher ? { matcher: h.matcher } : {}), hooks: [{ type: "command", ...("if" in h.handler ? { if: h.handler.if } : {}), command: `${base} ${h.sub}`, timeout: h.handler.timeout }] };
+        hooks[h.event] = [...withoutOurs(hooks[h.event]), group];
+    }
+    out.hooks = hooks;
     return out;
 }
-/** Removes our SessionStart hook (and empty leftovers); leaves other hooks alone. */
-export function withoutSessionHook(settings) {
+/** Removes our hooks (and empty leftovers) from every event; leaves other hooks alone. */
+export function withoutHooks(settings) {
     const out = structuredClone(settings);
-    if (!out.hooks?.SessionStart)
+    if (!out.hooks)
         return out;
-    const groups = out.hooks.SessionStart.map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) })).filter((g) => g.hooks.length > 0);
-    if (groups.length)
-        out.hooks.SessionStart = groups;
-    else
-        delete out.hooks.SessionStart;
+    for (const event of Object.keys(out.hooks)) {
+        const groups = withoutOurs(out.hooks[event]);
+        if (groups.length)
+            out.hooks[event] = groups;
+        else
+            delete out.hooks[event];
+    }
     if (!Object.keys(out.hooks).length)
         delete out.hooks;
     return out;
 }
 /**
- * The hook command. Published installs run through npx; a local checkout (development) runs its
- * own built file, so the hook works before the package is on npm.
+ * The command our hooks run, without the subcommand. Published installs run through npx; a local checkout
+ * (development) runs its own built file, so the hooks work before the package is on npm.
  */
-export function hookCommand(selfPath, execPath) {
+export function hookBase(selfPath, execPath) {
     if (/[\\/]_npx[\\/]|[\\/]node_modules[\\/]@openscaffold[\\/]cli[\\/]/.test(selfPath))
-        return `npx -y @openscaffold/cli session-start`;
-    return `${JSON.stringify(execPath)} ${JSON.stringify(selfPath)} session-start`;
+        return "npx -y @openscaffold/cli";
+    return `${JSON.stringify(execPath)} ${JSON.stringify(selfPath)}`;
 }
-/** A personal skill file for one default command: /os-<name>. */
-export function skillFile(c) {
+/** A skill file for one default command: /os-<name> as a personal skill, or /openscaffold:<name> in the plugin. */
+export function skillFile(c, name = `os-${c.name}`) {
     return [
         "---",
-        `name: os-${c.name}`,
-        `description: ${c.description.replace(/\n/g, " ")} (OpenScaffold)`,
+        `name: ${name}`,
+        // JSON-quoted: a valid YAML string whatever the text holds (a ": " or "#" would break a plain value).
+        `description: ${JSON.stringify(`${c.description.replace(/\n/g, " ")} (OpenScaffold)`)}`,
         "---",
         "",
         c.prompt,
@@ -58,28 +74,367 @@ export function gitInfo(remoteOut, branchOut) {
     const branch = branchOut?.trim() || undefined;
     return { git_remote: remote, git_branch: branch };
 }
-/** Whether our SessionStart hook is in settings.json. */
-export const hasSessionHook = (settings) => (settings.hooks?.SessionStart ?? []).some((g) => g.hooks.some(isOurs));
-const HOSTED = "https://app.openscaffold.ai";
+/** Which of our hooks are in settings.json, e.g. ["session-start", "pre-commit", "stop"]. */
+export const installedHooks = (settings) => OUR_HOOKS.filter((h) => (settings.hooks?.[h.event] ?? []).some((g) => g.hooks.some((x) => isOurs(x) && x.command.trim().replace(/"$/, "").endsWith(h.sub)))).map((h) => h.sub);
+export const hasSessionHook = (settings) => installedHooks(settings).includes("session-start");
+/** The hosted app, which the Claude Code plugin's MCP server always points at (plugin/.mcp.json). */
+export const HOSTED = "https://app.openscaffold.ai";
+/** The plugin's MCP server is this login's server: only then can login leave the MCP server and commands to it. */
+export const pluginServes = (apiUrl) => (apiUrl ?? "").replace(/\/+$/, "") === HOSTED;
 const RELOGIN = (apiUrl) => `npx @openscaffold/cli login${apiUrl && apiUrl !== HOSTED ? ` (or OPENSCAFFOLD_URL=${HOSTED} npx @openscaffold/cli login to use the hosted app)` : ""}`;
 /**
  * `openscaffold status`: one line per piece of the setup plus the single next step, in words a person or a
  * coding agent can act on (the agent onboarding playbook reads it). `mcp: null` = Claude Code isn't on PATH.
  */
 export function statusReport(s) {
-    const commandsOk = s.skillsExpected > 0 && s.skills >= s.skillsExpected;
+    // With the plugin, the MCP server and commands come from it; login installs only the hook.
+    const commandsOk = s.plugin || (s.skillsExpected > 0 && s.skills >= s.skillsExpected);
+    const mcpOk = s.plugin ? true : s.mcp;
     const lines = [
         `Signed in:    ${s.workspace ? `yes, workspace "${s.workspace}" (${s.apiUrl}${s.server === "down" ? ", not answering" : s.server === "revoked" ? ", login revoked" : ""})` : "no"}`,
-        `MCP server:   ${s.mcp === null ? "unknown (Claude Code not on PATH)" : s.mcp ? "added" : "missing"}`,
+        `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"}`,
-        `Commands:     ${commandsOk ? `${s.skills} /os-* commands` : s.skills ? `${s.skills} of ${s.skillsExpected || "?"} /os-* commands` : "missing"}`,
+        ...(s.guardrails === undefined ? [] : [`Guardrails:   ${s.guardrails ? "pre-commit plan check and end-of-session report reminder" : "missing"}`]),
+        `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" || s.mcp === false || !s.hook || !commandsOk
+    const next = !s.workspace || s.server === "revoked" || mcpOk === false || !s.hook || s.guardrails === false || !commandsOk
         ? `Run: ${RELOGIN(s.apiUrl)} (one browser click to approve).`
         : s.server !== "ok"
             ? `${s.apiUrl} isn't answering. If it's a local dev server, start it; otherwise run: ${RELOGIN(s.apiUrl)}.`
-            : s.mcp === null
+            : mcpOk === null
                 ? "Claude Code isn't on PATH, so the MCP server can't be checked or added. Put `claude` on PATH, then run: npx @openscaffold/cli login."
                 : "Ready. Start a new Claude Code session (or restart this one) to load OpenScaffold.";
     return { ready: next.startsWith("Ready"), next, text: `OpenScaffold setup\n${lines.map((l) => `  ${l}`).join("\n")}\n\nNext: ${next}` };
 }
+/**
+ * Whether the Claude Code plugin "openscaffold" is installed (and enabled), from `claude plugin list --json`, else
+ * from ~/.claude/plugins/installed_plugins.json. Then login adds no second MCP server and no /os-* skills.
+ */
+export function hasOpenScaffoldPlugin(listJson, installedJson) {
+    const ours = (id) => typeof id === "string" && id.startsWith(`${MCP_NAME}@`);
+    try {
+        const list = JSON.parse(listJson ?? "null");
+        if (Array.isArray(list))
+            return list.some((p) => ours(p.id) && p.enabled !== false);
+    }
+    catch { }
+    try {
+        const installed = JSON.parse(installedJson ?? "null");
+        return Object.keys(installed?.plugins ?? {}).some(ours);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * How to open a URL here, or null when there's no browser to open (a person opens the printed link on any device):
+ * OPENSCAFFOLD_NO_BROWSER, an SSH session, or Linux without a display (headless, WSL without a bridge, containers).
+ */
+export function browserCommand(url, platform, env) {
+    if (env.OPENSCAFFOLD_NO_BROWSER || env.SSH_CONNECTION || env.SSH_TTY)
+        return null;
+    if (platform === "darwin")
+        return ["open", [url]];
+    if (platform === "win32")
+        return ["cmd", ["/c", "start", "", url]];
+    if (env.WSL_DISTRO_NAME)
+        return ["wslview", [url]];
+    if (!env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return null;
+    return ["xdg-open", [url]];
+}
+/** A cmd.exe command line for `claude.cmd` (Windows npm installs), which execFile can't run without a shell. */
+export const windowsCommandLine = (args) => args.map((a) => (/^[\w./:@=-]+$/.test(a) ? a : `"${a.replace(/"/g, '\\"')}"`)).join(" ");
+/** The one prompt an FDE pastes into their coding agent to set up a customer (docs: agent-quickstart). */
+export const setupPrompt = (customer = "<Name>", domain = "<domain>") => `Set up OpenScaffold for my customer ${customer} (${domain}). Follow https://docs.openscaffold.ai/agent-quickstart.md. Use the files in ./customer-docs.`;
+/** The last line `login` prints, for a coding agent running it: one JSON object. */
+export const loginResultLine = (result, extra = {}) => JSON.stringify({ openscaffold_login: result, ...extra });
+/** setup's last line (§8.4). A file that didn't upload turns an otherwise-ok run into "partial", naming the files. */
+export const setupResultLine = (result, failed, extra = {}) => JSON.stringify({ openscaffold_setup: failed.length && result === "ok" ? "partial" : result, ...extra, ...(failed.length ? { failed_uploads: failed } : {}) });
+// --- Guardrail hooks (pre-commit, stop): pure, from local files only, never a network call ---------
+/** The deployment this cwd's session loaded (cache index.json from session-start), checking parent folders too. */
+export function deploymentForCwd(index, cwd) {
+    for (let dir = cwd;;) {
+        if (index[dir])
+            return index[dir];
+        const up = dir.replace(/[\\/][^\\/]*$/, "");
+        if (!up || up === dir)
+            return index[up || "/"];
+        dir = up;
+    }
+}
+/** 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 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_… “…”]`. */
+function sectionLines(md, heading, max = 10) {
+    const lines = md.split("\n");
+    const at = lines.findIndex((l) => l.trim() === `## ${heading}`);
+    if (at < 0)
+        return [];
+    const out = [];
+    for (const l of lines.slice(at + 1)) {
+        if (l.startsWith("## ") || l.startsWith("# "))
+            break;
+        if (l.startsWith("- ") && !l.startsWith("- …"))
+            out.push(l.replace(/\s\[[^\]]*\]$/, ""));
+    }
+    return out.slice(0, max);
+}
+/**
+ * The PreToolUse hook's stdout before a `git commit`: JSON with `hookSpecificOutput.additionalContext` naming the
+ * deployment's constraints and must-haves from the cached briefing, or "" when there's nothing to say.
+ */
+export function preCommitOutput(briefing, plugin) {
+    if (!briefing)
+        return "";
+    const name = /^# OpenScaffold — (.+)$/m.exec(briefing)?.[1]?.trim();
+    const constraints = sectionLines(briefing, "Constraints");
+    const musts = sectionLines(briefing, "In scope (must)");
+    if (!constraints.length && !musts.length)
+        return "";
+    const command = plugin ? "/openscaffold:check-plan" : "/os-check-plan";
+    const context = [
+        `OpenScaffold: before this commit, check it against ${name ?? "the customer"}'s plan.`,
+        ...(constraints.length ? ["Constraints:", ...constraints] : []),
+        ...(musts.length ? ["Must-haves:", ...musts] : []),
+        `Run ${command} if this change touches them.`,
+    ].join("\n");
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: context } });
+}
+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. */
+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? */
+export function transcriptActivity(jsonl) {
+    let edited = false;
+    let reported = false;
+    let reviewed = false;
+    for (const line of jsonl.split("\n")) {
+        if (!line.includes('"tool_use"'))
+            continue;
+        let content;
+        try {
+            content = JSON.parse(line).message?.content;
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(content))
+            continue;
+        for (const c of content) {
+            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;
+        }
+    }
+    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.";
+/**
+ * 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
+ * reported; else "". Never twice, and never while Claude is already continuing for a stop hook.
+ */
+export function stopOutput(s) {
+    if (s.stopHookActive || s.reminded || !s.loaded || !s.edited)
+        return "";
+    if (!s.reviewed)
+        return JSON.stringify({ decision: "block", reason: STOP_REVIEW_REASON });
+    if (!s.reported)
+        return JSON.stringify({ decision: "block", reason: STOP_REASON });
+    return "";
+}
+// --- setup: one command from a folder of customer files to a cited plan (SPEC §8.4) -------------
+/** What `setup` uploads: the upload panel's file types (§6.1). CSV/JSON become one ticket per row. */
+export const SETUP_EXTENSIONS = [".vtt", ".srt", ".txt", ".md", ".csv", ".json"];
+/** Under Vercel's request limit, like the upload panel. */
+export const MAX_FILE_BYTES = 4.2 * 1024 * 1024;
+/** `setup <domain> [folder]`: "acme.com", "@acme.com" or "dana@acme.com" → acme.com; folder defaults to ".". */
+export function parseSetupArgs(args) {
+    const [raw, folder = ".", ...extra] = args.filter((a) => !a.startsWith("--"));
+    const usage = "Usage: npx @openscaffold/cli@latest setup <customer domain> [folder], e.g. setup acme.com ./customer-docs";
+    if (!raw)
+        return { error: usage };
+    if (extra.length)
+        return { error: `Too many arguments. ${usage}` };
+    const domain = raw.trim().toLowerCase().replace(/^.*@/, "").replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/^www\./, "");
+    if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(domain))
+        return { error: `"${raw}" isn't an email domain. ${usage}` };
+    return { domain, folder };
+}
+/** acme-logistics.com → "Acme Logistics" (the workspace step's rule, §9). */
+export const nameFromDomain = (domain) => domain.split(".")[0].split("-").filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+/** The folder's files (top level only) → what to upload, sorted, and what's skipped with why. Hidden files are ignored. */
+export function selectFiles(entries) {
+    const upload = [];
+    const skipped = [];
+    for (const e of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!e.file || e.name.startsWith("."))
+            continue;
+        const ext = e.name.slice(e.name.lastIndexOf(".")).toLowerCase();
+        if (!e.name.includes(".") || !SETUP_EXTENSIONS.includes(ext))
+            skipped.push({ name: e.name, why: "not a supported type" });
+        else if (e.size === 0)
+            skipped.push({ name: e.name, why: "empty" });
+        else if (e.size > MAX_FILE_BYTES)
+            skipped.push({ name: e.name, why: "over 4.2 MB; split it or add it in the app" });
+        else
+            upload.push(e.name);
+    }
+    return { upload, skipped };
+}
+/** A markdown section's non-empty lines (the heading excluded), up to the next heading. */
+function section(md, heading) {
+    const out = [];
+    let on = false;
+    for (const line of md.split("\n")) {
+        if (/^#{1,2} /.test(line))
+            on = line === `## ${heading}`;
+        else if (on && line.trim() && !/^\(plan v\d+\)$/.test(line.trim()))
+            out.push(line);
+    }
+    return out;
+}
+/**
+ * The plan in a few cited lines, from get_plan and get_profile (full lists, every item with its quotes, unlike the
+ * session briefing): Goal, In scope (must), Constraints, Open questions. Empty sections are left out.
+ */
+export function planSummary(plan, profile) {
+    const parts = [
+        ["Goal", section(plan, "Goal")],
+        ["In scope (must)", section(plan, "In scope").filter((l) => /^- \S+ \[must,/.test(l))],
+        ["Constraints", section(profile, "Constraints")],
+        ["Open questions", section(plan, "Open questions")],
+    ];
+    return parts.filter(([, lines]) => lines.length).map(([h, lines]) => [`## ${h}`, ...lines].join("\n")).join("\n");
+}
+/** The Status line of a briefing written before the plan exists, if there is one. */
+export function briefingStatus(briefing) {
+    const line = /^## Status\n(.+)$/m.exec(briefing)?.[1]?.trim();
+    if (!line)
+        return null;
+    // Written for an agent: drop the sentences that tell it which tool to call next.
+    return line.split(/(?<=[.;])\s+/).filter((x) => !/`|tell the FDE/i.test(x)).join(" ").replace(/;$/, ".");
+}
+/** The verified facts a pre-plan briefing's Status lists ("- Goal: … [title · doc_… “quote”]"), without the document ids. */
+export function briefingFacts(briefing) {
+    return section(briefing, "Status").filter((l) => l.startsWith("- ")).map((l) => l.replace(/ · doc_\w+/, ""));
+}
+/**
+ * One MCP `tools/call` response body (JSON, or a streamable-HTTP SSE frame) → the tool's text, or its error. The first
+ * content block only: a second one may carry the "Since your briefing" freshness line.
+ */
+export function mcpText(raw) {
+    const data = raw.split("\n").find((l) => l.startsWith("data: "))?.slice(6) ?? raw;
+    let msg;
+    try {
+        msg = JSON.parse(data);
+    }
+    catch {
+        return { error: "OpenScaffold sent an answer this CLI can't read. Try `npx @openscaffold/cli@latest`." };
+    }
+    if (msg.error)
+        return { error: msg.error.message ?? "OpenScaffold refused the call." };
+    const text = msg.result?.content?.[0]?.text ?? "";
+    return msg.result?.isError ? { error: text || "OpenScaffold refused the call." } : { text };
+}
+// --- 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 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 === "--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("--"))
+            return { error: `Unknown option ${flag}. ${REVIEW_USAGE}` };
+        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)] };
+}
+/**
+ * A whole file as an added-file diff, as `git diff --no-index /dev/null <file>` prints it. Empty or binary: "". A
+ * symbolic link is a link (mode 120000, its target path as the content), as git records it.
+ */
+export function newFileDiff(path, file) {
+    const link = typeof file === "object";
+    const text = link ? file.link : file;
+    if (!text || text.includes("\0"))
+        return "";
+    const lines = link ? [text] : text.replace(/\r\n/g, "\n").split("\n");
+    const newline = !link && lines.at(-1) === "";
+    if (newline)
+        lines.pop();
+    return [`diff --git a/${path} b/${path}`, `new file mode ${link ? "120000" : "100644"}`, "--- /dev/null", `+++ b/${path}`, `@@ -0,0 +1,${lines.length} @@`,
+        ...lines.map((l) => `+${l}`), ...(newline ? [] : ["\"]), ""].join("\n");
+}
+/**
+ * The change to review, from where the agent works: in a git repo, everything since HEAD (staged, unstaged, and
+ * untracked files as new files), narrowed to `files` when given. Where git sees nothing (not a repo, a git-ignored
+ * folder, a repo with no commit), the listed files are sent whole as new files. `git` runs one git command in the
+ * folder and throws when git fails; `read` reads a file.
+ */
+export function collectDiff(files, git, read) {
+    let diff = "";
+    let repo = false;
+    try {
+        repo = git(["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+    }
+    catch { }
+    if (repo) {
+        const only = files.length ? ["--", ...files] : [];
+        let head = true;
+        try {
+            git(["rev-parse", "--verify", "-q", "HEAD"]);
+        }
+        catch {
+            head = false;
+        }
+        // No commit yet: compare with the empty tree, so staged and unstaged files both show.
+        const base = head ? "HEAD" : git(["hash-object", "-t", "tree", "/dev/null"]).trim();
+        // --no-ext-diff / --no-textconv: a repo's configured diff drivers and converters are commands; we never run them.
+        diff = git(["diff", "--no-color", "--no-ext-diff", "--no-textconv", base, ...only]);
+        const untracked = git(["ls-files", "--others", "--exclude-standard", "-z", ...only]).split("\0").filter(Boolean);
+        // Files the agent named that git ignores still get reviewed, even when other files changed.
+        if (files.length)
+            untracked.push(...git(["ls-files", "--others", "--ignored", "--exclude-standard", "-z", ...only]).split("\0").filter(Boolean));
+        const prefix = git(["rev-parse", "--show-prefix"]).trim();
+        diff += untracked.map((f) => newFileDiff(prefix + f, read(f))).join(""); // ls-files paths are from this folder; diff paths from the root
+    }
+    if (!diff.trim() && files.length)
+        diff = files.map((f) => newFileDiff(f.replace(/^\.\//, ""), read(f))).join("");
+    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}` };
+    }
+    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.` };
+    return { diff };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscaffold/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Connect Claude Code to your OpenScaffold workspace: each session loads the right customer deployment.",
   "type": "module",
   "bin": {
@@ -30,13 +30,11 @@
     "forward-deployed-engineering"
   ],
   "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Sigma-M-A/openscaffold.git",
-    "directory": "cli"
-  },
-  "homepage": "https://github.com/Sigma-M-A/openscaffold",
+  "homepage": "https://docs.openscaffold.ai",
   "publishConfig": {
     "access": "public"
+  },
+  "bugs": {
+    "url": "https://docs.openscaffold.ai/troubleshooting"
   }
 }