@fringetools/cli 0.4.1 → 0.6.0

package/README.md

@@ -22,7 +22,11 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | Command | What it does |
 |---|---|
 | `fringe check [dir\|file]` | Scan a directory (default `.`) or judge one file (the project root is found by climbing to the nearest `package.json`). Prints findings and the health score. Exit `1` on any `error`. |
-| `fringe scan <url> [--states file] [--json]` | **Runtime check of a live page** (needs `npm i -D playwright-core axe-core`; uses your installed Chrome). Runs axe-core for real contrast, computed names and ARIA relations (`FR-400`; critical/serious = `error`, the rest `review`), then walks the page with Tab and reports keyboard traps (`FR-401`, error) and controls Tab never reaches (review). Accepts `http(s)://` and `file://` URLs. Exit `1` on errors. |
+| `fringe scan <url> [--states file] [--stress] [--storage-state auth.json] [--screenshots dir] [--update-baseline] [--json]` | **Runtime check of a live page** (needs `npm i -D playwright-core axe-core`; uses your installed Chrome). Runs axe-core for real contrast, computed names and ARIA relations (`FR-400`; critical/serious = `error`, the rest `review`), then walks the page with Tab and reports keyboard traps (`FR-401`, error) and controls Tab never reaches (review). Accepts `http(s)://` and `file://` URLs. Exit `1` on errors. |
+| `fringe login <url> [--out file]` | **Log in once, by hand, in a real browser window** and save the session (default `.fringe/auth.json`) for `scan --storage-state`. Works with MFA and SSO. The file holds live cookies: keep it out of git. |
+| `fringe rules [dir] [--json]` | **Per-rule health for this repo**: findings still open, accepted into the baseline, and silenced with `fringe-ignore`, plus the ledger trend when `--record` has been used. A rule that is mostly overridden here is flagged: it may not suit the repo, so retune, disable or report it. `fringe/rules.v1`. |
+| `fringe handoff [dir\|file] [--scan url]` | **Work order for another agent or CI.** Prints a self-contained prompt (rules, definition of done, the ordered plan) and saves `.fringe/handoff.json` (`fringe/handoff.v1`). `--json` prints the file; `--out` chooses where. |
+| `fringe verify [--handoff file] [--json]` | **Proof it was done.** Re-checks everything the hand-off covered and reports `complete` / `partial` / `regressed`: errors fixed, remaining, introduced, and how many findings were silenced with `fringe-ignore` since. Exit `0` only when `complete` (`fringe/verify.v1`). |
 | `fringe plan [dir\|file] [--scan url] [--json] [--limit n]` | **Fix order for a repo with many findings**: P0 (errors in shared components or critical paths) → P1 (other errors, mechanical first) → P2 review → P3 polish, each cluster with its fix recipe. Never gates (exit 0). `--scan <url>` adds the live page's runtime findings to the same plan (one cluster per axe rule, with element selectors). `--json` = `fringe/plan.v1`. |
 | `fringe explain [FR-203]` | Why a rule matters, the preferred fix and the tempting fix to avoid. No id lists all 36 rules. |
 | `fringe explain pattern [form]` | Build-time best-practice checklist for a component type (`form`, `modal`, `navigation`, `data-view`); each item is marked *verified* (a rule checks it) or *judged*. |
@@ -32,6 +36,8 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | `fringe check --update-baseline` | Accept today's findings into `fringe.baseline.json` (commit it). Exit `0`. |
 | `fringe check --record [--manifest <path>]` | Also append this run to `.fringe/ledger.jsonl`, optionally merging an agent flow manifest. |
 | `fringe` (no arguments) | Checks the current folder, and if the post-edit check is not set up yet, says how to set it up. |
+| `fringe init --for <agents>` | Writes the Fringe rules where other agents read them: `codex`, `generic` (AGENTS.md), `gemini` (GEMINI.md), `cursor` (.cursor/rules), `copilot`, `windsurf`, `cline`, `kiro`. Appends to an existing file, never overwrites. Comma-separate several. |
+| `fringe init --git` | Installs a git pre-commit gate that blocks a commit while error-level problems remain, for any agent that commits. It fails open: if the checker cannot run (no network, no node), the commit goes through. Never replaces someone else's hook. |
 | `fringe init [path] [--global]` | Add the Claude Code hook and install the six skills. `--global` writes to `~/.claude` so every project is covered. Uses the project's own installed copy of Fringe when there is one (faster), otherwise `npx`. Safe to re-run; refuses to touch an invalid `settings.json`. |
 | `fringe open [path] [--port <n>]` | Serve the ledger as a plain HTML page on `127.0.0.1:4173` (loopback only). Ctrl+C to stop. |
 | `fringe --help` · `--version` | Usage / version. |
@@ -103,8 +109,82 @@ npx @fringetools/cli scan http://localhost:3000 --modes dark,reflow      # a sub
 
 Each mode runs on a fresh page so one mode's emulation never leaks into the next, and only findings the plain page did not already have are kept. Findings are labelled `[dark mode]`, `[reduced motion]`, `[reflow]`. Modes apply to the initial page, not to named states.
 
+### Pages behind a login
+
+Most apps hide the interesting pages behind a sign-in, and a scan that gets bounced to the login screen audits the wrong page. Three ways to be logged in; pick the one that fits.
+
+**1. Log in once by hand (works with MFA, SSO, captchas).**
+
+```sh
+npx @fringetools/cli login http://localhost:3000/login      # a Chrome window opens
+# sign in as you normally would, then press Enter in the terminal (close the window afterwards)
+npx @fringetools/cli scan http://localhost:3000/dashboard --storage-state .fringe/auth.json
+```
+
+The session (cookies and local storage) is saved to `.fringe/auth.json`. It is a live login: **keep it out of git** (the command warns if `.gitignore` does not list `.fringe/`) and expect it to expire.
+
+**2. A scripted login (for CI and agents).** Describe the steps in `fringe.scan.json`; credentials come from environment variables, so none are stored in the file:
+
+```json
+{
+  "login": {
+    "url": "/login",
+    "steps": [
+      { "fill": "#email", "value": "${env:FRINGE_EMAIL}" },
+      { "fill": "#password", "value": "${env:FRINGE_PASSWORD}" },
+      { "click": "button:has-text(\"Sign in\")" },
+      { "waitFor": "[data-test=dashboard]" }
+    ]
+  },
+  "states": [ { "name": "settings", "steps": [ { "goto": "/settings" } ] } ]
+}
+```
+
+Use a **test account**, not a real user. A missing variable stops the scan before any browser opens, naming the variable and never its value; messages show the step with the `${env:...}` placeholder, not the secret. Prefer specific selectors: `text=Sign in` can match the page heading instead of the button.
+
+**3. Several roles in one scan.** List sessions; each runs the whole scan (initial page, states, stress modes) and findings are labelled `[as admin]`, `[as member]`:
+
+```json
+{ "sessions": [
+  { "name": "member", "login": { "url": "/login", "steps": [ ... ] } },
+  { "name": "admin",  "storageState": "admin-auth.json" }
+] }
+```
+
+**What you will see when something is off**
+- `FR-405` "the scan was sent to /login, which looks like a login page": the session is missing or expired. Everything else in that run describes the login screen, not your app, so refresh the session first.
+- `FR-402` "login failed at step N": a selector did not match or the page did not reach the expected state. The step is shown; fix it in `fringe.scan.json`.
+
+### Screenshots and a baseline for scan findings
+
+- **Screenshots:** `--screenshots shots/` saves a full-page PNG of the initial page, each named state and each stress mode, so a reviewer can see what was audited.
+- **Baseline:** `scan --update-baseline` writes `fringe.scan.baseline.json` (commit it); later scans hide those known findings and report `N baselined`. Matching is by rule, page/state and element, not axe's wording, so a contrast ratio that shifts slightly stays known.
+
 Limits, plainly: states are independent (each starts from a fresh load of the URL, so there are no multi-page flows that depend on earlier state beyond `goto`); it needs the page running; findings have no source line (they carry a CSS selector); automated checks only find part of the real problems. `fringe plan --scan <url>` merges it with the static findings into one fix order. It does not feed the baseline or `fringe-ignore` yet, and is not part of the edit hook (it needs a running app and takes seconds).
 
