adsa-cli 0.1.1 → 0.1.4

package/lib/scan.mjs

@@ -3,8 +3,9 @@
  * 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;
 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";
@@ -14,20 +15,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 +64,102 @@ 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.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],
+        colocatedGuides: facts.guides.filter((g) => g.colocated).length,
+    };
+}
+
 /* ------------------------------------------------------------- platform */
 
 /**
@@ -151,6 +258,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 +279,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 +294,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) || "";
@@ -187,6 +317,19 @@ function findComponents(root, pkg, config, platform) {
     return [...out.values()].sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
+/**
+ * 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 +395,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,38 +455,108 @@ 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) || []),
@@ -361,62 +582,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),
@@ -466,7 +815,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 });
         }
@@ -555,8 +907,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 +928,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,