adsa-cli 0.1.2 → 0.1.5

package/lib/scan.mjs

@@ -3,10 +3,23 @@
  * every field is something observed in the repo, so a report can quote its evidence
  * and a maintainer can disagree with the reading rather than the number.
  */
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { exists, isDir, read, readJson, rel, walk, walkDirs } from "./fsx.mjs";
+import { COLOCATED_GUIDE, defaultGuideDirs, loadConfig, workspaceDirs } from "./config.mjs";
 
-const CODE_FENCE = /```(tsx|jsx|ts|js|typescript|javascript|swift|kotlin|kt)\s*\n([\s\S]*?)```/g;
+/**
+ * The languages a guide writes its examples in. HTML and CSS belong here for the same
+ * reason Swift does: a system distributed as a stylesheet and a class vocabulary
+ * documents itself in HTML, and reading only TypeScript reported its every example as
+ * absent — the tool then said "no examples" about a repository full of them.
+ */
+const CODE_FENCE = /```(tsx|jsx|ts|js|typescript|javascript|swift|kotlin|kt|html|vue|svelte|astro|css|scss)\s*\n([\s\S]*?)```/g;
+/** `--brand: #0af` is where a colour is *given* a name. The hex in it is the definition, not a raw value used in place of one. */
+const TOKEN_DEFINITION = /--[A-Za-z0-9_-]+\s*:[^;\n}]*/g;
+/** `--brand: #0af`, `--space-2: 4px` — a named decision in the format the browser itself reads. */
+const CUSTOM_PROPERTY = /(--[A-Za-z0-9_-]+)\s*:\s*([^;\n}]+)/g;
+/** Where a token is declared when it belongs to the system rather than to one component. */
+const GLOBAL_SCOPE = /(?:^|,|\s)(?::root|html|@theme|:host)\b|\[data-theme/;
 const PALETTE = "slate|gray|grey|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
 const RAW_PALETTE = new RegExp(`\\b(?:bg|text|border|ring|fill|stroke|from|to|via|divide|outline|shadow|decoration)-(?:${PALETTE})-\\d{2,3}\\b`, "g");
 const RAW_NEUTRAL = /\b(?:bg|text|border)-(?:white|black)\b/g;
@@ -14,20 +27,44 @@ const HEX = /#[0-9a-fA-F]{3,8}\b/g;
 const A11Y_HEADING = /^#{2,4}.*(keyboard|accessib|a11y|screen reader|aria|voiceover|talkback|dynamic type|touch target|contentdescription)/im;
 const GENERATED = /<!--\s*(?:generated|auto-?generated|do not edit|prop-table:start|props:start)/i;
 const PROP_TABLE = /^\|[^\n]*\bprops?\b[^\n]*\|[^\n]*\btype\b[^\n]*\|/im;
+/**
+ * A documentation site that renders its props from the types puts a component in the
+ * page — `<PropTable component="Button" />` — and never writes the table itself. That
+ * is the thing this dimension is looking for, and reading only markdown pipes counted
+ * the systems doing it properly as having no prop tables and hand-maintaining them.
+ */
+const PROP_COMPONENT = /<(Props?Table|PropsTable|PropTable|ComponentProps|ArgTypes|ApiTable|TypeTable|AutoTypeTable|PropertyTable|ApiReference|PropDefs)\b/;
 const PASCAL_EXPORT = /export\s+(?:default\s+)?(?:const|function|class)\s+([A-Z][A-Za-z0-9_]*)/g;
 const TYPE_EXPORT = /export\s+(?:type|interface)\s+([A-Z][A-Za-z0-9_]*)/g;
 /** `struct Foo: View`, `public class Foo: UIView` — captures the whole conformance list so a multi-protocol clause still matches. */
 const SWIFT_TYPE = /\b(?:@[\w:()]+\s+)*(?:public\s+|open\s+|internal\s+)?(?:final\s+)?(struct|class)\s+([A-Z][A-Za-z0-9_]*)\s*(?:<[^>{]*>)?\s*:\s*([^{]+?)\{/g;
 const SWIFT_SYMBOL = /\b(?:public\s+|open\s+)?(?:static\s+)?(?:struct|class|enum|func)\s+([A-Za-z][A-Za-z0-9_]*)/g;
 /** `@Composable` followed, within a short window (annotations, modifiers, newlines), by `fun Name(`. */
+/**
+ * Subpaths every second package exports and nobody imports as a component. Without
+ * this, a CLI that ships `./registry`, `./schema`, `./mcp` and `./utils` reads as a
+ * five-component design system and wins the workspace over the component library.
+ */
+const NOT_A_COMPONENT_SUBPATH = new Set([
+    "styles", "theme", "themes", "tokens", "eslint", "prose", "package.json", "registry", "schema", "mcp", "cli",
+    "utils", "utilities", "helpers", "hooks", "preset", "presets", "config", "plugin", "plugins", "types", "server",
+    "test", "testing", "next", "vite", "webpack", "babel", "codemod", "migrate", "internal", "unstable", "experimental",
+]);
+
+const NAMESPACE_EXPORT = /export\s+\*\s+as\s+([A-Z][A-Za-z0-9_]*)\s+from/g;
 const COMPOSABLE = /@Composable[\s\S]{0,120}?\bfun\s+([A-Z][A-Za-z0-9_]*)\s*\(/g;
 const KOTLIN_SYMBOL = /\b(?:public\s+|internal\s+)?(?:class|object|interface|enum class)\s+([A-Z][A-Za-z0-9_]*)/g;
 
-export function scan(root, config) {
+export function scan(root, config, repoRoot = root) {
     const pkg = readJson(join(root, "package.json")) || {};
+    const repoPkg = repoRoot === root ? pkg : readJson(join(repoRoot, "package.json")) || {};
     const platform = detectPlatform(root, pkg);
     const facts = {
         root,
+        repoRoot,
+        // What a package inherits from the repository around it: agent instructions,
+        // CI, the agent surface. Null when the package is the repository.
+        monorepo: repoRoot === root ? null : { root: repoRoot, package: rel(repoRoot, root) },
         name: detectName(root, pkg),
         version: pkg.version || null,
         packageJson: Boolean(pkg.name),
@@ -39,20 +76,106 @@ export function scan(root, config) {
     facts.components = findComponents(root, pkg, config, platform.primary);
     facts.icons = countIconExports(pkg);
     facts.symbols = findSymbols(root, config, platform.primary);
-    facts.guides = findGuides(root, config);
-    facts.agentFiles = readAgentFiles(root, config, facts.name);
-    facts.machine = findMachineSurface(root, pkg, config);
-    facts.ci = readCi(root, pkg, platform.primary);
+    let guideDirs = resolveGuideDirs(root, config, repoRoot);
+    facts.guides = findGuides(root, config, guideDirs);
+    const site = config.guidesExplicit ? null : findDocsSite(repoRoot, facts.components, facts.guides);
+    if (site) {
+        guideDirs = [...guideDirs, site];
+        facts.guides = findGuides(root, config, guideDirs);
+    }
+    facts.agentFiles = readAgentFiles(root, repoRoot, config, facts.name);
+    facts.machine = findMachineSurface(root, repoRoot, pkg, config);
+    facts.ci = readCi(repoRoot, pkg, repoPkg, platform.primary);
     facts.coverage = matchCoverage(facts.components, facts.guides);
     facts.freshness = checkFreshness(facts.guides, facts.symbols, facts.name, facts.ci);
-    facts.tokens = checkTokens(facts.guides, facts.ci, root, platform.primary);
+    facts.stylesheets = platform.primary === "web" ? findStylesheets(root, pkg, config) : [];
+    facts.shape = describeShape(root, config, platform.primary, facts.components);
+    facts.tokens = checkTokens(facts.guides, facts.ci, root, platform.primary, facts.stylesheets);
     facts.patterns = checkPatterns(facts.guides);
     facts.a11y = checkA11y(facts.guides, facts.ci, root, platform.primary);
-    facts.verification = checkVerification(root, pkg, facts.ci, platform.primary);
-    facts.gaps = checkGaps(root, facts.guides, facts.agentFiles, pkg);
+    facts.verification = checkVerification(root, pkg, repoPkg, facts.ci, platform.primary);
+    facts.gaps = checkGaps(root, repoRoot, facts.guides, facts.agentFiles, pkg, repoPkg);
+    facts.scanned = describeScan(facts, config, guideDirs);
     return facts;
 }
 
+/**
+ * Which directories this run actually read. Printed by `audit`, because "not found"
+ * and "not looked for" are the same sentence otherwise — the exact confusion this
+ * tool exists to stop an agent from making.
+ */
+/**
+ * The directory where this repository documents its components, found by asking which
+ * directory's markdown is *named after the components* — `accordion.mdx`, or
+ * `accordion/page.mdx`.
+ *
+ * No list of directory names finds these. A monorepo keeps its guides in whatever its
+ * documentation site happens to be called — `apps/www/content/docs`, `apps/v4/content`,
+ * `docs/src/app`, `apps/mantine.dev/src/pages` — and every system whose docs the list
+ * missed was reported as a system with no documentation at all. Matching against the
+ * component names is what makes the answer checkable: a folder of blog posts scores
+ * zero, and a folder of component guides cannot.
+ *
+ * Returns a directory only when it beats what has already been found.
+ */
+function findDocsSite(repoRoot, components, found) {
+    const slugs = new Set(components.map((c) => c.slug));
+    if (slugs.size < 3) return null;
+    const matched = (files) => new Set(files.filter((f) => slugs.has(guideSlug(f))).map((f) => guideSlug(f))).size;
+    const already = new Set(found.filter((g) => slugs.has(g.slug)).map((g) => g.slug)).size;
+
+    const byDir = new Map();
+    for (const file of walk(repoRoot, [".md", ".mdx"], 9)) {
+        if (/^(README|CHANGELOG|CONTRIBUTING|LICENSE|CODE_OF_CONDUCT|SECURITY)\./i.test(basename(file))) continue;
+        // A folder-routed site gives every guide a folder of its own, so the section
+        // that holds them all is one level further up: `components/button/page.mdx`
+        // groups with `components/card/page.mdx`, not alone.
+        const dir = ROUTE_FILE.test(basename(file)) ? dirname(dirname(file)) : dirname(file);
+        if (!byDir.has(dir)) byDir.set(dir, []);
+        byDir.get(dir).push(file);
+    }
+
+    let best = null;
+    for (const [dir, files] of byDir) {
+        const score = matched(files);
+        if (score >= 3 && score > already && (!best || score > best.score)) best = { dir, score };
+    }
+    return best ? docsRoot(best.dir) : null;
+}
+
+/**
+ * The documentation tree a component folder belongs to, so patterns and token pages
+ * beside the component pages are read too. Climbing stops at the first folder a
+ * documentation site is ever called, and after three levels, so a site nested in a
+ * repository never widens into the repository.
+ */
+const ROUTE_FILE = /^(page|index|content|_index|readme)\.mdx?$/i;
+
+const DOCS_ROOT_NAMES = new Set(["docs", "doc", "content", "pages", "guides", "documentation"]);
+
+function docsRoot(dir) {
+    let at = dir;
+    for (let i = 0; i < 3; i++) {
+        if (DOCS_ROOT_NAMES.has(basename(at).toLowerCase())) return at;
+        const parent = dirname(at);
+        if (parent === at) break;
+        at = parent;
+    }
+    return dir;
+}
+
+function describeScan(facts, config, guideDirs) {
+    return {
+        package: facts.monorepo ? facts.monorepo.package : ".",
+        repo: facts.repoRoot,
+        guides: guideDirs.map((d) => rel(facts.root, d) || "."),
+        source: [...config.source],
+        shape: facts.shape.kind,
+        stylesheets: (facts.stylesheets || []).slice(0, 3).map((f) => rel(facts.root, f)),
+        colocatedGuides: facts.guides.filter((g) => g.colocated).length,
+    };
+}
+
 /* ------------------------------------------------------------- platform */
 
 /**
@@ -151,6 +274,17 @@ function detectStack(root, pkg, platform) {
 
 /* ----------------------------------------------------------- components */
 
+/**
+ * How many importable components a directory would report if it were audited. This
+ * is how the right package is picked out of a monorepo, so it runs on packages that
+ * will never be audited — cheap enough to run on all of them, and exactly the same
+ * rule as the audit, so the count the reader is shown is the count that was ranked.
+ */
+export function countComponents(dir) {
+    const pkg = readJson(join(dir, "package.json")) || {};
+    return findComponents(dir, pkg, loadConfig(dir), detectPlatform(dir, pkg).primary).length;
+}
+
 /**
  * What a consumer can import. Package `exports` subpaths are the most reliable
  * answer, and when a package ships them they *are* the surface, so the source scan
@@ -161,10 +295,13 @@ function findComponents(root, pkg, config, platform) {
     if (platform === "swift") return findSwiftComponents(root, config);
     if (platform === "android") return findKotlinComponents(root, config);
 
+    const registry = readRegistry(root);
+    if (registry) return registry;
+
     const subpaths = Object.keys(pkg.exports || {})
         .filter((k) => k.startsWith("./") && !k.includes("*") && !/\.(css|json|js|mjs|cjs)$/.test(k))
         .map((k) => k.replace(/^\.\//, ""))
-        .filter((slug) => !["styles", "theme", "tokens", "eslint", "prose", "package.json"].includes(slug));
+        .filter((slug) => !NOT_A_COMPONENT_SUBPATH.has(slug));
     if (subpaths.length >= 5) {
         return subpaths
             .filter((slug) => !isIconSlug(slug))
@@ -173,6 +310,15 @@ function findComponents(root, pkg, config, platform) {
     }
     const out = new Map();
     for (const dir of config.source) {
+        // `export * as Dialog from "@acme/react-dialog"`: the aggregate package a
+        // monorepo publishes, whose own source is one line per component. Reading only
+        // JSX files reports the package a consumer actually installs as empty.
+        for (const file of walk(join(root, dir), [".ts"], 3)) {
+            for (const m of (read(file) || "").matchAll(NAMESPACE_EXPORT)) {
+                const slug = kebab(m[1]);
+                if (!out.has(slug)) out.set(slug, { slug, name: m[1], from: rel(root, file) });
+            }
+        }
         for (const file of walk(join(root, dir), [".tsx", ".jsx", ".vue", ".svelte"], 6)) {
             if (isNoiseFile(rel(root, file))) continue;
             const text = read(file) || "";
@@ -184,9 +330,147 @@ function findComponents(root, pkg, config, platform) {
             }
         }
     }
+    // Nothing importable anywhere. Before concluding "not a design system", ask the
+    // other question: is the surface a class vocabulary rather than an import list?
+    if (!out.size) return findClassComponents(root, pkg, config);
     return [...out.values()].sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
+/**
+ * What kind of thing this repository is, which decides which questions apply to it.
+ *
+ * "No components found" has two completely different meanings, and conflating them is
+ * how a stylesheet-and-conventions system got judged against a rubric written for an
+ * import list. If there are component source files and none of them parsed, that is
+ * this tool failing and the score should say so. If there are none at all, the repo is
+ * a different shape, and the dimensions that assume an importable API are not questions
+ * it can answer — so they are dropped from the maximum instead of scored as failures.
+ */
+function describeShape(root, config, platform, components) {
+    if (components.some((c) => c.kind === "class")) {
+        return { kind: "classes", surface: "CSS classes", componentFiles: 0 };
+    }
+    if (components.length) return { kind: "components", surface: "importable components", componentFiles: 0 };
+
+    const exts = platform === "swift" ? [".swift"] : platform === "android" ? [".kt"] : [".tsx", ".jsx", ".vue", ".svelte"];
+    const dirs = config.source.length ? config.source : ["."];
+    let componentFiles = 0;
+    for (const dir of dirs) {
+        componentFiles += walk(join(root, dir), exts, 6).filter((f) => !isNoiseFile(rel(root, f))).length;
+        if (componentFiles) break;
+    }
+    return componentFiles
+        ? { kind: "undetected", surface: null, componentFiles }
+        : { kind: "docs-only", surface: null, componentFiles: 0 };
+}
+
+/* ------------------------------------------------------- class-based systems */
+
+const CLASS_SELECTOR = /\.(-?[A-Za-z_][A-Za-z0-9_-]*)/g;
+/** State and layout classes are how a component behaves, not another component. */
+const CLASS_STATE = /^(?:is|has|js|no)-|^(?:active|open|closed|disabled|hidden|visible|selected|current|loading|error|success|warning|sr-only|visually-hidden|clearfix|container|wrapper|row|col|grid|flex|left|right|center)$/i;
+/**
+ * `mt-4`, `text-sm`, `w-full` — a utility names a value, not a thing. Deliberately
+ * narrow: the suffix has to be a scale step, so `text-field` and `border-box` survive
+ * as the components they are.
+ */
+const UTILITY_CLASS = /^[a-z]{1,6}(?:-[a-z]+)?-(?:\d{1,3}|xs|sm|md|lg|xl|\d?xl|full|auto|none|px)$/i;
+const PALETTE_CLASS = new RegExp(`^(?:bg|text|border|ring|fill|stroke)-(?:${PALETTE})-\\d{2,3}$`, "i");
+
+/**
+ * A design system distributed as a stylesheet, where what a consumer reaches for is a
+ * class name and not an import. It is a deliberate shape, not an unfinished one: it
+ * survives contact with engineers on four different stacks, which is exactly why teams
+ * without a designer keep choosing it.
+ *
+ * Reading only `exports` and JSX reported such a repository as having no components at
+ * all, and then judged its documentation against that zero. The class vocabulary *is*
+ * the API, so it is counted as one.
+ */
+function findClassComponents(root, pkg, config) {
+    const files = findStylesheets(root, pkg, config);
+    if (!files.length) return [];
+    const names = new Set();
+    for (const file of files) {
+        for (const m of selectorText(read(file) || "").matchAll(CLASS_SELECTOR)) names.add(m[1]);
+    }
+    const blocks = classBlocks([...names]);
+    // Under five and this is a page's own stylesheet; over three hundred and it is a
+    // utility framework, whose classes are values rather than components.
+    if (blocks.length < 5 || blocks.length > 300) return [];
+    const from = rel(root, files[0]);
+    return blocks
+        .map((slug) => ({ slug, name: pascal(slug), from, kind: "class", selector: `.${slug}` }))
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Selectors only: declarations are where `1.5rem` and `url(...)` live, and neither is a class. */
+function selectorText(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\{[^{}]*\}/g, "{}");
+}
+
+/**
+ * The blocks in a class vocabulary. `card__title--large` and `card-header` are parts
+ * of the card, not two more components, so both fold into it — the count answers
+ * "how many things does a consumer choose between", which is the question the
+ * coverage dimension goes on to ask a guide for.
+ */
+function classBlocks(names) {
+    const kept = unique(
+        names
+            .map((n) => n.replace(/__.*$/, "").replace(/--.*$/, "").replace(/^-+/, ""))
+            .filter((n) => n.length >= 3 && !CLASS_STATE.test(n) && !UTILITY_CLASS.test(n) && !PALETTE_CLASS.test(n)),
+    ).sort((a, b) => a.length - b.length || a.localeCompare(b));
+
+    const blocks = [];
+    for (const name of kept) {
+        if (blocks.some((b) => name.startsWith(`${b}-`))) continue;
+        blocks.push(name);
+    }
+    return blocks.sort();
+}
+
+/**
+ * The stylesheets this package actually ships, preferring what it declares over what
+ * happens to be lying around: an `exports` entry or `style` field is the file a
+ * consumer links, and a repository's own site CSS is not.
+ */
+function findStylesheets(root, pkg, config) {
+    const out = new Set();
+    const add = (value) => {
+        if (typeof value !== "string" || !/\.(css|scss)$/.test(value)) return;
+        const path = join(root, value.replace(/^\.\//, ""));
+        if (exists(path)) out.add(path);
+    };
+    for (const [key, value] of Object.entries(pkg.exports || {})) {
+        add(key);
+        add(typeof value === "string" ? value : value?.default || value?.style);
+    }
+    add(pkg.style);
+    add(pkg.main);
+    add(pkg.unpkg);
+    if (out.size) return [...out];
+    for (const dir of unique([...config.source, "styles", "css", "src", "."])) {
+        for (const file of walk(join(root, dir), [".css", ".scss"], dir === "." ? 0 : 4)) {
+            if (!/\.min\.css$/.test(file)) out.add(file);
+        }
+    }
+    return [...out].slice(0, 40);
+}
+
+/**
+ * A registry ships components as source rather than as an import, and `registry.json`
+ * declares which of its items are components: a block, an example and a chart are all
+ * in there too, and counting them makes a system of forty components look like one of
+ * four hundred, none of them documented.
+ */
+function readRegistry(root) {
+    const file = readJson(join(root, "registry.json"));
+    const items = Array.isArray(file?.items) ? file.items.filter((i) => i.type === "registry:ui" && i.name) : [];
+    if (items.length < 5) return null;
+    return [...new Map(items.map((i) => [kebab(i.name), { slug: kebab(i.name), name: pascal(i.name), from: "registry.json" }])).values()].sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
 /** `public struct Foo: View` / `open class Foo: UIView` / `struct Foo: UIViewController`. */
 function findSwiftComponents(root, config) {
     const out = new Map();
@@ -252,12 +536,20 @@ function findSymbols(root, config, platform) {
     if (platform === "android") return findKotlinSymbols(root, config);
 
     const symbols = new Set();
-    const dirs = [...config.source, "dist"];
+    // Wider than the component scan on purpose: `config.source` is where components
+    // live, and a provider, a hook or a type exported from `src/styled-system` is
+    // still a symbol a guide may legitimately import. Reading only the component
+    // folder reported real exports as imports that do not exist.
+    const dirs = [...new Set([...config.source, "src", "lib", "dist"])];
     for (const dir of dirs) {
         for (const file of walk(join(root, dir), [".tsx", ".ts", ".jsx", ".vue", ".svelte"], 7)) {
             const text = read(file) || "";
             for (const m of text.matchAll(PASCAL_EXPORT)) symbols.add(m[1]);
             for (const m of text.matchAll(TYPE_EXPORT)) symbols.add(m[1]);
+            // `export * as Accordion from "./accordion"` is how a namespace API is
+            // published, and a guide importing `Accordion` was being reported as
+            // importing something that does not exist.
+            for (const m of text.matchAll(NAMESPACE_EXPORT)) symbols.add(m[1]);
             for (const m of text.matchAll(/export\s*\{([^}]+)\}/g)) {
                 for (const part of m[1].split(",")) {
                     const name = part.trim().split(/\s+as\s+/).pop().trim();
@@ -304,41 +596,114 @@ function isNotAComponent(symbol, text) {
 /* --------------------------------------------------------------- guides */
 
 /**
- * Markdown guides from `config.guides`, plus any DocC bundle (`*.docc`) found
- * anywhere in the repo — that is where a Swift package's guides usually live, and
- * it is not a directory a maintainer would think to list in `adsa.config.json`.
+ * Pages a documentation site keeps beside its guides that are not guides: a blog, a
+ * changelog, release notes, a migration write-up. They quote APIs that were removed
+ * on purpose, and counting them made a well-documented system look stale — a hundred
+ * "imports that do not exist", every one of them a symbol a release note is explaining
+ * the removal of.
  */
-function findGuides(root, config) {
-    const dirs = new Set(config.guides);
-    for (const doccDir of walkDirs(root, [".docc"], 6)) dirs.add(rel(root, doccDir));
+const NOT_A_GUIDE = /(^|\/)(blog|posts?|changelogs?|releases?|release-notes|news|migrations?|migrating[^/]*|upgrade(-guide)?|archive)(\/|\.mdx?$|$)/i;
+
+/** Every markdown guide in `guideDirs`, plus the ones colocated with the source. */
+function findGuides(root, config, guideDirs) {
     const guides = [];
-    for (const dir of dirs) {
-        for (const file of walk(join(root, dir), [".md", ".mdx"], 6)) {
+    const seen = new Set();
+    for (const dir of guideDirs) {
+        for (const file of walk(dir, [".md", ".mdx"], 6)) {
             const name = basename(file);
             if (/^(README|CHANGELOG|CONTRIBUTING|LICENSE|CODE_OF_CONDUCT|SECURITY)\./i.test(name)) continue;
-            const text = read(file) || "";
-            guides.push(guideFacts(root, file, text));
+            if (NOT_A_GUIDE.test(file)) continue;
+            if (seen.has(file)) continue;
+            seen.add(file);
+            guides.push(guideFacts(root, file, read(file) || "", false));
         }
     }
+    for (const file of colocatedGuides(root, config)) {
+        if (seen.has(file)) continue;
+        seen.add(file);
+        guides.push(guideFacts(root, file, read(file) || "", true));
+    }
     return guides;
 }
 
-function guideFacts(root, file, text) {
+/**
+ * Absolute directories to read guides from.
+ *
+ * `config.guides` first; then any DocC bundle (`*.docc`) found anywhere in the
+ * package, because that is where a Swift package's guides live and it is not a
+ * directory a maintainer would think to list; then — unless the config named the
+ * directories by hand — the repository's own, because a monorepo commonly documents
+ * every package centrally in one `docs/` at the root.
+ */
+export function resolveGuideDirs(root, config, repoRoot = root) {
+    const dirs = new Set(config.guides.map((d) => join(root, d)));
+    for (const doccDir of walkDirs(root, [".docc"], 6)) dirs.add(doccDir);
+    if (repoRoot !== root && !config.guidesExplicit) {
+        for (const d of defaultGuideDirs(repoRoot)) dirs.add(join(repoRoot, d));
+    }
+    // A skill's references are documentation — written for an agent, which is the
+    // reader this whole audit is about. A system that ships its catalog, its patterns
+    // and its motion rules as a skill has documented itself, and reading only `docs/`
+    // reported the most agent-native shape there is as having no documentation at all.
+    for (const base of unique([root, repoRoot])) {
+        for (const d of SKILL_DIRS) if (isDir(join(base, d))) dirs.add(join(base, d));
+    }
+    return [...dirs];
+}
+
+const SKILL_DIRS = [".claude/skills", ".cursor/skills", "skills"];
+
+/**
+ * A guide can live next to the component it documents — `Button/Button.spec.md` —
+ * rather than in a documentation folder. That is a deliberate layout, not an absent
+ * one, and a scanner that only reads `docs/` reports a fully documented system as
+ * having no guides at all.
+ */
+function colocatedGuides(root, config) {
+    const out = [];
+    for (const dir of config.source) {
+        for (const file of walk(join(root, dir), [".md", ".mdx"], 6)) {
+            if (!COLOCATED_GUIDE.test(basename(file))) continue;
+            if (/^(README|CHANGELOG)\./i.test(basename(file))) continue;
+            out.push(file);
+        }
+    }
+    return out;
+}
+
+/**
+ * The component a guide is about. `Button.spec.md`, `ButtonGroup.md` and
+ * `button-group.md` all name a component the same way once the documentation
+ * suffix is dropped and the casing is normalised.
+ */
+function guideSlug(file) {
+    const stem = basename(file).replace(/\.mdx?$/, "").replace(/\.(spec|docs?|guide)$/i, "");
+    // A docs site routes by folder: `components/accordion/page.mdx` is the accordion
+    // guide, and every one of them would otherwise be a guide called "page".
+    if (/^(page|index|content|_index|readme)$/i.test(stem)) return kebab(basename(dirname(file)));
+    return kebab(stem);
+}
+
+function guideFacts(root, file, text, colocated = false) {
     const blocks = [...text.matchAll(CODE_FENCE)].map((m) => m[2]);
     const code = blocks.join("\n");
     return {
         path: rel(root, file),
-        slug: basename(file).replace(/\.mdx?$/, "").toLowerCase(),
+        colocated,
+        slug: guideSlug(file),
         title: (text.match(/^#\s+(.+)$/m) || [, ""])[1].trim(),
         lines: text.split("\n").length,
         blocks: blocks.length,
         imports: importedNames(code),
         tags: jsxTags(code),
-        hasPropTable: PROP_TABLE.test(text),
-        generated: GENERATED.test(text),
+        hasPropTable: PROP_TABLE.test(text) || PROP_COMPONENT.test(text),
+        generated: GENERATED.test(text) || PROP_COMPONENT.test(text),
         hasA11y: A11Y_HEADING.test(text),
         rawPalette: unique([...(code.match(RAW_PALETTE) || []), ...(code.match(RAW_NEUTRAL) || [])]),
-        hex: unique(code.match(HEX) || []),
+        // Hex inside `--brand: #0af` is the token being defined. Counting it as a raw
+        // value punished the guide that does the exact thing this dimension asks for.
+        hex: unique(code.replace(TOKEN_DEFINITION, "").match(HEX) || []),
+        customProperties: unique([...code.matchAll(CUSTOM_PROPERTY)].map((m) => m[1])),
         body: text,
     };
 }
@@ -361,62 +726,190 @@ function jsxTags(code) {
 
 /* --------------------------------------------------------- agent instructions */
 
-function readAgentFiles(root, config, packageName) {
+/**
+ * Agent instructions, read from the package and from the repository that declares it.
+ * A monorepo writes AGENTS.md once, at the root, and it governs every package under
+ * it — reading only the package directory reports a documented repo as undocumented.
+ */
+function readAgentFiles(root, repoRoot, config, packageName) {
     const out = [];
-    for (const candidate of config.agentFiles) {
-        const path = join(root, candidate);
-        const text = read(path);
-        if (text === null) continue;
-        out.push({
-            file: candidate,
-            lines: text.split("\n").length,
-            mentionsPackage: packageName ? text.includes(packageName) : false,
-            hasImportRule: /import\s*\{|from ["'][^"']+["']|import path|subpath|^import\s+\w/im.test(text),
-            hasLookupCommand: /```|npx |yarn |pnpm |run `|swift |gradlew/i.test(text),
-            hasTokenRule: /token|bg-primary|text-secondary|semantic|colorset|colors\.xml|theme/i.test(text),
-            hasForbidden: /forbidden|never|do not|don't|avoid/i.test(text),
-            hasFinishCheck: /before you (?:finish|call the work done)|before finishing|definition of done|must pass|checklist/i.test(text),
-            hasStopAndAsk: /stop and ask|ask (?:the |a )?(?:human|person|maintainer)|do not invent|don't invent|never invent/i.test(text),
-        });
+    const seen = new Set();
+    for (const base of [root, repoRoot]) {
+        for (const candidate of config.agentFiles) {
+            const path = join(base, candidate);
+            const text = read(path);
+            if (text === null || seen.has(path)) continue;
+            seen.add(path);
+            const fromRepoRoot = base !== root;
+            out.push({
+                file: candidate,
+                scope: fromRepoRoot ? "repo" : "package",
+                label: fromRepoRoot ? `${candidate} at the repository root` : candidate,
+                lines: text.split("\n").length,
+                mentionsPackage: packageName ? text.includes(packageName) : false,
+                hasImportRule: /import\s*\{|from ["'][^"']+["']|import path|subpath|^import\s+\w/im.test(text),
+                hasLookupCommand: /```|npx |yarn |pnpm |run `|swift |gradlew/i.test(text),
+                hasTokenRule: /token|bg-primary|text-secondary|semantic|colorset|colors\.xml|theme/i.test(text),
+                hasForbidden: /forbidden|never|do not|don't|avoid/i.test(text),
+                hasFinishCheck: /before you (?:finish|call the work done)|before finishing|definition of done|must pass|checklist/i.test(text),
+                hasStopAndAsk: /stop and ask|ask (?:the |a )?(?:human|person|maintainer)|do not invent|don't invent|never invent/i.test(text),
+            });
+        }
     }
     return out;
 }
 
 /* ------------------------------------------------------- machine surface */
 
-function findMachineSurface(root, pkg, config) {
-    const mcpConfigs = [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json"].filter((f) => exists(join(root, f)));
-    const declaredServers = mcpConfigs.flatMap((f) => {
-        const json = readJson(join(root, f)) || {};
-        return Object.keys(json.mcpServers || json.servers || {});
-    });
-    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+/** Packages that make up the repository: its own manifest, plus every workspace it declares. */
+function repoPackages(repoRoot) {
+    const out = [];
+    for (const dir of [repoRoot, ...workspaceDirs(repoRoot)]) {
+        const pkg = readJson(join(dir, "package.json"));
+        if (pkg) out.push({ dir, pkg });
+    }
+    return out;
+}
+
+/** Libraries a repository uses to *serve* MCP, rather than to consume one. */
+const MCP_SERVER_DEPS = ["mcp-handler", "@modelcontextprotocol/sdk", "@vercel/mcp-adapter", "fastmcp", "mcp-lite"];
+const MCP_CONFIG_FILES = [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json", ".windsurf/mcp.json"];
+const LLMS_TXT_FILES = ["llms.txt", "public/llms.txt", "static/llms.txt", "docs/llms.txt", "app/llms.txt"];
+const ROUTE_FILES = ["route.ts", "route.tsx", "route.js", "route.mjs", "route.jsx"];
+const MCP_SERVER_FILES = ["mcp-server.ts", "mcp-server.mjs", "mcp-server.js", "mcp.server.ts"];
+
+/**
+ * What an agent can query instead of reading files. Two things were invisible here
+ * before: a surface the repository *serves* rather than commits — an MCP endpoint or
+ * an llms.txt behind a route handler — and a surface that lives in a sibling
+ * workspace, which is where a monorepo always puts its CLI.
+ */
+function findMachineSurface(root, repoRoot, pkg, config) {
+    const bases = unique([root, repoRoot]);
+    const mcpConfigs = [];
+    const declaredServers = [];
+    for (const base of bases) {
+        for (const candidate of MCP_CONFIG_FILES) {
+            const path = join(base, candidate);
+            if (!exists(path)) continue;
+            mcpConfigs.push(rel(repoRoot, path));
+            const json = readJson(path) || {};
+            declaredServers.push(...Object.keys(json.mcpServers || json.servers || {}));
+        }
+    }
+
+    const packages = repoPackages(repoRoot);
+    const repoDeps = Object.assign({}, ...packages.map((p) => ({ ...(p.pkg.dependencies || {}), ...(p.pkg.devDependencies || {}) })));
     const binNames = Object.keys(pkg.bin && typeof pkg.bin === "object" ? pkg.bin : pkg.bin ? { [pkg.name]: pkg.bin } : {});
     const shippedFiles = pkg.files || [];
     const cliShipped = binNames.length > 0 && shippedFiles.some((f) => /^(cli|bin|dist)/.test(f));
     const mcpInPackage = cliShipped && walk(root, [".mjs", ".ts", ".js"], 2).some((f) => /mcp/i.test(basename(f)));
-    const skills = [...walk(join(root, ".claude/skills"), ["SKILL.md"], 3), ...walk(join(root, "skills"), ["SKILL.md"], 3)];
+    // One walk of the repository, split afterwards: a route that answers on /mcp,
+    // a route that renders llms.txt, and a server file named outright.
+    const found = walk(repoRoot, [...ROUTE_FILES, ...MCP_SERVER_FILES], 10).map((f) => rel(repoRoot, f));
+    const routes = found.filter((f) => ROUTE_FILES.some((r) => f.endsWith(r)));
+    const servers = found.filter((f) => MCP_SERVER_FILES.some((r) => f.endsWith(r)));
+
     return {
         mcpConfigs,
         declaredServers: unique(declaredServers),
-        storybookMcp: Boolean(deps["@storybook/addon-mcp"]),
+        servedMcp: findServedMcp(repoRoot, packages, routes, servers),
+        storybookMcp: Boolean(repoDeps["@storybook/addon-mcp"]),
         binNames,
         cliShipped,
         mcpInPackage,
-        llmsTxt: ["llms.txt", "public/llms.txt", "static/llms.txt", "docs/llms.txt"].filter((f) => exists(join(root, f))),
-        skills: skills.map((f) => rel(root, f)),
+        siblingClis: findSiblingClis(root, packages),
+        llmsTxt: findLlmsTxt(bases, repoRoot, routes),
+        skills: findSkills(bases, repoRoot),
+        commands: findCommands(bases, repoRoot),
     };
 }
 
+/**
+ * An MCP server this repository hosts: the library that implements one, or the route
+ * that answers on it. A system that serves MCP from its docs site never writes the
+ * `.mcp.json` that consumes it — that file belongs to the projects using the system.
+ */
+function findServedMcp(repoRoot, packages, routes, servers) {
+    const evidence = [];
+    for (const { dir, pkg } of packages) {
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        const found = MCP_SERVER_DEPS.filter((d) => deps[d]);
+        if (found.length) evidence.push(`${found.join(", ")} in ${rel(repoRoot, join(dir, "package.json")) || "package.json"}`);
+    }
+    for (const route of routes) {
+        if (/(^|\/)mcp(\/|$)/i.test(dirname(route))) evidence.push(route);
+    }
+    evidence.push(...servers);
+    return unique(evidence);
+}
+
+/** A docs CLI shipped from a sibling workspace — where a monorepo keeps it. */
+function findSiblingClis(root, packages) {
+    return packages
+        .filter((p) => p.dir !== root && p.pkg.bin && !p.pkg.private)
+        .map((p) => ({ name: p.pkg.name, bin: Object.keys(typeof p.pkg.bin === "object" ? p.pkg.bin : { [p.pkg.name]: p.pkg.bin }) }))
+        .filter((c) => c.name);
+}
+
+/** A committed llms.txt, or one a route handler generates from the live docs. */
+function findLlmsTxt(bases, repoRoot, routes) {
+    const out = [];
+    for (const base of bases) {
+        for (const candidate of LLMS_TXT_FILES) {
+            if (exists(join(base, candidate))) out.push(rel(repoRoot, join(base, candidate)));
+        }
+    }
+    for (const route of routes) {
+        if (/llms[.-]txt/i.test(route)) out.push(route);
+    }
+    return unique(out);
+}
+
+/**
+ * Published agent skills. A skill is a markdown file in a skills directory — the
+ * `SKILL.md` convention is one shape of that, not the only one, and requiring the
+ * filename reported a repo full of skills as having none.
+ */
+function findSkills(bases, repoRoot) {
+    const out = [];
+    for (const base of bases) {
+        for (const dir of [".claude/skills", "skills", ".cursor/skills"]) {
+            for (const file of walk(join(base, dir), [".md"], 3)) {
+                if (/^(README|CHANGELOG)\./i.test(basename(file))) continue;
+                out.push(rel(repoRoot, file));
+            }
+        }
+    }
+    return unique(out);
+}
+
+/** Slash commands are instructions an agent can run by name, same as a skill. */
+function findCommands(bases, repoRoot) {
+    const out = [];
+    for (const base of bases) {
+        for (const file of walk(join(base, ".claude/commands"), [".md"], 2)) {
+            if (/^(README|CHANGELOG)\./i.test(basename(file))) continue;
+            out.push(rel(repoRoot, file));
+        }
+    }
+    return unique(out);
+}
+
 /* ------------------------------------------------------------------- CI */
 
-function readCi(root, pkg, platform) {
-    const files = [...walk(join(root, ".github/workflows"), [".yml", ".yaml"], 2)];
+/**
+ * CI belongs to the repository, not to a package inside it: a monorepo keeps one
+ * `.github/workflows` at the root and runs every package from there. `repoPkg` is
+ * the root manifest, whose scripts are what those workflows actually call.
+ */
+function readCi(repoRoot, pkg, repoPkg, platform) {
+    const files = [...walk(join(repoRoot, ".github/workflows"), [".yml", ".yaml"], 2)];
     const text = files.map((f) => read(f) || "").join("\n");
-    const scripts = pkg.scripts || {};
+    const scripts = { ...(repoPkg.scripts || {}), ...(pkg.scripts || {}) };
     const all = text + "\n" + Object.values(scripts).join("\n");
     return {
-        workflows: files.map((f) => rel(root, f)),
+        workflows: files.map((f) => rel(repoRoot, f)),
         scripts,
         runsTests: /\b(vitest|jest|node --test|yarn test|npm test|pnpm test|xcodebuild|swift test|gradlew|gradle test|fastlane)\b/.test(all),
         runsStoryTests: /(test-storybook|test:storybook|storybook.*test|addon-vitest)/.test(all),
@@ -442,12 +935,15 @@ function matchCoverage(components, guides) {
     const documented = [];
     const missing = [];
     for (const c of components) {
-        const guide = bySlug.get(c.slug) || bySlug.get(depluralize(c.slug)) || bySlug.get(c.slug + "s") || byPrefix(guides, c.slug) || byMention(guides, c.name);
+        const mentioned = c.kind === "class" ? byClass(guides, c.slug) : byMention(guides, c.name);
+        const guide = bySlug.get(c.slug) || bySlug.get(depluralize(c.slug)) || bySlug.get(c.slug + "s") || byPrefix(guides, c.slug) || mentioned;
         if (guide) documented.push({ ...c, guide: guide.path });
         else missing.push(c);
     }
     const total = components.length;
-    return { total, documented: documented.length, missing: missing.map((c) => c.name), ratio: total ? documented.length / total : 0 };
+    // A class system's reader looks for `.dialog`, not `Dialog`: name the missing thing
+    // the way the person would have to type it.
+    return { total, documented: documented.length, missing: missing.map((c) => c.selector || c.name), ratio: total ? documented.length / total : 0 };
 }
 
 function depluralize(slug) {
@@ -458,6 +954,12 @@ function byPrefix(guides, slug) {
     return guides.find((g) => g.slug.length >= 4 && (slug.startsWith(g.slug + "-") || slug.startsWith(depluralize(g.slug) + "-")));
 }
 
+/** A class is documented where an example applies it: `.btn` in prose, `class="btn"` in HTML. */
+function byClass(guides, slug) {
+    const re = new RegExp(`\\.${slug}\\b|class(?:Name)?=["'\`][^"'\`]*\\b${slug}\\b`);
+    return guides.find((g) => re.test(g.body));
+}
+
 function byMention(guides, name) {
     const re = new RegExp(`(<|\\b)${name}\\b`);
     return guides.find((g) => re.test(g.body));
@@ -466,7 +968,10 @@ function byMention(guides, name) {
 function checkFreshness(guides, symbols, packageName, ci) {
     const unknown = [];
     for (const guide of guides) {
-        const fromSystem = guide.imports.filter((i) => (packageName && i.from.startsWith(packageName)) || i.from.startsWith("."));
+        // A relative import in a documentation page is the reader's own file —
+        // `./components/UserForm` in an example is not a claim about this package.
+        // Beside a component, in a colocated guide, `./Button` is exactly that claim.
+        const fromSystem = guide.imports.filter((i) => (packageName && i.from.startsWith(packageName)) || (guide.colocated && i.from.startsWith(".")));
         for (const imp of fromSystem) {
             if (!symbols.has(imp.name)) unknown.push({ guide: guide.path, name: imp.name, from: imp.from });
         }
@@ -482,20 +987,29 @@ function checkFreshness(guides, symbols, packageName, ci) {
     };
 }
 
-function checkTokens(guides, ci, root, platform) {
-    const docs = guides.filter((g) => /token|colour|color|typography|spacing|motion|elevation|shadow|radius|theme|palette/i.test(g.slug + " " + g.title));
+function checkTokens(guides, ci, root, platform, stylesheets = []) {
+    // Two ways a guide can be about tokens. The name is the cheap one, and it fails on
+    // the system whose page is headed "Values" — so a guide that actually carries named
+    // custom properties counts as token documentation whatever it is called.
+    const named = /token|colour|color|typography|spacing|motion|elevation|shadow|radius|theme|palette|variable|value/i;
+    const docs = guides.filter((g) => named.test(g.slug + " " + g.title) || (g.customProperties || []).length >= 3);
     const rawHits = guides.flatMap((g) => g.rawPalette.map((c) => ({ guide: g.path, value: c })));
     const hexHits = guides.flatMap((g) => g.hex.map((c) => ({ guide: g.path, value: c })));
+    const source = findSourceTokens(root, platform, stylesheets);
+    // A `--duration-fast` in the stylesheet is a motion decision with a name, whether or
+    // not a heading anywhere spells the word "motion".
+    const documented = (re, headings, flag) =>
+        docs.some((g) => re.test(g.slug + g.title) || headings.test(g.body) || (g.customProperties || []).some((n) => re.test(n))) || Boolean(source && source[flag]);
     return {
         docs: docs.map((g) => g.path),
-        motion: docs.some((g) => /motion|duration|easing|transition/i.test(g.slug + g.title) || /^#{1,4}\s.*(motion|easing|duration)/im.test(g.body)),
-        spacing: docs.some((g) => /spacing|space|layout|grid/i.test(g.slug + g.title) || /^#{1,4}\s.*(spacing|space scale)/im.test(g.body)),
+        motion: documented(/motion|duration|easing|transition/i, /^#{1,4}\s.*(motion|easing|duration)/im, "motion"),
+        spacing: documented(/spacing|space|layout|grid/i, /^#{1,4}\s.*(spacing|space scale)/im, "spacing"),
         rawPalette: rawHits.slice(0, 30),
         rawPaletteCount: rawHits.length,
         hex: hexHits.slice(0, 20),
         hexCount: hexHits.length,
         lintEnforced: /(eslint|biome).*(token|palette)|no-restricted-syntax/i.test(Object.values(ci.scripts).join(" ")),
-        source: findSourceTokens(root, platform),
+        source,
     };
 }
 
@@ -505,7 +1019,26 @@ function checkTokens(guides, ci, root, platform) {
  * `colors.xml`/`themes.xml`. Real files, real counts — an agent can open either and
  * see the same semantic names a guide would otherwise have to spell out.
  */
-function findSourceTokens(root, platform) {
+function findSourceTokens(root, platform, stylesheets = []) {
+    // The web had no branch here at all, which meant the one file holding the answer —
+    // `:root { --colour-brand: … }` — was the only resource format this tool refused to
+    // open, while it happily read an asset catalog and an Android colors.xml.
+    if (platform === "web" && stylesheets.length) {
+        const names = new Set();
+        for (const file of stylesheets) {
+            for (const name of globalCustomProperties(read(file) || "")) names.add(name);
+        }
+        if (names.size < 3) return null;
+        const all = [...names];
+        return {
+            kind: "CSS custom properties",
+            files: stylesheets.slice(0, 4).map((f) => rel(root, f)),
+            count: all.length,
+            names: all.slice(0, 6),
+            motion: all.some((n) => /duration|easing|transition|motion|delay/i.test(n)),
+            spacing: all.some((n) => /space|spacing|gap|size|radius|inset/i.test(n)),
+        };
+    }
     if (platform === "swift") {
         const catalogs = walkDirs(root, [".xcassets"], 6);
         const colorSets = catalogs.flatMap((c) => walkDirs(c, [".colorset"], 3));
@@ -533,6 +1066,41 @@ function findSourceTokens(root, platform) {
     return null;
 }
 
+/**
+ * Custom properties declared at the root, where they are a decision the whole system
+ * shares. `--actionbar-height` inside `.ActionBar` is a local variable: counting it as
+ * a design token would let any CSS-modules repo claim a token system it does not have.
+ */
+function globalCustomProperties(css) {
+    const clean = css.replace(/\/\*[\s\S]*?\*\//g, "");
+    const names = new Set();
+    const stack = [];
+    let buf = "";
+    // A hand-rolled walk rather than a regex, because the block that matters nests:
+    // Tailwind's `@theme` holds `@keyframes`, and a pattern that stops at the first
+    // brace reads the largest token file in the repository as empty.
+    const global = () => stack.some((sel) => GLOBAL_SCOPE.test(sel));
+    const collect = (text) => {
+        if (!global()) return;
+        for (const prop of text.matchAll(CUSTOM_PROPERTY)) names.add(prop[1]);
+    };
+    for (const ch of clean) {
+        if (ch === "{") {
+            const cut = buf.lastIndexOf(";");
+            collect(buf.slice(0, cut + 1));
+            stack.push(buf.slice(cut + 1).trim());
+            buf = "";
+        } else if (ch === "}") {
+            collect(buf);
+            stack.pop();
+            buf = "";
+        } else {
+            buf += ch;
+        }
+    }
+    return names;
+}
+
 function checkPatterns(guides) {
     const files = guides.filter((g) => /pattern|template|recipe|layout|page|blueprint|composition/i.test(g.slug + " " + g.title));
     // A pattern is worth 5 only if it carries structure: states, traps, a skeleton.
@@ -555,8 +1123,10 @@ function checkA11y(guides, ci, root, platform) {
     };
 }
 
-function checkVerification(root, pkg, ci, platform) {
-    const scripts = pkg.scripts || {};
+function checkVerification(root, pkg, repoPkg, ci, platform) {
+    // A workspace package often leaves `test` and `lint` to the repository root that
+    // runs them; both sets are the same promise to a reader.
+    const scripts = { ...(repoPkg.scripts || {}), ...(pkg.scripts || {}) };
     const tests = walk(root, [".test.ts", ".test.tsx", ".test.mjs", ".spec.ts", ".spec.tsx", "Tests.swift", "Test.kt", "Tests.kt"], 6).length;
     const stories = walk(root, [".stories.ts", ".stories.tsx", ".stories.js"], 6).length;
     return {
@@ -574,10 +1144,11 @@ function checkVerification(root, pkg, ci, platform) {
     };
 }
 
-function checkGaps(root, guides, agentFiles, pkg) {
+function checkGaps(root, repoRoot, guides, agentFiles, pkg, repoPkg) {
     const guideFile = guides.find((g) => /gap|absence|missing|not-built|unsupported|what-we-don/i.test(g.slug + " " + g.title));
-    const named = ["GAPS.md", "docs/GAPS.md", "guidelines/GAPS.md", "docs/gaps.md"].filter((f) => exists(join(root, f)));
-    const scripts = Object.entries(pkg.scripts || {}).filter(([k]) => /gap/i.test(k));
+    const candidates = ["GAPS.md", "docs/GAPS.md", "guidelines/GAPS.md", "docs/gaps.md"];
+    const named = unique([root, repoRoot]).flatMap((base) => candidates.filter((f) => exists(join(base, f))).map((f) => (base === root ? f : rel(root, join(base, f)))));
+    const scripts = Object.entries({ ...(repoPkg.scripts || {}), ...(pkg.scripts || {}) }).filter(([k]) => /gap/i.test(k));
     return {
         file: named[0] || (guideFile ? guideFile.path : null),
         reportCommand: scripts.length ? scripts[0][0] : null,