getclaros 0.1.0 → 0.2.0

package/README.md

@@ -12,8 +12,50 @@ The package name (`getclaros`) is a placeholder and lives only in `package.json`
 npx getclaros init
 ```
 
-Not published yet (`"private": true`); until then run `node dist/cli.js init` with
-`GETCLAROS_LAUNCHER="node /abs/path/to/dist/cli.js"` so the configs launch your build instead of `npx -y getclaros`.
+To try a local build, run `node dist/cli.js init` with `GETCLAROS_LAUNCHER="node /abs/path/to/dist/cli.js"` so the
+configs launch your build instead of `npx -y getclaros`.
+
+One command for every kind of agent: it guards the MCP servers your agent clients run, and, when run in a Playwright
+or browser-use project, installs the browser hook with that project's own package manager (see
+[Browser agents](#browser-agents-playwright-browser-use)). `npx getclaros doctor` then says, per agent type, whether it
+is guarded and can reach Claros.
+
+```
+  claros”  getclaros 0.2.0
+
+  Sign in  opening your browser
+  › https://claros-eta.vercel.app/device?code=ZQRC-ZCTP
+    Code ZQRC-ZCTP  approve only if the page shows this code
+
+  ✓ Signed in to workspace "Acme"  key clr_7f3a91c2_…
+    <claros server> · key saved in ~/.config/getclaros/config.json, readable only by you
+
+  MCP agents
+
+  Claude Code  ~/.claude.json
+     1 ● erpnext                     npx -y frappe-mcp-server  Work Map "Process a supplier invoice"
+     2 ○ github                      docker run -i …
+     3 ○ playwright (project ~/proj) npx @playwright/mcp@latest
+
+  Cursor  ~/.cursor/mcp.json
+     4 ● erpnext                     npx frappe-mcp-server  Work Map "Process a supplier invoice"
+
+  · 3 remote servers need OAuth — guard them later: linear, notion, figma
+
+  ● matches a Work Map: recommended
+  Guard which? Enter = 1,4 (recommended) · numbers like 1,3 · all · none ›
+
+  ✓ Guarded erpnext  in Claude Code, Cursor
+  ✓ Added the Claros MCP server  in Claude Code, Cursor
+    every file backed up first: ~/.config/getclaros/backups/2026-10-24T01-34-53-159Z
+
+  Next  restart Claude Code, Cursor, then run  npx getclaros test
+        undo anytime: npx getclaros undo
+```
+
+On a terminal the output is coloured in Claros's inks (stop magenta, ask green, nudge vermilion) with a spinner while
+it waits for the browser. Piped, it is plain text with no escape codes and no header; `NO_COLOR` turns colour off,
+`FORCE_COLOR` turns it on. Old Windows consoles get ASCII marks.
 
 `init` signs you in through the browser (RFC 8628 device flow): it prints a URL and a code (XXXX-XXXX), opens the
 URL (`--no-browser` to skip), and once you approve on Claros's `/device` page and pick a workspace it receives an
@@ -44,9 +86,39 @@ What it changes, in files that already exist (it never creates a client config):
   up front with `get_workflow`; in each client's user config (or its project config when it has no user config).
 - Every file is backed up before it changes (`~/.config/getclaros/backups/<time>/`) and written atomically.
 
+### Browser agents (Playwright, browser-use)
+
+`init` also looks at the project directory (the current one, or `--project <dir>`):
+
+| Found | Install (never global) | Hook |
+|---|---|---|
+| `@playwright/test` in package.json | `pnpm add -D` / `yarn add -D` / `bun add -d` / `npm install -D getclaros-browser`, by lockfile | writes `claros.fixture.ts` next to `playwright.config.*`; you change each spec's `from "@playwright/test"` to `from "<rel>/claros.fixture"` (init prints the exact line) |
+| `playwright` (the library) in package.json | the same, as a dependency | printed: `import { guard } from "getclaros-browser"; await guard(page);` |
+| `browser-use` in pyproject.toml / requirements*.txt / uv.lock / poetry.lock | `uv add` / `poetry add claros-browser`, else `pip install` into the project's virtualenv (none: printed, not run) | printed: `from claros_browser import guard_tools; guard_tools(tools)`, with the file that builds the `Agent` |
+
+Each project gets its plan (the exact install command, the file it writes, where the key goes, the hook) and one
+question, `Set up Playwright? Enter = yes`. `--yes` says yes without asking; `--no-browser-hooks` shows the plan and
+changes nothing. User source files are never edited: the hook is printed.
+
+Why a fixture file for Playwright Test: Playwright has no config-level page hook, and a fixture is its supported way to
+run code for every test's `page`. The file lives in your repo (you can read it, compose it with your own fixtures), it
+imports `getclaros-browser` and `@playwright/test` from your own `node_modules` (works with pnpm's strict layout), and
+it re-exports everything from `@playwright/test`, so swapping the import never loses a type or helper. It also reads
+`CLAROS_*` from `.env` when the shell doesn't set them, because Playwright doesn't read `.env` itself.
+
+The browser hooks read `CLAROS_KEY` (and `CLAROS_URL` / `CLAROS_WEB_URL` when you aren't on the hosted Claros) from the
+environment. `init` writes them to the project's `.env` only when it already exists, git ignores it and git doesn't
+track it (no repo: the `.gitignore` next to it decides). Otherwise it prints an export line that reads the saved key
+without showing it: `export CLAROS_KEY="$(node -p "require('$HOME/.config/getclaros/config.json').key")"`.
+browser-use loads `.env` itself.
+
+The fixture file is new (undo deletes it, unless you changed it) and `.env` is backed up like any config (undo restores
+it, or, if you edited it since, removes only the `CLAROS_*` lines). Undo doesn't uninstall the package.
+
 ```
