agentready-design-cli 0.1.0 → 0.2.1

package/README.md

@@ -1,37 +1,72 @@
 # agentready-design-cli
 
-Deterministic checks for the [Agent-Ready Design rubric](https://github.com/hgillispie/Agent-Ready-Design). Walks a design-system repo and scores everything that can be scored without an LLM. Emits Markdown + JSON in the [shared report format](../../schema/).
+Score a design system against the [Agent-Ready Design rubric](https://github.com/hgillispie/Agent-Ready-Design) in one command.
 
-## Usage
+## Quick start
+
+### Deterministic + paste-into-agent (zero config)
 
 ```bash
 npx agentready-design-cli ./path/to/your/design-system
 ```
 
-Writes `agent-ready-report.md` and `agent-ready-report.json` next to the target. Anything that requires judgment is emitted as `status: "pending"` — the report stays complete.
+Walks the repo, scores everything that can be scored without a model, and writes a paste-ready prompt for the rest:
 
-### Flags
+```
+✓ ./agent-ready-report.json
+✓ ./agent-ready-report.md
+✓ ./agent-ready-prompt.md      ← paste this into your agent
 
+Tier 1 — Human-ready, AI-hostile  ·  floor 2/4  ·  retrieval 1/4  ·  median 2.0/4
 ```
---format markdown|json|both   # default both
---out <dir>                   # default = target path
---target <name>               # friendly name in the report header
---merge <existing.json>       # only re-run pending criteria from a prior run
---help
+
+### Fully auto-scored (hosted API, no agent needed)
+
+```bash
+npx agentready-design-cli ./your-ds --remote
 ```
 
-### Output
+Same as above, but also calls the hosted scoring endpoint (Claude Haiku) to fill in the judgment-required rows. **You don't need an API key** — the endpoint is hosted by the project. Privacy notes below.
 
-A Markdown heatmap with a `0`–`4` cell per criterion (and `?` for pending), and a JSON file conforming to [`schema/report.schema.json`](../../schema/report.schema.json).
+## Flags
 
 ```
-Tier 1 — Human-ready, AI-hostile  ·  floor 2/4  ·  retrieval 1/4  ·  median 2.0/4
-12 criteria require an agent. Paste prompts/self-assessment.md to complete the report.
+--format markdown|json|both   default both
+--out <dir>                   default = target path
+--target <name>               friendly name in the report header
+--merge <existing.json>       only re-run pending criteria from a prior run
+--remote                      auto-fill pending rows via the hosted scoring API
+--api <url>                   override the API endpoint (default agentreadydesign.com)
+--no-prompt                   skip writing agent-ready-prompt.md
+--help
 ```
 
-## What it checks
+## What gets scored
 
-Roughly half the rubric is deterministically checkable; the rest is `pending: requires-agent`. See [`CRITERIA.md`](./CRITERIA.md) for the full split.
+| | |
+|---|---|
+| Deterministic checks (no model needed) | tokens dir, DTCG format, `AGENTS.md`, `llms.txt`, component manifest, layout primitives, raw `<button>`/`<input>` in components, hex literals in component CSS, Storybook config, Chromatic/Percy, axe, semver, … |
+| Judgment-required (filled by `--remote` or paste-prompt) | prop-naming consistency, anti-pattern docs, composition rules, doc structure, hand-curation of AGENTS.md, drift detection, eval suite, trust levels, governance |
+
+See [`CRITERIA.md`](./CRITERIA.md) for the full split.
+
+## Privacy — what `--remote` sends
+
+When you pass `--remote`, the CLI sends a curated sample (up to ~60 KB) of your repo to `https://agentreadydesign.com/api/score`. Files included:
+
+- `package.json`, `README.md`, `tsconfig.json`
+- `AGENTS.md`, `.builder/AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`
+- `llms.txt`, `llms-full.txt`
+- `custom-elements.json`, `registry.json`, Storybook main config
+- Token files under `tokens/`, `src/tokens/`, `packages/tokens/`
+- Up to 5 component files from each of `components/`, `src/components/`, `packages/ui/src/`
+- Up to 3 files each from `patterns/` and `recipes/`
+
+Hard caps: ≤40 files, ≤4 KB per file, ≤60 KB total. Files matching `.env*`, `*.key`, `*.pem`, etc. are never matched by the included glob patterns.
+
+The endpoint forwards your sample to Anthropic Claude Haiku for scoring and returns only the deltas. No content is logged or retained. Source: [`site/netlify/functions/score.ts`](https://github.com/hgillispie/Agent-Ready-Design/blob/main/site/netlify/functions/score.ts).
+
+**If you'd rather not send anything**: omit `--remote`. The default flow writes a paste-ready prompt locally and your AI tool reads your repo directly.
 
 ## Programmatic use
 
@@ -42,10 +77,6 @@ const report = await runAssessment({ target: "./packages/ui" });
 console.log(renderMarkdown(report));
 ```
 
-## Pair it with the prompt
-
-After running the CLI, paste [`prompts/self-assessment.md`](https://github.com/hgillispie/Agent-Ready-Design/blob/main/prompts/self-assessment.md) into your agent. It will detect `agent-ready-report.json` at the repo root and fill in only the `pending` rows, marking `producer.kind: "merged"` in the output.
-
 ## License
 
 MIT.

package/dist/{chunk-GWF7PSLR.js → chunk-WHGIRQPX.js}

@@ -1,5 +1,125 @@
 #!/usr/bin/env node
 
+// src/context.ts
+import { readFile, stat } from "fs/promises";
+import { resolve, relative, sep } from "path";
+import fg from "fast-glob";
+var IGNORES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/.astro/**",
+  "**/.cache/**",
+  "**/.turbo/**",
+  "**/coverage/**",
+  "**/.git/**"
+];
+var CheckContext = class {
+  root;
+  fileCache = /* @__PURE__ */ new Map();
+  globCache = /* @__PURE__ */ new Map();
+  pkgJsonCache;
+  constructor(root) {
+    this.root = resolve(root);
+  }
+  resolve(...p) {
+    return resolve(this.root, ...p);
+  }
+  relative(p) {
+    return relative(this.root, p).split(sep).join("/");
+  }
+  async exists(rel) {
+    try {
+      await stat(this.resolve(rel));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async existsAny(rels) {
+    for (const r of rels) {
+      if (await this.exists(r)) return r;
+    }
+    return null;
+  }
+  async readFile(rel) {
+    if (this.fileCache.has(rel)) return this.fileCache.get(rel) ?? null;
+    try {
+      const content = await readFile(this.resolve(rel), "utf8");
+      this.fileCache.set(rel, content);
+      return content;
+    } catch {
+      this.fileCache.set(rel, null);
+      return null;
+    }
+  }
+  async glob(pattern, opts) {
+    const key = JSON.stringify({ p: pattern, i: opts?.ignore ?? null });
+    const cached = this.globCache.get(key);
+    if (cached) return cached;
+    const matches = await fg(pattern, {
+      cwd: this.root,
+      ignore: [...IGNORES, ...opts?.ignore ?? []],
+      dot: true,
+      onlyFiles: true,
+      followSymbolicLinks: false
+    });
+    matches.sort();
+    this.globCache.set(key, matches);
+    return matches;
+  }
+  async firstMatch(pattern) {
+    const matches = await this.glob(pattern);
+    return matches[0] ?? null;
+  }
+  async pkgJson() {
+    if (this.pkgJsonCache !== void 0) return this.pkgJsonCache;
+    const raw = await this.readFile("package.json");
+    if (!raw) {
+      this.pkgJsonCache = null;
+      return null;
+    }
+    try {
+      this.pkgJsonCache = JSON.parse(raw);
+    } catch {
+      this.pkgJsonCache = null;
+    }
+    return this.pkgJsonCache;
+  }
+  /**
+   * Heuristic "component directories" — places to look for component source.
+   * Covers common conventions: top-level components/, ui/, lib/, src/, packages/*\/src.
+   */
+  async componentDirs() {
+    const candidates = [
+      "components",
+      "src/components",
+      "src/ui",
+      "ui",
+      "lib/components",
+      "packages/ui/src",
+      "packages/components/src",
+      "packages/ui/src/components"
+    ];
+    const found = [];
+    for (const c of candidates) {
+      if (await this.exists(c)) found.push(c);
+    }
+    if (found.length === 0) {
+      const pkgs = await this.glob("packages/*/package.json");
+      for (const p of pkgs) {
+        const base = p.replace(/\/package\.json$/, "");
+        for (const sub of ["src", "src/components", "components"]) {
+          const full = `${base}/${sub}`;
+          if (await this.exists(full)) found.push(full);
+        }
+      }
+    }
+    return found;
+  }
+};
+
 // src/rubric.ts
 var RUBRIC = [
   // Category 1 — Tokens & Foundations
@@ -151,126 +271,6 @@ function generateBacklog(criteria) {
   }));
 }
 
-// src/context.ts
-import { readFile, stat } from "fs/promises";
-import { resolve, relative, sep } from "path";
-import fg from "fast-glob";
-var IGNORES = [
-  "**/node_modules/**",
-  "**/dist/**",
-  "**/build/**",
-  "**/.next/**",
-  "**/.astro/**",
-  "**/.cache/**",
-  "**/.turbo/**",
-  "**/coverage/**",
-  "**/.git/**"
-];
-var CheckContext = class {
-  root;
-  fileCache = /* @__PURE__ */ new Map();
-  globCache = /* @__PURE__ */ new Map();
-  pkgJsonCache;
-  constructor(root) {
-    this.root = resolve(root);
-  }
-  resolve(...p) {
-    return resolve(this.root, ...p);
-  }
-  relative(p) {
-    return relative(this.root, p).split(sep).join("/");
-  }
-  async exists(rel) {
-    try {
-      await stat(this.resolve(rel));
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  async existsAny(rels) {
-    for (const r of rels) {
-      if (await this.exists(r)) return r;
-    }
-    return null;
-  }
-  async readFile(rel) {
-    if (this.fileCache.has(rel)) return this.fileCache.get(rel) ?? null;
-    try {
-      const content = await readFile(this.resolve(rel), "utf8");
-      this.fileCache.set(rel, content);
-      return content;
-    } catch {
-      this.fileCache.set(rel, null);
-      return null;
-    }
-  }
-  async glob(pattern, opts) {
-    const key = JSON.stringify({ p: pattern, i: opts?.ignore ?? null });
-    const cached = this.globCache.get(key);
-    if (cached) return cached;
-    const matches = await fg(pattern, {
-      cwd: this.root,
-      ignore: [...IGNORES, ...opts?.ignore ?? []],
-      dot: true,
-      onlyFiles: true,
-      followSymbolicLinks: false
-    });
-    matches.sort();
-    this.globCache.set(key, matches);
-    return matches;
-  }
-  async firstMatch(pattern) {
-    const matches = await this.glob(pattern);
-    return matches[0] ?? null;
-  }
-  async pkgJson() {
-    if (this.pkgJsonCache !== void 0) return this.pkgJsonCache;
-    const raw = await this.readFile("package.json");
-    if (!raw) {
-      this.pkgJsonCache = null;
-      return null;
-    }
-    try {
-      this.pkgJsonCache = JSON.parse(raw);
-    } catch {
-      this.pkgJsonCache = null;
-    }
-    return this.pkgJsonCache;
-  }
-  /**
-   * Heuristic "component directories" — places to look for component source.
-   * Covers common conventions: top-level components/, ui/, lib/, src/, packages/*\/src.
-   */
-  async componentDirs() {
-    const candidates = [
-      "components",
-      "src/components",
-      "src/ui",
-      "ui",
-      "lib/components",
-      "packages/ui/src",
-      "packages/components/src",
-      "packages/ui/src/components"
-    ];
-    const found = [];
-    for (const c of candidates) {
-      if (await this.exists(c)) found.push(c);
-    }
-    if (found.length === 0) {
-      const pkgs = await this.glob("packages/*/package.json");
-      for (const p of pkgs) {
-        const base = p.replace(/\/package\.json$/, "");
-        for (const sub of ["src", "src/components", "components"]) {
-          const full = `${base}/${sub}`;
-          if (await this.exists(full)) found.push(full);
-        }
-      }
-    }
-    return found;
-  }
-};
-
 // src/checks/category-1-tokens.ts
 var TOKEN_DIRS = ["tokens", "src/tokens", "design-tokens", "src/design-tokens", "packages/tokens"];
 async function findTokenSources(ctx) {
@@ -1197,6 +1197,7 @@ function renderMarkdown(report) {
 }
 
 export {
+  CheckContext,
   RUBRIC,
   TOTAL_CRITERIA,
   computeRollup,

package/dist/cli.js

@@ -1,15 +1,411 @@
 #!/usr/bin/env node
 import {
+  CheckContext,
   TIER_LABELS,
+  computeRollup,
+  generateBacklog,
   renderMarkdown,
   runAssessment
-} from "./chunk-GWF7PSLR.js";
+} from "./chunk-WHGIRQPX.js";
 
 // src/cli.ts
 import { writeFile, mkdir } from "fs/promises";
-import { dirname, resolve } from "path";
+import { dirname, resolve, relative } from "path";
 import { existsSync } from "fs";
 import kleur from "kleur";
+
+// src/embedded.ts
+var SELF_ASSESSMENT_PROMPT = `# Agent-Ready Design \u2014 Self-Assessment Prompt
+
+> Paste this prompt into Builder.io Fusion, Cursor, Codex, Claude Code, or any agentic coding tool with your design system repository open as the working directory. The agent will score it against the v0.1 Agent-Ready Design rubric and emit a Markdown heatmap and a JSON sidecar in the format defined at [schema/report.schema.json](https://github.com/hgillispie/Agent-Ready-Design/blob/main/schema/report.schema.json).
+
+---
+
+You are auditing the current repository against the **Agent-Ready Design v0.1 rubric**. The canonical rubric is at \`https://github.com/hgillispie/Agent-Ready-Design/blob/main/RUBRIC.md\`. If you have web access, fetch it. Otherwise rely on the inline summary below \u2014 it is sufficient for scoring.
+
+## Your job
+
+1. Traverse the repository. Identify it as a design system (or a repo *containing* one \u2014 e.g. a monorepo with a \`packages/ui\` package).
+2. **If a file named \`agent-ready-report.json\` exists at the repo root, load it.** It was produced by \`agentready-design-cli\`. Trust its \`score\`/\`evidence\` for any criterion with \`status: "scored"\` unless you find clear contradicting evidence. Complete every criterion with \`status: "pending"\`. Set \`producer.kind\` to \`"merged"\` in your output.
+3. Otherwise, score every criterion 0\u20134 from scratch.
+4. Emit **both** a Markdown heatmap AND a JSON file conforming to the shared schema. Write the JSON to \`agent-ready-report.json\` at the repo root. Print the Markdown in your response.
+5. Surface the **foundational floor** (lowest score in Categories 1\u20134) prominently. Below 2 means the system will ship "uncanny valley" output regardless of any retrieval infrastructure.
+6. Produce a **prioritized 5\u201310 item action backlog**. Rank by leverage on the foundational floor first, retrieval level second.
+
+## Scoring scale
+
+| Level | Meaning |
+|---|---|
+| 0 | Absent. Does not exist or is not discoverable. |
+| 1 | Ad hoc. Exists but incomplete, inconsistent, or human-only. |
+| 2 | Documented. Human-readable, consistent. |
+| 3 | Machine-readable. Structured data agents can ingest, discoverable from a single canonical entry. |
+| 4 | Agent-native. Exposed via MCP/registry + validated by an automated eval loop. |
+
+## The rubric \u2014 all 31 criteria
+
+### Category 1 \u2014 Tokens & Foundations
+
+- **1.1** Tokens exist as exported, versioned source files (canonical \`/tokens/\` dir, JSON/YAML/CSS, not Figma-only).
+- **1.2** Semantic tokens exist on top of primitives; components reference semantics.
+- **1.3** Tokens are closed and enumerable from a single source.
+- **1.4** Token usage is enforced (lint/CI rejects raw hex/px in component CSS).
+
+### Category 2 \u2014 Component API Contract
+
+- **2.1** Every component has a machine-readable manifest (CEM 2.x, Storybook Component Manifest, custom JSON, or react-docgen) covering props/variants/slots/events.
+- **2.2** Prop naming is consistent across the library (e.g. visual prominence always \`variant\`, size always \`size\`).
+- **2.3** Composition and slot rules are explicit (compound-component children/parents enumerated).
+- **2.4** Anti-patterns are documented per component (Do/Don't, "when not to use").
+- **2.5** Accessibility metadata travels with the component (ARIA, keyboard, focus, in a structured field).
+
+### Category 3 \u2014 Documentation Format
+
+- **3.1** Single canonical docs site, no scattered duplicates.
+- **3.2** Component pages have a stable, predictable structure (front-matter + section ordering).
+- **3.3** At least 3 concrete usage examples per component, including anti-patterns.
+- **3.4** \`llms.txt\` (and ideally \`llms-full.txt\`) is published at the docs root.
+
+### Category 4 \u2014 Composition & Layout
+
+- **4.1** Layout primitives (\`Stack\`, \`Inline\`, \`Grid\`, \`Box\`, \`Container\`) exist as first-class components.
+- **4.2** Responsive conventions are explicit and uniform (single canonical pattern, tokenized breakpoints).
+- **4.3** A "patterns" or "recipes" layer exists for compositions agents should reuse.
+
+### Category 5 \u2014 Retrieval & Discoverability
+
+- **5.1** \`AGENTS.md\` (or \`CLAUDE.md\`) exists and is **hand-curated** (per ETH Zurich evidence, auto-generated ones often *hurt* performance).
+- **5.2** An MCP server (or registry endpoint) exposes the system to agents.
+- **5.3** Always-on foundational rules (spacing/color/type) are injected into every agent run via rules files.
+- **5.4** Components are addressable by stable, predictable identifiers (one canonical import path).
+
+### Category 6 \u2014 Distribution & Versioning
+
+- **6.1** Installable through a single well-known mechanism (npm package, shadcn registry, monorepo workspace \u2014 not "copy from Confluence").
+- **6.2** Breaking changes and deprecations are machine-readable (manifest \`deprecated: true\`, codemods).
+- **6.3** A clear "current vs. latest" version is communicated to agents (AGENTS.md states target version).
+
+### Category 7 \u2014 Quality Signals
+
+- **7.1** Every component has interaction tests / stories.
+- **7.2** Visual regression is in place.
+- **7.3** Accessibility checks are automated (axe/Lighthouse in CI).
+- **7.4** Code quality and consistency within the library itself (no raw hex codes internally).
+
+### Category 8 \u2014 Evaluation & Governance for Agents
+
+- **8.1** An eval suite tests agent output against the design system.
+- **8.2** Trust levels are defined for agent actions (suggest / PR / auto-merge).
+- **8.3** Drift detection between docs, tokens, and code.
+- **8.4** Generated-code attribution and review (PRs from agents are labeled and tracked).
+
+## How to score
+
+For each criterion:
+
+1. State the **observable signal** you'd look for (the rubric is specific about this; the inline summary above lists the headline signal \u2014 read it carefully).
+2. Look. Use \`grep\`, \`find\`, \`ls\`, \`cat\`, AST traversal, whatever is appropriate. Prefer evidence from the repo over training-data priors.
+3. Pick a score 0\u20134. **Be strict.** A \`custom-elements.json\` with \`variant: string\` instead of an enumerated union is a 2, not a 3. An auto-generated \`AGENTS.md\` is a 1, not a 3. \`llms.txt\` pointing to outdated MDX is gaming the rubric.
+4. Record one sentence of rationale and at least one file path (with a line number where useful) as evidence.
+
+## Output \u2014 Markdown
+
+Print this format in your response:
+
+\`\`\`markdown
+# Agent-Ready Design \u2014 Assessment
+
+**Target:** \`<repo name or path>\`
+**Producer:** <agent name> (paste-prompt)
+**Generated:** <ISO 8601 timestamp>
+
+## Roll-up
+
+- **Foundational floor (Categories 1\u20134): N / 4** \u2014 <one-line interpretation>
+- **Retrieval level (Category 5 max): N / 4**
+- **Overall median: N.N / 4**
+- **Tier: N \u2014 <label>** (per RUBRIC.md \xA74)
+
+## Heatmap
+
+| Cat | 1 | 2 | 3 | 4 | 5 | Floor | Median |
+|---|---|---|---|---|---|---|---|
+| **1. Tokens & Foundations** | N | N | N | N | \u2013 | N | N |
+| **2. Component API Contract** | N | N | N | N | N | N | N |
+| **3. Documentation Format** | N | N | N | N | \u2013 | N | N |
+| **4. Composition & Layout** | N | N | N | \u2013 | \u2013 | N | N |
+| **5. Retrieval & Discoverability** | N | N | N | N | \u2013 | N | N |
+| **6. Distribution & Versioning** | N | N | N | \u2013 | \u2013 | N | N |
+| **7. Quality Signals** | N | N | N | N | \u2013 | N | N |
+| **8. Evaluation & Governance** | N | N | N | N | \u2013 | N | N |
+
+(Use the criterion number, not stars or emoji. Use \`\u2013\` for cells that don't exist \u2014 e.g. Category 4 only has 3 criteria.)
+
+## Per-criterion
+
+### Category 1 \u2014 Tokens & Foundations
+
+- **1.1 Tokens exist as exported, versioned source files. \u2014 N/4**
+  - Rationale: <one sentence>
+  - Evidence: \`tokens/colors.json:1\` \u2026
+  - Suggestion: <how to raise one level>
+
+\u2026 (continue for every criterion)
+
+## Prioritized backlog
+
+1. **<Action title>** \u2014 Criteria <ids>. <One-sentence rationale.> _Effort: hours/days/weeks/months._
+2. \u2026
+\`\`\`
+
+## Output \u2014 JSON
+
+Also write \`agent-ready-report.json\` at the repo root, conforming to the schema below. **Every criterion must be present** \u2014 use \`status: "pending"\` if you cannot score one. Use \`status: "skipped"\` for criteria that don't apply (e.g. a Vue-only repo skipping \`2.1\` CEM-vs-react-docgen distinctions \u2014 but still attempt scoring first).
+
+\`\`\`jsonc
+{
+  "schemaVersion": "0.1.0",
+  "rubricVersion": "0.1.0",
+  "generatedAt": "<ISO timestamp>",
+  "target": { "path": "<repo path>", "name": "<optional>" },
+  "producer": { "kind": "prompt", "name": "self-assessment.md", "version": "0.1.0" },
+  "criteria": [
+    {
+      "id": "1.1",
+      "category": 1,
+      "title": "Tokens exist as exported, versioned source files.",
+      "score": 2,
+      "status": "scored",
+      "rationale": "tokens/colors.css exists but no DTCG JSON export.",
+      "evidence": [
+        { "kind": "file", "path": "tokens/colors.css", "line": 1 },
+        { "kind": "glob", "path": "**/*.tokens.json", "detail": "no matches" }
+      ],
+      "suggestion": "Add Style Dictionary v4 with DTCG JSON output."
+    }
+    // \u2026 one entry per criterion (31 total) \u2026
+  ],
+  "rollup": {
+    "foundationalFloor": 1,
+    "retrievalLevel": 0,
+    "overallMedian": 1.5,
+    "tier": 1,
+    "categoryFloors": { "1": 1, "2": 2, "3": 1, "4": 2, "5": 0, "6": 2, "7": 1, "8": 0 },
+    "categoryMedians": { "1": 2, "2": 2, "3": 1.5, "4": 2, "5": 0.5, "6": 2, "7": 1, "8": 0 }
+  },
+  "backlog": [
+    {
+      "title": "Publish tokens as DTCG-formatted JSON",
+      "criteria": ["1.1", "1.3"],
+      "priority": 1,
+      "estimatedEffort": "days",
+      "rationale": "Foundational floor \u2014 unblocks Categories 2 and 5."
+    }
+  ]
+}
+\`\`\`
+
+## Roll-up rules
+
+- \`foundationalFloor\` = min(scores in Categories 1\u20134). If any criterion in 1\u20134 is \`pending\`, treat the floor as unknown and explicitly say so.
+- \`retrievalLevel\` = max(scores in Category 5).
+- \`overallMedian\` = median of all scored criteria (ignore pending/skipped).
+- Tier mapping (per RUBRIC.md \xA74):
+  - **0 \u2014 Pre-agentic.** Foundational floor 0\u20131.
+  - **1 \u2014 Human-ready, AI-hostile.** Foundational floor 2, retrieval 0\u20131.
+  - **2 \u2014 Agent-legible.** Foundational floor 2, retrieval 2, overall median 2.
+  - **3 \u2014 Agent-collaborative.** Foundational floor 3, retrieval 3, overall median 3.
+  - **4 \u2014 Self-healing.** All categories \u2265 3 and Category 8 \u2265 3.
+
+## Rules of engagement
+
+- **Be honest.** A confidently wrong "3" is worse than a humble "1, here's what's missing."
+- **Be specific.** Every score needs a file path or a "I looked for X and did not find it" note.
+- **Be brief.** One sentence of rationale. The evidence array does the talking.
+- **Do not invent files.** If you can't find a manifest, score the criterion \`1\` or \`0\` \u2014 do not pretend it exists.
+- **Use the repo's own language.** If they say "Tokens v2" call it that, not "your design token system."
+
+When you're done, print the Markdown heatmap, confirm that you've written \`agent-ready-report.json\`, and stop. Do not modify any other repo files.
+`;
+
+// src/remote.ts
+var DEFAULT_API_URL = "https://agentreadydesign.com/api/score";
+var MAX_FILE_BYTES = 4 * 1024;
+var MAX_TOTAL_BYTES = 60 * 1024;
+var MAX_FILES = 40;
+var ALWAYS_PATHS = [
+  "package.json",
+  "README.md",
+  "AGENTS.md",
+  ".builder/AGENTS.md",
+  "CLAUDE.md",
+  ".cursorrules",
+  ".windsurfrules",
+  ".clinerules",
+  "llms.txt",
+  "llms-full.txt",
+  "custom-elements.json",
+  ".storybook/main.ts",
+  ".storybook/main.tsx",
+  ".storybook/main.js",
+  ".storybook/main.cjs",
+  ".storybook/main.mjs",
+  "tsconfig.json",
+  "registry.json"
+];
+var SAMPLE_GLOBS = [
+  { pattern: "tokens/**/*.{json,css,scss}", max: 5 },
+  { pattern: "src/tokens/**/*.{json,css,scss}", max: 5 },
+  { pattern: "packages/tokens/**/*.json", max: 3 },
+  { pattern: "components/*.{ts,tsx,jsx,vue,svelte}", max: 5 },
+  { pattern: "src/components/*.{ts,tsx,jsx,vue,svelte}", max: 5 },
+  { pattern: "src/components/**/index.{ts,tsx,jsx}", max: 5 },
+  { pattern: "packages/ui/src/**/*.{ts,tsx,jsx}", max: 5 },
+  { pattern: "patterns/**/*.{md,tsx,jsx}", max: 3 },
+  { pattern: "recipes/**/*.{md,tsx,jsx}", max: 3 }
+];
+async function gatherSample(ctx) {
+  const sample = [];
+  const seen = /* @__PURE__ */ new Set();
+  let totalBytes = 0;
+  const tryAdd = async (rel) => {
+    if (sample.length >= MAX_FILES) return false;
+    if (totalBytes >= MAX_TOTAL_BYTES) return false;
+    if (seen.has(rel)) return false;
+    const content = await ctx.readFile(rel);
+    if (!content) return false;
+    const truncated = content.length > MAX_FILE_BYTES ? content.slice(0, MAX_FILE_BYTES) + "\n\u2026[truncated]" : content;
+    if (totalBytes + truncated.length > MAX_TOTAL_BYTES) return false;
+    sample.push({ path: rel, content: truncated });
+    seen.add(rel);
+    totalBytes += truncated.length;
+    return true;
+  };
+  for (const p of ALWAYS_PATHS) await tryAdd(p);
+  for (const { pattern, max } of SAMPLE_GLOBS) {
+    const matches = await ctx.glob(pattern);
+    for (const m of matches.slice(0, max)) await tryAdd(m);
+  }
+  return sample;
+}
+var PENDING_PER_CHUNK = 6;
+async function callRemote(opts) {
+  const pending = opts.report.criteria.filter((c) => c.status === "pending");
+  if (pending.length === 0) return { deltas: [] };
+  const scored = opts.report.criteria.filter((c) => c.status === "scored");
+  const chunks = [];
+  for (let i = 0; i < pending.length; i += PENDING_PER_CHUNK) {
+    chunks.push(pending.slice(i, i + PENDING_PER_CHUNK));
+  }
+  const results = await Promise.all(
+    chunks.map(
+      (chunk) => callRemoteOnce({
+        apiUrl: opts.apiUrl,
+        sample: opts.sample,
+        signal: opts.signal,
+        // Each chunk gets its own pending subset plus the full scored context.
+        report: {
+          ...opts.report,
+          criteria: [...chunk, ...scored]
+        }
+      })
+    )
+  );
+  const deltas = results.flatMap((r) => r.deltas ?? []);
+  const totalInput = results.reduce(
+    (n, r) => n + (r.meta?.inputTokens ?? 0),
+    0
+  );
+  const totalOutput = results.reduce(
+    (n, r) => n + (r.meta?.outputTokens ?? 0),
+    0
+  );
+  return {
+    deltas,
+    meta: {
+      model: results[0]?.meta?.model,
+      pendingScored: deltas.length,
+      inputTokens: totalInput,
+      outputTokens: totalOutput
+    }
+  };
+}
+async function callRemoteOnce(opts) {
+  const url = opts.apiUrl ?? process.env.AGENT_READY_API_URL ?? DEFAULT_API_URL;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ report: opts.report, sample: opts.sample }),
+    signal: opts.signal
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    let detail = text;
+    try {
+      const parsed = JSON.parse(text);
+      detail = parsed.error ? `${parsed.error}${parsed.detail ? ": " + parsed.detail : ""}` : text;
+    } catch {
+    }
+    throw new Error(`API ${res.status} ${res.statusText}: ${detail}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`API returned non-JSON: ${text.slice(0, 200)}`);
+  }
+}
+function clampScore(s) {
+  if (typeof s !== "number") return null;
+  const r = Math.round(s);
+  if (r < 0 || r > 4) return null;
+  return r;
+}
+function sanitizeEvidence(e) {
+  if (!Array.isArray(e)) return [];
+  const out = [];
+  for (const item of e.slice(0, 5)) {
+    if (!item || typeof item !== "object") continue;
+    const obj = item;
+    const kind = obj.kind;
+    if (kind !== "file" && kind !== "glob" && kind !== "command" && kind !== "url" && kind !== "note")
+      continue;
+    out.push({
+      kind,
+      ...typeof obj.path === "string" ? { path: obj.path } : {},
+      ...typeof obj.detail === "string" ? { detail: obj.detail.slice(0, 500) } : {},
+      ...typeof obj.snippet === "string" ? { snippet: obj.snippet.slice(0, 500) } : {}
+    });
+  }
+  return out;
+}
+function mergeDeltas(report, response) {
+  const byId = new Map(response.deltas.map((d) => [d.id, d]));
+  const criteria = report.criteria.map((c) => {
+    if (c.status !== "pending") return c;
+    const delta = byId.get(c.id);
+    if (!delta) return c;
+    const score = clampScore(delta.score);
+    if (score === null) return c;
+    return {
+      ...c,
+      score,
+      status: "scored",
+      pending: void 0,
+      rationale: typeof delta.rationale === "string" ? delta.rationale : c.rationale,
+      evidence: sanitizeEvidence(delta.evidence),
+      ...typeof delta.suggestion === "string" ? { suggestion: delta.suggestion } : {}
+    };
+  });
+  return {
+    ...report,
+    criteria,
+    rollup: computeRollup(criteria),
+    backlog: generateBacklog(criteria),
+    producer: { ...report.producer, kind: "merged" }
+  };
+}
+
+// src/cli.ts
 function parseArgs(argv) {
   const args = argv.slice(2);
   let target = ".";
@@ -17,6 +413,9 @@ function parseArgs(argv) {
   let out = ".";
   let name;
   let merge;
+  let noPrompt = false;
+  let remote = false;
+  let apiUrl;
   let help = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -25,12 +424,15 @@ function parseArgs(argv) {
     else if (a === "--out") out = args[++i] ?? ".";
     else if (a === "--target") name = args[++i];
     else if (a === "--merge") merge = args[++i];
+    else if (a === "--no-prompt") noPrompt = true;
+    else if (a === "--remote") remote = true;
+    else if (a === "--api") apiUrl = args[++i];
     else if (!a.startsWith("-")) target = a;
   }
-  return { target, format, out, name, merge, help };
+  return { target, format, out, name, merge, noPrompt, remote, apiUrl, help };
 }
 var HELP = `
-${kleur.bold("agent-ready")} \u2014 score a design system against the Agent-Ready Design rubric.
+${kleur.bold("agentready-design-cli")} \u2014 score a design system against the Agent-Ready Design rubric.
 
 ${kleur.bold("Usage")}
   npx agentready-design-cli [path] [options]
@@ -40,13 +442,46 @@ ${kleur.bold("Options")}
   --out <dir>                     Directory to write reports into. Default: <path>.
   --target <name>                 Friendly name for the report header.
   --merge <file.json>             Existing agent-ready-report.json to merge into (re-runs only pending rows).
+  --no-prompt                     Don't write agent-ready-prompt.md alongside the report.
+  --remote                        Auto-fill pending rows by calling the hosted scoring API.
+                                  (sends a sample of your repo files; see PRIVACY note in the README)
+  --api <url>                     Override the API endpoint URL (default ${DEFAULT_API_URL}).
   -h, --help                      Show this help.
 
 ${kleur.bold("Examples")}
   npx agentready-design-cli ./packages/ui
+  npx agentready-design-cli ./ds --remote
   npx agentready-design-cli ./ds --format markdown --target "Acme UI"
   npx agentready-design-cli ./ds --merge ./ds/agent-ready-report.json
 `;
+function displayPath(p, cwd) {
+  const rel = relative(cwd, p);
+  return rel === "" ? "." : rel.startsWith("..") ? p : `./${rel}`;
+}
+async function writeReports(outDir, report, format, writePromptFile) {
+  const written = [];
+  await mkdir(outDir, { recursive: true });
+  if (format === "json" || format === "both") {
+    const p = resolve(outDir, "agent-ready-report.json");
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, JSON.stringify(report, null, 2) + "\n", "utf8");
+    written.push(p);
+  }
+  if (format === "markdown" || format === "both") {
+    const p = resolve(outDir, "agent-ready-report.md");
+    await writeFile(p, renderMarkdown(report) + "\n", "utf8");
+    written.push(p);
+  }
+  const pendingCount = report.criteria.filter(
+    (c) => c.status === "pending"
+  ).length;
+  if (pendingCount > 0 && writePromptFile) {
+    const p = resolve(outDir, "agent-ready-prompt.md");
+    await writeFile(p, SELF_ASSESSMENT_PROMPT, "utf8");
+    written.push(p);
+  }
+  return written;
+}
 async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
@@ -60,19 +495,47 @@ async function main() {
     return;
   }
   console.log(kleur.dim(`Scoring ${target} against Agent-Ready Design v0.1...`));
-  const report = await runAssessment({ target, name: opts.name, merge: opts.merge });
-  const outDir = resolve(opts.out);
-  await mkdir(outDir, { recursive: true });
-  if (opts.format === "json" || opts.format === "both") {
-    const p = resolve(outDir, "agent-ready-report.json");
-    await mkdir(dirname(p), { recursive: true });
-    await writeFile(p, JSON.stringify(report, null, 2) + "\n", "utf8");
-    console.log(kleur.green(`\u2713 ${p}`));
+  let report = await runAssessment({ target, name: opts.name, merge: opts.merge });
+  let remoteMeta = null;
+  if (opts.remote) {
+    const pending = report.criteria.filter((c) => c.status === "pending");
+    if (pending.length > 0) {
+      console.log(
+        kleur.dim(
+          `Calling hosted scoring API for ${pending.length} pending criteria...`
+        )
+      );
+      try {
+        const ctx = new CheckContext(target);
+        const sample = await gatherSample(ctx);
+        const response = await callRemote({
+          apiUrl: opts.apiUrl,
+          report,
+          sample
+        });
+        report = mergeDeltas(report, response);
+        remoteMeta = response.meta ?? null;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(kleur.red(`\u2716 Remote scoring failed: ${msg}`));
+        console.error(
+          kleur.dim(
+            "  Falling back to deterministic-only output. Pending rows kept as-is."
+          )
+        );
+      }
+    }
   }
-  if (opts.format === "markdown" || opts.format === "both") {
-    const p = resolve(outDir, "agent-ready-report.md");
-    await writeFile(p, renderMarkdown(report) + "\n", "utf8");
-    console.log(kleur.green(`\u2713 ${p}`));
+  const outDir = resolve(opts.out);
+  const written = await writeReports(
+    outDir,
+    report,
+    opts.format,
+    !opts.noPrompt
+  );
+  const cwd = process.cwd();
+  for (const p of written) {
+    console.log(kleur.green(`\u2713 ${displayPath(p, cwd)}`));
   }
   const r = report.rollup;
   console.log("");
@@ -81,15 +544,45 @@ async function main() {
       `Tier ${r.tier} \u2014 ${TIER_LABELS[r.tier]}  \xB7  floor ${r.foundationalFloor}/4  \xB7  retrieval ${r.retrievalLevel}/4  \xB7  median ${r.overallMedian.toFixed(1)}/4`
     )
   );
-  const pendingCount = report.criteria.filter((c) => c.status === "pending").length;
-  if (pendingCount > 0) {
+  if (remoteMeta) {
     console.log(
-      kleur.yellow(
-        `
-${pendingCount} criteria require an agent. Paste prompts/self-assessment.md from the rubric repo to complete the report.`
+      kleur.dim(
+        `  (remote: ${remoteMeta.pendingScored ?? 0} criteria scored by ${remoteMeta.model ?? "API"})`
       )
     );
   }
+  const pendingCount = report.criteria.filter(
+    (c) => c.status === "pending"
+  ).length;
+  if (pendingCount > 0) {
+    console.log("");
+    console.log(kleur.yellow(`${pendingCount} criteria require an agent to score.`));
+    const promptFile = written.find((p) => p.endsWith("agent-ready-prompt.md"));
+    if (promptFile) {
+      const promptRel = displayPath(promptFile, cwd);
+      console.log("");
+      if (!opts.remote) {
+        console.log(kleur.bold("Two ways to finish:"));
+        console.log(
+          `  ${kleur.cyan("--remote")}            Re-run with ${kleur.cyan("--remote")} to auto-fill via the hosted scoring API.`
+        );
+        console.log(
+          `  ${kleur.cyan("Paste the prompt")}    Open ${kleur.cyan(promptRel)} and paste it into your AI tool`
+        );
+        console.log(
+          `                      (Builder.io Fusion, Cursor, Claude Code, Codex, ...).`
+        );
+      } else {
+        console.log(kleur.bold("Next step:"));
+        console.log(
+          `  Open ${kleur.cyan(promptRel)} and paste it into your AI tool to fill the remaining rows.`
+        );
+      }
+    }
+  } else {
+    console.log("");
+    console.log(kleur.green("\u2713 All criteria scored."));
+  }
 }
 main().catch((err) => {
   console.error(kleur.red("\u2716 "), err);

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   generateBacklog,
   renderMarkdown,
   runAssessment
-} from "./chunk-GWF7PSLR.js";
+} from "./chunk-WHGIRQPX.js";
 export {
   RUBRIC,
   TIER_LABELS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentready-design-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Deterministic checks for the Agent-Ready Design rubric. Run against a design-system repo to score what can be scored without an LLM.",
   "license": "MIT",
   "author": "Hunter Gillispie <hunter@builder.io>",
@@ -37,6 +37,10 @@
     "README.md"
   ],
   "scripts": {
+    "embed": "node scripts/embed-prompt.mjs",
+    "prebuild": "pnpm embed",
+    "pretest": "pnpm embed",
+    "pretypecheck": "pnpm embed",
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",