@cairnvibe/indexer 0.1.0

package/LICENSE

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

package/dist/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@cairnvibe/core");
+const l1_scan_1 = require("./l1-scan");
+const l2_reachability_1 = require("./l2-reachability");
+const l3_describe_1 = require("./l3-describe");
+const crawl_1 = require("./crawl");
+const crawl_describe_1 = require("./crawl-describe");
+const llm_1 = require("./llm");
+const manifest_1 = require("./manifest");
+const diff_1 = require("./diff");
+const docs_1 = require("./docs");
+const init_1 = require("./init");
+function parseArgs(rest) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg.startsWith("--")) {
+            flags[arg.slice(2)] = rest[i + 1] ?? "";
+            i++;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags };
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const { positional, flags } = parseArgs(rest);
+    const dir = positional[0] ?? ".";
+    if (command === "scan") {
+        const facts = (0, l1_scan_1.scanL1)(dir);
+        process.stdout.write(JSON.stringify(facts, null, 2) + "\n");
+        return;
+    }
+    if (command === "build") {
+        const provider = flags.provider === "groq" ? "groq" : "anthropic";
+        if (provider === "anthropic" && !process.env.ANTHROPIC_API_KEY) {
+            console.error("cairn build: ANTHROPIC_API_KEY is not set. Export it, or pass --provider groq, and re-run.");
+            process.exit(1);
+        }
+        if (provider === "groq" && !process.env.GROQ_API_KEYS) {
+            console.error("cairn build --provider groq: GROQ_API_KEYS is not set (comma-separated). Export it and re-run.");
+            process.exit(1);
+        }
+        const client = provider === "groq" ? new llm_1.GroqDescribeClient() : new llm_1.AnthropicDescribeClient();
+        // Crawl mode: the positional is a URL to a running app, not a source
+        // directory — auto-detected (a directory is never a URL), or forced
+        // via --mode=crawl. This is the framework-agnostic path (see
+        // ROADMAP.md Phase 2): reads the *rendered* DOM instead of parsing
+        // Next.js-specific source conventions, so it works on any framework's
+        // output, at the cost of less precision than reading real source.
+        const isCrawl = flags.mode === "crawl" || /^https?:\/\//.test(dir);
+        if (isCrawl) {
+            const outDir = flags.out ?? ".";
+            if (flags["storage-state"]) {
+                console.error(`cairn build --mode=crawl: replaying saved session from ${flags["storage-state"]}`);
+            }
+            console.error(`cairn build --mode=crawl: launching a headless browser against ${dir} ...`);
+            const facts = await (0, crawl_1.crawlSite)({ startUrl: dir, storageStatePath: flags["storage-state"] });
+            if (facts.pages.length === 0) {
+                console.error(`cairn build --mode=crawl: found no reachable pages at ${dir} — is it actually running?`);
+                process.exit(1);
+            }
+            const l3 = await (0, crawl_describe_1.describeCrawled)(outDir, facts, client);
+            const manifest = (0, manifest_1.assembleManifest)(outDir, facts, { dead: [], conflicts: [] }, l3);
+            const validated = core_1.ManifestSchema.parse(manifest);
+            const outPath = node_path_1.default.join(node_path_1.default.resolve(outDir), "ui-manifest.json");
+            node_fs_1.default.writeFileSync(outPath, JSON.stringify(validated, null, 2) + "\n");
+            console.error(`cairn build --mode=crawl (${provider}): ${validated.pages.length} page(s) crawled — ` +
+                `L3 cache: ${l3.cacheHits} hit / ${l3.cacheMisses} miss.`);
+            console.error(`wrote ${outPath}`);
+            return;
+        }
+        const facts = (0, l1_scan_1.scanL1)(dir);
+        const l2 = (0, l2_reachability_1.computeL2)(dir, facts);
+        const l3 = await (0, l3_describe_1.describeAll)(dir, facts, client);
+        const manifest = (0, manifest_1.assembleManifest)(dir, facts, l2, l3);
+        const validated = core_1.ManifestSchema.parse(manifest);
+        const outPath = node_path_1.default.join(node_path_1.default.resolve(dir), "ui-manifest.json");
+        node_fs_1.default.writeFileSync(outPath, JSON.stringify(validated, null, 2) + "\n");
+        console.error(`cairn build (${provider}): ${validated.pages.length} page(s), ${validated.dead.length} dead file(s), ` +
+            `${validated.conflicts.length} conflict(s) — L3 cache: ${l3.cacheHits} hit / ${l3.cacheMisses} miss.`);
+        console.error(`wrote ${outPath}`);
+        return;
+    }
+    if (command === "init") {
+        const result = (0, init_1.runInit)(dir);
+        console.error(`cairn init: detected ${result.framework}.`);
+        for (const f of result.filesWritten)
+            console.error(`  wrote   ${node_path_1.default.relative(process.cwd(), f) || f}`);
+        for (const f of result.filesSkipped)
+            console.error(`  skipped ${node_path_1.default.relative(process.cwd(), f) || f} (already exists)`);
+        console.error("");
+        console.error("Next steps:");
+        for (const step of result.nextSteps)
+            console.error(`  ${step}`);
+        return;
+    }
+    if (command === "diff") {
+        const [oldPath, newPath] = positional;
+        if (!oldPath || !newPath) {
+            console.error("usage: cairn diff <old-manifest.json> <new-manifest.json>");
+            process.exit(1);
+        }
+        const before = core_1.ManifestSchema.parse(JSON.parse(node_fs_1.default.readFileSync(oldPath, "utf8")));
+        const after = core_1.ManifestSchema.parse(JSON.parse(node_fs_1.default.readFileSync(newPath, "utf8")));
+        console.log((0, diff_1.formatDiffAsText)((0, diff_1.diffManifests)(before, after)));
+        return;
+    }
+    if (command === "docs") {
+        const manifestPath = node_path_1.default.join(node_path_1.default.resolve(dir), "ui-manifest.json");
+        if (!node_fs_1.default.existsSync(manifestPath)) {
+            console.error(`cairn docs: no ${manifestPath} — run \`cairn build ${dir}\` first.`);
+            process.exit(1);
+        }
+        const manifest = core_1.ManifestSchema.parse(JSON.parse(node_fs_1.default.readFileSync(manifestPath, "utf8")));
+        const outPath = node_path_1.default.join(node_path_1.default.resolve(dir), "CAIRN_DOCS.md");
+        node_fs_1.default.writeFileSync(outPath, (0, docs_1.generateDocsMarkdown)(manifest) + "\n");
+        console.error(`wrote ${outPath}`);
+        return;
+    }
+    console.error("usage:");
+    console.error("  cairn init <dir>   (scaffolds the API route/server + .env.example, detects your framework)");
+    console.error("  cairn scan <dir>");
+    console.error("  cairn build <dir> [--provider anthropic|groq]   (Next.js source scan)");
+    console.error("  cairn build <url> [--provider anthropic|groq] [--out <dir>] [--storage-state <file>]   (any framework — crawls a running app; --storage-state replays a saved logged-in session for auth-gated apps)");
+    console.error("  cairn diff <old-manifest.json> <new-manifest.json>");
+    console.error("  cairn docs <dir>   (reads <dir>/ui-manifest.json, writes <dir>/CAIRN_DOCS.md)");
+    process.exit(command ? 1 : 0);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/concurrency.js