-npx getclaros test     # a made-up record that breaks one of your rules → prints the stop (rule, expert's words, who to ask)
-npx getclaros status   # which servers are guarded, Claros reachable, key valid
+npx getclaros test     # made-up records checked against your rules → prints the stop (and, in the demo, a nudge with its fix)
+npx getclaros doctor   # per agent type: guarded? reachable? (server, key, MCP wrapping, browser package + hook + key), with the fix
+npx getclaros status   # the same as doctor
 npx getclaros undo     # undo the last init; --all: every init, plus any guard wrapping it finds
 npx getclaros export <workflow_id> [--format agents|design|skill] > AGENTS.md   # a map's rules as markdown
 ```
@@ -62,7 +134,43 @@ rules page. Exit codes: 0 sent, 1 no such check / not valid, 2 bad usage, 3 unre
 
 `test` asks Claros for a record that breaks a precise rule of a Work Map for one of your guarded servers
 (`GET /v1/check/example?app=…`), checks it with `POST /v1/check` and prints the stop. Nothing is sent to the app.
-With no guarded server matching a map it uses the newest map and says `DEMO`. Exit codes: 0 stopped, 1 not stopped
+
+With no guarded server matching a map it runs a demo on two Starter maps (added to your workspace the first time, as
+drafts that are never enforced; delete them on the web and they stay deleted): a production deploy during a release
+freeze, which is stopped, and a coding agent's stylesheet with a raw hex colour, which the judge nudges with a fix.
+Both are checked side by side and it ends with a `Demo:` note:
+
+```
+  ◉ Stopped · ✎ Nudged  2 checks in 827 ms
+
+    ◉ stop  No production deploys during the release freeze.
+            “Nothing goes to prod during the freeze. Not even a typo fix.” — Release manager
+            Who to ask: Release manager
+            Test action: deploy deploy.environment = production, deploy.freeze_active = true
+
+    ✎ nudge No hand-picked hex values in UI code; use the design tokens (var(--primary) and the rest).
+            “If it's not a token, it's a bug. No hand-picked hex values.” — Design systems lead
+            → Replace #7C3AED and #FFFFFF with design tokens like var(--primary)
+            Test action: write_file file_path = src/components/Button.css, content = .button { background: #7C3AED; color: #FFFFFF; border-radius: 6px; }
+
+  Your agent gets a stop as the tool's error; a nudge lets the call through, with the fix. Nothing reached any app.
+  Demo: no server is guarded yet, so this used the Starter maps (examples, not enforced; delete them on the web).
+```
+
+For a guarded server whose app has a Work Map:
+
+```
+  ◉ Stopped in 1.3 s  Work Map "Process a supplier invoice" · check chk_0b14cb5eef
+
+    ◉ stop  Equipment over 5,000 is capex: book it to the capital equipment account, never to expense.
+            “Equipment above five thousand is an asset, it goes to capex.” — AP lead
+            Who to ask: Controller
+
+  Test action for erpnext, made up, only checked: items.0.item_group = Machinery, items.0.amount = 7200
+  Your agent gets the rule as the tool's error. Nothing reached erpnext.
+```
+
+Exit codes: 0 stopped, 1 not stopped
 or no map to test, 2 not signed in / bad usage, 3 Claros unreachable or key rejected (`status` uses 0 / 2 / 3 too).
 
 `undo` restores a file from its backup when it is byte-for-byte what `init` wrote; if anything changed it since, it

package/dist/cli.js

@@ -404,7 +404,7 @@ async function main(argv) {
     }
     if (argv[0] === "mcp")
         return void import("./bridge.js").then((m) => m.bridge());
-    if (["init", "test", "status", "undo", "export", "override"].includes(argv[0])) {
+    if (["init", "test", "status", "doctor", "undo", "export", "override"].includes(argv[0])) {
         process.exitCode = await (await import("./setup.js")).run(argv);
         return;
     }

package/dist/projects.js

@@ -0,0 +1,179 @@
+// Browser agents in a project directory: Playwright (package.json) and browser-use (pyproject / requirements / locks).
+// For each: the install command in the project's own package manager (never global), where the hook goes, whether
+// it's there, and where CLAROS_KEY can be written safely (an existing .env that git ignores and doesn't track).
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+const SKIP = new Set(["node_modules", "dist", "build", "out", "venv", "__pycache__", "site-packages", "coverage"]);
+/** source files under dir (not dot dirs, deps or builds), at most `cap` of them */
+function sources(dir, ext, cap = 2000) {
+    const out = [];
+    const walk = (d, depth) => {
+        let names;
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (out.length >= cap)
+                return;
+            const p = join(d, n);
+            if (n.startsWith(".") || SKIP.has(n))
+                continue;
+            let s;
+            try {
+                s = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                if (depth < 8)
+                    walk(p, depth + 1);
+            }
+            else if (ext.test(n) && s.size < 512_000) {
+                out.push({ path: p, text: readFileSync(p, "utf8") });
+            }
+        }
+    };
+    walk(dir, 0);
+    return out;
+}
+const read = (p) => { try {
+    return readFileSync(p, "utf8");
+}
+catch {
+    return "";
+} };
+export function nodePm(dir, dev, pkg) {
+    const has = (f) => existsSync(join(dir, f));
+    if (has("pnpm-lock.yaml"))
+        return { name: "pnpm", argv: ["pnpm", "add", ...(dev ? ["-D"] : []), pkg] };
+    if (has("yarn.lock"))
+        return { name: "yarn", argv: ["yarn", "add", ...(dev ? ["-D"] : []), pkg] };
+    if (has("bun.lockb") || has("bun.lock"))
+        return { name: "bun", argv: ["bun", "add", ...(dev ? ["-d"] : []), pkg] };
+    return { name: "npm", argv: ["npm", "install", ...(dev ? ["-D"] : []), pkg] };
+}
+export function pyPm(dir, pkg) {
+    if (existsSync(join(dir, "uv.lock")))
+        return { name: "uv", argv: ["uv", "add", pkg] };
+    if (existsSync(join(dir, "poetry.lock")) || /^\[tool\.poetry\]/m.test(read(join(dir, "pyproject.toml")))) {
+        return { name: "poetry", argv: ["poetry", "add", pkg] };
+    }
+    // pip only into a virtualenv: the active one if it lives in this project, else ./.venv or ./venv
+    const venvs = [process.env.VIRTUAL_ENV && !relative(dir, process.env.VIRTUAL_ENV).startsWith("..") ? process.env.VIRTUAL_ENV : "",
+        join(dir, ".venv"), join(dir, "venv")].filter(Boolean);
+    for (const v of venvs) {
+        const py = [join(v, "bin", "python"), join(v, "Scripts", "python.exe")].find(existsSync);
+        if (py)
+            return { name: "pip", argv: [py, "-m", "pip", "install", pkg] };
+    }
+    return { name: "pip", argv: null, note: `no virtualenv in this project: activate yours, then pip install ${pkg} (init never installs globally)` };
+}
+const FIXTURE = (ext) => `// Written by \`npx getclaros init\`: every test's \`page\` goes through the Claros guard (consequential clicks and
+// submits are checked against your team's rules first). Import { test, expect } from here instead of
+// "@playwright/test". \`npx getclaros undo\` removes this file.
+import { existsSync, readFileSync } from "node:fs";
+import * as util from "node:util";
+import { test as base } from "@playwright/test";
+import { guard } from "getclaros-browser";
+
+// Playwright doesn't read .env: take CLAROS_KEY (and CLAROS_URL / CLAROS_WEB_URL) from it when the shell doesn't set them
+const env${ext === "ts" || ext === "mts" ? ": Record<string, string | undefined>" : ""} = existsSync(".env") && util.parseEnv ? util.parseEnv(readFileSync(".env", "utf8")) : {};
+for (const [k, v] of Object.entries(env)) if (k.startsWith("CLAROS_")) process.env[k] ??= v;
+
+export * from "@playwright/test";
+export const test = base.extend({
+  page: async ({ page }, use) => {
+    await guard(page);
+    await use(page);
+  },
+});
+`;
+export const fixtureText = (path) => FIXTURE(path.split(".").pop());
+// ponytail: only `dir` itself is a project (no monorepo workspace walk); run init in the package, or use --project
+export function detectBrowser(dir) {
+    const out = [];
+    let pkg; // eslint-disable-line @typescript-eslint/no-explicit-any
+    try {
+        pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    }
+    catch { /* not a Node project */ }
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    if (deps["@playwright/test"] || deps.playwright) {
+        const runner = !!deps["@playwright/test"], pm = nodePm(dir, runner, "getclaros-browser");
+        const src = sources(dir, /\.(c|m)?[jt]sx?$/);
+        const p = { kind: "Playwright", dir, via: `${runner ? "@playwright/test" : "playwright"}, ${pm.name}`,
+            install: pm.argv, installed: !!deps["getclaros-browser"] || existsSync(join(dir, "node_modules", "getclaros-browser")),
+            more: 0, hooked: false };
+        if (runner) {
+            const config = ["ts", "mts", "js", "mjs", "cjs", "cts"].map((e) => join(dir, `playwright.config.${e}`)).find(existsSync);
+            const ext = config?.split(".").pop()?.replace(/^c/, "m") ?? "ts";
+            p.fixture = join(config ? dirname(config) : dir, `claros.fixture.${ext}`);
+            const specs = src.filter((f) => f.path !== config && f.path !== p.fixture && /from\s+["']@playwright\/test["']/.test(f.text));
+            p.hookFile = specs[0]?.path;
+            p.more = Math.max(0, specs.length - 1);
+            p.hooked = existsSync(p.fixture) && src.some((f) => f.path !== p.fixture && /claros\.fixture/.test(f.text));
+        }
+        else {
+            p.hookFile = src.find((f) => /["']playwright["']/.test(f.text))?.path;
+            p.hooked = src.some((f) => /["']getclaros-browser["']/.test(f.text));
+        }
+        out.push(p);
+    }
+    const manifests = ["pyproject.toml", "uv.lock", "poetry.lock",
+        ...(existsSync(dir) ? readdirSync(dir).filter((n) => /^requirements.*\.txt$/.test(n)) : [])].map((n) => read(join(dir, n))).join("\n");
+    if (/browser[-_]use/i.test(manifests)) {
+        const pm = pyPm(dir, "claros-browser"), src = sources(dir, /\.py$/);
+        const venvLib = join(dir, ".venv", "lib");
+        const inVenv = existsSync(venvLib) && readdirSync(venvLib).some((v) => existsSync(join(venvLib, v, "site-packages", "claros_browser")));
+        out.push({ kind: "browser-use", dir, via: `browser-use, ${pm.name}`, install: pm.argv, installNote: pm.note,
+            installed: /claros[-_]browser/i.test(manifests) || inVenv,
+            hookFile: (src.find((f) => /browser_use/.test(f.text) && /\bAgent\(/.test(f.text)) ?? src.find((f) => /browser_use/.test(f.text)))?.path,
+            more: 0, hooked: src.some((f) => /\bguard_tools\(/.test(f.text)) });
+    }
+    return out;
+}
+/** The import line a Playwright spec needs to use the fixture. */
+export function fixtureImport(p) {
+    const from = p.hookFile ? dirname(p.hookFile) : p.dir;
+    let rel = relative(from, p.fixture).split("\\").join("/");
+    if (/\.ts$/.test(rel))
+        rel = rel.slice(0, -3);
+    return `import { test, expect } from "${rel.startsWith(".") ? rel : "./" + rel}";`;
+}
+/** Where CLAROS_* may be written: an existing .env that git ignores and doesn't track. ok=false says why not. */
+export function envTarget(dir) {
+    const path = join(dir, ".env");
+    if (!existsSync(path))
+        return { path, ok: false, why: "no .env in this project" };
+    const git = (...a) => spawnSync("git", ["-C", dir, ...a], { stdio: "ignore" }).status;
+    if (git("ls-files", "--error-unmatch", "--", ".env") === 0)
+        return { path, ok: false, why: ".env is tracked by git" };
+    const ignored = git("check-ignore", "-q", "--", ".env");
+    if (ignored === 0)
+        return { path, ok: true };
+    if (ignored === 1)
+        return { path, ok: false, why: ".env isn't in .gitignore" };
+    // not a git repo (or no git): the .gitignore next to it decides
+    const lines = read(join(dir, ".gitignore")).split(/\r?\n/).map((l) => l.trim());
+    return lines.some((l) => /^\/?(\.env|\.env\*|\.env\.?\*|\*\.env|\.env\/?)$/.test(l))
+        ? { path, ok: true } : { path, ok: false, why: ".env isn't in .gitignore" };
+}
+/** The .env text with each var set (an existing line replaced in place, else appended). */
+export function setEnv(text, vars) {
+    for (const [k, v] of Object.entries(vars)) {
+        const line = `${k}=${v}`, re = new RegExp(`^(export\\s+)?${k}=.*$`, "m");
+        text = re.test(text) ? text.replace(re, line) : text + (text && !text.endsWith("\n") ? "\n" : "") + line + "\n";
+    }
+    return text;
+}
+/** The value of a var in a .env file ("" when absent). */
+export const envValue = (path, k) => {
+    const m = new RegExp(`^(?:export\\s+)?${k}=["']?([^"'\\r\\n]*)`, "m").exec(read(path));
+    return m ? m[1].trim() : "";
+};
+export const short = (p, dir) => relative(dir, p) || basename(p);

package/dist/setup.js

@@ -1,23 +1,26 @@
-// getclaros init | test | undo | status (| export: a map's rules as markdown): puts the guard in front of the MCP servers an agent client already runs.
-// Edits only existing config files, backs each one up first (~/.config/getclaros/backups/<time>/, 0600), writes
-// atomically, and never prints the key.
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { spawn } from "node:child_process";
+// getclaros init | test | undo | doctor (= status) (| export: a map's rules as markdown): puts the guard in front of
+// the MCP servers an agent client already runs, and in front of the browser agents (Playwright, browser-use) in this
+// project. Edits only existing config files (plus, for Playwright Test, one new fixture file and CLAROS_KEY in a
+// gitignored .env), backs each one up first (~/.config/getclaros/backups/<time>/, 0600), writes atomically, and never
+// prints the key.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
 import { homedir, hostname } from "node:os";
 import { basename, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { addClaros, argvOf, CLAROS, detect, launcher, load, removeEntry, sha, unwrapServer, wrapServer, writeAtomic, } from "./clients.js";
-import { cfgDir, loadConfig, relocate, resolve, saveConfig } from "./config.js";
+import { cfgDir, DEFAULT_WEB, loadConfig, relocate, resolve, saveConfig } from "./config.js";
+import { detectBrowser, envTarget, envValue, fixtureImport, fixtureText, setEnv, short } from "./projects.js";
+import { c, dur, header, mark, say, spinner, VERSION, wrap } from "./ui.js";
 const NAME = launcher().at(-1) === "getclaros" ? "npx getclaros" : "getclaros";
-const say = (s = "") => process.stdout.write(s + "\n");
 const warn = (s) => process.stderr.write(s + "\n");
 const tilde = (p) => p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p;
 const keyId = (k) => k.split("_").slice(0, 2).join("_") + "_…"; // clr_<prefix>_… (the prefix is the lookup id, not the secret)
 const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
-export const USAGE = `usage: ${NAME} init   [--key clr_… | env CLAROS_KEY | --paste] [--no-browser] [--url <claros server> | --web <claros web app>] [--yes] [--servers a,b] [--project <dir>] [--no-mcp]
+export const USAGE = `usage: ${NAME} init   [--key clr_… | env CLAROS_KEY | --paste] [--no-browser] [--url <claros server> | --web <claros web app>] [--yes] [--servers a,b] [--project <dir>] [--no-mcp] [--no-browser-hooks]
        ${NAME} test   [--app <server>]
-       ${NAME} status
+       ${NAME} doctor [--project <dir>]   (status: the same)
        ${NAME} undo   [--all]
        ${NAME} export <workflow_id> [--format agents|design|skill] [> AGENTS.md]
        ${NAME} override <check_id> --reason "…" [--rule <rule id>] [--verdict wrong_stop|wrong_nudge|missed|right]`;
@@ -28,7 +31,7 @@ export async function run(argv) {
         ({ values: v, positionals: pos } = parseArgs({ args: rest, allowPositionals: cmd === "export" || cmd === "override", options: {
                 url: { type: "string" }, web: { type: "string" }, key: { type: "string" }, yes: { type: "boolean", short: "y" }, servers: { type: "string" },
                 project: { type: "string" }, all: { type: "boolean" }, "no-mcp": { type: "boolean" }, app: { type: "string" },
-                paste: { type: "boolean" }, "no-browser": { type: "boolean" }, format: { type: "string" },
+                paste: { type: "boolean" }, "no-browser": { type: "boolean" }, "no-browser-hooks": { type: "boolean" }, format: { type: "string" },
                 reason: { type: "string" }, rule: { type: "string" }, verdict: { type: "string" },
             } }));
     }
@@ -41,8 +44,8 @@ export async function run(argv) {
         return init(v, project);
     if (cmd === "test")
         return test(v, project);
-    if (cmd === "status")
-        return status(v, project);
+    if (cmd === "status" || cmd === "doctor")
+        return doctor(v, project);
     if (cmd === "undo")
         return undo(v, project);
     if (cmd === "export" && pos.length === 1 && ["agents", "design", "skill"].includes(v.format ?? "agents")) {
@@ -89,7 +92,6 @@ async function locate(v) {
     return r;
 }
 // ---- browser sign-in (RFC 8628 device flow) ----
-const VERSION = "0.1.0";
 const sleep = (s) => new Promise((ok) => setTimeout(ok, s * Number(process.env.GETCLAROS_INTERVAL_MS ?? 1000)));
 function openBrowser(url) {
     if (process.env.GETCLAROS_NO_BROWSER)
@@ -115,13 +117,22 @@ async function deviceSignIn(url, browser) {
     catch {
         return "unsupported";
     }
-    say(`Sign in to Claros in your browser:
-
-  ${d.verification_uri_complete ?? d.verification_uri}
-
-and check it shows the code ${d.user_code}. Waiting…`);
+    const link = d.verification_uri_complete ?? d.verification_uri;
+    say(`  ${c.bold("Sign in")}  ${c.dim(browser ? "opening your browser" : "open this in your browser")}`);
+    say(`  ${c.violet(mark.arrow)} ${c.ul(link)}`);
+    say(`    Code ${c.bold(c.violet(d.user_code))}  ${c.dim("approve only if the page shows this code")}`);
+    say();
     if (browser)
-        openBrowser(d.verification_uri_complete ?? d.verification_uri);
+        openBrowser(link);
+    const spin = spinner("Waiting for you to approve in the browser…");
+    try {
+        return await poll(url, d);
+    }
+    finally {
+        spin.stop();
+    }
+}
+async function poll(url, d) {
     let interval = Number(d.interval) || 5;
     const until = Date.now() + (Number(d.expires_in) || 600) * 1000;
     while (Date.now() < until) {
@@ -201,16 +212,20 @@ function askHidden(q) {
 }
 const backupsDir = () => join(cfgDir(), "backups");
 const newRun = (suffix = "") => ({ dir: join(backupsDir(), new Date().toISOString().replace(/[:.]/g, "-") + suffix), files: [] });
-/** Backs up `before`, writes `after` atomically, records both hashes. */
-function commit(run, path, before, after) {
+/** Backs up `before` (null: a new file), writes `after` atomically, records both hashes. */
+function commit(run, path, before, after, vars) {
     if (!run.files.length) {
         mkdirSync(cfgDir(), { recursive: true, mode: 0o700 });
         mkdirSync(run.dir, { recursive: true, mode: 0o700 });
     }
     const backup = join(run.dir, `${run.files.length}-${basename(path)}`);
-    writeFileSync(backup, before, { mode: 0o600 });
-    writeAtomic(path, after);
-    run.files.push({ path, backup, before: sha(before), after: sha(after) });
+    writeFileSync(backup, before ?? "", { mode: 0o600 });
+    if (before === null)
+        writeFileSync(path, after, { flag: "wx" });
+    else
+        writeAtomic(path, after);
+    run.files.push({ path, backup, before: sha(before ?? ""), after: sha(after), ...(before === null ? { created: true } : {}),
+        ...(vars ? { vars } : {}) });
     writeFileSync(join(run.dir, "manifest.json"), JSON.stringify({ files: run.files }, null, 2), { mode: 0o600 });
 }
 function runs() {
@@ -242,6 +257,7 @@ catch {
 const where = (s) => s.scope[0] === "projects" ? ` (project ${tilde(s.scope[1])})` : "";
 // ---- init ----
 async function init(v, project) {
+    header();
     const at = await locate(v);
     if (!at)
         return 3;
@@ -274,42 +290,89 @@ async function init(v, project) {
     workspace ??= await whoami(url, key);
     const cfg = saved.url === url && saved.web === web && saved.key === key && saved.workspace?.name === workspace?.name
         ? join(cfgDir(), "config.json") : saveConfig({ url, web, key, ...(workspace ? { workspace } : {}) });
-    say(`Signed in to ${url}${workspace?.name ? ` (workspace "${workspace.name}")` : ""} with key ${keyId(key)} (saved in ${tilde(cfg)}, readable only by you).`);
-    const files = detect(project);
-    if (!files.length) {
-        say(`\nSee a stop now: ${NAME} test`);
-        say("To guard an agent's tools: add an MCP server to Claude Code, Claude Desktop, Cursor, VS Code or Codex (none has one yet), then run init again.");
+    say(`  ${c.ask(mark.ok)} Signed in${workspace?.name ? ` to workspace ${c.bold(`"${workspace.name}"`)}` : ""}  ${c.dim(`key ${keyId(key)}`)}`);
+    say(c.dim(`    ${url} ${mark.dot} key saved in ${tilde(cfg)}, readable only by you`));
+    const files = detect(project), browsers = detectBrowser(project);
+    if (!files.length && !browsers.length) {
+        say(`\n  See a stop now: ${c.bold(`${NAME} test`)}`);
+        say(c.dim(wrap("  To guard an agent: add an MCP server to Claude Code, Claude Desktop, Cursor, VS Code or Codex (none has one yet), or run init in a Playwright or browser-use project, then run init again.", 2)));
         return 1;
     }
+    const run = newRun();
+    let mcp = { changed: [], guardedIn: new Map(), added: [] };
+    if (files.length) {
+        const r = await mcpSetup(v, files, url, key, run);
+        if (typeof r === "number")
+            return r;
+        mcp = r;
+    }
+    else {
+        say(`\n  ${c.bold("MCP agents")}`);
+        say(c.dim(wrap("    none found (Claude Code, Claude Desktop, Cursor, VS Code, Codex); add an MCP server to one, then run init again", 4)));
+    }
+    const br = await browserSetup(v, browsers, project, at, key, run);
+    const { changed, guardedIn, added } = mcp;
+    if (!changed.length && !br.done.length) {
+        if (br.todo)
+            say(`  ${c.bold("Next")}  add the hook shown above, then run your browser agent`);
+        say("  Nothing to change.");
+        return 0;
+    }
+    const list = (xs) => [...new Set(xs)].join(", ");
+    for (const [n, cl] of guardedIn)
+        say(`  ${c.ask(mark.ok)} Guarded ${c.bold(n)}  ${c.dim(`in ${list(cl)}`)}`);
+    if (added.length)
+        say(`  ${c.ask(mark.ok)} Added the Claros MCP server  ${c.dim(`in ${list(added)}`)}`);
+    for (const l of br.done)
+        say(`  ${c.ask(mark.ok)} ${l}`);
+    if (run.files.length)
+        say(c.dim(`    every file backed up first: ${tilde(run.dir)}`));
+    say(`\n  ${c.bold("Next")}  ${changed.length ? `restart ${list(changed)}, then run  ${c.violet(`${NAME} test`)}` : `run  ${c.violet(`${NAME} test`)}`}`);
+    if (br.todo)
+        say(`        add the browser hook shown above, then run your browser agent`);
+    say(c.dim(`        check the setup: ${NAME} doctor ${mark.dot} undo anytime: ${NAME} undo`));
+    return 0;
+}
+/** MCP agents: list each client's servers, ask which to guard, wrap them. A number = exit with it. */
+async function mcpSetup(v, files, url, key, run) {
     const maps = await api(url, key, "/api/workflows").then((r) => (Array.isArray(r.json) ? r.json : []), () => []);
     const mapOf = (name) => maps.find((m) => (m.apps ?? []).some((a) => norm(a) && norm(name) && (norm(a).includes(norm(name)) || norm(name).includes(norm(a)))));
-    const cands = [];
-    say();
+    // per client: the servers it can guard (numbered, ● = matches a Work Map), the ones already guarded; the remote
+    // servers it can't guard yet are gathered into one line per reason under the list
+    const cands = [], gaps = new Map();
+    const all = files.flatMap((f) => f.servers);
+    const w = Math.min(28, Math.max(8, ...all.map((s) => (s.name + where(s)).length)));
+    say(`\n  ${c.bold("MCP agents")}`);
     for (const f of files) {
-        say(`${f.client}  ${tilde(f.path)}`);
+        say(`\n  ${c.bold(f.client)}  ${c.dim(tilde(f.path))}`);
         if (f.error)
-            say(`      couldn't read it (${f.error}); left alone`);
+            say(c.dim(`    couldn't read it (${f.error}); left alone`));
         for (const s of f.servers) {
+            const label = (s.name + where(s)).padEnd(w);
             if (s.ours)
-                say(`      ${s.name}${where(s)}  Claros MCP server (agents read the Work Map with get_workflow)`);
+                continue;
+            if (s.gap)
+                gaps.set(s.gap, [...(gaps.get(s.gap) ?? []), s.name]);
             else if (s.guarded)
-                say(`  [=] ${s.name}${where(s)}  already guarded`);
-            else if (s.gap)
-                say(`  [ ] ${s.name}${where(s)}  remote ${site(s.entry.url)}: ${s.gap}`);
+                say(`    ${c.ask(" =")}   ${label} ${c.dim("already guarded")}`);
             else {
                 const m = mapOf(s.name);
                 cands.push(s);
-                say(`  ${String(cands.length).padStart(2)}. ${s.name}${where(s)}  ${s.remote ? `remote ${site(s.entry.url)}` : show(argvOf(s.entry))}` +
-                    (m ? `  ← Work Map "${m.name}"` : ""));
+                say(`    ${String(cands.length).padStart(2)} ${m ? c.ask(mark.on) : c.dim(mark.off)} ${m ? c.bold(label) : label} ` +
+                    c.dim(s.remote ? `remote ${site(s.entry.url)}` : show(argvOf(s.entry))) + (m ? `  ${c.ask(`Work Map "${m.name}"`)}` : ""));
             }
         }
     }
+    for (const [gap, names] of gaps) {
+        const u = [...new Set(names)], n = u.length, why = gap.replace(/ – not guarded yet$/, "");
+        const what = why.startsWith("needs ") ? `${n > 1 ? "need" : "needs"} ${why.slice(6)}` : `(${why})`;
+        say(c.dim(wrap(`\n  ${mark.dot} ${n} remote server${n > 1 ? "s" : ""} ${what} ${mark.dash} guard ${n > 1 ? "them" : "it"} later: ${u.join(", ")}`, 4)));
+    }
     say();
     const byName = (names) => cands.filter((s) => names.includes(s.name));
     let picks = cands.filter((s) => mapOf(s.name));
     if (v.servers !== undefined) {
         const names = v.servers.split(",").map((s) => s.trim()).filter(Boolean);
-        const all = files.flatMap((f) => f.servers);
         for (const n of names) {
             const hit = all.filter((s) => s.name === n);
             if (!hit.length) {
@@ -317,9 +380,9 @@ async function init(v, project) {
                 return 2;
             }
             if (hit.every((s) => s.gap))
-                say(`${n}: remote server, ${hit[0].gap}.`);
+                say(c.dim(`  ${mark.dot} ${n}: remote server, ${hit[0].gap}.`));
             else if (hit.every((s) => s.guarded || s.gap))
-                say(`${n}: already guarded.`);
+                say(c.dim(`  ${mark.dot} ${n}: already guarded.`));
         }
         picks = byName(names);
     }
@@ -329,8 +392,11 @@ async function init(v, project) {
             return 2;
         }
         const def = picks.map((s) => cands.indexOf(s) + 1).join(",");
+        if (def)
+            say(c.dim(`  ${mark.on} matches a Work Map: recommended`));
         for (;;) {
-            const a = (await ask(`Guard which? Numbers (1,3), "all", "none"${def ? `, Enter = ${def}` : ""}: `)).trim().toLowerCase();
+            const a = (await ask(`  ${c.bold("Guard which?")} ${c.dim(`Enter = ${def ? `${def} (recommended)` : "none"} ${mark.dot} numbers like 1,3 ${mark.dot} all ${mark.dot} none`)} ${c.violet(mark.arrow)} `))
+                .trim().toLowerCase();
             if (!a)
                 break;
             if (a === "none") {
@@ -346,22 +412,23 @@ async function init(v, project) {
                 picks = ns.map((n) => cands[n - 1]);
                 break;
             }
-            warn(`Pick numbers between 1 and ${cands.length}.`);
+            warn(`  Pick numbers between 1 and ${cands.length}.`);
         }
+        say();
     }
     else if (!picks.length && cands.length) {
-        say("None of these servers matches a Work Map yet, so none is guarded. Pick them with --servers a,b.");
+        say(c.dim(wrap("  None of these servers matches a Work Map yet, so none is guarded. Pick them with --servers a,b.", 2)));
     }
-    const run = newRun();
-    const changed = [];
+    const changed = [], guardedIn = new Map(), added = [];
     const userClients = new Set(files.filter((f) => f.user && !f.error).map((f) => f.client));
     for (const f of files.filter((x) => !x.error)) {
-        const before = f.text, mine = picks.filter((s) => s.file === f);
+        const before = f.text, mine = picks.filter((s) => s.file === f), got = [];
+        let mcp = false;
         try {
             for (const s of mine) {
                 f.text = wrapServer(f, s);
                 load(f);
-                say(`guarded ${s.name}${where(s)} in ${f.client} (${tilde(f.path)})`);
+                got.push(s.name + where(s));
             }
             // the Claros MCP server: in each client's user config, or its project file when the client has none
             const top = f.servers.find((s) => s.name === CLAROS && s.scope.length === 1);
@@ -369,32 +436,119 @@ async function init(v, project) {
                 if (!top) {
                     f.text = addClaros(f);
                     load(f);
-                    say(`added the Claros MCP server to ${f.client} (${tilde(f.path)})`);
+                    mcp = true;
                 }
                 else if (!top.ours)
-                    say(`kept the existing "${CLAROS}" entry in ${tilde(f.path)} (not ours)`);
+                    say(c.dim(`  ${mark.dot} kept the existing "${CLAROS}" entry in ${tilde(f.path)} (not ours)`));
             }
         }
         catch (e) {
-            warn(`${tilde(f.path)}: ${e.message}; left unchanged`);
+            warn(`  ${tilde(f.path)}: ${e.message}; left unchanged`);
             f.text = before;
             continue;
         }
         if (f.text !== before) {
             commit(run, f.path, before, f.text);
             changed.push(f.client);
+            for (const n of got)
+                guardedIn.set(n, [...(guardedIn.get(n) ?? []), f.client]);
+            if (mcp)
+                added.push(f.client);
         }
     }
-    if (!changed.length) {
-        say("Nothing to change.");
-        return 0;
+    return { changed, guardedIn, added };
+}
+// ---- browser agents (Playwright, browser-use) in this project ----
+/** A shell line that exports the saved key without printing it. */
+const exportKey = () => `export CLAROS_KEY="$(node -p "require('${join(cfgDir(), "config.json").replace(homedir(), "$HOME")}').key")"`;
+/** The 2-line hook for a project, as lines to print (Playwright Test: the import of the fixture init writes). */
+function hookLines(p) {
+    if (p.fixture)
+        return [fixtureImport(p)];
+    if (p.kind === "Playwright")
+        return ['import { guard } from "getclaros-browser";', "await guard(page);   // right after you create the page"];
+    return ["from claros_browser import guard_tools", "guard_tools(tools)   # the Tools() you pass to Agent(..., tools=tools)"];
+}
+/** Each detected project's plan (install, fixture, key, hook), a question per project (Enter = yes; --yes; skipped
+ *  with --no-browser-hooks), then the install, the fixture file and CLAROS_KEY in a gitignored .env. User source
+ *  files are never edited: the hook is printed. */
+async function browserSetup(v, ps, project, at, key, run) {
+    const done = [];
+    let todo = false, wantKey = false;
+    if (!ps.length)
+        return { done, todo };
+    const env = envTarget(project);
+    const vars = { CLAROS_KEY: key,
+        ...(at.source === "pinned" ? { CLAROS_URL: at.url } : at.web !== DEFAULT_WEB ? { CLAROS_WEB_URL: at.web } : {}) };
+    const keySet = Object.entries(vars).every(([k, x]) => process.env[k] === x || (env.ok && envValue(env.path, k) === x));
+    const rel = (f) => short(f, project);
+    say(`\n  ${c.bold("Browser agents in this project")}`);
+    for (const p of ps) {
+        const row = (what, s) => say(`    ${c.dim(what.padEnd(8))} ${s}`);
+        say(`\n  ${c.bold(p.kind)}  ${c.dim(`${tilde(p.dir)} ${mark.dot} ${p.via}`)}`);
+        row("install", p.installed ? c.dim("already installed") : p.install ? c.violet(p.install.map(tilde).join(" ")) : c.dim(p.installNote));
+        if (p.fixture && !existsSync(p.fixture))
+            row("write", `${rel(p.fixture)}  ${c.dim("a fixture: every test's page goes through the guard")}`);
+        row("key", keySet ? c.dim("CLAROS_KEY already set") : env.ok ? `CLAROS_KEY ${mark.to} .env  ${c.dim("gitignored")}`
+            : c.dim(`CLAROS_KEY: export it (${env.why})`));
+        if (p.hooked)
+            row("hook", c.dim("already in place"));
+        else {
+            say(`    ${c.dim("hook".padEnd(8))} ${p.fixture ? "in" : "add to"} ${p.hookFile ? c.bold(rel(p.hookFile)) : p.fixture ? "each spec" : p.kind === "Playwright"
+                ? "the file that opens the page" : "the file that builds your Agent"}${p.more ? ` (and ${p.more} more spec${p.more > 1 ? "s" : ""})` : ""}` +
+                c.dim(p.fixture ? `, instead of "@playwright/test":` : ":"));
+            for (const l of hookLines(p))
+                say(`             ${c.violet(l)}`);
+        }
+        if (v["no-browser-hooks"]) {
+            say(c.dim("    skipped (--no-browser-hooks)"));
+            continue;
+        }
+        if (!v.yes) {
+            if (!process.stdin.isTTY) {
+                say(c.dim(`    not set up: not a terminal, pass --yes`));
+                continue;
+            }
+            const a = (await ask(`  ${c.bold(`Set up ${p.kind}?`)} ${c.dim(`Enter = yes ${mark.dot} n = skip`)} ${c.violet(mark.arrow)} `)).trim().toLowerCase();
+            if (a && !a.startsWith("y"))
+                continue;
+        }
+        if (!p.installed && p.install) {
+            say(c.dim(`    running ${p.install.map(tilde).join(" ")}`));
+            const r = spawnSync(p.install[0], p.install.slice(1), { cwd: p.dir, stdio: ["ignore", 2, 2], shell: process.platform === "win32" });
+            if (r.status === 0)
+                done.push(`Installed ${p.kind === "Playwright" ? "getclaros-browser" : "claros-browser"}  ${c.dim(`with ${p.install[0].includes("python") ? "pip" : p.install[0]}`)}`);
+            else
+                warn(`  ${p.install.map(tilde).join(" ")} failed (${r.error?.message ?? `exit ${r.status}`}); run it yourself`);
+        }
+        if (p.fixture && !existsSync(p.fixture)) {
+            commit(run, p.fixture, null, fixtureText(p.fixture));
+            done.push(`Wrote ${rel(p.fixture)}`);
+        }
+        wantKey = true;
+        todo ||= !p.hooked;
     }
-    say(`\nBacked up every file before changing it (${tilde(run.dir)}).`);
-    say(`Restart ${[...new Set(changed)].join(", ")} to load the change. Then: ${NAME} test   Undo: ${NAME} undo`);
-    return 0;
+    say();
+    if (wantKey && !keySet) {
+        if (env.ok) {
+            const before = readFileSync(env.path, "utf8");
+            commit(run, env.path, before, setEnv(before, vars), Object.keys(vars));
+            done.push(`Set ${Object.keys(vars).join(", ")} in .env  ${c.dim(`key ${keyId(key)} ${mark.dot} gitignored`)}`);
+        }
+        else {
+            say(`  ${c.bold("CLAROS_KEY")}  ${c.dim(`not written to a file (${env.why}); in the shell that runs the agent:`)}`);
+            say(`    ${c.violet(exportKey())}  ${c.dim(`# key ${keyId(key)}`)}`);
+            for (const [k, x] of Object.entries(vars))
+                if (k !== "CLAROS_KEY")
+                    say(`    ${c.violet(`export ${k}=${x}`)}`);
+            say();
+        }
+    }
+    return { done, todo };
 }
 // ---- test ----
 async function test(v, project) {
+    header();
     const at = await locate(v);
     if (!at)
         return 3;
@@ -412,32 +566,34 @@ async function test(v, project) {
             return 3;
         }
         if (ex.status === 404) {
-            say(`No approved Work Map with an exact rule to test yet. Paste a policy at ${at.web}/policy, approve the map, then run this again.`);
+            say(`  No approved Work Map with an exact rule to test yet. Paste a policy at ${at.web}/policy, approve the map, then run this again.`);
             return 1;
         }
         if (ex.status !== 200)
             throw new Error(`HTTP ${ex.status}`);
-        const e = ex.json, t0 = Date.now();
+        const e = ex.json;
+        if (e.demo && e.examples?.length > 1)
+            return await demo(e, url, key, guarded);
+        const t0 = Date.now();
         const r = await api(url, key, "/v1/check", { workflow_id: e.workflow_id, app: e.app ?? guarded[0] ?? undefined,
             tool: "getclaros_test", actor: "getclaros test", state: e.state });
         if (r.status !== 200)
             throw new Error(`HTTP ${r.status}`);
         const ms = Date.now() - t0;
-        if (e.demo)
-            say(`DEMO: ${guarded.length ? `none of your guarded servers (${guarded.join(", ")}) matches` : "no server is guarded yet, so nothing matches"} a Work Map, so this checks a made-up record against "${e.name}".`);
-        say(`Made-up test action for ${e.app ?? "a demo app"} (only checked, never run): ${Object.entries(e.state).map(([k, x]) => `${k} = ${x}`).join(", ")}`);
         if (r.json.allowed) {
-            say(`\nClaros let it through (check ${r.json.check_id}). It should have been stopped by rule ${e.guardrail_id}; tell the Claros team.`);
+            say(`  ${c.stop(mark.no)} Claros let it through (check ${r.json.check_id}). It should have been stopped by rule ${e.guardrail_id}; tell the Claros team.`);
             return 1;
         }
-        say(`\nClaros stopped it in ${ms} ms (Work Map "${e.name}", check ${r.json.check_id}):`);
-        for (const x of r.json.violations.filter((x) => x.action === "stop" || x.action === "ask")) {
-            say(`\n  Rule: ${x.rule}`);
-            if (x.quote)
-                say(`  In the expert's words${x.expert ? ` (${x.expert})` : ""}: "${x.quote}"`);
-            say(`  Who to ask: ${x.who_to_ask || x.owner || x.expert || "the process owner"}`);
-        }
-        say(`\nYour agent gets this as the tool's error instead of the call going through. Nothing was sent to ${e.app ?? "any app"}.`);
+        // the outcome first, then a card per broken rule, then the made-up action and what the agent sees
+        const held = r.json.result === "ask", ink = held ? c.ask : c.stop;
+        say(`  ${ink(c.bold(`${held ? mark.ask : mark.stop} ${held ? "Held to ask first" : "Stopped"} in ${dur(ms)}`))}  ` +
+            c.dim(`Work Map "${e.name}" ${mark.dot} check ${r.json.check_id}`));
+        stopCards(r.json);
+        say();
+        say(c.dim(wrap(`  Test action for ${e.app ?? "a demo app"}, made up, only checked: ${Object.entries(e.state).map(([k, x]) => `${k} = ${x}`).join(", ")}`, 4)));
+        say(wrap(`  Your agent gets the rule as the tool's error. Nothing reached ${e.app ?? "any app"}.`, 2));
+        if (e.demo)
+            say(c.dim(wrap(`  Demo: ${guarded.length ? `none of your guarded servers (${guarded.join(", ")}) matches a Work Map` : "no server is guarded yet"}, so this used your newest Work Map.`, 2)));
         return 0;
     }
     catch (err) {
@@ -445,6 +601,57 @@ async function test(v, project) {
         return 3;
     }
 }
+/** a card per stop / ask rule the check broke: the rule, the expert's words, who to ask */
+function stopCards(r) {
+    for (const x of r.violations.filter((x) => x.action === "stop" || x.action === "ask")) {
+        const ask = x.action === "ask", p = ask ? c.ask : c.stop;
+        say();
+        say(`    ${p(`${ask ? mark.ask : mark.stop} ${ask ? "ask " : "stop"}`)}  ${c.bold(wrap(x.rule, 12))}`);
+        if (x.quote)
+            say(`            ${wrap(`“${x.quote}”`, 12)}${x.expert ? c.dim(` ${mark.dash} ${x.expert}`) : ""}`);
+        say(`            ${c.dim("Who to ask:")} ${x.who_to_ask || x.owner || x.expert || "the process owner"}`);
+    }
+}
+/** a made-up record on one line: whitespace in strings collapsed, long values cut */
+const record = (tool, state) => `${tool ? `${tool} ` : ""}${Object.entries(state).map(([k, x]) => {
+    const v = typeof x === "string" ? x.replace(/\s+/g, " ").trim() : String(x);
+    return `${k} = ${v.length > 80 ? v.slice(0, 79) + "…" : v}`;
+}).join(", ")}`;
+/** demo (no guarded server matches a map): the starter maps' examples, a stop then a nudge, checked side by side */
+async function demo(e, url, key, guarded) {
+    const t0 = Date.now();
+    const rs = await Promise.all(e.examples.map((x) => api(url, key, "/v1/check", { workflow_id: x.workflow_id, tool: x.tool, actor: "getclaros test", state: x.state })));
+    const bad = rs.find((r) => r.status !== 200);
+    if (bad)
+        throw new Error(`HTTP ${bad.status}`);
+    const ms = Date.now() - t0, [stop, ...rest] = rs.map((r) => r.json), [se, ...re] = e.examples;
+    if (stop.allowed) {
+        say(`  ${c.stop(mark.no)} Claros let it through (check ${stop.check_id}). It should have been stopped by rule ${se.guardrail_id}; tell the Claros team.`);
+        return 1;
+    }
+    const held = stop.result === "ask", nudged = rest.some((r) => r.result === "nudge");
+    const outcome = [(held ? c.ask : c.stop)(c.bold(`${held ? mark.ask : mark.stop} ${held ? "Held to ask first" : "Stopped"}`)),
+        ...(nudged ? [c.nudge(c.bold(`${mark.nudge} Nudged`))] : [])].join(` ${mark.dot} `);
+    say(`  ${outcome}  ${c.dim(`${rs.length} checks in ${dur(ms)}`)}`);
+    stopCards(stop);
+    say(c.dim(`            ${wrap(`Test action: ${record(se.tool, se.state)}`, 12)}`));
+    rest.forEach((r, i) => {
+        const x = r.violations.find((v) => v.action === "nudge"), ex = re[i];
+        say();
+        say(`    ${c.nudge(`${mark.nudge} nudge`)} ${c.bold(wrap(x?.rule ?? ex.rule ?? `Work Map "${ex.name}"`, 12))}`);
+        if (x?.quote)
+            say(`            ${wrap(`“${x.quote}”`, 12)}${x.expert ? c.dim(` ${mark.dash} ${x.expert}`) : ""}`);
+        if (x?.fix)
+            say(`            ${c.nudge(mark.to)} ${wrap(x.fix, 14)}`);
+        else if (!x)
+            say(c.dim(`            Not judged this time (${r.judge?.error ?? r.judge?.status ?? "the server's judge is off"}).`));
+        say(c.dim(`            ${wrap(`Test action: ${record(ex.tool, ex.state)}`, 12)}`));
+    });
+    say();
+    say(wrap("  Your agent gets a stop as the tool's error; a nudge lets the call through, with the fix. Nothing reached any app.", 2));
+    say(c.dim(wrap(`  Demo: ${guarded.length ? `none of your guarded servers (${guarded.join(", ")}) matches a Work Map` : "no server is guarded yet"}, so this used the Starter maps (examples, not enforced; delete them on the web).`, 2)));
+    return 0;
+}
 // ---- export ----
 /** A Work Map's rules as markdown on stdout (GET /v1/maps/<id>/export): redirect it into AGENTS.md, DESIGN.md or a
  *  skill's SKILL.md. An advisory copy: Claros still enforces the rules when an agent acts. */
@@ -501,8 +708,11 @@ async function override(v, checkId) {
         return 3;
     }
 }
-// ---- status ----
-async function status(v, project) {
+// ---- doctor (status is the same command) ----
+/** Per agent type: is it guarded and can it reach Claros, with the command that fixes what isn't.
+ *  Exit: 0 all good, 1 a browser agent here isn't set up, 2 no key, 3 Claros unreachable or the key rejected. */
+async function doctor(v, project) {
+    header();
     const at = await locate(v);
     if (!at)
         return 3;
@@ -510,15 +720,59 @@ async function status(v, project) {
     const up = await fetch(url + "/healthz", { signal: AbortSignal.timeout(10_000) }).then((r) => r.ok, () => false);
     const ks = key ? await keyStatus(url, key) : "not set (run init)";
     const ws = ks === "valid" ? (await whoami(url, key))?.name ?? (loadConfig().key === key ? loadConfig().workspace?.name : null) : null;
-    say(`Claros  ${url}  ${up ? "reachable" : "unreachable"}  key ${key ? keyId(key) + " " : ""}${ks}${ws ? `  workspace "${ws}"` : ""}`);
-    for (const f of detect(project)) {
-        say(`\n${f.client}  ${tilde(f.path)}${f.error ? `  couldn't read it (${f.error})` : ""}`);
+    const ok = (good, s) => (good ? c.ask(s) : c.stop(s));
+    const fine = up && ks === "valid";
+    say(`  ${ok(fine, fine ? mark.ok : mark.no)} ${c.bold("Claros")}  ${url}  ${ok(up, up ? "reachable" : "unreachable")}` +
+        `  key ${key ? keyId(key) + " " : ""}${ok(ks === "valid", ks)}${ws ? `  workspace "${ws}"` : ""}`);
+    const fix = (s) => say(`    ${c.violet(mark.to)} ${s}`);
+    if (!key || /rejected|scope/.test(ks))
+        fix(`${NAME} init  ${c.dim("signs in and saves an agent key")}`);
+    else if (!up)
+        fix(c.dim(`check your network; a moved server is followed on the next run (or pass --url)`));
+    const files = detect(project);
+    say(`\n  ${c.bold("MCP agents")}`);
+    if (!files.length)
+        say(c.dim("    none found (Claude Code, Claude Desktop, Cursor, VS Code, Codex)"));
+    for (const f of files) {
+        say(`\n  ${c.bold(f.client)}  ${c.dim(tilde(f.path))}${f.error ? `  couldn't read it (${f.error})` : ""}`);
         for (const s of f.servers) {
-            say(`  ${(s.name + where(s)).padEnd(24)} ${s.ours ? "Claros MCP server" : s.guarded ? "guarded"
-                : s.gap ? `remote, ${s.gap}` : s.remote ? "remote, not guarded" : "not guarded"}`);
+            const [m, state] = s.ours ? [c.violet(mark.dot), c.dim("Claros MCP server")] : s.guarded ? [c.ask(mark.ok), c.ask("guarded")]
+                : s.gap ? [c.dim(mark.dot), c.dim(`remote, ${s.gap}`)] : [c.dim(mark.off), s.remote ? "remote, not guarded" : "not guarded"];
+            say(`    ${m} ${(s.name + where(s)).padEnd(24)} ${state}`);
         }
     }
-    return !key ? 2 : up && ks === "valid" ? 0 : 3;
+    const servers = files.flatMap((f) => f.servers.filter((s) => !s.ours));
+    if (servers.some((s) => !s.guarded && !s.gap))
+        fix(`${NAME} init  ${c.dim(`guards the servers you pick${servers.some((s) => s.guarded) ? "" : " (none is guarded yet)"}`)}`);
+    // browser agents: package installed, hook present, a key the agent can read (env or a safe .env)
+    let broken = false;
+    const ps = detectBrowser(project);
+    if (ps.length)
+        say(`\n  ${c.bold("Browser agents in this project")}`);
+    const env = envTarget(project), fromFile = envValue(env.path, "CLAROS_KEY");
+    const agentKey = process.env.CLAROS_KEY || fromFile;
+    const aks = !ps.length || !agentKey ? "" : agentKey === key ? ks : await keyStatus(url, agentKey);
+    for (const p of ps) {
+        const row = (good, s, hint) => {
+            broken ||= !good;
+            say(`    ${ok(good, good ? mark.ok : mark.no)} ${s}`);
+            if (!good && hint)
+                fix(hint);
+        };
+        say(`\n  ${c.bold(p.kind)}  ${c.dim(`${tilde(p.dir)} ${mark.dot} ${p.via}`)}`);
+        const pkg = p.kind === "Playwright" ? "getclaros-browser" : "claros-browser";
+        row(p.installed, `${pkg} ${p.installed ? "installed" : "not installed"}`, p.install ? `${p.install.map(tilde).join(" ")}  ${c.dim(`(or ${NAME} init)`)}` : p.installNote);
+        row(p.hooked, p.hooked ? `hook in place${p.fixture ? ` (${short(p.fixture, project)})` : ""}` : "no hook yet", p.fixture && !existsSync(p.fixture) ? `${NAME} init  ${c.dim(`writes ${short(p.fixture, project)}; then import from it in your specs`)}`
+            : `${p.hookFile ? `in ${short(p.hookFile, project)}` : "add"}:\n${hookLines(p).map((l) => `        ${l}`).join("\n")}`);
+        if (!agentKey)
+            row(false, "CLAROS_KEY not set", env.ok ? `${NAME} init  ${c.dim("writes it to .env (gitignored)")}` : `${exportKey()}  ${c.dim(`(${env.why})`)}`);
+        else if (fromFile && !process.env.CLAROS_KEY && !env.ok) {
+            row(false, `CLAROS_KEY is in .env, but ${env.why}`, `move it out of .env, and make a new key if it was ever committed`);
+        }
+        else
+            row(aks === "valid", `CLAROS_KEY ${keyId(agentKey)} from ${process.env.CLAROS_KEY ? "the environment" : ".env"} ${aks}`, `${NAME} init  ${c.dim("writes a valid key")}`);
+    }
+    return !key ? 2 : !(up && ks === "valid") ? 3 : broken ? 1 : 0;
 }
 // ---- undo ----
 /** Unwraps every guarded server and removes our Claros entry in place; the rest of the file stays. */
@@ -536,9 +790,10 @@ function unwrapAll(f) {
     return n;
 }
 async function undo(v, project) {
+    header();
     const scope = v.all ? runs() : runs().slice(-1);
     if (!scope.length && !v.all) {
-        say(`Nothing to undo: no backups from ${NAME} init.`);
+        say(`  Nothing to undo: no backups from ${NAME} init.`);
         return 0;
     }
     const chains = new Map();
@@ -549,14 +804,29 @@ async function undo(v, project) {
     const byPath = new Map(detect(project).map((f) => [f.path, f]));
     for (const [path, chain] of chains) {
         if (!existsSync(path)) {
-            say(`${tilde(path)}: gone; nothing to undo`);
+            say(`  ${mark.dot} ${tilde(path)}: gone; nothing to undo`);
             continue;
         }
         const cur = readFileSync(path, "utf8");
         const same = sha(cur) === chain.at(-1).after && chain.every((b, i) => !i || b.before === chain[i - 1].after);
-        if (same) {
+        const vars = chain.flatMap((b) => b.vars ?? []);
+        if (chain[0].created) { // a file init wrote (the Playwright fixture): deleted only while it's exactly what init wrote
+            if (same) {
+                unlinkSync(path);
+                say(`  ${c.ask(mark.ok)} ${tilde(path)}: removed (init wrote it)`);
+            }
+            else
+                warn(`${tilde(path)}: changed since init wrote it; left in place (delete it yourself)`);
+        }
+        else if (!same && vars.length) { // a .env edited since: drop only the lines init set
+            const t = cur.replace(new RegExp(`^(export\\s+)?(${vars.join("|")})=.*(\\r?\\n|$)`, "gm"), "");
+            if (t !== cur)
+                commit(safety, path, cur, t);
+            say(`  ${c.ask(mark.ok)} ${tilde(path)}: changed since init, so removed ${vars.join(", ")} and kept the other lines`);
+        }
+        else if (same) {
             commit(safety, path, cur, readFileSync(chain[0].backup, "utf8"));
-            say(`${tilde(path)}: restored from the backup taken before init (unchanged since)`);
+            say(`  ${c.ask(mark.ok)} ${tilde(path)}: restored from the backup taken before init (unchanged since)`);
         }
         else {
             const f = byPath.get(path) ?? detect(project).find((x) => x.path === path);
@@ -567,7 +837,7 @@ async function undo(v, project) {
             const n = unwrapAll(f);
             if (f.text !== cur)
                 commit(safety, path, cur, f.text);
-            say(`${tilde(path)}: changed since init, so unwrapped ${n} server(s) in place and kept the other edits`);
+            say(`  ${c.ask(mark.ok)} ${tilde(path)}: changed since init, so unwrapped ${n} server(s) in place and kept the other edits`);
         }
         byPath.delete(path);
     }
@@ -578,12 +848,12 @@ async function undo(v, project) {
             const cur = f.text, n = unwrapAll(f);
             if (f.text !== cur) {
                 commit(safety, f.path, cur, f.text);
-                say(`${tilde(f.path)}: unwrapped ${n} server(s) in place`);
+                say(`  ${c.ask(mark.ok)} ${tilde(f.path)}: unwrapped ${n} server(s) in place`);
             }
         }
     }
     for (const r of scope)
         renameSync(r.dir, r.dir + ".undone");
-    say(`Done. Restart your agent clients to load the change.${safety.files.length ? ` What undo replaced is in ${tilde(safety.dir)}.` : ""}`);
+    say(`\n  ${c.bold("Done.")} Restart your agent clients to load the change.${safety.files.length ? ` What undo replaced is in ${tilde(safety.dir)}.` : ""}`);
     return 0;
 }

package/dist/ui.js

@@ -0,0 +1,67 @@
+// Terminal styling for init / test / status / undo: hand-rolled ANSI, no dependency.
+// fancy (the header, the spinner, wrapped cards) when stdout is a terminal or FORCE_COLOR is set; colour when the
+// terminal has it, by Node's own rules (NO_COLOR, FORCE_COLOR, TERM=dumb, COLORTERM, Windows versions). Piped:
+// plain text, no escape codes, so the output stays greppable. Marks fall back to ASCII on old Windows consoles.
+import { readFileSync } from "node:fs";
+import { WriteStream } from "node:tty";
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export function styleFor(s, env = process.env, platform = process.platform) {
+    const forced = env.FORCE_COLOR !== undefined && !["0", "false"].includes(env.FORCE_COLOR);
+    const fancy = !!s.isTTY || forced;
+    const depth = fancy ? WriteStream.prototype.getColorDepth.call(null, env) : 1;
+    const uni = platform !== "win32" || !!(env.WT_SESSION || env.TERM_PROGRAM || env.TERM?.startsWith("xterm"));
+    return { fancy, depth, uni };
+}
+export const S = styleFor(process.stdout);
+// the brand's three answers (stop magenta, ask green, nudge vermilion) and the quote's violet, a shade brighter than
+// the web's inks so they read on dark terminals as well as light ones: [truecolor, 256-colour, 16-colour]
+const INK = { stop: ["#c8359a", 162, 35], ask: ["#22995f", 29, 32], nudge: ["#e0531f", 166, 31], violet: ["#8b5cf6", 98, 34] };
+const fg = ([hex, n, basic]) => S.depth >= 24
+    ? `38;2;${[1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)).join(";")}` : S.depth >= 8 ? `38;5;${n}` : String(basic);
+const sgr = (on, off) => (s) => (S.depth > 1 && s ? `\x1b[${on}m${s}\x1b[${off}m` : s);
+export const c = {
+    bold: sgr("1", "22"), dim: sgr("2", "22"), ul: sgr("4", "24"),
+    stop: sgr(fg(INK.stop), "39"), ask: sgr(fg(INK.ask), "39"), nudge: sgr(fg(INK.nudge), "39"), violet: sgr(fg(INK.violet), "39"),
+};
+const U = S.uni;
+/** stop = the seal, ask = the thread hooked to a person, nudge = the proofreader's pencil */
+export const mark = {
+    stop: U ? "◉" : "x", ask: U ? "↳" : "?", nudge: U ? "✎" : "~", ok: U ? "✓" : "+", no: U ? "✗" : "x",
+    on: U ? "●" : "*", off: U ? "○" : "o", dot: U ? "·" : "-", arrow: U ? "›" : ">", dash: U ? "—" : "-", to: U ? "→" : "->",
+};
+export const say = (s = "") => process.stdout.write(s + "\n");
+/** claros” and the version: only on a terminal (piped output starts with what it says) */
+export function header() {
+    if (S.fancy)
+        say(`\n  ${c.bold("claros")}${c.violet(U ? "”" : '"')}  ${c.dim(`getclaros ${VERSION}`)}\n`);
+}
+/** wraps to the terminal's width with a hanging indent (plain output isn't wrapped) */
+export function wrap(text, indent) {
+    const width = (process.stdout.columns || 0) - indent;
+    if (!S.fancy || width < 30)
+        return text;
+    const lead = /^\s*/.exec(text)[0], out = [];
+    let line = lead;
+    for (const w of text.slice(lead.length).split(" ")) {
+        if (line.trim() && (line + " " + w).length > width) {
+            out.push(line);
+            line = w;
+        }
+        else
+            line = line.trim() ? line + " " + w : line + w;
+    }
+    out.push(line);
+    return out.join("\n" + " ".repeat(indent));
+}
+/** a braille spinner on a real terminal (never when piped or forced); stop() clears its line */
+export function spinner(text) {
+    if (!process.stdout.isTTY)
+        return { stop() { } };
+    const F = U ? "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏" : "|/-\\";
+    let i = 0;
+    const draw = () => process.stdout.write(`\r\x1b[2K  ${c.violet(F[i++ % F.length])} ${c.dim(text)}`);
+    draw();
+    const t = setInterval(draw, 80);
+    return { stop() { clearInterval(t); process.stdout.write("\r\x1b[2K"); } };
+}
+export const dur = (ms) => (ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(1)} s`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getclaros",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Claros guard: checks an agent's MCP tool calls against your experts' rules before they run",
   "license": "MIT",
   "type": "module",