adsa-cli 0.1.1 → 0.1.4

package/README.md

@@ -34,7 +34,7 @@ fails when the score drops, so documentation debt cannot land quietly next to a
 feature. `adsa badge` prints the README line for your own score — this is what the
 example system in this repo earns after its fixes:
 
-![Agent-ready 23/45](https://img.shields.io/badge/agent--ready-23%2F45-a2650b)
+![Agent-ready 23/45](https://img.shields.io/badge/agent--ready-23%2F45-a16207)
 
 **The experiment.** `adsa eval` gives an agent a real page to build, then counts what
 it invented. It is the only number that has ever changed anyone's mind.
@@ -42,6 +42,41 @@ it invented. It is the only number that has ever changed anyone's mind.
 **An MCP server.** `adsa mcp` serves the guides as tools, so agents query the docs of
 the version checked out in front of them instead of reading files and guessing.
 
+## What a score means
+
+13 public design systems, audited with this rubric at the commit named in
+`rubric/reference.json`, on 2026-09-10:
+
+| Score | System | Repository | Package audited |
+| :-- | :-- | :-- | :-- |
+| 33/45 | Astryx · Meta | `facebook/astryx` | `@astryxdesign/core` |
+| 29/45 | Chakra UI | `chakra-ui/chakra-ui` | `@chakra-ui/react` |
+| 25/45 | React Spectrum · Adobe | `adobe/react-spectrum` | `@react-spectrum/s2` |
+| 25/45 | shadcn/ui | `shadcn-ui/ui` | `v4` |
+| 23/45 | HeroUI | `heroui-inc/heroui` | `@heroui/react` |
+| 23/45 | Polaris · Shopify | `Shopify/polaris` | `@shopify/polaris` |
+| 21/45 | BoardUI | `BoardUI/boardui` | `boardui@0.5.5` — npx boardui add + skill, in the starter repo |
+| 21/45 | Mantine | `mantinedev/mantine` | `@mantine/core` |
+| 19/45 | Base UI · MUI | `mui/base-ui` | `@base-ui/react` |
+| 19/45 | Carbon · IBM | `carbon-design-system/carbon` | `@carbon/react` |
+| 17/45 | Primer · GitHub | `primer/react` | `@primer/react` |
+| 13/45 | Radix Primitives · WorkOS | `radix-ui/primitives` | `radix-ui` |
+| 13/45 | Untitled UI React | `untitleduico/react` | `@untitledui/react` |
+
+Two things follow, and both are the point of publishing this table.
+
+**45 is nobody's score.** The best-documented public design system reaches 33. The
+bands are anchored to that measured field rather than to a wish: **31+ agent-ready**,
+**24–30 good foundation**, **15–23 gaps to address**, **below 15 not ready**. A system
+in the low twenties is in the middle of the field, not failing.
+
+**This is not a ranking of design systems.** It measures one thing: what a coding
+agent can find in the repository it is working in. A system whose documentation lives
+on an excellent website scores low here and may well be the better system for people.
+
+Every row is reproducible: clone the repository and run `npx adsa-cli audit <clone>`.
+`npx adsa-cli reference` prints this table from the tool.
+
 ## The nine dimensions
 
 | | Dimension | The question |
@@ -58,6 +93,10 @@ the version checked out in front of them instead of reading files and guessing.
 
 `npx adsa-cli rubric` prints what 1, 3 and 5 mean for each.
 
+`--out <dir>` puts every artifact of a run together somewhere else — the report, the
+score, the badge and the history — and reads the previous score from there too, so a
+repository can be audited without writing anything into it.
+
 ## Commands
 
 ```
@@ -75,6 +114,39 @@ adsa rubric                 The nine dimensions in full
 ```
 
 `--json` everywhere. `--dry-run` on `fix`. `--gate --min <n>` on `audit`.
+`--workspace <name>` and `--no-workspace` on everything that reads a repository.
+
+## Monorepos
+
+A design system usually is not the repository — it is one package in it, and the
+things an agent needs are spread across both. `adsa` reads them where they are:
+
+| What | Where it looks |
+| :-- | :-- |
+| Components, guides, tokens | The package being audited |
+| `AGENTS.md`, `CLAUDE.md` | The package, then the repository that declares it |
+| CI workflows, root scripts | The repository |
+| MCP server, `llms.txt`, CLI, skills, commands | The repository, including sibling workspaces |
+
+"The repository that declares it" is exact: an ancestor counts only when its
+`workspaces` or `pnpm-workspace.yaml` actually lists this package. A design system
+vendored inside an unrelated repo inherits nothing, because it was promised nothing.
+
+Detection picks the workspace that looks most like the design system and says which
+one it picked. When it picks wrong, `--workspace @acme/ui` names one by hand and
+`--no-workspace` audits the directory exactly as given. Every run prints the
+directories it read, because *not found* and *never looked* are otherwise the same
+sentence — which is the mistake this tool exists to stop an agent from making.
+
+## Where guides can live
+
+`guidelines/`, `docs/components/`, `docs/`, a Swift package's `.docc` bundle — and
+next to the component itself, as `Button/Button.spec.md`, `Card/Card.docs.md` or
+`Field/Field.guide.md`. A colocated guide is a deliberate layout, not a missing one.
+
+An agent surface counts whether the repository commits it or serves it: an MCP
+endpoint behind a route handler, an `llms.txt` generated from the live docs, and a
+CLI published from a sibling package are all things an agent can query.
 
 ## The skill
 
@@ -90,7 +162,7 @@ gets it wrong, `adsa.config.json`:
 
 ```json
 {
-    "guides": ["guidelines"],
+    "guides": ["guidelines", "src/components"],
     "source": ["src/components"],
     "forbidden": ["lucide-react"],
     "skip": ["patterns"],
@@ -101,6 +173,9 @@ gets it wrong, `adsa.config.json`:
 `skip` is for dimensions that genuinely do not apply — a primitives-only library has
 no page patterns, and a skipped dimension lowers the maximum instead of the score.
 
+Naming `guides` yourself turns off the repository-level guide folder that a
+workspace package otherwise inherits: an explicit list is a complete answer.
+
 ## Platforms
 
 ADSA detects which platform a design system is built for from real evidence in the
@@ -141,23 +216,35 @@ not assessed — it never guesses a number.
 
 ## Try it
 
+One design system, in the three states of the loop. All three are in the repository,
+and all three numbers are a command away:
+
 ```bash
 git clone https://github.com/nrmk13/ADSA && cd ADSA
-node bin/adsa.mjs audit example/design-system        # 9/45
-node bin/adsa.mjs fix --all --cwd example/design-system
-node bin/adsa.mjs audit example/design-system        # 23/45
+node bin/adsa.mjs audit example/design-system-as-found   # 11/45 — as most systems are
+node bin/adsa.mjs audit example/design-system            # 23/45 — after `fix --all`
+node bin/adsa.mjs audit example/design-system-ready      # 45/45 — after the briefs
 ```
 
-`example/agent-output` is what an agent built against that system before it was
-fixed. `adsa eval score example/agent-output --system example/design-system` counts
-the three components it invented.
+The middle state is what the tool writes for you: instructions, an MCP entry, a gap
+list, a CI workflow. The last state is what it cannot write for you — generated prop
+tables, keyboard contracts, page patterns, and checks in CI that fail when a guide
+starts lying. `example/design-system-ready/scripts` is that work, done: four checks,
+each with a test in `test/checks.test.mjs` that breaks the docs on purpose and asserts
+the check goes red. It is the only 45/45 anywhere, and it is a six-component system
+with a person's whole afternoon in it.
+
+`example/agent-output` is what an agent built against the first state.
+`adsa eval score example/agent-output --system example/design-system` counts the three
+components it invented.
 
-Small fixtures for the other platforms live under `test/fixtures/` — a React Native
-library, a Swift package documented with DocC, and a Kotlin/Compose library — and
-run the same loop:
+Small fixtures live under `test/fixtures/` — a React Native library, a Swift package
+documented with DocC, a Kotlin/Compose library, and a pnpm monorepo whose guides sit
+next to its components — and run the same loop:
 
 ```bash
 node bin/adsa.mjs audit test/fixtures/swift-ds
+node bin/adsa.mjs audit test/fixtures/monorepo-ds        # 39/45, audited from the root
 ```
 
 ## Licence

package/bin/adsa.mjs

@@ -8,17 +8,21 @@
  *   adsa eval init | score <dir>  run the experiment and measure the result
  *   adsa mcp                      serve the guides as MCP tools
  *   adsa doctor                   is this repo wired up for agents
+ *   adsa reference                the field: what other design systems score
  *   adsa badge                    the README badge for the committed score
  */
+import { spawn } from "node:child_process";
 import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { loadConfig, resolveTarget } from "../lib/config.mjs";
+import { loadConfig, resolveRepoRoot } from "../lib/config.mjs";
+import { resolveTarget } from "../lib/target.mjs";
 import { scan } from "../lib/scan.mjs";
 import { RUBRIC, score, scoreFile } from "../lib/score.mjs";
 import { buildTodo, html, markdown } from "../lib/report.mjs";
-import { badgeEndpoint, badgeMarkdown } from "../lib/badge.mjs";
-import { isDir } from "../lib/fsx.mjs";
+import { band, badgeEndpoint, badgeMarkdown } from "../lib/badge.mjs";
+import { REFERENCE, standing } from "../lib/reference.mjs";
+import { exists, isDir } from "../lib/fsx.mjs";
 import { DIR, appendHistory, compare, readHistory, write } from "../lib/history.mjs";
 import { FIXES, applyFix } from "../lib/fix.mjs";
 import { evaluate, taskFile } from "../lib/eval.mjs";
@@ -42,24 +46,28 @@ Usage
   adsa eval score <dir>       Measure what the agent actually built
   adsa mcp                    Serve the guides as MCP tools over stdio
   adsa doctor                 Check this repo's agent surface
+  adsa reference              The measured field: public design systems, same rubric
   adsa badge                  Print the README badge for the committed score
   adsa rubric                 Print the nine dimensions and what each level means
 
 Options
   --json                      Machine-readable output
-  --out <dir>                 Where to write the report (default: .adsa)
+  --out <dir>                 Write every artifact here instead of .adsa/
   --gate                      Exit non-zero if the score dropped, or is below --min
   --min <n>                   Minimum acceptable total for --gate
   --dry-run                   fix: show what would change, write nothing
   --system <dir>              eval score: the design system the project should use
   --cwd <dir>                 fix: the repository to change (default: .)
+  --workspace <name>          audit this workspace package, not the detected one
+  --no-workspace              audit the given directory as it stands
+  --no-open                   audit: do not open the report in a browser
   --quiet                     Only the score line
   --full                      docs: keep the prose
   --color / --no-color        Force ANSI colour on or off (default: on for a terminal)
 `;
 
 export function parseArgs(argv) {
-    const flags = { out: null, json: false, gate: false, min: null, dryRun: false, system: null, quiet: false, list: false, all: false, cwd: null };
+    const flags = { out: null, json: false, gate: false, min: null, dryRun: false, system: null, quiet: false, list: false, all: false, cwd: null, workspace: null, noWorkspace: false };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -72,6 +80,10 @@ export function parseArgs(argv) {
         else if (arg === "--color") flags.color = true;
         else if (arg === "--no-color") flags.color = false;
         else if (arg === "--all") flags.all = true;
+        else if (arg === "--open") flags.open = true;
+        else if (arg === "--no-open") flags.open = false;
+        else if (arg === "--no-workspace") flags.noWorkspace = true;
+        else if (arg === "--workspace") flags.workspace = argv[++i];
         else if (arg === "--out") flags.out = argv[++i];
         else if (arg === "--min") flags.min = Number(argv[++i]);
         else if (arg === "--system") flags.system = argv[++i];
@@ -83,12 +95,22 @@ export function parseArgs(argv) {
     return { command: positional[0], args: positional.slice(1), flags };
 }
 
+/** A bad --workspace is the reader's mistake to fix, not a reason to audit something else. */
+class TargetError extends Error {}
+
+/** Set once per run so every command resolves the same target the reader asked for. */
+let targetFlags = {};
+
 function load(dir) {
     const given = resolve(dir || ".");
-    const target = resolveTarget(given);
+    const target = resolveTarget(given, targetFlags);
+    if (target.error) throw new TargetError(target.error);
     const root = target.dir;
     const config = loadConfig(root);
-    const facts = scan(root, config);
+    // Agent instructions, CI and the agent surface belong to the repository that
+    // declares this package, not to the package directory.
+    const repoRoot = targetFlags.noWorkspace ? root : resolveRepoRoot(root) || root;
+    const facts = scan(root, config, repoRoot);
     facts.workspace = target.note;
     return { root, config, facts };
 }
@@ -109,6 +131,7 @@ export async function run(argv, io = {}) {
     const json = (v) => out(JSON.stringify(v, null, 2));
     const { command, args, flags } = parseArgs(argv);
     if (flags.color !== undefined) setColor(flags.color);
+    targetFlags = { workspace: flags.workspace, noWorkspace: flags.noWorkspace };
     if (flags.help || !command) {
         out(HELP);
         return 0;
@@ -118,6 +141,18 @@ export async function run(argv, io = {}) {
         return 1;
     }
 
+    try {
+        return await dispatch(command, args, flags, io, out, json);
+    } catch (error) {
+        if (error instanceof TargetError) {
+            out(red(error.message));
+            return 1;
+        }
+        throw error;
+    }
+}
+
+async function dispatch(command, args, flags, io, out, json) {
     switch (command) {
         case "audit":
             return cmdAudit(args[0], flags, out, json);
@@ -136,6 +171,8 @@ export async function run(argv, io = {}) {
             return cmdDocs(args, flags, out, json);
         case "doctor":
             return cmdDoctor(args[0], flags, out, json);
+        case "reference":
+            return cmdReference(flags, out, json);
         case "badge":
             return cmdBadge(args[0], flags, out, json);
         case "rubric":
@@ -146,6 +183,60 @@ export async function run(argv, io = {}) {
     }
 }
 
+/**
+ * Which directories the run actually read. "Not found" and "never looked" print the
+ * same in a report, and a reader cannot tell a bad layout from a bad scan without it.
+ */
+function scannedLine(facts) {
+    const s = facts.scanned;
+    const parts = [`guides ${s.guides.length ? s.guides.join(", ") : "none found"}`, `source ${s.source.length ? s.source.join(", ") : "none found"}`];
+    if (s.colocatedGuides) parts.push(`${s.colocatedGuides} colocated`);
+    if (facts.monorepo) parts.push(`repo-level files from ${basename(facts.repoRoot)}/`);
+    return `  scanned: ${parts.join(" · ")}`;
+}
+
+/**
+ * Whether to hand the report to the reader's browser. Opening a window is the kind of
+ * thing a tool should only do when a person is watching: a TTY, no CI environment
+ * variable, and not asked for machine output.
+ */
+function shouldOpen(flags) {
+    if (flags.open === false || flags.json || flags.quiet || flags.gate) return false;
+    if (flags.open === true) return true;
+    if (process.env.CI || process.env.ADSA_NO_OPEN) return false;
+    return Boolean(process.stdout.isTTY);
+}
+
+function openInBrowser(file, out) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        spawn(cmd, [pathToFileURL(file).href], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+    } catch {
+        out(dim("  (could not open a browser — the path above is the file)"));
+    }
+}
+
+/* ------------------------------------------------------------ reference */
+
+/** The measured field, so a reader can see what 45 is worth without leaving the terminal. */
+function cmdReference(flags, out, json) {
+    if (flags.json) {
+        json(REFERENCE);
+        return 0;
+    }
+    out(`Public design systems audited with rubric ${REFERENCE.rubric}, ${REFERENCE.measured}:\n`);
+    for (const s of REFERENCE.systems) {
+        const label = `${s.name}${s.org ? ` · ${s.org}` : ""}`;
+        out(`  ${String(s.total).padStart(2)}/${s.max}  ${byScore(bandScore(s.total, s.max), label.padEnd(26))} ${dim(`${s.repo}@${s.commit}  ${s.package}`)}`);
+    }
+    out(dim("\n  Not a ranking of design systems: it measures what an agent can find in the repository."));
+    out(dim("  Reproduce any row with `npx adsa-cli audit <clone>`."));
+    return 0;
+}
+
+/** The 1/3/5 colour the bar chart uses, borrowed for a whole score. */
+const bandScore = (total, max) => ({ ready: 5, good: 5, gaps: 3, unready: 1 })[band(total, max).id];
+
 /* ---------------------------------------------------------------- audit */
 
 function cmdAudit(dir, flags, out, json) {
@@ -157,20 +248,26 @@ function cmdAudit(dir, flags, out, json) {
         return 1;
     }
     const scored = score(facts, config);
-    const outDir = flags.out || DIR;
+    // Everything one run writes lands together. --out is read from where the command
+    // was typed, so an absolute path is absolute and a relative one is relative to
+    // the reader, not to the repository being audited.
+    const artefacts = flags.out ? resolve(process.cwd(), flags.out) : join(root, DIR);
+    const fresh = !exists(join(artefacts, "score.json"));
     const file = scoreFile(facts, scored);
-    const previous = readJson(join(root, DIR, "score.json"));
+    const previous = readJson(join(artefacts, "score.json"));
     const delta = compare(previous, file);
 
     if (flags.json) {
-        json({ ...file, dimensions: scored.dimensions, delta });
+        json({ ...file, scanned: facts.scanned, dimensions: scored.dimensions, delta });
     } else {
-        const band = scored.total / scored.max;
-        // Same bands the report uses, so the terminal and the HTML never disagree.
-        const paint = (t) => (band >= 0.85 ? green(t) : band >= 0.35 ? yellow(t) : red(t));
-        out(`${facts.name}${facts.version ? " " + facts.version : ""} — agent readiness ${paint(`${scored.total}/${scored.max}`)}`);
+        // One band table, in lib/badge.mjs, so the terminal, the report and the
+        // badge never disagree about what a number means.
+        const verdict = band(scored.total, scored.max);
+        const paint = (t) => (verdict.id === "ready" || verdict.id === "good" ? green(t) : verdict.id === "gaps" ? yellow(t) : red(t));
+        out(`${facts.name}${facts.version ? " " + facts.version : ""} — agent readiness ${paint(`${scored.total}/${scored.max}`)}  ${paint(verdict.label)}`);
         if (facts.workspace) out(`  ${facts.workspace}`);
         if (!flags.quiet) {
+            out(dim(scannedLine(facts)));
             out("");
             for (const d of scored.dimensions) {
                 const bar = d.skipped ? dim("  skip") : byScore(d.score, "█".repeat(d.score)) + dim("·".repeat(5 - d.score));
@@ -188,17 +285,35 @@ function cmdAudit(dir, flags, out, json) {
                 const move = `Since the last run: ${delta.from} → ${delta.to} (${delta.delta >= 0 ? "+" : ""}${delta.delta})`;
                 out(delta.delta > 0 ? green(move) : delta.delta < 0 ? red(move) : dim(move));
             }
+            // A score out of 45 answers nothing until you know what 45 is worth.
+            out(dim(standing(scored.total).sentence));
         }
     }
 
-    const history = appendHistory(root, { date: file.generatedAt, total: file.total, max: file.max, dimensions: file.dimensions });
-    write(join(root, DIR, "score.json"), file);
-    write(join(root, DIR, "badge.json"), badgeEndpoint(file.total, file.max));
-    const reportDir = join(root, outDir);
-    mkdirSync(reportDir, { recursive: true });
-    writeFileSync(join(reportDir, "report.html"), html(facts, scored, history));
-    writeFileSync(join(reportDir, "report.md"), markdown(facts, scored));
-    if (!flags.json && !flags.quiet) out(dim(`\nReport: ${join(outDir, "report.html")} · score: ${join(DIR, "score.json")}`));
+    const history = appendHistory(artefacts, { date: file.generatedAt, total: file.total, max: file.max, dimensions: file.dimensions });
+    write(join(artefacts, "score.json"), file);
+    write(join(artefacts, "badge.json"), badgeEndpoint(file.total, file.max));
+    mkdirSync(artefacts, { recursive: true });
+    writeFileSync(join(artefacts, "report.html"), html(facts, scored, history));
+    writeFileSync(join(artefacts, "report.md"), markdown(facts, scored));
+    // A path that climbs out of the current directory reads better absolute than as
+    // a ladder of "..".
+    const near = relative(process.cwd(), artefacts);
+    const shown = !near ? "." : near.startsWith("..") ? artefacts : near;
+    if (!flags.json && !flags.quiet) {
+        const report = join(artefacts, "report.html");
+        out(`\nReport: ${pathToFileURL(report).href}`);
+        out(dim(`  ${join(shown, "report.html")} · score: ${join(shown, "score.json")}`));
+        // The report is the deliverable, so it opens. `--no-open` for a script, and
+        // it never opens on its own in CI or when the output is being piped.
+        if (shouldOpen(flags)) openInBrowser(report, out);
+        // Say once what the directory is for, rather than leave someone to guess
+        // whether a new folder in their repository belongs in the commit.
+        if (fresh && !flags.out && exists(join(root, ".git"))) {
+            out(dim("  score.json, badge.json and history.json are meant to be committed — the badge and the gate read them."));
+            out(dim("  report.html and report.md are rewritten every run; ignore them if you would rather not carry them."));
+        }
+    }
 
     if (flags.gate) {
         const floor = flags.min ?? config.minScore ?? (previous ? previous.total : null);
@@ -350,10 +465,11 @@ function cmdDoctor(dir, flags, out, json) {
     const checks = [];
     const add = (id, status, message, fix) => checks.push({ id, status, message, ...(fix ? { fix } : {}) });
     const agents = facts.agentFiles.find((a) => a.mentionsPackage);
-    agents ? add("agent-docs", "pass", `${agents.file} references ${facts.name}.`) : add("agent-docs", "fail", "No agent instructions mention this system.", "adsa fix agents-md");
-    facts.machine.declaredServers.includes("adsa") || facts.machine.mcpInPackage
-        ? add("mcp", "pass", "An MCP server is registered for this repository.")
-        : add("mcp", "warn", "No MCP server registered, so agents read files instead of querying.", "npx adsa-cli fix mcp-config");
+    agents ? add("agent-docs", "pass", `${agents.label || agents.file} references ${facts.name}.`) : add("agent-docs", "fail", "No agent instructions mention this system.", "adsa fix agents-md");
+    const served = facts.machine.servedMcp || [];
+    if (served.length) add("mcp", "pass", `This repository serves an MCP server: ${served.slice(0, 2).join(", ")}.`);
+    else if (facts.machine.declaredServers.includes("adsa") || facts.machine.mcpInPackage) add("mcp", "pass", "An MCP server is registered for this repository.");
+    else add("mcp", "warn", "No MCP server registered, so agents read files instead of querying.", "npx adsa-cli fix mcp-config");
     facts.gaps.file ? add("gaps", "pass", `${facts.gaps.file} lists known absences.`) : add("gaps", "fail", "Nothing states what the system does not have.", "adsa fix gaps-file");
     facts.verification.workflows.length ? add("ci", "pass", `CI: ${facts.verification.workflows.join(", ")}.`) : add("ci", "warn", "No CI workflow found.", "adsa fix ci-workflow");
     facts.config.file ? add("config", "pass", `${facts.config.file} present.`) : add("config", "warn", "No adsa.config.json — detection is doing the guessing.");

package/lib/badge.mjs

@@ -1,19 +1,35 @@
-/** README badge. Static shields.io URL, plus an endpoint file for repos that prefer one.
+/** The four verdicts, and the README badge that carries one of them.
  *
- * The four bands are the four verdicts the report uses, and the colours are the
- * page palette darkened until white text on them clears 4.5:1 — a badge is small
- * text on a solid fill, and it is the one artifact that ends up on someone else's
- * README. One scale, so the badge, the report and the page never disagree. */
-const COLORS = [
-    [0.85, "166534", "agent-ready"],
-    [0.6, "15803d", "good foundation"],
-    [0.35, "a16207", "gaps to address"],
-    [0, "b91c1c", "not ready"],
+ * The thresholds are not a curve and not a guess: the public design systems in `rubric/reference.json` were
+ * audited with this rubric (`rubric/reference.json`), and the field runs from 13/45
+ * to 33/45. Nothing reaches 40, and the systems people hold up as the good ones sit
+ * between 21 and 33 — so a scale where 38/45 was the first green band called every
+ * design system in the world unready, which is a scale that tells you nothing.
+ *
+ * So the bands are anchored to the measured field: *agent-ready* starts at the level
+ * the best-documented system reaches today, and the middle of the field is *gaps to
+ * address*, because the middle of the field is where an agent still guesses.
+ *
+ * The colours are the page palette darkened until white text on them clears 4.5:1 —
+ * a badge is small text on a solid fill, and it is the one artifact that ends up on
+ * somebody else's README. One scale, so the badge, the report, the terminal and the
+ * page never disagree.
+ */
+export const BANDS = [
+    { floor: 0.68, id: "ready", label: "agent-ready", color: "166534", note: "At the level of the best-documented public design system measured." },
+    { floor: 0.53, id: "good", label: "good foundation", color: "15803d", note: "Above most public design systems. An agent can work here, with gaps." },
+    { floor: 0.33, id: "gaps", label: "gaps to address", color: "a16207", note: "Where most design systems sit. An agent fills the rest by guessing." },
+    { floor: 0, id: "unready", label: "not ready", color: "b91c1c", note: "An agent will invent most of what it needs." },
 ];
 
-export function badgeColor(total, max) {
+/** @returns {{floor:number,id:string,label:string,color:string,note:string}} */
+export function band(total, max) {
     const ratio = max ? total / max : 0;
-    return COLORS.find(([floor]) => ratio >= floor)[1];
+    return BANDS.find((b) => ratio >= b.floor);
+}
+
+export function badgeColor(total, max) {
+    return band(total, max).color;
 }
 
 export function badgeMarkdown(total, max, link) {