@fringetools/cli 0.1.0 → 0.1.1

package/README.md

@@ -17,8 +17,6 @@ That is the whole setup. `init` adds a `PostToolUse` hook to `.claude/settings.j
 
 Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe check`. Existing messy repo? Run `npx @fringetools/cli check --update-baseline` once so only *new* problems gate (see [Baseline](#baseline)).
 
-> **Until the first npm release:** build from source — `pnpm install && pnpm --filter @fringetools/cli build`, then use `node packages/cli/dist/bin.js` in place of `npx @fringetools/cli`.
-
 ## Commands
 
 | Command | What it does |
@@ -29,7 +27,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | `fringe check --hook` | One-line `fringe/hook.v1` JSON for CI / pre-commit. Exits `1` on errors. Claude Code does **not** feed this back — use `--claude-hook` for agents. Wins over `--json`. |
 | `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 init [path]` | Add the Claude Code hook and install the skill. Safe to re-run; refuses to touch an invalid `settings.json`. |
+| `fringe init [path]` | Add the Claude Code hook and install the three skills. 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,7 +101,9 @@ After each edit the hook runs; with errors it returns, for example:
 
 This was verified end to end with real agent runs: the agent receives the findings and fixes them (see [docs/architecture.md](../../docs/architecture.md)). Why `--claude-hook` and not `--hook`: Claude Code only passes a hook's output to the agent as `decision`/`reason` JSON on exit 0 (or stderr on exit 2); the CI contract `--hook` exits 1 and is ignored.
 
-**The skill** (`.claude/skills/fringe/SKILL.md`, source: [skill/SKILL.md](skill/SKILL.md)) teaches the agent the ladder: *Flow* (cut what users don't need, with evidence in `.fringe/manifest.json`) → *Edges* (fix every hook finding, never silence a rule to get green) → *Polish* (tokens, scales, no AI look), then record the run. It is plain Markdown, so any agent platform that reads `AGENTS.md`/skill files can use it as-is.
+**Skills** — `fringe init` installs three into `.claude/skills/` (sources in [skill/](skill/)): `fringe` (below), `fringe-review` ("review this page": runs the checker and reports ranked, plain-English findings with fixes; invoke as `/fringe-review`) and `fringe-audit` (whole-repo plan: top rules and files, a suggested fix order, offers `--update-baseline`; `/fringe-audit`). Reviews run `fringe check`, so Claude Code will ask you to approve that command once (or allow `Bash(fringe:*)` / `Bash(npx:*)`).
+
+**The main skill** (`.claude/skills/fringe/SKILL.md`) teaches the agent the ladder: *Flow* (cut what users don't need, with evidence in `.fringe/manifest.json`) → *Edges* (fix every hook finding, never silence a rule to get green) → *Polish* (tokens, scales, no AI look), then record the run. It is plain Markdown, so any agent platform that reads `AGENTS.md`/skill files can use it as-is.
 
 For CI or pre-commit use `fringe check --hook` (or just the exit code):
 

package/dist/bin.js

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

package/dist/{chunk-AOUZJDQL.js → chunk-W23H5MXS.js}

@@ -1166,7 +1166,7 @@ import { createServer } from "http";
 var esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 function renderBoard(records, corrupt = 0) {
   const rows = [...records].reverse().map((r) => {
-    const flows = (r.manifest?.flows ?? []).map((f) => `<li>${esc(f.action)}: ${esc(f.what)} <small>(${esc(f.evidence)}) \u2014 judged</small></li>`).join("");
+    const flows = (r.manifest?.flows ?? []).map((f) => `<li>${esc(f.action)}: ${esc(f.what)} <small>(${esc(f.evidence)}) \u2014 judged${f.unsupported ? ", <b>no evidence</b>" : ""}</small></li>`).join("");
     return `<tr><td>${esc(r.ts)}</td><td>${r.score}</td><td>${r.counts.error}</td><td>${r.counts.review}</td><td>${r.counts.signal}</td><td>${r.files}</td><td>${r.suppressed ?? 0}</td><td>${flows ? `<ul>${flows}</ul>` : ""}</td></tr>`;
   }).join("");
   const body = records.length === 0 ? "<p>No runs yet. Run <code>fringe check --record</code> and reload.</p>" : `<table><tr><th>When</th><th>Health</th><th>Errors</th><th>Review</th><th>Signals</th><th>Files</th><th>Suppressed</th><th>Flow cuts</th></tr>${rows}</table>`;
@@ -1190,7 +1190,8 @@ import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as rea
 import { dirname, join as join7 } from "path";
 import { fileURLToPath } from "url";
 var HOOK = "npx -y @fringetools/cli check --claude-hook";
-var SKILL = fileURLToPath(new URL("../skill/SKILL.md", import.meta.url));
+var SKILLS = { fringe: "SKILL.md", "fringe-review": "review.md", "fringe-audit": "audit.md" };
+var skillSrc = (file) => fileURLToPath(new URL(`../skill/${file}`, import.meta.url));
 function initProject(root) {
   const done = [];
   const settingsPath = join7(root, ".claude", "settings.json");
@@ -1210,12 +1211,14 @@ function initProject(root) {
     writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     done.push(`hook added to ${settingsPath}`);
   }
-  const skillPath = join7(root, ".claude", "skills", "fringe", "SKILL.md");
-  if (existsSync2(skillPath)) done.push("skill already present");
-  else {
-    mkdirSync2(dirname(skillPath), { recursive: true });
-    copyFileSync(SKILL, skillPath);
-    done.push(`skill installed at ${skillPath}`);
+  for (const [name, file] of Object.entries(SKILLS)) {
+    const skillPath = join7(root, ".claude", "skills", name, "SKILL.md");
+    if (existsSync2(skillPath)) done.push(`skill ${name} already present`);
+    else {
+      mkdirSync2(dirname(skillPath), { recursive: true });
+      copyFileSync(skillSrc(file), skillPath);
+      done.push(`skill ${name} installed`);
+    }
   }
   return done;
 }
@@ -1235,6 +1238,13 @@ function readManifest(path2, warn) {
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || !Array.isArray(parsed.flows)) throw new Error("missing flows");
+    for (const f of parsed.flows) {
+      if (f.action === "cut" && weakEvidence(f.evidence)) {
+        f.unsupported = true;
+        warn(`fringe: warning: cut '${f.what}' has no real evidence \u2014 recorded as unsupported
+`);
+      }
+    }
     return parsed;
   } catch {
     warn(`fringe: warning: manifest at ${path2} is not valid '{ flows: [...] }' JSON \u2014 continuing without
@@ -1242,6 +1252,7 @@ function readManifest(path2, warn) {
     return void 0;
   }
 }
+var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\/?a|none|tbd|obvious|unnecessary|clutter|unused)\.?$/i.test(e.trim());
 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

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-AOUZJDQL.js";
+} from "./chunk-W23H5MXS.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -5,6 +5,8 @@ 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` in its place (e.g. `npx -y @fringetools/cli check --json .`).
+
 Ponytail trims your code. Fringe handles your edges. Work the ladder in order.
 
 1. **Flow (judged).** Before building, ask what the user can skip. Cut steps, screens or options nobody needs. Write each decision with its evidence to `.fringe/manifest.json`: `{"flows":[{"action":"cut"|"kept","what":"...","evidence":"..."}]}`. No evidence, no cut.

package/skill/audit.md

@@ -0,0 +1,19 @@
+---
+name: fringe-audit
+description: Use when the user wants a whole-repo UX/accessibility audit, a plan for an existing frontend with many problems, or to adopt Fringe on a messy repo ("audit this codebase", "where do we start", "adopt fringe"). Produces a prioritized plan and sets a baseline.
+---
+
+# Fringe audit
+
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
+
+1. Run `fringe check --json .` and note the totals. Do not print every finding.
+2. Summarize as a plan:
+   - Totals by severity and the health score, plus files scanned and skipped.
+   - **Top rules** by count, and **top files** by error count (the 5 worst of each).
+   - For each top rule: what it means in one sentence, a typical fix, and whether it is likely mechanical (add `aria-label`, add `alt`) or needs design judgment.
+   - A suggested order: mechanical `error` fixes first, then `error`s needing judgment, then `review`, then `signal`.
+3. Offer the baseline: "`fringe check --update-baseline` records today's findings so only new problems gate; commit `fringe.baseline.json`." Run it only if the user agrees.
+4. Ask before changing code. If the user says go, fix one rule at a time, re-run `fringe check` after each, and re-baseline at the end so the file shrinks.
+
+Spot-check a few reported findings by reading the code before presenting them as certain; Fringe is static and can be wrong. Say which you checked.

package/skill/review.md

@@ -0,0 +1,18 @@
+---
+name: fringe-review
+description: Use when the user asks to review, check or critique a UI, page or component for accessibility and UX edges ("review this page", "what's wrong with this form", "is this accessible"). Runs Fringe and reports ranked findings with fixes, in plain English.
+---
+
+# Fringe review
+
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
+
+1. Run `fringe check --json .` from the project root. Fringe takes directories, not single files, so if the user named one file or page, run on the folder and keep only the findings whose `loc.file` matches it.
+2. Report in plain English, no jargon left unexplained:
+   - **Must fix** — `error` findings. Group by rule. For each: where (`file:line`), what is wrong in one sentence, the exact fix, and who is hurt (for example "a screen reader says only 'button'"). Cite the `wcag` criterion when present.
+   - **Worth a look** — `review` findings. These are heuristics: say they need your judgment, and give your call on each.
+   - **Polish** — `signal` findings, only the top few. Never present them as bugs.
+3. End with the health score as measured, the count by severity, and one line on what was not checked (Fringe is static: it cannot judge contrast on images, real focus order, or whether copy is good).
+4. Change no code unless asked. If asked to fix, fix `error` items first and re-run to confirm.
+
+Do not invent findings the tool did not report, and do not call the score an estimate: it is measured.