@@ -0,0 +1,72 @@
+"use strict";
+// A fixed-size worker pool, not Promise.all(items.map(...)) — for a large
+// app (hundreds of pages), firing every LLM call at once would slam
+// straight into provider rate limits; sequential (the original L3
+// implementation) is correct but leaves real throughput on the table —
+// GroqDescribeClient's KeyRotator already round-robins multiple API keys
+// specifically for this, but a for-loop awaiting one call at a time never
+// actually exercised more than one key at once. A bounded pool is the
+// middle ground: real parallelism, still capped.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapWithConcurrency = mapWithConcurrency;
+exports.withRetry = withRetry;
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        for (;;) {
+            const i = nextIndex++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const workerCount = Math.max(1, Math.min(limit, items.length));
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}
+/**
+ * Retries a rate-limited (429) or transient-server-error (5xx) call with
+ * backoff — found live and necessary, not theoretical: raising describeAll's
+ * concurrency (see DEFAULT_DESCRIBE_CONCURRENCY) surfaced a real 429 from
+ * Groq on a 40-page build within seconds ("Rate limit reached... tokens per
+ * minute"), which without this would have thrown straight out of
+ * mapWithConcurrency's Promise.all and aborted the *entire* build,
+ * discarding every other page's already-completed work too. Honors the
+ * provider's Retry-After header when present (both the Anthropic and Groq
+ * SDKs expose one on a 429), falls back to exponential backoff otherwise.
+ */
+async function withRetry(fn, opts) {
+    const maxAttempts = opts?.maxAttempts ?? 4;
+    const baseDelayMs = opts?.baseDelayMs ?? 1000;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryable(err) || attempt === maxAttempts)
+                throw err;
+            const delayMs = retryAfterMs(err) ?? baseDelayMs * 2 ** (attempt - 1);
+            console.error(`[cairn] retryable error (attempt ${attempt}/${maxAttempts}), waiting ${Math.round(delayMs)}ms:`, errorMessage(err));
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    throw lastErr;
+}
+function isRetryable(err) {
+    const status = err?.status;
+    return status === 429 || (typeof status === "number" && status >= 500);
+}
+function retryAfterMs(err) {
+    const headers = err?.headers;
+    const raw = headers?.get?.("retry-after");
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) ? seconds * 1000 : null;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/crawl-describe.js

