adsa-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nazar Melnyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+<img src="assets/cover.png" alt="Agentic Design System" width="100%">
+
+# ADSA
+
+[adsa.space](https://adsa.space) — agentic design system audit
+
+Your design system is documented for people. An agent is not a person: it cannot ask
+a colleague, it cannot tell *this does not exist* from *I have not found it yet*, and
+when it cannot find something it invents a component and moves on, confidently.
+
+ADSA scores a design system out of 45 on how well a coding agent can use it, writes
+the report, and then fixes what it can.
+
+```bash
+npx adsa-cli audit            # score this repo, write the report
+npx adsa-cli fix --all        # apply what can be applied, brief the rest
+npx adsa-cli audit            # measure again
+```
+
+That loop is the whole product. Everything below is detail.
+
+## What you get
+
+**A score with its evidence.** Nine dimensions, each 1, 3 or 5, each quoting the
+files that produced the number, so you can disagree with the reading rather than the
+verdict. Written to `.adsa/report.html`, `.adsa/report.md` and `.adsa/score.json`.
+
+**A to-do list that runs.** Every item is a command, not advice. Five fixes write
+files. Five write a task brief for your agent, because they need your repo's own
+stack and a generic codemod would do them badly.
+
+**A gate, and a badge.** `.adsa/score.json` is committed and `adsa audit --gate`
+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)
+
+**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.
+
+**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.
+
+## The nine dimensions
+
+| | Dimension | The question |
+| :-- | :-- | :-- |
+| 1 | Agent instructions | When an agent opens this repo, does anything tell it how to use the system? |
+| 2 | Machine surface | Can an agent query the system, or must it read files and guess? |
+| 3 | Docs coverage | Does every component a consumer can import have a guide? |
+| 4 | Docs freshness | If a guide drifts from the code, does anything notice? |
+| 5 | Tokens | Are colour, spacing, radius and motion documented as named decisions? |
+| 6 | Patterns | Is there anything above component level — how a real page is assembled? |
+| 7 | Accessibility docs | Do the guides say how a component behaves for assistive technology? |
+| 8 | Verification | Can an agent check its own work before calling it done? |
+| 9 | Gap handling | What happens when the system genuinely does not have the thing? |
+
+`npx adsa-cli rubric` prints what 1, 3 and 5 mean for each.
+
+## Commands
+
+```
+adsa audit [dir]            Score, write report.html, report.md, score.json
+adsa fix <id> | --all       Apply a fix, or write its task brief
+adsa fix --list             What each fix does
+adsa search "<task>"        Which component do I need for this
+adsa docs <component>       That component's guide, prose stripped
+adsa eval init              Write the experiment task for an agent
+adsa eval score <dir>       Measure what the agent actually built
+adsa mcp                    Serve the guides as MCP tools over stdio
+adsa doctor                 Is this repo wired up for agents
+adsa badge                  The README badge for the committed score
+adsa rubric                 The nine dimensions in full
+```
+
+`--json` everywhere. `--dry-run` on `fix`. `--gate --min <n>` on `audit`.
+
+## The skill
+
+For Claude Code, `skills/ds-audit` runs the whole audit as a conversation: it asks
+where the system is, whether a consumer project exists, which agent your team uses
+and whether there is a Figma library — then runs the tool, reads the guides itself,
+runs the experiment and writes the findings. Copy it into `.claude/skills/`.
+
+## Configuration
+
+None required. Everything the tool can read from the repo, it reads. When detection
+gets it wrong, `adsa.config.json`:
+
+```json
+{
+    "guides": ["guidelines"],
+    "source": ["src/components"],
+    "forbidden": ["lucide-react"],
+    "skip": ["patterns"],
+    "minScore": 30
+}
+```
+
+`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.
+
+## Platforms
+
+ADSA detects which platform a design system is built for from real evidence in the
+repo, and audits it accordingly:
+
+| Platform | Detected from | Components | Tokens |
+| :-- | :-- | :-- | :-- |
+| React / web | `react`, `vue` or `svelte` in `package.json` | Exported symbols or `exports` subpaths | Guide prose, raw Tailwind/hex in examples |
+| React Native | `react-native` or `expo` in `package.json` | Same as web — RN is still TSX | Guide prose, or raw `StyleSheet`/NativeWind values |
+| Swift / SwiftUI / UIKit | `Package.swift`, an `.xcodeproj`/`.xcworkspace`, or several `.swift` files | `public struct X: View` / `open class X: UIView` | Guide prose, or named colours in an `.xcassets` catalog |
+| Kotlin / Jetpack Compose | A Gradle build next to `.kt` files | `@Composable fun X(...)` | Guide prose, or named colours in `colors.xml`/`themes.xml` |
+
+`facts.platform` reports the strongest match as `primary` and every other platform
+it saw real evidence for as `detected` — a monorepo with a web app and a native
+shell is not forced into one label, it is reported honestly as both.
+
+Guides are always markdown, wherever they live: `guidelines/`, `docs/`, or — for a
+Swift package — its own `.docc` bundle, found automatically rather than requiring
+`adsa.config.json` to list it.
+
+Per platform, the agent-instructions and tokens fixes write in that platform's own
+vocabulary (SwiftUI modifiers and `swift build`/`swift test`, Compose semantics and
+`./gradlew test lint`, `StyleSheet`/NativeWind and Metro), and the accessibility
+dimension asks about VoiceOver/Dynamic Type or TalkBack/content description instead
+of demanding "keyboard" from a platform that has none. A dimension that genuinely
+does not apply is skipped — via `adsa.config.json`'s `skip` — not scored down.
+
+## What it supports honestly
+
+Detection is built for React, TypeScript and markdown guides — that path is the
+most mature — and works on any repo where guides live in markdown and components
+are exported from source. Vue and Svelte are detected but less well covered. React
+Native, Swift and Kotlin/Compose detection is newer: components, tokens and
+accessibility evidence are read from real files (see the table above), but the
+freshness fixes (`prop-tables`, `examples-check`) still assume a typed TypeScript
+component library, and their briefs say so. Anything it cannot assess it reports as
+not assessed — it never guesses a number.
+
+## Try it
+
+```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
+```
+
+`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.
+
+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:
+
+```bash
+node bin/adsa.mjs audit test/fixtures/swift-ds
+```
+
+## Licence
+
+MIT.
+
+---
+
+*From one designer to designers with love <3*