+## Agent hand-off
+
+For agent-to-agent or CI-to-agent work with no human in the middle: one agent (or a CI job) finds problems, another fixes them, and a check proves it.
+
+```sh
+fringe handoff --scan http://localhost:3000 > prompt.md    # the work order; also saved as .fringe/handoff.json
+claude -p "$(cat prompt.md)"                               # or any agent that takes a prompt
+fringe verify                                              # exit 0 only when complete; --json for the orchestrator
+```
+
+The prompt carries the rules (fix the cause, never silence a rule to get green, list any `fringe-ignore` you add, stop and report anything that needs a human decision), the definition of done, and the ordered plan with fix recipes. `verify` compares with the hand-off's fingerprints, so it can tell an error that was *fixed* from one that was *introduced*, and it reports new suppressions for a human to review. Tested end to end: a fresh agent given only the prompt fixed all 122 errors of a messy app, `verify` returned `complete` with 0 introduced and 0 silenced.
+
+## Using Fringe with other coding agents
+
+| Layer | Works with | Notes |
+|---|---|---|
+| **Rules file** (`init --for …`) | Codex, Gemini CLI, Cursor, Copilot, Windsurf, Cline, Kiro, Amp, Jules, Zed, anything reading `AGENTS.md` | The agent is told to run `fringe check` after edits and fix errors. It depends on the model following instructions. |
+| **Git pre-commit gate** (`init --git`) | Any agent that runs `git commit` | The hook output goes to the agent's terminal. Fails open. |
+| **CLI, `plan`, `handoff`/`verify`, CI** | Everything | Plain commands, exit codes and JSON. |
+| **Live post-edit hook** | Claude Code | Verified. Other hosts have their own hook contracts, which must each be tested against the real tool before we claim support. |
+
+Verified so far: Claude Code (hook and skills); Codex CLI (read `AGENTS.md` and tried to run the check; its sandbox crashed `npx` with a keychain error, so there use `npm i -D @fringetools/cli`). Gemini CLI could not be tested here (no output headlessly), so `GEMINI.md` is written but unverified.
+
 ## Priority, clusters and fix plans
 
 Every finding in `--json` carries `priority`, `cluster` and `fixability`, and the result has a `clusters` list. A cluster is one rule in one file: usually one root cause and one fix.

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-7ZFEVMML.js";
+} from "./chunk-JJI65ERU.js";
 
 // src/bin.ts
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/{chunk-7ZFEVMML.js → chunk-JJI65ERU.js}

@@ -1,10 +1,10 @@
 // src/index.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync3, readFileSync as readFileSync9, statSync } from "fs";