@@ -0,0 +1,87 @@
+"use strict";
+// Crawl mode's equivalent of l3-describe.ts's describeAll — same LLM
+// description step, same content-hash caching (a warm build with no
+// change in what was crawled never re-calls the model), but hashing the
+// crawled page's rendered text + elements instead of reading source off
+// disk (crawl mode has no source file — see types.ts's RawPage.renderedText).
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeCrawled = describeCrawled;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const concurrency_1 = require("./concurrency");
+const CACHE_DIR = ".cairn-cache";
+const DEFAULT_DESCRIBE_CONCURRENCY = 6;
+async function describeCrawled(outDir, facts, client, concurrency = DEFAULT_DESCRIBE_CONCURRENCY) {
+    const absOut = node_path_1.default.resolve(outDir);
+    const cacheDir = node_path_1.default.join(absOut, CACHE_DIR);
+    node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
+    const descriptions = new Map();
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    const toDescribe = [];
+    for (const page of facts.pages) {
+        const hash = hashCrawledPage(page.route, page.renderedText ?? "", page.elements);
+        const cachePath = node_path_1.default.join(cacheDir, `${hash}.json`);
+        if (node_fs_1.default.existsSync(cachePath)) {
+            descriptions.set(page.route, JSON.parse(node_fs_1.default.readFileSync(cachePath, "utf8")));
+            cacheHits += 1;
+            continue;
+        }
+        toDescribe.push({ page, cachePath });
+    }
+    await (0, concurrency_1.mapWithConcurrency)(toDescribe, concurrency, async ({ page, cachePath }) => {
+        let description;
+        let succeeded = true;
+        try {
+            description = await (0, concurrency_1.withRetry)(() => client.describePage({
+                route: page.route,
+                file: page.file, // a URL in crawl mode, not a filesystem path
+                source: page.renderedText ?? "",
+                elements: page.elements.map(toDescribeElementInput),
+            }));
+        }
+        catch (err) {
+            console.error(`[cairn crawl] describing ${page.route} failed after retries — degrading this page only:`, err);
+            description = {
+                title: "(description unavailable)",
+                purpose: "Could not be described — the description service failed after retries.",
+                whenToUse: "Unknown.",
+                confidence: 0,
+                elements: page.elements.map((el) => ({ id: el.id, does: "Unknown — description generation failed.", confidence: 0 })),
+            };
+            succeeded = false;
+        }
+        // Not cached when degraded — a re-crawl should naturally retry this
+        // page instead of being permanently pinned to a failure placeholder.
+        if (succeeded)
+            node_fs_1.default.writeFileSync(cachePath, JSON.stringify(description, null, 2));
+        descriptions.set(page.route, description);
+        cacheMisses += 1;
+    });
+    // Crawl mode has no static concept of "present on every page" (that's a
+    // component-import fact l1-scan.ts derives from source) — nav bars etc.
+    // just show up as regular elements on every crawled page that renders
+    // them, described individually per page like anything else.
+    return { descriptions, globalElements: [], cacheHits, cacheMisses };
+}
+function toDescribeElementInput(el) {
+    return {
+        id: el.id,
+        tag: el.tag,
+        text: el.text,
+        dataAi: el.dataAi,
+        ariaLabel: el.ariaLabel,
+        handlerCall: el.handlerCall,
+    };
+}
+function hashCrawledPage(route, renderedText, elements) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    hash.update(route);
+    hash.update(renderedText);
+    hash.update(JSON.stringify(elements));
+    return hash.digest("hex");
+}