package/bin/adsa.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+/**
+ * adsa — score a design system on how well coding agents can use it, then fix what
+ * is missing.
+ *
+ *   adsa audit [dir]              score it, write the report
+ *   adsa fix <id> | --all         apply a fix, or write its task brief
+ *   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 badge                    the README badge for the committed score
+ */
+import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadConfig, resolveTarget } from "../lib/config.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 { DIR, appendHistory, compare, readHistory, write } from "../lib/history.mjs";
+import { FIXES, applyFix } from "../lib/fix.mjs";
+import { evaluate, taskFile } from "../lib/eval.mjs";
+import { findGuide, searchGuides, serve } from "../lib/mcp.mjs";
+import { dense } from "../lib/dense.mjs";
+import { readJson } from "../lib/fsx.mjs";
+import { byScore, detectColor, dim, green, red, setColor, yellow } from "../lib/color.mjs";
+
+const HELP = `adsa — agentic design system audit
+
+  npx adsa-cli <command>      without installing
+  adsa <command>              once the package is installed
+
+Usage
+  adsa audit [dir]            Score the design system in dir (default: .)
+  adsa search "<task>"        Which component do I need for this
+  adsa docs <component>       That component's guide, prose stripped
+  adsa fix <id>               Apply one fix, or write its task brief
+  adsa fix --list             What each fix does and which are automatic
+  adsa eval init              Write the experiment task for an agent
+  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 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)
+  --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: .)
+  --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 positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--json") flags.json = true;
+        else if (arg === "--gate") flags.gate = true;
+        else if (arg === "--dry-run") flags.dryRun = true;
+        else if (arg === "--quiet") flags.quiet = true;
+        else if (arg === "--list") flags.list = true;
+        else if (arg === "--full") flags.full = true;
+        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 === "--out") flags.out = argv[++i];
+        else if (arg === "--min") flags.min = Number(argv[++i]);
+        else if (arg === "--system") flags.system = argv[++i];
+        else if (arg === "--cwd") flags.cwd = argv[++i];
+        else if (arg === "--help" || arg === "-h") flags.help = true;
+        else if (arg.startsWith("-")) flags.unknown = arg;
+        else positional.push(arg);
+    }
+    return { command: positional[0], args: positional.slice(1), flags };
+}
+
+function load(dir) {
+    const given = resolve(dir || ".");
+    const target = resolveTarget(given);
+    const root = target.dir;
+    const config = loadConfig(root);
+    const facts = scan(root, config);
+    facts.workspace = target.note;
+    return { root, config, facts };
+}
+
+/** Auditing the wrong directory produces a confident, meaningless number. Say so instead. */
+function looksLikeADesignSystem(facts) {
+    if (facts.components.length >= 3 || facts.guides.length >= 2) return true;
+    // A small native design system (Swift, Kotlin) can be real with fewer files than a
+    // web one. Strong platform evidence plus at least one real component or guide is
+    // enough to not reject it just for being small.
+    const platform = facts.platform;
+    if (platform && platform.primary !== "web" && platform.detected.length && (facts.components.length >= 1 || facts.guides.length >= 1)) return true;
+    return false;
+}
+
+export async function run(argv, io = {}) {
+    const out = (s) => (io.stdout ?? process.stdout).write(s + "\n");
+    const json = (v) => out(JSON.stringify(v, null, 2));
+    const { command, args, flags } = parseArgs(argv);
+    if (flags.color !== undefined) setColor(flags.color);
+    if (flags.help || !command) {
+        out(HELP);
+        return 0;
+    }
+    if (flags.unknown) {
+        out(`Unknown option ${flags.unknown}\n\n${HELP}`);
+        return 1;
+    }
+
+    switch (command) {
+        case "audit":
+            return cmdAudit(args[0], flags, out, json);
+        case "fix":
+            return cmdFix(args, flags, out, json);
+        case "eval":
+            return cmdEval(args, flags, out, json);
+        case "mcp": {
+            const ctx = load(args[0]);
+            await serve(io.stdin ?? process.stdin, io.stdout ?? process.stdout, ctx);
+            return 0;
+        }
+        case "search":
+            return cmdSearch(args, flags, out, json);
+        case "docs":
+            return cmdDocs(args, flags, out, json);
+        case "doctor":
+            return cmdDoctor(args[0], flags, out, json);
+        case "badge":
+            return cmdBadge(args[0], flags, out, json);
+        case "rubric":
+            return cmdRubric(flags, out, json);
+        default:
+            out(`Unknown command "${command}".\n\n${HELP}`);
+            return 1;
+    }
+}
+
+/* ---------------------------------------------------------------- audit */
+
+function cmdAudit(dir, flags, out, json) {
+    const { root, config, facts } = load(dir);
+    if (!looksLikeADesignSystem(facts)) {
+        out(`${facts.name}: found ${facts.components.length} importable components and ${facts.guides.length} guides in ${root}.`);
+        out("That does not look like a design system. Point adsa at the package that exports the components,");
+        out("or set `source` and `guides` in adsa.config.json.");
+        return 1;
+    }
+    const scored = score(facts, config);
+    const outDir = flags.out || DIR;
+    const file = scoreFile(facts, scored);
+    const previous = readJson(join(root, DIR, "score.json"));
+    const delta = compare(previous, file);
+
+    if (flags.json) {
+        json({ ...file, 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}`)}`);
+        if (facts.workspace) out(`  ${facts.workspace}`);
+        if (!flags.quiet) {
+            out("");
+            for (const d of scored.dimensions) {
+                const bar = d.skipped ? dim("  skip") : byScore(d.score, "█".repeat(d.score)) + dim("·".repeat(5 - d.score));
+                out(`  ${String(d.skipped ? "—" : d.score).padStart(2)}/5 ${bar}  ${d.skipped ? dim(d.title) : d.title}`);
+            }
+            out("");
+            const todo = buildTodo(scored);
+            if (todo.length) {
+                // The command once, then the ids. Three full npx lines is 90 columns
+                // of mostly repeated prefix.
+                const rest = todo.length - 1;
+                out(dim(`Next: npx adsa-cli fix ${todo[0].fix}${rest ? `  · ${rest} more in the report` : ""}`));
+            }
+            if (delta) {
+                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));
+            }
+        }
+    }
+
+    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")}`));
+
+    if (flags.gate) {
+        const floor = flags.min ?? config.minScore ?? (previous ? previous.total : null);
+        if (floor != null && file.total < floor) {
+            out(red(`\nGate: ${file.total}/${file.max} is below ${floor}.`));
+            return 1;
+        }
+    }
+    return 0;
+}
+
+/* ------------------------------------------------------------------ fix */
+
+function cmdFix(args, flags, out, json) {
+    if (flags.list || (!args.length && !flags.all)) {
+        if (flags.json) return json(Object.entries(FIXES).map(([id, f]) => ({ id, kind: f.kind, title: f.title, dimension: f.dimension }))), 0;
+        out("Fixes\n");
+        for (const [id, fix] of Object.entries(FIXES)) {
+            out(`  ${id.padEnd(16)} ${fix.kind === "apply" ? "writes files " : "writes a brief"}  ${fix.title}`);
+        }
+        out("\n  A brief is a task specification for an agent to execute: those fixes need");
+        out("  your repository's own stack, and a generic codemod would do them badly.");
+        return 0;
+    }
+    const { root, config, facts } = load(flags.cwd || ".");
+    const ids = flags.all ? Object.keys(FIXES) : args;
+    const actions = [];
+    for (const id of ids) {
+        try {
+            actions.push(...applyFix(id, facts, config, { dryRun: flags.dryRun }).map((a) => ({ ...a, fix: id })));
+        } catch (error) {
+            out(String(error.message));
+            return 1;
+        }
+    }
+    if (flags.json) {
+        json({ dryRun: flags.dryRun, actions });
+        return 0;
+    }
+    for (const a of actions) {
+        if (a.action === "note") out(`  note   ${a.note}`);
+        else out(`  ${(flags.dryRun ? "would " + a.action : a.action).padEnd(6)} ${a.file}${a.note ? ` — ${a.note}` : ""}`);
+    }
+    const briefs = actions.filter((a) => a.file.includes(".adsa/fixes"));
+    if (briefs.length && !flags.dryRun) out(`\nHand ${briefs.length === 1 ? "the brief" : "these briefs"} to your agent, then re-run \`adsa audit\`.`);
+    return 0;
+}
+
+/* ----------------------------------------------------------------- eval */
+
+function cmdEval(args, flags, out, json) {
+    const sub = args[0];
+    if (sub === "init") {
+        const { root, config, facts } = load(args[1]);
+        const file = join(DIR, "eval", "TASK.md");
+        if (!flags.dryRun) {
+            mkdirSync(join(root, DIR, "eval"), { recursive: true });
+            writeFileSync(join(root, file), taskFile(facts, config));
+        }
+        out(`  create ${file} — give this to an agent in a fresh session`);
+        return 0;
+    }
+    if (sub === "score") {
+        const project = args[1];
+        if (!project) {
+            out("Usage: adsa eval score <project-dir> [--system <design-system-dir>]");
+            return 1;
+        }
+        const { config, facts } = load(flags.system || ".");
+        const result = evaluate(resolve(project), facts, config);
+        if (flags.json) {
+            json(result);
+            return result.invented.length ? 1 : 0;
+        }
+        out(`${result.project}`);
+        out(`  against ${result.system} — ${plural(result.files, "file")}, ${plural(result.systemImports, "import")}, ${plural(result.used.length, "component")} used`);
+        out(`  invented: ${result.invented.length ? red(String(result.invented.length)) : green("0")}`);
+        for (const i of result.invented.slice(0, 12)) out(`    ${red(i.name)} — ${i.file} (from ${i.from})`);
+        if (result.forbiddenImports.length) out(`  forbidden packages: ${[...new Set(result.forbiddenImports.map((f) => f.package))].join(", ")}`);
+        if (result.rawPalette.length) out(`  raw palette classes: ${result.rawPalette.length}, first ${result.rawPalette[0].value} at ${result.rawPalette[0].file}:${result.rawPalette[0].line}`);
+        if (result.localUiFolder.length) out(`  local component folder: ${result.localUiFolder.join(", ")}`);
+        out(`\n  ${result.invented.length ? result.verdict : green(result.verdict)}`);
+        return result.invented.length ? 1 : 0;
+    }
+    out("Usage: adsa eval init | adsa eval score <dir>");
+    return 1;
+}
+
+/* ----------------------------------------------------------- search/docs */
+
+function cmdSearch(args, flags, out, json) {
+    const { facts } = load(flags.cwd || ".");
+    const query = args.join(" ");
+    const results = searchGuides(facts, query, 10);
+    if (flags.json) {
+        json(results);
+        return results.length ? 0 : 1;
+    }
+    if (!results.length) {
+        out(`Nothing in ${facts.name} matched "${query}".`);
+        out(facts.gaps.file ? `Check ${facts.gaps.file} before assuming it exists.` : "Nothing lists what this system lacks, so ask rather than inventing it.");
+        return 1;
+    }
+    for (const r of results) out(`  ${r.slug.padEnd(22)} ${r.title || ""}  (${r.path})`);
+    return 0;
+}
+
+function cmdDocs(args, flags, out, json) {
+    const { facts } = load(flags.cwd || ".");
+    const name = args.join(" ");
+    const guide = findGuide(facts, name);
+    if (!guide) {
+        const near = searchGuides(facts, name, 5).map((r) => r.slug);
+        out(`No guide for "${name}".${near.length ? ` Closest: ${near.join(", ")}.` : ""}`);
+        return 1;
+    }
+    const body = flags.full ? guide.body : dense(guide.body);
+    if (flags.json) {
+        json({ path: guide.path, title: guide.title, body });
+        return 0;
+    }
+    out(body);
+    return 0;
+}
+
+/** One file, not 1 files. The output is read by people. */
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+/* --------------------------------------------------------------- doctor */
+
+function cmdDoctor(dir, flags, out, json) {
+    const { facts, config } = load(dir);
+    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");
+    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.");
+    const ok = !checks.some((c) => c.status === "fail");
+    if (flags.json) {
+        json({ ok, checks });
+        return ok ? 0 : 1;
+    }
+    for (const c of checks) {
+        const tint = c.status === "pass" ? green : c.status === "warn" ? yellow : red;
+        out(`  ${tint(c.status.toUpperCase().padEnd(4))} ${c.id.padEnd(11)} ${c.message}`);
+        if (c.fix) out(dim(`       ${" ".repeat(11)} → ${c.fix}`));
+    }
+    return ok ? 0 : 1;
+}
+
+/* ---------------------------------------------------------------- badge */
+
+function cmdBadge(dir, flags, out, json) {
+    const root = resolve(dir || ".");
+    const file = readJson(join(root, DIR, "score.json"));
+    if (!file) {
+        out("No .adsa/score.json yet. Run `npx adsa-cli audit` first.");
+        return 1;
+    }
+    if (flags.json) {
+        json(badgeEndpoint(file.total, file.max));
+        return 0;
+    }
+    out(badgeMarkdown(file.total, file.max));
+    return 0;
+}
+
+/* --------------------------------------------------------------- rubric */
+
+function cmdRubric(flags, out, json) {
+    if (flags.json) {
+        json(RUBRIC);
+        return 0;
+    }
+    out(`Agent readiness, rubric ${RUBRIC.version} — ${RUBRIC.dimensions.length} dimensions, ${RUBRIC.max} points\n`);
+    for (const d of RUBRIC.dimensions) {
+        out(`${d.title}`);
+        out(`  ${d.question}`);
+        for (const level of ["1", "3", "5"]) out(`    ${level}  ${d.levels[level]}`);
+        out("");
+    }
+    return 0;
+}
+
+/* ----------------------------------------------------------------- main */
+
+function isMain() {
+    if (!process.argv[1]) return false;
+    try {
+        return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+    } catch {
+        return false;
+    }
+}
+
+if (isMain()) {
+    setColor(detectColor());
+    run(process.argv.slice(2))
+        .then((code) => process.exit(code))
+        .catch((error) => {
+            process.stderr.write(`adsa: ${error.stack || error.message}\n`);
+            process.exit(1);
+        });
+}