-import { dirname as dirname2, join as join10, resolve } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync11, statSync } from "fs";
+import { dirname as dirname3, join as join12, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.4.1";
+var VERSION = "0.6.0";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -1601,6 +1601,7 @@ function receipts(root, findings) {
 
 // src/scan.ts
 import { createRequire } from "module";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync3 } from "fs";
 import { join as join8 } from "path";
 var SCAN_HELP = "fringe scan needs two optional packages in your project: npm i -D playwright-core axe-core (it uses your installed Google Chrome; otherwise run npx playwright-core install chromium)";
 var WCAG_TAG = /^wcag(\d)(\d)(\d+)$/;
@@ -1640,31 +1641,61 @@ function tabWalkFindings(url, focusables, visits) {
   return out;
 }
 var STEP_KEYS = ["click", "fill", "press", "hover", "waitFor", "goto"];
+var bad = (m) => {
+  throw new Error(`fringe.scan.json: ${m}`);
+};
+function checkSteps(steps, where2) {
+  if (!Array.isArray(steps) || steps.length === 0) return bad(`${where2} needs a non-empty "steps" list`);
+  for (const [k, step] of steps.entries()) {
+    const keys = STEP_KEYS.filter((x) => step && typeof step === "object" && x in step);
+    if (keys.length !== 1 || typeof step[keys[0]] !== "string") bad(`${where2} step ${k + 1} must be exactly one of ${STEP_KEYS.join(", ")} with a string value`);
+    if (keys[0] === "fill" && typeof step.value !== "string") bad(`${where2} step ${k + 1}: fill needs a "value"`);
+  }
+  return steps;
+}
 function parseStates(json) {
-  const bad = (m) => {
-    throw new Error(`fringe.scan.json: ${m}`);
-  };
-  const states = json?.states;
-  if (!Array.isArray(states)) return bad('expected { "states": [ ... ] }');
-  return states.map((s, i) => {
+  const o = json;
+  if (o?.states === void 0 && (o?.login !== void 0 || o?.sessions !== void 0 || o?.storageState !== void 0)) return [];
+  if (!Array.isArray(o?.states)) return bad('expected { "states": [ ... ] }');
+  return o.states.map((s, i) => {
     if (typeof s?.name !== "string" || !s.name.trim()) bad(`states[${i}] needs a "name"`);
-    if (!Array.isArray(s.steps) || s.steps.length === 0) bad(`state "${s.name}" needs a non-empty "steps" list`);
-    for (const [k, step] of s.steps.entries()) {
-      const keys = STEP_KEYS.filter((x) => step && typeof step === "object" && x in step);
-      if (keys.length !== 1 || typeof step[keys[0]] !== "string") bad(`state "${s.name}" step ${k + 1} must be exactly one of ${STEP_KEYS.join(", ")} with a string value`);
-      if (keys[0] === "fill" && typeof step.value !== "string") bad(`state "${s.name}" step ${k + 1}: fill needs a "value"`);
-    }
-    return { name: s.name.trim(), steps: s.steps };
+    return { name: s.name.trim(), steps: checkSteps(s.steps, `state "${s.name}"`) };
   });
 }
+function parseSessions(json, baseDir) {
+  const o = json ?? {};
+  const one = (x, where2, name) => {
+    if (x?.storageState !== void 0 && typeof x.storageState !== "string") bad(`${where2}: storageState must be a file path`);
+    if (x?.login !== void 0 && typeof x.login?.url !== "undefined" && typeof x.login.url !== "string") bad(`${where2}: login.url must be a string`);
+    return { ...name ? { name } : {}, ...x?.storageState ? { storageState: join8(baseDir, x.storageState) } : {}, ...x?.login ? { login: { ...x.login.url ? { url: x.login.url } : {}, steps: checkSteps(x.login.steps, `${where2} login`) } } : {} };
+  };
+  const out = [];
+  if (o.login !== void 0 || o.storageState !== void 0) out.push(one(o, "top level"));
+  if (o.sessions !== void 0) {
+    if (!Array.isArray(o.sessions) || o.sessions.length === 0) bad('"sessions" must be a non-empty list');
+    for (const [i, s] of o.sessions.entries()) {
+      if (typeof s?.name !== "string" || !s.name.trim()) bad(`sessions[${i}] needs a "name"`);
+      if (!s.storageState && !s.login) bad(`session "${s.name}" needs a "storageState" or a "login"`);
+      out.push(one(s, `session "${s.name}"`, s.name.trim()));
+    }
+  }
+  return out;
+}
+var ENV_REF = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;
+var expandEnv = (s) => s.replace(ENV_REF, (_m, n) => {
+  const v = process.env[n];
+  if (v === void 0) throw new Error(`environment variable ${n} is not set (named in fringe.scan.json)`);
+  return v;
+});
+var envNames = (steps) => steps.flatMap((st) => ("fill" in st ? [st.value] : "goto" in st ? [st.goto] : []).flatMap((v) => [...v.matchAll(ENV_REF)].map((m) => m[1])));
 async function runStep(page, step, base) {
   const t = { timeout: 1e4 };
   if ("click" in step) await page.click(step.click, t);
-  else if ("fill" in step) await page.fill(step.fill, step.value, t);
+  else if ("fill" in step) await page.fill(step.fill, expandEnv(step.value), t);
   else if ("press" in step) await page.keyboard.press(step.press);
   else if ("hover" in step) await page.hover(step.hover, t);
   else if ("waitFor" in step) await page.waitForSelector(step.waitFor, t);
-  else await page.goto(new URL(step.goto, base).href, { waitUntil: "load", timeout: 3e4 });
+  else await page.goto(new URL(expandEnv(step.goto), base).href, { waitUntil: "load", timeout: 3e4 });
   await page.waitForTimeout(150);
 }
 async function audit(page, axePath, url) {
@@ -1682,12 +1713,12 @@ async function audit(page, axePath, url) {
   }
   return [...axeToFindings(url, axeRes.violations), ...tabWalkFindings(url, focusables, visits)];
 }
-var inState = (name, url, f) => ({ ...f, message: `[${name}] ${f.message}`, loc: { ...f.loc, file: `${url} [${name}]` }, ...f.cluster ? { cluster: `${f.cluster} [${name}]` } : {} });
+var inState = (name, url, f) => ({ ...f, message: `[${name}] ${f.message}`, loc: { ...f.loc, file: `${f.loc.file === url ? url : f.loc.file} [${name}]` }, ...f.cluster ? { cluster: `${f.cluster} [${name}]` } : {} });
 var MODES = ["dark", "reduced", "reflow"];
 function parseModes(list) {
   const out = list.split(",").map((m) => m.trim()).filter(Boolean);
-  const bad = out.find((m) => !MODES.includes(m));
-  if (bad || out.length === 0) throw new Error(`unknown scan mode '${bad ?? ""}': use ${MODES.join(", ")}`);
+  const bad2 = out.find((m) => !MODES.includes(m));
+  if (bad2 || out.length === 0) throw new Error(`unknown scan mode '${bad2 ?? ""}': use ${MODES.join(", ")}`);
   return out;
 }
 function onlyNew(base, extra) {
@@ -1695,36 +1726,106 @@ function onlyNew(base, extra) {
   return extra.filter((f) => !seen.has(`${f.rule}|${f.message}`));
 }
 var countRunningLoops = `[...document.getAnimations()].filter((a) => a.playState === 'running' && a.effect && a.effect.getComputedTiming().iterations === Infinity).map((a) => { const t = a.effect.target; return t ? t.tagName.toLowerCase() + (t.id ? '#' + t.id : '') + (typeof t.className === 'string' && t.className ? '.' + t.className.trim().split(/\\s+/)[0] : '') : 'unknown'; })`;
-async function stress(browser, axePath, url, mode, base) {
-  const page = await browser.newPage();
+async function stress(context, axePath, url, mode, base, shot) {
+  const page = await context.newPage();
   try {
-    return await stressOn(page, axePath, url, mode, base);
+    return await stressOn(page, axePath, url, mode, base, shot);
   } finally {
     await page.close();
   }
 }
-async function stressOn(page, axePath, url, mode, base) {
+async function stressOn(page, axePath, url, mode, base, shot) {
   const at0 = { file: `${url} [${mode}]`, line: 1, col: 0 };
   await page.goto(url, { waitUntil: "load", timeout: 3e4 });
   if (mode === "dark") {
     await page.emulateMedia({ colorScheme: "dark" });
     await page.waitForTimeout(150);
+    await shot(page, "mode-dark");
     return onlyNew(base, await audit(page, axePath, url)).map((f) => inState("dark mode", url, f));
   }
   if (mode === "reduced") {
     await page.emulateMedia({ reducedMotion: "reduce" });
     await page.waitForTimeout(300);
+    await shot(page, "mode-reduced");
     const loops = await page.evaluate(countRunningLoops);
     return loops.length === 0 ? [] : [{ rule: "FR-403", severity: "review", message: `[reduced motion] ${loops.length} animation(s) keep looping when the user asks for reduced motion: ${loops.slice(0, 3).join(", ")}`, hint: "honour prefers-reduced-motion: stop or replace infinite animations under @media (prefers-reduced-motion: reduce)", loc: at0 }];
   }
   await page.setViewportSize({ width: 320, height: 256 });
   await page.waitForTimeout(250);
+  await shot(page, "mode-reflow");
   const wide = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth);
   const out = wide > 1 ? [{ rule: "FR-404", severity: "review", message: `[reflow] content is ${wide}px wider than a 320px screen, so it needs horizontal scrolling`, hint: "let content reflow to one column at 320px (WCAG 1.4.10); wide tables and code blocks may scroll inside their own container", loc: at0, wcag: "1.4.10" }] : [];
   return [...out, ...onlyNew(base, await audit(page, axePath, url)).map((f) => inState("reflow", url, f))];
 }
-async function scan(url, cwd = process.cwd(), states = [], modes = []) {
+var baselinePath = (cwd) => join8(cwd, "fringe.scan.baseline.json");
+var scanKey = (f) => `${f.rule}|${f.loc.file}|${f.message.split(": ")[0]}`;
+function applyScanBaseline(cwd, findings) {
+  if (!existsSync2(baselinePath(cwd))) return { fresh: findings, known: 0 };
+  let keys;
+  try {
+    keys = JSON.parse(readFileSync8(baselinePath(cwd), "utf8"));
+    if (!Array.isArray(keys)) throw 0;
+  } catch {
+    throw new Error("fringe.scan.baseline.json is not a JSON array: rerun with --update-baseline");
+  }
+  const left = /* @__PURE__ */ new Map();
+  for (const k of keys) left.set(k, (left.get(k) ?? 0) + 1);
+  const fresh = findings.filter((f) => {
+    const k = scanKey(f), n = left.get(k) ?? 0;
+    if (n > 0) {
+      left.set(k, n - 1);
+      return false;
+    }
+    return true;
+  });
+  return { fresh, known: findings.length - fresh.length };
+}
+var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "page";
+var LOGINISH = /log-?in|sign-?in|sso|auth/i;
+var firstLine = (e) => String(e.message).split("\n")[0].slice(0, 120);
+async function loginRedirect(page, requested, who) {
+  let now, want;
+  try {
+    now = new URL(page.url());
+    want = new URL(requested);
+  } catch {
+    return [];
+  }
+  if (now.pathname === want.pathname) return [];
+  const hasPassword = await page.evaluate(() => !!document.querySelector("input[type=password]"));
+  if (!LOGINISH.test(now.pathname) && !hasPassword) return [];
+  return [{ rule: "FR-405", severity: "review", message: `the scan was sent to ${now.pathname}, which looks like a login page: ${who ? `the "${who}" session may have expired or the login failed` : "this page needs a login"}`, hint: 'save a session with `fringe login <url>` or add a "login" block to fringe.scan.json; findings for this page describe the login screen, not your app', loc: { file: requested, line: 1, col: 0 } }];
+}
+async function auditContext(context, axePath, url, opts, who, shot) {
+  const { states = [], modes = [] } = opts;
+  const page = await context.newPage();
+  await page.goto(url, { waitUntil: "load", timeout: 3e4 });
+  await shot(page, "initial");
+  const all = [...await loginRedirect(page, url, who), ...await audit(page, axePath, url)];
+  const plain = [...all];
+  for (const st of states) {
+    await page.goto(url, { waitUntil: "load", timeout: 3e4 });
+    let step = 0;
+    try {
+      for (; step < st.steps.length; step++) await runStep(page, st.steps[step], url);
+    } catch (e) {
+      all.push({ rule: "FR-402", severity: "review", message: `[${st.name}] state could not be reached: step ${step + 1} ${JSON.stringify(st.steps[step])} failed (${firstLine(e)})`, hint: "fix the step in fringe.scan.json or the page; nothing in this state was audited", loc: { file: `${url} [${st.name}]`, line: 1, col: 0 } });
+      continue;
+    }
+    await shot(page, `state-${st.name}`);
+    all.push(...(await audit(page, axePath, url)).map((f) => inState(st.name, url, f)));
+  }
+  for (const m of modes) all.push(...await stress(context, axePath, url, m, plain, shot));
+  return all;
+}
+async function scan(url, cwd = process.cwd(), opts = {}) {
+  const { states = [], modes = [] } = opts;
   if (!/^(https?|file):\/\//i.test(url)) throw new Error(`fringe scan takes an http(s):// or file:// URL, got '${url}'`);
+  const sessions = opts.sessions?.length ? opts.sessions : [opts.storageState ? { storageState: opts.storageState } : {}];
+  for (const n of /* @__PURE__ */ new Set([...sessions.flatMap((s) => envNames(s.login?.steps ?? [])), ...states.flatMap((s) => envNames(s.steps))])) {
+    if (process.env[n] === void 0) throw new Error(`environment variable ${n} is not set (named in fringe.scan.json)`);
+  }
+  for (const s of sessions) if (s.storageState && !existsSync2(s.storageState)) throw new Error(`storage state file not found: ${s.storageState} (create one with: fringe login ${url})`);
   const req = createRequire(join8(cwd, "noop.js"));
   let playwright, axePath;
   try {
@@ -1744,26 +1845,46 @@ async function scan(url, cwd = process.cwd(), states = [], modes = []) {
     }
   }
   try {
-    const page = await browser.newPage();
-    await page.goto(url, { waitUntil: "load", timeout: 3e4 });
-    const all = await audit(page, axePath, url);
-    const plain = [...all];
-    for (const st of states) {
-      await page.goto(url, { waitUntil: "load", timeout: 3e4 });
-      let step = 0;
+    const all = [];
+    for (const s of sessions) {
+      const who = s.name, label = who ? `as ${who}` : void 0;
+      const shot = async (page, name) => {
+        if (!opts.screenshots) return;
+        mkdirSync3(opts.screenshots, { recursive: true });
+        await page.screenshot({ path: join8(opts.screenshots, `${slug(who ? `${who}-${name}` : name)}.png`), fullPage: true });
+      };
+      const context = await browser.newContext(s.storageState ? { storageState: s.storageState } : {});
       try {
-        for (; step < st.steps.length; step++) await runStep(page, st.steps[step], url);
-      } catch (e) {
-        all.push({ rule: "FR-402", severity: "review", message: `[${st.name}] state could not be reached: step ${step + 1} ${JSON.stringify(st.steps[step])} failed (${String(e.message).split("\n")[0].slice(0, 120)})`, hint: "fix the step in fringe.scan.json or the page; nothing in this state was audited", loc: { file: `${url} [${st.name}]`, line: 1, col: 0 } });
-        continue;
+        let found;
+        if (s.login) {
+          const lp = await context.newPage();
+          let step = 0;
+          try {
+            await lp.goto(new URL(s.login.url ?? url, url).href, { waitUntil: "load", timeout: 3e4 });
+            for (; step < s.login.steps.length; step++) await runStep(lp, s.login.steps[step], url);
+            found = await auditContext(context, axePath, url, opts, who, shot);
+          } catch (e) {
+            found = [{ rule: "FR-402", severity: "review", message: `login${who ? ` as ${who}` : ""} failed at step ${step + 1} ${JSON.stringify(s.login.steps[step] ?? {})} (${firstLine(e)})`, hint: "check the login steps and selectors in fringe.scan.json; nothing was scanned for this session", loc: { file: url, line: 1, col: 0 } }];
+          } finally {
+            await lp.close().catch(() => {
+            });
+          }
+        } else found = await auditContext(context, axePath, url, opts, who, shot);
+        all.push(...label ? found.map((f) => inState(label, url, f)) : found);
+      } finally {
+        await context.close();
       }
-      all.push(...(await audit(page, axePath, url)).map((f) => inState(st.name, url, f)));
     }
-    for (const m of modes) all.push(...await stress(browser, axePath, url, m, plain));
-    const { findings, clusters } = rankScan(url, all);
+    const files = sessions.length * (1 + states.length + modes.length);
+    if (opts.updateBaseline) {
+      writeFileSync3(baselinePath(cwd), JSON.stringify(all.map(scanKey).sort(), null, 2) + "\n");
+      return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files, skipped: [], findings: [], clusters: [], counts: { error: 0, review: 0, signal: 0 }, score: 100, baselined: all.length };
+    }
+    const { fresh, known } = applyScanBaseline(cwd, all);
+    const { findings, clusters } = rankScan(url, fresh);
     const counts = { error: 0, review: 0, signal: 0 };
     for (const f of findings) counts[f.severity]++;
-    return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files: 1 + states.length + modes.length, skipped: [], findings, clusters, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1) };
+    return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files, skipped: [], findings, clusters, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1), ...known ? { baselined: known } : {} };
   } finally {
     await browser.close();
   }
@@ -1784,22 +1905,74 @@ function rankScan(url, findings) {
 }
 function mergeScan(base, scanned, weights) {
   const counts = { error: base.counts.error + scanned.counts.error, review: base.counts.review + scanned.counts.review, signal: base.counts.signal + scanned.counts.signal };
-  return { ...base, findings: [...base.findings, ...scanned.findings], clusters: [...base.clusters ?? [], ...scanned.clusters ?? []].sort((a, b) => b.priority - a.priority), counts, score: score(counts, weights, base.files) };
+  return { ...base, findings: [...base.findings, ...scanned.findings], clusters: [...base.clusters ?? [], ...scanned.clusters ?? []].sort((a, b) => b.priority - a.priority), counts, score: score(counts, weights, base.files), ...(base.baselined ?? 0) + (scanned.baselined ?? 0) ? { baselined: (base.baselined ?? 0) + (scanned.baselined ?? 0) } : {} };
 }
 
-// src/init.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync3, writeFileSync as writeFileSync3, copyFileSync } from "fs";
+// src/login.ts
+import { createRequire as createRequire2 } from "module";
+import { mkdirSync as mkdirSync4 } from "fs";
 import { dirname, join as join9 } from "path";
+import { createInterface } from "readline";
+async function saveSession(url, cwd, out, o = {}) {
+  if (!/^https?:\/\//i.test(url)) throw new Error(`fringe login takes an http(s):// URL, got '${url}'`);
+  const req = createRequire2(join9(cwd, "noop.js"));
+  let playwright;
+  try {
+    playwright = req("playwright-core");
+  } catch {
+    throw new Error(SCAN_HELP);
+  }
+  let browser;
+  const headless = o.headless ?? false;
+  try {
+    browser = await playwright.chromium.launch({ channel: "chrome", headless });
+  } catch {
+    try {
+      browser = await playwright.chromium.launch({ headless });
+    } catch {
+      throw new Error(SCAN_HELP);
+    }
+  }
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: "load", timeout: 6e4 });
+    if (o.wait) await o.wait();
+    else {
+      process.stderr.write("fringe: log in in the browser window, then come back here and press Enter. Close the window afterwards, not before.\n");
+      await new Promise((ok, fail) => {
+        const rl = createInterface({ input: process.stdin });
+        rl.once("line", () => {
+          rl.close();
+          ok();
+        });
+        browser.once("disconnected", () => {
+          rl.close();
+          fail(new Error("the browser was closed before the session was saved: press Enter in this terminal first, then close the window"));
+        });
+      });
+    }
+    mkdirSync4(dirname(out), { recursive: true });
+    await context.storageState({ path: out });
+  } finally {
+    await browser.close().catch(() => {
+    });
+  }
+}
+
+// src/init.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync9, readdirSync as readdirSync3, writeFileSync as writeFileSync4, copyFileSync } from "fs";
+import { dirname as dirname2, join as join10 } from "path";
 import { fileURLToPath } from "url";
 var HOOK = "npx -y @fringetools/cli check --claude-hook";
 var SKILL_DIR = fileURLToPath(new URL("../skill/", import.meta.url));
 function hookCommand(root) {
-  return existsSync2(join9(root, "node_modules", "@fringetools", "cli", "package.json")) ? "npx --no-install fringe check --claude-hook" : HOOK;
+  return existsSync3(join10(root, "node_modules", "@fringetools", "cli", "package.json")) ? "npx --no-install fringe check --claude-hook" : HOOK;
 }
 function isWired(root, home) {
   for (const dir of [root, home]) {
     try {
-      if (/claude-hook|fringe(tool)?@/.test(readFileSync8(join9(dir, ".claude", "settings.json"), "utf8"))) return true;
+      if (/claude-hook|fringe(tool)?@/.test(readFileSync9(join10(dir, ".claude", "settings.json"), "utf8"))) return true;
     } catch {
     }
   }
@@ -1807,11 +1980,11 @@ function isWired(root, home) {
 }
 function initProject(root) {
   const done = [];
-  const settingsPath = join9(root, ".claude", "settings.json");
+  const settingsPath = join10(root, ".claude", "settings.json");
   let settings = {};
-  if (existsSync2(settingsPath)) {
+  if (existsSync3(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync8(settingsPath, "utf8"));
+      settings = JSON.parse(readFileSync9(settingsPath, "utf8"));
     } catch {
       throw new Error(`${settingsPath} is not valid JSON \u2014 fix it and rerun`);
     }
@@ -1820,21 +1993,93 @@ function initProject(root) {
   if (/(fringe|@fringetools\/cli) check/.test(JSON.stringify(post))) done.push("hook already present");
   else {
     post.push({ matcher: "Edit|Write", hooks: [{ type: "command", command: hookCommand(root) }] });
-    mkdirSync3(dirname(settingsPath), { recursive: true });
-    writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    mkdirSync5(dirname2(settingsPath), { recursive: true });
+    writeFileSync4(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     done.push(`hook added to ${settingsPath}`);
   }
   for (const name of readdirSync3(SKILL_DIR)) {
-    const skillPath = join9(root, ".claude", "skills", name, "SKILL.md");
-    if (existsSync2(skillPath)) done.push(`skill ${name} already present`);
+    const skillPath = join10(root, ".claude", "skills", name, "SKILL.md");
+    if (existsSync3(skillPath)) done.push(`skill ${name} already present`);
     else {
-      mkdirSync3(dirname(skillPath), { recursive: true });
-      copyFileSync(join9(SKILL_DIR, name, "SKILL.md"), skillPath);
+      mkdirSync5(dirname2(skillPath), { recursive: true });
+      copyFileSync(join10(SKILL_DIR, name, "SKILL.md"), skillPath);
       done.push(`skill ${name} installed`);
     }
   }
   return done;
 }
+var RULES_FILE = fileURLToPath(new URL("../rules/fringe.md", import.meta.url));
+var AGENT_FILES = {
+  codex: { path: "AGENTS.md" },
+  generic: { path: "AGENTS.md" },
+  amp: { path: "AGENTS.md" },
+  jules: { path: "AGENTS.md" },
+  zed: { path: "AGENTS.md" },
+  gemini: { path: "GEMINI.md" },
+  cursor: { path: ".cursor/rules/fringe.mdc", wrap: (b) => `---
+description: Fringe: check and fix UX/accessibility problems after editing frontend files
+alwaysApply: true
+---
+
+${b}` },
+  copilot: { path: ".github/copilot-instructions.md" },
+  windsurf: { path: ".windsurf/rules/fringe.md" },
+  cline: { path: ".clinerules/fringe.md" },
+  kiro: { path: ".kiro/steering/fringe.md" }
+};
+var AGENTS = Object.keys(AGENT_FILES);
+var MARK2 = "<!-- fringe:rules -->";
+function initFor(root, agents) {
+  const body = readFileSync9(RULES_FILE, "utf8");
+  const done = [];
+  for (const a of agents) {
+    const spec = AGENT_FILES[a];
+    if (!spec) throw new Error(`unknown agent '${a}': use ${AGENTS.join(", ")} (or 'claude' for the hook + skills)`);
+    const file2 = join10(root, spec.path);
+    const text = spec.wrap ? spec.wrap(body) : body;
+    if (existsSync3(file2)) {
+      const cur = readFileSync9(file2, "utf8");
+      if (cur.includes(MARK2) || cur.includes("# Fringe: handle your edges")) {
+        done.push(`${spec.path} already has the Fringe rules`);
+        continue;
+      }
+      writeFileSync4(file2, `${cur.replace(/\n*$/, "\n")}
+${MARK2}
+${spec.wrap ? body : text}`);
+      done.push(`rules appended to ${spec.path}`);
+    } else {
+      mkdirSync5(dirname2(file2), { recursive: true });
+      writeFileSync4(file2, text.replace("# Fringe: handle your edges", `${MARK2}
+# Fringe: handle your edges`));
+      done.push(`${spec.path} created`);
+    }
+  }
+  return done;
+}
+function initGit(root) {
+  const dir = join10(root, ".git", "hooks");
+  if (!existsSync3(join10(root, ".git"))) throw new Error("not a git repository (no .git here)");
+  const file2 = join10(dir, "pre-commit");
+  const local = existsSync3(join10(root, "node_modules", "@fringetools", "cli", "package.json"));
+  const cmd = local ? "npx --no-install fringe check" : "npx -y @fringetools/cli check";
+  const script = `#!/bin/sh
+# fringe pre-commit: blocks the commit while error-level UX/accessibility problems remain
+out=$(${cmd} 2>&1); code=$?
+printf '%s\\n' "$out"
+if [ "$code" -eq 1 ] && printf '%s' "$out" | grep -q '^\\[ERROR\\]'; then
+  echo "fringe: fix the errors above (or record them with: fringe check --update-baseline) and commit again." >&2
+  exit 1
+fi
+exit 0
+`;
+  if (existsSync3(file2)) {
+    if (readFileSync9(file2, "utf8").includes("# fringe pre-commit")) return ["pre-commit hook already present"];
+    throw new Error(`${file2} already exists and is not Fringe's: add 'npx -y @fringetools/cli check || exit 1' to it yourself`);
+  }
+  mkdirSync5(dir, { recursive: true });
+  writeFileSync4(file2, script, { mode: 493 });
+  return [`pre-commit hook installed at ${file2}`];
+}
 
 // src/index.ts
 import { homedir } from "os";
@@ -1962,13 +2207,143 @@ After each batch, verify: \`fringe check ${target}\``);
   return out.join("\n");
 }
 
+// src/rulereport.ts
+import { existsSync as existsSync4, readFileSync as readFileSync10 } from "fs";
+import { join as join11 } from "path";
+async function ruleReport(root) {
+  const cfg = loadConfig(root);
+  const result = await runCheck(root, cfg, false);
+  const baselinedBy = /* @__PURE__ */ new Map();
+  const bl = join11(root, "fringe.baseline.json");
+  if (existsSync4(bl)) {
+    try {
+      for (const k of JSON.parse(readFileSync10(bl, "utf8"))) baselinedBy.set(k.split("|")[0], (baselinedBy.get(k.split("|")[0]) ?? 0) + 1);
+    } catch {
+    }
+  }
+  const silencedBy = /* @__PURE__ */ new Map();
+  for (const f of walk(root, cfg)) {
+    let src = "";
+    try {
+      src = readFileSync10(f, "utf8");
+    } catch {
+      continue;
+    }
+    for (const m of src.matchAll(/fringe-ignore\s+((?:FR-\d+[\s,]*)+)/g)) for (const id of m[1].match(/FR-\d+/g) ?? []) silencedBy.set(id, (silencedBy.get(id) ?? 0) + 1);
+  }
+  const rawBy = /* @__PURE__ */ new Map();
+  for (const f of result.findings) rawBy.set(f.rule, (rawBy.get(f.rule) ?? 0) + 1);
+  const { records } = readLedger(root);
+  const first = records[0]?.byRule, last = records[records.length - 1]?.byRule;
+  return ALL_RULES.map((r) => {
+    const baselined = Math.min(baselinedBy.get(r.id) ?? 0, rawBy.get(r.id) ?? 0), silenced = silencedBy.get(r.id) ?? 0;
+    const open = (rawBy.get(r.id) ?? 0) - baselined;
+    const trend = records.length >= 2 && first && last ? `${first[r.id] ?? 0} -> ${last[r.id] ?? 0}` : void 0;
+    return { rule: r.id, severity: r.severity, open, baselined, silenced, overridden: baselined + silenced, ...trend ? { trend } : {} };
+  }).filter((x) => x.open + x.baselined + x.silenced > 0).sort((a, b) => b.overridden - a.overridden || b.open - a.open);
+}
+function rulesToText(rows) {
+  if (rows.length === 0) return "No findings, baselined entries or suppressions: nothing to report per rule.";
+  const hasTrend = rows.some((r) => r.trend);
+  const head = ["rule", "severity", "open", "baselined", "silenced", ...hasTrend ? ["ledger trend"] : []];
+  const body = rows.map((r) => [r.rule, r.severity, String(r.open), String(r.baselined), String(r.silenced), ...hasTrend ? [r.trend ?? "-"] : []]);
+  const w = head.map((h, i) => Math.max(h.length, ...body.map((b) => b[i].length)));
+  const line = (c) => c.map((x, i) => x.padEnd(w[i])).join("  ").trimEnd();
+  const noisy = rows.filter((r) => r.overridden >= 5 && r.overridden / (r.open + r.overridden) >= 0.5);
+  return [
+    line(head),
+    ...body.map(line),
+    ...noisy.length ? ["", `Mostly overridden here (${noisy.map((r) => r.rule).join(", ")}): the rule may not suit this repo. Check a few silenced cases; if they are wrong findings, disable the rule in fringe.config.json or report a false positive.`] : []
+  ].join("\n");
+}
+
+// src/handoff.ts
+import { relative as relative5 } from "path";
+var fp = (root, f) => `${f.rule}|${f.loc.file.startsWith("/") ? relative5(root, f.loc.file) : f.loc.file}|${f.message}`;
+var where = (root, f) => `${f.loc.file.startsWith("/") ? relative5(root, f.loc.file) : f.loc.file}${f.loc.line > 1 || !f.target ? `:${f.loc.line}` : ""}${f.target ? ` ${f.target}` : ""}`;
+var RULES = [
+  "Fix the problems in the order given. Re-run `fringe verify` after each batch; stop only when it says `status: complete`.",
+  "Do not change the visual design or behavior; fix the underlying problem (labels, names, contrast, focus), not the symptom.",
+  "Do not silence a rule to get green. A `fringe-ignore FR-xxx` comment is only for a genuine false positive; list every one you add, with the reason, in your final message. `verify` reports how many were added.",
+  "Prefer fixing a shared component once over its many uses.",
+  "If a finding needs a design or content decision you cannot make, leave it and say so in your final message instead of guessing."
+];
+function buildHandoff(result, meta, limit = 15) {
+  const batches = buildPlan(result, limit);
+  const verifyCmd = "fringe verify";
+  const prompt = [
+    "# Fix the UX problems Fringe found",
+    "",
+    `You are taking over from another agent or a CI job. Fringe found ${result.counts.error} error(s), ${result.counts.review} review item(s) and ${result.counts.signal} polish item(s) in \`${meta.target}\` (health ${result.score}/100).`,
+    "Your goal: no errors left, and nothing new introduced.",
+    "",
+    "## Rules",
+    ...RULES.map((r) => `- ${r}`),
+    "",
+    "## Definition of done",
+    "Commands: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place.",
+    `Run \`${verifyCmd}\` (it re-checks everything this hand-off covers). You are done when it prints \`status: complete\` and exits 0. If it prints \`regressed\`, you broke something: fix what it lists as introduced first.`,
+    "",
+    toPlanMarkdown(result, meta.target, limit).replace(/^# Fringe fix plan\n\n/, "## The work\n\n")
+  ].join("\n");
+  return {
+    schema: "fringe/handoff.v1",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    root: meta.root,
+    target: meta.target,
+    ...meta.only ? { only: meta.only } : {},
+    ...meta.scan ? { scan: meta.scan } : {},
+    score: result.score,
+    counts: result.counts,
+    suppressed: result.suppressed ?? 0,
+    fingerprints: result.findings.map((f) => fp(meta.root, f)),
+    batches,
+    prompt
+  };
+}
+function verifyHandoff(h, now) {
+  const left = /* @__PURE__ */ new Map();
+  for (const k of h.fingerprints) left.set(k, (left.get(k) ?? 0) + 1);
+  const introduced = [];
+  const remaining = [];
+  for (const f of now.findings) {
+    const k = fp(h.root, f), n = left.get(k) ?? 0;
+    if (n > 0) {
+      left.set(k, n - 1);
+      remaining.push(f);
+    } else introduced.push(f);
+  }
+  const errs = (fs) => fs.filter((f) => f.severity === "error");
+  const row = (f) => ({ rule: f.rule, where: where(h.root, f), message: f.message });
+  const remainingErrors = errs(remaining).length, introducedErrors = errs(introduced).length;
+  return {
+    schema: "fringe/verify.v1",
+    status: introducedErrors > 0 ? "regressed" : remainingErrors === 0 ? "complete" : "partial",
+    score: { before: h.score, after: now.score },
+    errors: { before: h.counts.error, fixed: h.counts.error - remainingErrors, remaining: remainingErrors, introduced: introducedErrors },
+    review: { remaining: remaining.filter((f) => f.severity === "review").length, introduced: introduced.filter((f) => f.severity === "review").length },
+    introduced: introduced.filter((f) => f.severity !== "signal").map(row).slice(0, 20),
+    remaining: errs(remaining).map(row).slice(0, 20),
+    newSuppressions: Math.max(0, (now.suppressed ?? 0) - h.suppressed)
+  };
+}
+function verifyToMarkdown(v) {
+  const out = [`status: ${v.status}`, `health ${v.score.before} -> ${v.score.after}`, `errors: ${v.errors.fixed} of ${v.errors.before} fixed, ${v.errors.remaining} remaining, ${v.errors.introduced} introduced`];
+  if (v.review.introduced) out.push(`review items introduced: ${v.review.introduced}`);
+  if (v.introduced.length) out.push("", "Introduced since the hand-off (fix these first):", ...v.introduced.map((x) => `- ${x.rule} ${x.where}: ${x.message}`));
+  if (v.remaining.length) out.push("", "Errors still to fix:", ...v.remaining.slice(0, 10).map((x) => `- ${x.rule} ${x.where}: ${x.message}`), ...v.remaining.length > 10 ? [`- \u2026and ${v.remaining.length - 10} more`] : []);
+  if (v.newSuppressions) out.push("", `Needs human review: ${v.newSuppressions} finding(s) were silenced with fringe-ignore since the hand-off.`);
+  return out.join("\n");
+}
+
 // src/index.ts
+import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "fs";
 var log = (o) => o.log ?? ((s) => console.log(s));
 var err = (o) => o.err ?? ((s) => process.stderr.write(s));
 function readManifest(path2, warn) {
   let raw;
   try {
-    raw = readFileSync9(path2, "utf8");
+    raw = readFileSync11(path2, "utf8");
   } catch {
     warn(`fringe: warning: manifest not found at ${path2} \u2014 continuing without
 `);
@@ -1993,27 +2368,39 @@ function readManifest(path2, warn) {
 }
 function resolveTarget(arg) {
   if (!statSync(arg).isFile()) return { root: arg };
-  let dir = dirname2(arg);
-  for (let d = dir, i = 0; i < 12; i++, d = dirname2(d)) {
-    if (existsSync3(join10(d, "package.json")) || existsSync3(join10(d, "fringe.config.json"))) {
+  let dir = dirname3(arg);
+  for (let d = dir, i = 0; i < 12; i++, d = dirname3(d)) {
+    if (existsSync5(join12(d, "package.json")) || existsSync5(join12(d, "fringe.config.json"))) {
       dir = d;
       break;
     }
-    if (dirname2(d) === d) break;
+    if (dirname3(d) === d) break;
   }
   return { root: dir, only: /* @__PURE__ */ new Set([arg]) };
 }
-function loadStates(cwd, rest) {
-  const i = rest.indexOf("--states");
-  const file2 = i !== -1 ? resolve(cwd, rest[i + 1] ?? "") : join10(cwd, "fringe.scan.json");
-  if (i === -1 && !existsSync3(file2)) return [];
-  let raw;
-  try {
-    raw = JSON.parse(readFileSync9(file2, "utf8"));
-  } catch (e) {
-    throw new Error(`${file2}: ${e.message}`);
+function loadScanOptions(cwd, rest) {
+  const flag = (n) => {
+    const i = rest.indexOf(n);
+    return i === -1 ? void 0 : rest[i + 1];
+  };
+  const si = rest.indexOf("--states");
+  const file2 = si !== -1 ? resolve(cwd, rest[si + 1] ?? "") : join12(cwd, "fringe.scan.json");
+  let states = [];
+  let sessions;
+  const storageFlag = flag("--storage-state") ? resolve(cwd, flag("--storage-state")) : void 0;
+  if (si !== -1 || existsSync5(file2)) {
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync11(file2, "utf8"));
+    } catch (e) {
+      throw new Error(`${file2}: ${e.message}`);
+    }
+    states = parseStates(raw);
+    const parsed = parseSessions(raw, dirname3(file2));
+    if (parsed.length) sessions = parsed;
   }
-  return parseStates(raw);
+  const shots = flag("--screenshots");
+  return { states, modes: loadModes(rest), ...storageFlag ? { storageState: storageFlag } : sessions ? { sessions } : {}, ...shots ? { screenshots: resolve(cwd, shots) } : {}, ...rest.includes("--update-baseline") ? { updateBaseline: true } : {} };
 }
 function loadModes(rest) {
   const i = rest.indexOf("--modes");
@@ -2023,11 +2410,17 @@ var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\
 var HELP = `fringe check [--json] [--hook] [--record] [--manifest <path>] [path]
 fringe check --claude-hook [path]       for Claude Code hooks (feeds errors back to the agent)
 fringe check --update-baseline [path]   accept today's findings; only new ones gate
-fringe scan <url> [--states f] [--stress | --modes dark,reduced,reflow] [--json]               runtime check in a real browser (axe-core + keyboard walk); needs playwright-core and axe-core
+fringe login <url> [--out auth.json]     log in once in a browser window and save the session for scans
+fringe scan <url> [--states f] [--stress | --modes ...] [--storage-state auth.json] [--screenshots dir] [--update-baseline] [--json]               runtime check in a real browser (axe-core + keyboard walk); needs playwright-core and axe-core
+fringe rules [dir] [--json]               per rule: open / baselined / silenced, to spot rules that don't suit this repo
+fringe handoff [dir|file] [--scan url]    a work order for another agent or CI (saved to .fringe/handoff.json)
+fringe verify [--handoff file]             did the receiving agent finish? exit 0 only when complete
 fringe plan [dir|file] [--scan url] [--json] [--limit n]   ordered fix batches with recipes; --scan adds the live page
 fringe explain pattern [form]           best-practice checklist for a component type
 fringe explain [FR-203]                 why a rule matters and how to fix it well
 fringe init [path] [--global]          add the Claude Code hook + skills (--global: every project)
+fringe init --for cursor,codex,...     write the rules file other agents read (cursor, codex, gemini, copilot, windsurf, cline, kiro, generic)
+fringe init --git                      pre-commit gate for any agent that commits
 fringe open [path] [--port <n>]   serve the .fringe ledger on 127.0.0.1
 fringe --help | --version`;
 var KNOWN_FLAGS = /* @__PURE__ */ new Set(["--json", "--hook", "--claude-hook", "--record", "--manifest", "--update-baseline"]);
@@ -2048,6 +2441,28 @@ function parseArgs(rest, warn) {
   }
   return paths;
 }
+async function gather(opts, rest) {
+  const si = rest.indexOf("--scan");
+  const scanUrl = si !== -1 ? rest[si + 1] : void 0;
+  if (si !== -1 && (!scanUrl || scanUrl.startsWith("--"))) throw new Error("--scan needs a URL, e.g. fringe plan --scan http://localhost:3000");
+  const li = rest.indexOf("--limit");
+  const limit = li !== -1 ? Number(rest[li + 1]) || void 0 : void 0;
+  const valued = /* @__PURE__ */ new Set(["--limit", "--scan", "--states", "--modes", "--out", "--storage-state", "--screenshots"]);
+  const flags = /* @__PURE__ */ new Set(["--json", "--stress"]);
+  const paths = parseArgs(rest.filter((a, i) => !valued.has(a) && !valued.has(rest[i - 1]) && !flags.has(a)), (s) => process.stderr.write(s));
+  const cwd = opts.cwd ?? process.cwd();
+  const { root, only } = resolveTarget(resolve(cwd, paths[0] ?? "."));
+  const cfg = loadConfig(root);
+  let result = await runCheck(root, cfg, true, only);
+  let scanMeta;
+  if (scanUrl) {
+    result = mergeScan(result, await scan(scanUrl, cwd, loadScanOptions(cwd, rest)), cfg.weights);
+    const sf = rest.indexOf("--states");
+    const so = loadScanOptions(cwd, rest);
+    scanMeta = { url: scanUrl, ...sf !== -1 ? { statesFile: resolve(cwd, rest[sf + 1]) } : {}, modes: so.modes ?? [], ...so.storageState ? { storageState: so.storageState } : {} };
+  }
+  return { result, root, target: paths[0] ?? ".", only: only ? [...only][0] : void 0, limit, scan: scanMeta };
+}
 async function runCli(argv, opts = {}) {
   const [cmd, ...rest] = argv;
   if (cmd === void 0) {
@@ -2105,13 +2520,20 @@ async function runCli(argv, opts = {}) {
   }
   if (cmd === "scan") {
     try {
-      const url = rest.find((a, i) => !a.startsWith("--") && rest[i - 1] !== "--states" && rest[i - 1] !== "--modes");
+      const url = rest.find((a, i) => !a.startsWith("--") && !["--states", "--modes", "--storage-state", "--screenshots"].includes(rest[i - 1]));
       if (!url) {
         err(opts)("fringe: scan needs a URL, e.g. fringe scan http://localhost:3000\n");
         return 2;
       }
       const cwd = opts.cwd ?? process.cwd();
-      const result = await scan(url, cwd, loadStates(cwd, rest), loadModes(rest));
+      const so = loadScanOptions(cwd, rest);
+      const result = await scan(url, cwd, so);
+      if (so.updateBaseline) {
+        log(opts)(`fringe: scan baseline written: ${result.baselined ?? 0} known findings in fringe.scan.baseline.json (commit it); only new ones show from now on`);
+        return 0;
+      }
+      if (so.screenshots) err(opts)(`fringe: screenshots saved in ${so.screenshots}
+`);
       log(opts)(rest.includes("--json") ? toJson(result) : toPretty(result));
       return result.counts.error > 0 ? 1 : 0;
     } catch (e) {
@@ -2120,29 +2542,80 @@ async function runCli(argv, opts = {}) {
       return 2;
     }
   }
-  if (cmd === "plan") {
+  if (cmd === "login") {
     try {
-      const si = rest.indexOf("--scan");
-      const scanUrl = si !== -1 ? rest[si + 1] : void 0;
-      if (si !== -1 && (!scanUrl || scanUrl.startsWith("--"))) {
-        err(opts)("fringe: --scan needs a URL, e.g. fringe plan --scan http://localhost:3000\n");
+      const url = rest.find((a, i) => !a.startsWith("--") && rest[i - 1] !== "--out");
+      if (!url) {
+        err(opts)("fringe: login needs a URL, e.g. fringe login http://localhost:3000/login\n");
         return 2;
       }
-      const li = rest.indexOf("--limit");
-      const limit = li !== -1 ? Number(rest[li + 1]) || void 0 : void 0;
-      const paths = parseArgs(rest.filter((a, i) => a !== "--limit" && rest[i - 1] !== "--limit" && a !== "--json" && a !== "--scan" && rest[i - 1] !== "--scan" && a !== "--states" && rest[i - 1] !== "--states" && a !== "--stress" && a !== "--modes" && rest[i - 1] !== "--modes"), err(opts));
-      const arg = resolve(opts.cwd ?? process.cwd(), paths[0] ?? ".");
-      const { root, only } = resolveTarget(arg);
-      const cfg = loadConfig(root);
-      let result = await runCheck(root, cfg, true, only);
-      if (scanUrl) {
-        const cwd = opts.cwd ?? process.cwd();
-        result = mergeScan(result, await scan(scanUrl, cwd, loadStates(cwd, rest), loadModes(rest)), cfg.weights);
+      const cwd = opts.cwd ?? process.cwd();
+      const oi = rest.indexOf("--out");
+      const out = resolve(cwd, oi !== -1 ? rest[oi + 1] ?? "" : ".fringe/auth.json");
+      await saveSession(url, cwd, out, { headless: rest.includes("--headless"), wait: opts.waitForUser });
+      log(opts)(`fringe: session saved to ${out}
+It holds your logged-in cookies: keep it out of git. Use it with: fringe scan <url> --storage-state ${oi !== -1 ? rest[oi + 1] : ".fringe/auth.json"}`);
+      if (oi === -1 && existsSync5(join12(cwd, ".gitignore")) && !/\.fringe/.test(readFileSync11(join12(cwd, ".gitignore"), "utf8"))) log(opts)("fringe: your .gitignore does not list .fringe/: add it, or the session file could be committed.");
+      return 0;
+    } catch (e) {
+      err(opts)(`fringe: ${e.message}
+`);
+      return 2;
+    }
+  }
+  if (cmd === "rules") {
+    try {
+      const root = resolve(opts.cwd ?? process.cwd(), rest.find((a) => !a.startsWith("--")) ?? ".");
+      const rows = await ruleReport(root);
+      log(opts)(rest.includes("--json") ? JSON.stringify({ schema: "fringe/rules.v1", rules: rows }, null, 2) : rulesToText(rows));
+      return 0;
+    } catch (e) {
+      err(opts)(`fringe: ${e.message}
+`);
+      return 2;
+    }
+  }
+  if (cmd === "plan" || cmd === "handoff") {
+    try {
+      const g = await gather(opts, rest);
+      if (cmd === "plan") {
+        log(opts)(rest.includes("--json") ? toPlanJson(g.result, g.limit) : toPlanMarkdown(g.result, g.target, g.limit));
+        return 0;
       }
-      log(opts)(rest.includes("--json") ? toPlanJson(result, limit) : toPlanMarkdown(result, paths[0] ?? ".", limit));
+      const h = buildHandoff(g.result, { root: g.root, target: g.target, ...g.only ? { only: g.only } : {}, ...g.scan ? { scan: g.scan } : {} }, g.limit);
+      const oi = rest.indexOf("--out");
+      const outFile = resolve(g.root, oi !== -1 ? rest[oi + 1] ?? "" : ".fringe/handoff.json");
+      mkdirSync6(dirname3(outFile), { recursive: true });
+      writeFileSync5(outFile, JSON.stringify(h, null, 2) + "\n");
+      log(opts)(rest.includes("--json") ? JSON.stringify(h, null, 2) : h.prompt);
+      err(opts)(`fringe: hand-off saved to ${outFile}; the receiving agent proves it is done with: fringe verify${oi !== -1 ? ` --handoff ${outFile}` : ""}
+`);
       return 0;
     } catch (e) {
-      err(opts)(`fringe: internal error: ${e.message}
+      err(opts)(`fringe: ${e.message}
+`);
+      return 2;
+    }
+  }
+  if (cmd === "verify") {
+    try {
+      const hi = rest.indexOf("--handoff");
+      const file2 = resolve(opts.cwd ?? process.cwd(), hi !== -1 ? rest[hi + 1] ?? "" : ".fringe/handoff.json");
+      let h;
+      try {
+        h = JSON.parse(readFileSync11(file2, "utf8"));
+      } catch {
+        throw new Error(`no readable hand-off at ${file2} \u2014 run 'fringe handoff' first`);
+      }
+      if (h.schema !== "fringe/handoff.v1") throw new Error(`${file2} is not a fringe/handoff.v1 file`);
+      const cfg = loadConfig(h.root);
+      let result = await runCheck(h.root, cfg, true, h.only ? /* @__PURE__ */ new Set([h.only]) : void 0);
+      if (h.scan) result = mergeScan(result, await scan(h.scan.url, h.root, { ...loadScanOptions(h.root, h.scan.statesFile ? ["--states", h.scan.statesFile] : []), modes: h.scan.modes, ...h.scan.storageState ? { storageState: h.scan.storageState } : {} }), cfg.weights);
+      const v = verifyHandoff(h, result);
+      log(opts)(rest.includes("--json") ? JSON.stringify(v, null, 2) : verifyToMarkdown(v));
+      return v.status === "complete" ? 0 : 1;
+    } catch (e) {
+      err(opts)(`fringe: ${e.message}
 `);
       return 2;
     }
@@ -2170,8 +2643,17 @@ async function runCli(argv, opts = {}) {
   if (cmd === "init") {
     try {
       const global = rest.includes("--global") || rest.includes("-g");
-      const target = global ? opts.home ?? homedir() : resolve(opts.cwd ?? process.cwd(), rest.find((a) => !a.startsWith("-")) ?? ".");
-      for (const line of initProject(target)) log(opts)(`fringe: ${line}`);
+      const target = global ? opts.home ?? homedir() : resolve(opts.cwd ?? process.cwd(), rest.find((a, i) => !a.startsWith("-") && rest[i - 1] !== "--for") ?? ".");
+      const fi = rest.indexOf("--for");
+      const agents = fi !== -1 ? (rest[fi + 1] ?? "").split(",").map((a) => a.trim().toLowerCase()).filter(Boolean) : [];
+      if (fi !== -1 && agents.length === 0) throw new Error(`--for needs an agent: ${AGENTS.join(", ")}, claude`);
+      const lines = [];
+      const wantsClaude = fi === -1 && !rest.includes("--git") || agents.includes("claude");
+      if (wantsClaude) lines.push(...initProject(target));
+      const others = agents.filter((a) => a !== "claude");
+      if (others.length) lines.push(...initFor(target, others));
+      if (rest.includes("--git")) lines.push(...initGit(target));
+      for (const line of lines) log(opts)(`fringe: ${line}`);
       if (global) log(opts)("fringe: set up for your user, so every project is covered (run without --global to set up one project only)");
       return 0;
     } catch (e) {

package/dist/index.d.ts

@@ -2,7 +2,8 @@ interface CliOpts {
     log?: (s: string) => void;
     cwd?: string;
     err?: (s: string) => void; /** Home directory for `init --global` (tests override it). */
-    home?: string;
+    home?: string; /** `fringe login` waits for this instead of Enter on the terminal (tests). */
+    waitForUser?: () => Promise<void>;
 }
 declare function runCli(argv: string[], opts?: CliOpts): Promise<number>;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-7ZFEVMML.js";
+} from "./chunk-JJI65ERU.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "skill"
+    "skill",
+    "rules"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/bin.ts --format esm --dts --outDir dist --clean",

package/rules/fringe.md

@@ -0,0 +1,23 @@
+# Fringe: handle your edges
+
+For any coding agent that reads a rules file. Fringe is a static checker for frontends: it measures accessibility, interaction states, dark patterns and the generic "AI look", and exits non-zero on hard failures.
+
+Run it from the project root: `npx -y @fringetools/cli check` (or `fringe check` if installed). It takes a directory, not a single file.
+
+## While you work
+
+1. **Flow.** Before building UI, ask what the user can skip. Cut steps, screens and options nobody needs, and say why with evidence (a metric, a usage count, a requirement). No evidence, no cut.
+2. **Edges.** After every edit to a frontend file, run `fringe check`. Fix every `[ERROR]` before you finish: missing `alt`, unnamed buttons, unlabeled inputs, skipped headings, removed focus rings, `onClick` on non-interactive elements, invalid `aria-*`. Do not finish with errors outstanding.
+   Many findings? `fringe plan` orders them (shared components first) with a fix recipe each; `fringe explain FR-203` shows why a rule matters and the preferred fix.
+3. **Polish.** Fix `[REVIEW]` items you agree with and cheap `[SIGNAL]` items; say which you left and why.
+
+## Rules
+
+- Never silence a rule to get green. A `// fringe-ignore FR-123` comment is for a real false positive only; say so in your final message with the rule and the reason. Every run prints `N suppressed`.
+- On a repo that already has problems, do not fix everything first: `fringe check --update-baseline` records today's findings so only new ones gate (commit `fringe.baseline.json`).
+- If `npx` cannot run here (a sandbox with no network), ask the user to run `npm i -D @fringetools/cli` once, then use `npx --no-install fringe check`. If Fringe still cannot run, say so. Do not skip the check silently.
+- Report the health score as measured; never estimate it.
+
+Works alongside Ponytail: Ponytail keeps the code small and promises never to cut accessibility; Fringe is the check that verifies that promise.
+
+Reference: https://github.com/skc-learn/fringe/blob/main/packages/cli/README.md

package/skill/fringe/SKILL.md

@@ -5,7 +5,7 @@ description: Use when writing or changing frontend code (JSX/TSX, HTML, CSS, Vue
 
 # Fringe
 
-Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.0` in its place (e.g. `npx -y @fringetools/cli@0.4.0 check --json .`).
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.1` in its place (e.g. `npx -y @fringetools/cli@0.4.1 check --json .`).
 
 Ponytail trims your code. Fringe handles your edges. Work the ladder in order.
 

package/skill/fringe-audit/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user wants a whole-repo UX/accessibility audit, a plan
 
 # Fringe audit
 
-Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.0` in its place (e.g. `npx -y @fringetools/cli@0.4.0 check --json .`).
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.1` in its place (e.g. `npx -y @fringetools/cli@0.4.1 check --json .`).
 
 1. Run `fringe plan --json --limit 5` (or `fringe plan` for Markdown). It already orders the work: P0 errors in shared components or critical paths, P1 other errors with mechanical fixes first, P2 review, P3 polish, each cluster with its recipe. Use that order; do not re-derive it. Add `"critical": ["src/checkout/**"]` to `fringe.config.json` if the user names the pages that matter most. Do not print every finding.
 2. Summarize as a plan:

package/skill/fringe-debt/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user asks what Fringe findings have been silenced or d
 
 Fringe has two ways to defer a finding: an inline `fringe-ignore` comment and the `fringe.baseline.json` file. This lists both so a deferral can't quietly become permanent.
 
-Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.0` in its place.
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.1` in its place.
 
 1. **Inline suppressions.** `git grep --no-index --exclude-standard -nE 'fringe-ignore +FR-[0-9]+'`. One row per hit: `<file>:<line>, <rule> — <why, if the comment or nearby code says>`. Skip hits that are only prose mentioning the convention.
 2. **Baseline.** If `fringe.baseline.json` exists, count entries per rule (each entry is `rule|file|message`) and list the files with the most. If it is missing, say there is no baseline.

package/skill/fringe-help/SKILL.md

@@ -18,7 +18,7 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `/fringe-setup` | Guided onboarding: wire the hook, offer a baseline, set critical paths |
 | `/fringe-help` | This reference |
 
-**Commands** (`fringe`, or `npx -y @fringetools/cli@0.4.0`)
+**Commands** (`fringe`, or `npx -y @fringetools/cli@0.4.1`)
 
 | Command | What it does |
 |---|---|
@@ -27,6 +27,10 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `check --update-baseline` | Accept today's findings; only new ones gate |
 | `scan <url>` | Runtime check of a live page: real contrast, keyboard walk, and named states from `fringe.scan.json` (needs `playwright-core` + `axe-core`) |
 | `plan [dir\|file] [--scan url]` | Ordered fix batches (shared components first) with recipes; `--scan` adds the live page |
+| `login <url>` | Log in once in a browser window and save the session, so `scan` can reach pages behind a sign-in |
+| `handoff` / `verify` | Work order for another agent or CI, and proof it was done (complete / partial / regressed) |
+| `rules` | Per rule: open / baselined / silenced, to spot rules that do not suit this repo |
+| `init --for <agents>` / `--git` | Rules file for Codex, Cursor, Copilot, Gemini…; commit gate for any agent |
 | `explain [FR-203]` | Why a rule matters and how to fix it well |
 | `check --record [--manifest f]` | Append the run to `.fringe/ledger.jsonl` |
 | `init` | Add the hook and install the skills |

package/skill/fringe-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user asks to review, check or critique a UI, page or c
 
 # Fringe review
 
-Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.0` in its place (e.g. `npx -y @fringetools/cli@0.4.0 check --json .`).
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli@0.4.1` in its place (e.g. `npx -y @fringetools/cli@0.4.1 check --json .`).
 
 1. Run `fringe check --json <file or folder>` from the project root: the file or page the user named, else `.`. Each finding already carries `priority` and `fixability`; report highest priority first. For the fix text use `fringe explain <rule>` (why, recipe, what to avoid) rather than improvising.
 2. Report in plain English, no jargon left unexplained: