getclaros 0.1.1 → 0.2.0

package/README.md

@@ -15,8 +15,13 @@ npx getclaros init
 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.1.1
+  claros”  getclaros 0.2.0
 
   Sign in  opening your browser
   › https://claros-eta.vercel.app/device?code=ZQRC-ZCTP
@@ -25,7 +30,7 @@ configs launch your build instead of `npx -y getclaros`.
   ✓ Signed in to workspace "Acme"  key clr_7f3a91c2_…
     <claros server> · key saved in ~/.config/getclaros/config.json, readable only by you
 
-  MCP servers
+  MCP agents
 
   Claude Code  ~/.claude.json
      1 ● erpnext                     npx -y frappe-mcp-server  Work Map "Process a supplier invoice"
@@ -81,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
 ```
@@ -99,7 +134,30 @@ 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 workspace's newest map and ends with a `Demo:` note.
+
+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

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 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")) {
@@ -209,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() {
@@ -285,12 +292,49 @@ async function init(v, project) {
         ? join(cfgDir(), "config.json") : saveConfig({ url, web, key, ...(workspace ? { workspace } : {}) });
     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);
-    if (!files.length) {
+    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's tools: add an MCP server to Claude Code, Claude Desktop, Cursor, VS Code or Codex (none has one yet), then run init again.", 2)));
+        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)))));
     // per client: the servers it can guard (numbered, ● = matches a Work Map), the ones already guarded; the remote
@@ -298,7 +342,7 @@ async function init(v, project) {
     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 servers")}`);
+    say(`\n  ${c.bold("MCP agents")}`);
     for (const f of files) {
         say(`\n  ${c.bold(f.client)}  ${c.dim(tilde(f.path))}`);
         if (f.error)
@@ -375,7 +419,6 @@ async function init(v, project) {
     else if (!picks.length && cands.length) {
         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 = [], 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)) {
@@ -413,19 +456,95 @@ async function init(v, project) {
                 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;
     }
-    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)}`)}`);
-    say(c.dim(`    every file backed up first: ${tilde(run.dir)}`));
-    say(`\n  ${c.bold("Next")}  restart ${list(changed)}, then run  ${c.violet(`${NAME} test`)}`);
-    say(c.dim(`        undo anytime: ${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) {
@@ -452,7 +571,10 @@ async function test(v, project) {
         }
         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)
@@ -466,14 +588,7 @@ async function test(v, project) {
         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}`));
-        for (const x of r.json.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"}`);
-        }
+        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));
@@ -486,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. */
@@ -542,8 +708,10 @@ 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)
@@ -556,7 +724,16 @@ async function status(v, project) {
     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}"` : ""}`);
-    for (const f of detect(project)) {
+    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) {
             const [m, state] = s.ours ? [c.violet(mark.dot), c.dim("Claros MCP server")] : s.guarded ? [c.ask(mark.ok), c.ask("guarded")]
@@ -564,7 +741,38 @@ async function status(v, project) {
             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. */
@@ -601,7 +809,22 @@ async function undo(v, project) {
         }
         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(`  ${c.ask(mark.ok)} ${tilde(path)}: restored from the backup taken before init (unchanged since)`);
         }

package/dist/ui.js

@@ -27,7 +27,7 @@ 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 ? "—" : "-",
+    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) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getclaros",
-  "version": "0.1.1",
+  "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",