package/lib/badge.mjs

@@ -0,0 +1,28 @@
+/** README badge. Static shields.io URL, plus an endpoint file for repos that prefer one.
+ *
+ * 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"],
+];
+
+export function badgeColor(total, max) {
+    const ratio = max ? total / max : 0;
+    return COLORS.find(([floor]) => ratio >= floor)[1];
+}
+
+export function badgeMarkdown(total, max, link) {
+    const url = `https://img.shields.io/badge/agent--ready-${total}%2F${max}-${badgeColor(total, max)}`;
+    const img = `![Agent-ready ${total}/${max}](${url})`;
+    return link ? `[${img}](${link})` : img;
+}
+
+/** shields.io endpoint schema, so a badge can read the committed score directly. */
+export function badgeEndpoint(total, max) {
+    return { schemaVersion: 1, label: "agent-ready", message: `${total}/${max}`, color: `#${badgeColor(total, max)}` };
+}

package/lib/color.mjs

@@ -0,0 +1,32 @@
+/**
+ * ANSI colour. Off by default so piped output, CI logs and tests stay plain text;
+ * the bin turns it on when it is talking to a real terminal.
+ */
+let enabled = false;
+
+export function setColor(on) {
+    enabled = Boolean(on);
+}
+
+/** A real terminal, unless the environment says otherwise. Honours NO_COLOR and FORCE_COLOR. */
+export function detectColor(stream = process.stdout, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "") return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0") return true;
+    if (env.TERM === "dumb") return false;
+    return Boolean(stream && stream.isTTY);
+}
+
+const wrap = (open, close) => (text) => (enabled ? `\x1b[${open}m${text}\x1b[${close}m` : String(text));
+
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const dim = wrap(2, 22);
+export const bold = wrap(1, 22);
+
+/** 1 is a problem, 3 is a compromise, 5 is done. The bars carry that without a legend. */
+export function byScore(score, text) {
+    if (score >= 5) return green(text);
+    if (score >= 3) return yellow(text);
+    return red(text);
+}