package/dist/crawl.js

@@ -0,0 +1,174 @@
+"use strict";
+// Framework-agnostic analyzer: instead of parsing a framework's *source
+// code* (l1-scan.ts, Next.js-only), this crawls the *rendered* app with a
+// headless browser and reads the live DOM — by the time a page reaches the
+// browser, Vue/Angular/Svelte/Next.js output is just DOM, so this one
+// crawler works on any of them without a framework-specific parser.
+//
+// Trade-off, stated plainly (see ROADMAP.md Phase 2): needs a running
+// server to crawl, and can't see handler/API-call evidence the way reading
+// real source can — an element's "does" description is inferred from its
+// visible text and page context alone. Output is the exact same RawFacts
+// shape l1-scan.ts produces, so everything downstream (computeL2,
+// describeAll's DescribeClient, assembleManifest) needs zero changes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crawlSite = crawlSite;
+const playwright_1 = require("playwright");
+const concurrency_1 = require("./concurrency");
+const DEFAULT_MAX_PAGES = 30;
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_PAGE_TIMEOUT_MS = 15_000;
+const DEFAULT_CRAWL_CONCURRENCY = 4;
+/**
+ * Visits every page reachable within maxDepth hops of startUrl, one BFS
+ * "level" at a time — same-depth pages are visited concurrently (bounded
+ * pool, real parallel tabs in the same browser context), then their
+ * discovered links become the next level. Processing depth-by-depth rather
+ * than a single shared work queue sidesteps the coordination problem of
+ * "is a concurrent worker really done, or about to discover more work" —
+ * simpler to reason about correctly, at the minor cost of a slightly
+ * bursty (not perfectly smoothed) request pattern.
+ */
+async function crawlSite(opts) {
+    const maxPages = opts.maxPages ?? DEFAULT_MAX_PAGES;
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const pageTimeoutMs = opts.pageTimeoutMs ?? DEFAULT_PAGE_TIMEOUT_MS;
+    const concurrency = opts.concurrency ?? DEFAULT_CRAWL_CONCURRENCY;
+    const startUrl = new URL(opts.startUrl);
+    const origin = startUrl.origin;
+    const browser = await playwright_1.chromium.launch();
+    const pages = [];
+    const visited = new Set([normalizeForDedup(startUrl.toString())]);
+    try {
+        const context = await browser.newContext(opts.storageStatePath ? { storageState: opts.storageStatePath } : {});
+        let currentLevel = [startUrl.toString()];
+        let depth = 0;
+        while (currentLevel.length > 0 && depth <= maxDepth && pages.length < maxPages) {
+            const budget = Math.max(0, maxPages - pages.length);
+            const levelUrls = currentLevel.slice(0, budget);
+            const linkBatches = await (0, concurrency_1.mapWithConcurrency)(levelUrls, concurrency, async (url) => {
+                const page = await context.newPage();
+                try {
+                    const response = await page.goto(url, { waitUntil: "networkidle", timeout: pageTimeoutMs });
+                    if (!response || !response.ok()) {
+                        console.error(`[cairn crawl] skipping ${url} — HTTP ${response?.status() ?? "no response"}`);
+                        return [];
+                    }
+                    const finalUrl = page.url();
+                    const extracted = await extractPageData(page);
+                    const route = new URL(finalUrl).pathname || "/";
+                    pages.push({
+                        route,
+                        file: finalUrl,
+                        reachableFiles: [],
+                        elements: extracted.elements,
+                        renderedText: extracted.bodyText,
+                    });
+                    if (depth >= maxDepth)
+                        return [];
+                    const nextLinks = [];
+                    for (const href of extracted.links) {
+                        let abs;
+                        try {
+                            abs = new URL(href, finalUrl);
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (abs.origin !== origin)
+                            continue;
+                        nextLinks.push(abs.toString());
+                    }
+                    return nextLinks;
+                }
+                catch (err) {
+                    console.error(`[cairn crawl] skipping ${url} — ${err instanceof Error ? err.message : String(err)}`);
+                    return [];
+                }
+                finally {
+                    await page.close();
+                }
+            });
+            const nextLevel = [];
+            for (const links of linkBatches) {
+                for (const url of links) {
+                    const key = normalizeForDedup(url);
+                    if (visited.has(key))
+                        continue;
+                    visited.add(key);
+                    nextLevel.push(url);
+                }
+            }
+            currentLevel = nextLevel;
+            depth += 1;
+        }
+        await context.close();
+    }
+    finally {
+        await browser.close();
+    }
+    return {
+        version: "1",
+        pages,
+        allScannedFiles: [],
+        frameworkReachableFiles: [],
+        frameworkElements: [],
+    };
+}
+function normalizeForDedup(url) {
+    const u = new URL(url);
+    return u.origin + u.pathname; // query/hash don't distinguish routes for crawl purposes
+}
+/**
+ * Runs inside the page (page.evaluate — this function is serialized and
+ * executed in the browser's context, not Node's), so it can only use
+ * plain DOM APIs, nothing from the surrounding module.
+ */
+async function extractPageData(page) {
+    return page.evaluate(() => {
+        function normalizeText(t) {
+            return (t ?? "").trim().replace(/\s+/g, " ");
+        }
+        const seen = new Set();
+        const elements = [];
+        const candidates = Array.from(document.querySelectorAll("button, a, [role='button'], input[type='submit'], input[type='button'], [data-ai]"));
+        for (const el of candidates) {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0)
+                continue; // not actually visible
+            const dataAi = el.getAttribute("data-ai");
+            const ariaLabel = el.getAttribute("aria-label");
+            const text = normalizeText(el.textContent);
+            // Id is the raw (not slugified) data-ai/aria-label/text value, on
+            // purpose — the runtime widget's findElement() ladder matches
+            // aria-label and text *exactly as they appear on the element*, so a
+            // slugified id (e.g. "new-invoice") would never actually be found at
+            // runtime for an element with no data-ai. Nothing to identify or
+            // meaningfully describe an element by (no data-ai, no aria-label, no
+            // text) means it's skipped, not guessed at.
+            const id = dataAi || ariaLabel || text;
+            if (!id)
+                continue;
+            if (seen.has(id))
+                continue; // first occurrence of a repeated element (e.g. every row's "Archive") stands in for all of them
+            seen.add(id);
+            const tagName = el.tagName.toLowerCase();
+            const tag = tagName === "a" ? "a" : tagName === "input" ? "input" : tagName === "form" ? "form" : "button";
+            elements.push({
+                id,
+                tag,
+                dataAi: dataAi || null,
+                ariaLabel: ariaLabel || null,
+                text: text || null,
+                handlerCall: null,
+                file: location.href,
+                line: 0,
+            });
+        }
+        const links = Array.from(document.querySelectorAll("a[href]"))
+            .map((a) => a.getAttribute("href"))
+            .filter((h) => !!h && !/^(mailto:|tel:|javascript:|#)/.test(h));
+        const bodyText = document.body.innerText.trim().replace(/\n{3,}/g, "\n\n").slice(0, 12_000);
+        return { elements, links, bodyText };
+    });
+}

package/dist/diff.js

@@ -0,0 +1,83 @@
+"use strict";
+// "What changed" between two manifest builds — e.g. CI comparing the
+// current build against the last one on main. Pure comparison, no I/O.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffManifests = diffManifests;
+exports.formatDiffAsText = formatDiffAsText;
+function diffManifests(before, after) {
+    const beforeByRoute = new Map(before.pages.map((p) => [p.route, p]));
+    const afterByRoute = new Map(after.pages.map((p) => [p.route, p]));
+    const pagesAdded = [...afterByRoute.keys()].filter((r) => !beforeByRoute.has(r)).sort();
+    const pagesRemoved = [...beforeByRoute.keys()].filter((r) => !afterByRoute.has(r)).sort();
+    const pagesChanged = [];
+    for (const [route, beforePage] of beforeByRoute) {
+        const afterPage = afterByRoute.get(route);
+        if (!afterPage)
+            continue;
+        const change = diffPage(beforePage, afterPage);
+        if (change)
+            pagesChanged.push(change);
+    }
+    pagesChanged.sort((a, b) => a.route.localeCompare(b.route));
+    return {
+        pagesAdded,
+        pagesRemoved,
+        pagesChanged,
+        deadAdded: after.dead.filter((f) => !before.dead.includes(f)).sort(),
+        deadRemoved: before.dead.filter((f) => !after.dead.includes(f)).sort(),
+    };
+}
+function diffPage(before, after) {
+    const beforeElements = new Map(before.elements.map((e) => [e.id, e]));
+    const afterElements = new Map(after.elements.map((e) => [e.id, e]));
+    const elementsAdded = [...afterElements.keys()].filter((id) => !beforeElements.has(id)).sort();
+    const elementsRemoved = [...beforeElements.keys()].filter((id) => !afterElements.has(id)).sort();
+    const elementsChanged = [];
+    for (const [id, beforeEl] of beforeElements) {
+        const afterEl = afterElements.get(id);
+        if (!afterEl)
+            continue;
+        if (elementContentChanged(beforeEl, afterEl)) {
+            elementsChanged.push({
+                id,
+                doesBefore: beforeEl.does,
+                doesAfter: afterEl.does,
+                confidenceBefore: beforeEl.confidence,
+                confidenceAfter: afterEl.confidence,
+            });
+        }
+    }
+    elementsChanged.sort((a, b) => a.id.localeCompare(b.id));
+    const purposeChanged = before.purpose !== after.purpose || before.whenToUse !== after.whenToUse;
+    if (!purposeChanged && elementsAdded.length === 0 && elementsRemoved.length === 0 && elementsChanged.length === 0) {
+        return null;
+    }
+    return { route: before.route, purposeChanged, elementsAdded, elementsRemoved, elementsChanged };
+}
+function elementContentChanged(a, b) {
+    return a.does !== b.does || a.confidence !== b.confidence;
+}
+function formatDiffAsText(diff) {
+    const lines = [];
+    if (diff.pagesAdded.length)
+        lines.push(`+ pages added: ${diff.pagesAdded.join(", ")}`);
+    if (diff.pagesRemoved.length)
+        lines.push(`- pages removed: ${diff.pagesRemoved.join(", ")}`);
+    for (const change of diff.pagesChanged) {
+        lines.push(`~ ${change.route}:`);
+        if (change.purposeChanged)
+            lines.push(`    purpose/whenToUse changed`);
+        for (const id of change.elementsAdded)
+            lines.push(`    + element added: ${id}`);
+        for (const id of change.elementsRemoved)
+            lines.push(`    - element removed: ${id}`);
+        for (const c of change.elementsChanged) {
+            lines.push(`    ~ ${c.id}: "${c.doesBefore}" -> "${c.doesAfter}" (confidence ${c.confidenceBefore} -> ${c.confidenceAfter})`);
+        }
+    }
+    if (diff.deadAdded.length)
+        lines.push(`+ newly dead: ${diff.deadAdded.join(", ")}`);
+    if (diff.deadRemoved.length)
+        lines.push(`- no longer dead: ${diff.deadRemoved.join(", ")}`);
+    return lines.length > 0 ? lines.join("\n") : "no changes";
+}

package/dist/docs.js

@@ -0,0 +1,38 @@
+"use strict";
+// Turns a manifest into human-readable Markdown docs. The content already
+// exists in the manifest — this is just formatting, no LLM call.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocsMarkdown = generateDocsMarkdown;
+function generateDocsMarkdown(manifest) {
+    const sections = [
+        `# App Reference`,
+        ``,
+        `Generated by \`cairn docs\` from commit \`${manifest.commit}\` at ${manifest.generatedAt}. Do not edit by hand — regenerate instead.`,
+        ``,
+    ];
+    const pages = [...manifest.pages].sort((a, b) => a.route.localeCompare(b.route));
+    for (const page of pages) {
+        sections.push(`## ${page.title} (\`${page.route}\`)`, ``, page.purpose, ``, `**When to use:** ${page.whenToUse}`, ``);
+        if (page.elements.length > 0) {
+            sections.push(`| Element | Does |`, `|---|---|`);
+            for (const el of page.elements) {
+                sections.push(`| ${el.label} | ${el.does} |`);
+            }
+            sections.push(``);
+        }
+    }
+    if (manifest.dead.length > 0) {
+        sections.push(`## Dead code`, ``, `Not reachable from any route — safe-ish to remove:`, ``);
+        for (const file of [...manifest.dead].sort())
+            sections.push(`- \`${file}\``);
+        sections.push(``);
+    }
+    if (manifest.conflicts.length > 0) {
+        sections.push(`## Naming conflicts resolved during the last build`, ``);
+        for (const c of manifest.conflicts) {
+            sections.push(`- Between ${c.candidates.map((f) => `\`${f}\``).join(" and ")}, chose \`${c.chose}\` — ${c.reason}.`);
+        }
+        sections.push(``);
+    }
+    return sections.join("\n");
+}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyRotator = exports.generateDocsMarkdown = exports.formatDiffAsText = exports.diffManifests = exports.GroqDescribeClient = exports.AnthropicDescribeClient = exports.assembleManifest = exports.describeAll = exports.computeL2 = exports.scanL1 = void 0;
+var l1_scan_1 = require("./l1-scan");
+Object.defineProperty(exports, "scanL1", { enumerable: true, get: function () { return l1_scan_1.scanL1; } });
+var l2_reachability_1 = require("./l2-reachability");
+Object.defineProperty(exports, "computeL2", { enumerable: true, get: function () { return l2_reachability_1.computeL2; } });
+var l3_describe_1 = require("./l3-describe");
+Object.defineProperty(exports, "describeAll", { enumerable: true, get: function () { return l3_describe_1.describeAll; } });
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "assembleManifest", { enumerable: true, get: function () { return manifest_1.assembleManifest; } });
+var llm_1 = require("./llm");
+Object.defineProperty(exports, "AnthropicDescribeClient", { enumerable: true, get: function () { return llm_1.AnthropicDescribeClient; } });
+Object.defineProperty(exports, "GroqDescribeClient", { enumerable: true, get: function () { return llm_1.GroqDescribeClient; } });
+var diff_1 = require("./diff");
+Object.defineProperty(exports, "diffManifests", { enumerable: true, get: function () { return diff_1.diffManifests; } });
+Object.defineProperty(exports, "formatDiffAsText", { enumerable: true, get: function () { return diff_1.formatDiffAsText; } });
+var docs_1 = require("./docs");
+Object.defineProperty(exports, "generateDocsMarkdown", { enumerable: true, get: function () { return docs_1.generateDocsMarkdown; } });
+var key_rotator_1 = require("./key-rotator");
+Object.defineProperty(exports, "KeyRotator", { enumerable: true, get: function () { return key_rotator_1.KeyRotator; } });