daftari 1.12.5 → 1.13.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-05-30
+
+### Added
+
+- `daftari audit` CLI subcommand. Scans N markdown repos and reports broken
+  cross-repo references and link-graph transitive staleness. Outputs markdown
+  (default: stdout) and optional JSON. Exit code 1 if `fail_on.broken_refs` or
+  `fail_on.transitive_staleness` thresholds are exceeded. Anonymous repos passed
+  via `--repo` get no URL patterns — URL-based cross-refs into them aren't
+  detected; use `--config` with an `urls:` block to enable them. See issue #85.
+
+## [1.12.6] - 2026-05-27
+
+### Changed
+
+- **`manifest.json` `description` and `long_description` rewritten to
+  lead with the cortex framing.** Brings the `.mcpb` install UI (which
+  Claude Desktop shows when a user installs the extension) into sync
+  with the Anthropic Connectors Directory listing copy. Previously,
+  the listing leads with "an external cortex for AI agents…" while the
+  install UI led with "an MCP server that exposes a curated markdown
+  vault" — same facts, different framing. Same product describing
+  itself two ways was a coherence cost worth paying down.
+
+  - `description` is now the tagline ("A persistent cortex Claude
+    reads, writes, and curates over time.") instead of the older
+    knowledge-vault opener.
+  - `long_description` is the 47-word cortex-led version used in the
+    directory listing form (which caps at 50 words). Trims the
+    `OPENAI_API_KEY` env-var hint and the `embeddings.provider:
+    openai-3-small` config path from the long copy — both still live
+    in `PRIVACY.md` and the README for anyone wiring up the OpenAI
+    embedding provider.
+
+  No functional change. The `.mcpb` artifact is repacked from this
+  commit so the bundled manifest matches what's submitted to the
+  directory.
+
 ## [1.12.5] - 2026-05-26
 
 ### Changed

package/README.md

@@ -164,6 +164,54 @@ Deliberately deferred to keep the surface tight:
 
 Each is a clean increment on a surface that already works.
 
+## Coherence audit
+
+`daftari audit` runs a read-only, deterministic check across one or more
+markdown repos for broken cross-repo references and link-graph transitive
+staleness. It does **not** create a `.daftari/` vault on disk and does not
+write to the audited repos.
+
+```bash
+# Anonymous repos (no URL patterns):
+daftari audit --repo ~/repos/service-a --repo ~/repos/service-b
+
+# Or with a config file (recommended; see daftari audit --help for the schema):
+daftari audit --config audit.yaml
+```
+
+Anonymous repos passed via `--repo` do not get URL patterns, so cross-repo
+references that take the form of GitHub URLs (e.g.
+`https://github.com/org/service-a/blob/main/docs/api.md`) into them will be
+silently treated as external. Declare repos in `audit.yaml` with their `urls`
+field to detect these.
+
+`audit.yaml` schema:
+
+```yaml
+repos:
+  - name: service-a
+    path: ~/repos/service-a
+    docs_glob: "docs/**/*.md"       # default: "**/*.md"
+    urls:                            # optional; enables URL-pattern matching
+      - "github.com/org/service-a"
+
+  - name: service-b
+    path: ~/repos/service-b
+    urls:
+      - "github.com/org/service-b"
+
+output:
+  markdown: coherence-report.md      # default: stdout
+  json: coherence-report.json        # default: not emitted
+
+staleness:
+  threshold_days: 540                # default: 540 (18 months)
+
+fail_on:
+  broken_refs: 1                     # default: fail on any broken ref
+  transitive_staleness: 100          # default: generous; teams tune
+```
+
 ## Development
 
 ```
@@ -181,6 +229,13 @@ Design tenets: functions and types, no classes; tool handlers return
 - <docs/architecture.md> — layered design, request path, accumulation vs. generative domains
 - <docs/file-format.md> — complete frontmatter reference
 
+## Integrations
+
+- [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
+  Python package that exposes the 14 daftari tools as LangChain `BaseTool`s
+  for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
+  live from `tools/list`.
+
 ## Privacy
 
 Daftari is a local MCP server. It runs on your machine, against vault files on

package/dist/audit/checks/broken_refs.d.ts

@@ -0,0 +1,3 @@
+import type { BrokenRefFinding, LinkEdge, RepoSnapshot } from "../types.js";
+export declare function checkBrokenRefs(snapshots: RepoSnapshot[], edges: LinkEdge[]): BrokenRefFinding[];
+//# sourceMappingURL=broken_refs.d.ts.map

package/dist/audit/checks/broken_refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broken_refs.d.ts","sourceRoot":"","sources":["../../../src/audit/checks/broken_refs.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,gBAAgB,EAAE,CA0DhG"}

package/dist/audit/checks/broken_refs.js

@@ -0,0 +1,67 @@
+// src/audit/checks/broken_refs.ts
+// Pure function: given snapshots and classified edges, return every broken
+// reference as a BrokenRefFinding. No throws. No classes.
+//
+// Resolution logic:
+//   1. Look up target repo by name; if not found → missing_file.
+//   2. Look up targetPath in that repo's docs Map.
+//   3. If not found and targetPath lacks a ".md" extension, try targetPath +
+//      ".md" (spec §7 bare-path fallback).
+//   4. If still not found → missing_file.
+//   5. If found and targetAnchor is set: check DocSnapshot.headings. If absent
+//      → missing_anchor.
+export function checkBrokenRefs(snapshots, edges) {
+    // Index snapshots by repo name for O(1) lookup.
+    const byRepo = new Map();
+    for (const snap of snapshots) {
+        byRepo.set(snap.config.name, snap);
+    }
+    const findings = [];
+    for (const edge of edges) {
+        const targetSnap = byRepo.get(edge.targetRepo);
+        if (!targetSnap) {
+            // Target repo itself is unknown — treat as missing file.
+            findings.push({
+                kind: "missing_file",
+                source: { repo: edge.sourceRepo, path: edge.sourcePath },
+                target: { repo: edge.targetRepo, path: edge.targetPath, anchor: edge.targetAnchor },
+                rawHref: edge.rawHref,
+            });
+            continue;
+        }
+        // Resolve the target doc: exact match, then .md fallback.
+        let resolvedPath = null;
+        if (targetSnap.docs.has(edge.targetPath)) {
+            resolvedPath = edge.targetPath;
+        }
+        else if (!edge.targetPath.endsWith(".md")) {
+            const withMd = `${edge.targetPath}.md`;
+            if (targetSnap.docs.has(withMd)) {
+                resolvedPath = withMd;
+            }
+        }
+        if (resolvedPath === null) {
+            findings.push({
+                kind: "missing_file",
+                source: { repo: edge.sourceRepo, path: edge.sourcePath },
+                target: { repo: edge.targetRepo, path: edge.targetPath, anchor: edge.targetAnchor },
+                rawHref: edge.rawHref,
+            });
+            continue;
+        }
+        // File found. Check anchor if present.
+        if (edge.targetAnchor !== null) {
+            const doc = targetSnap.docs.get(resolvedPath);
+            if (doc && !doc.headings.has(edge.targetAnchor)) {
+                findings.push({
+                    kind: "missing_anchor",
+                    source: { repo: edge.sourceRepo, path: edge.sourcePath },
+                    target: { repo: edge.targetRepo, path: resolvedPath, anchor: edge.targetAnchor },
+                    rawHref: edge.rawHref,
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=broken_refs.js.map

package/dist/audit/checks/broken_refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broken_refs.js","sourceRoot":"","sources":["../../../src/audit/checks/broken_refs.ts"],"names":[],"mappings":"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"}

package/dist/audit/checks/staleness.d.ts

@@ -0,0 +1,3 @@
+import type { LinkEdge, RepoSnapshot, StalenessFinding } from "../types.js";
+export declare function checkStaleness(snapshots: RepoSnapshot[], edges: LinkEdge[], thresholdDays: number, now: Date): StalenessFinding[];
+//# sourceMappingURL=staleness.d.ts.map

package/dist/audit/checks/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../../src/audit/checks/staleness.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAY5E,wBAAgB,cAAc,CAC5B,SAAS,EAAE,YAAY,EAAE,EACzB,KAAK,EAAE,QAAQ,EAAE,EACjB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,IAAI,GACR,gBAAgB,EAAE,CAsGpB"}

package/dist/audit/checks/staleness.js

@@ -0,0 +1,114 @@
+// src/audit/checks/staleness.ts
+// Memoized BFS from each fresh doc to the nearest directly-stale leaf. BFS
+// (not DFS) so the recorded chain is the shortest path. Cycles handled by
+// the BFS visited set; verdicts memoized across roots.
+const key = (repo, path) => `${repo} ${path}`;
+function isDirectlyStale(mtimeIso, now, thresholdDays) {
+    const ms = now.getTime() - new Date(mtimeIso).getTime();
+    return ms > thresholdDays * 86_400_000;
+}
+export function checkStaleness(snapshots, edges, thresholdDays, now) {
+    const nodes = new Map();
+    for (const snap of snapshots) {
+        for (const d of snap.docs.values()) {
+            nodes.set(key(snap.config.name, d.relPath), {
+                repo: snap.config.name,
+                path: d.relPath,
+                mtime: d.mtime,
+            });
+        }
+    }
+    const adj = new Map();
+    for (const edge of edges) {
+        const src = key(edge.sourceRepo, edge.sourcePath);
+        const dst = key(edge.targetRepo, edge.targetPath);
+        // Resolve the dst against the .md-extension fallback so transitive edges
+        // see the same node identity broken-refs check does.
+        let dstKey = dst;
+        if (!nodes.has(dstKey)) {
+            const alt = key(edge.targetRepo, `${edge.targetPath}.md`);
+            if (nodes.has(alt))
+                dstKey = alt;
+        }
+        if (!nodes.has(dstKey))
+            continue; // dangling edge — broken_refs handles it
+        if (!nodes.has(src))
+            continue;
+        const list = adj.get(src) ?? [];
+        list.push(dstKey);
+        adj.set(src, list);
+    }
+    // Classify directly stale leaves.
+    const direct = new Set();
+    for (const [k, info] of nodes) {
+        if (isDirectlyStale(info.mtime, now, thresholdDays))
+            direct.add(k);
+    }
+    // BFS from each fresh root to find shortest path to a stale node.
+    // Memoize the shortest chain per node so a second root reaching it
+    // doesn't recompute.
+    const shortestChain = new Map(); // null = no stale path
+    function chainFor(root) {
+        if (direct.has(root))
+            return null; // direct, not transitive
+        if (shortestChain.has(root))
+            return shortestChain.get(root) ?? null;
+        const prev = new Map();
+        prev.set(root, null);
+        const queue = [root];
+        let target = null;
+        while (queue.length > 0) {
+            const cur = queue.shift();
+            if (cur !== root && direct.has(cur)) {
+                target = cur;
+                break;
+            }
+            for (const next of adj.get(cur) ?? []) {
+                if (prev.has(next))
+                    continue;
+                prev.set(next, cur);
+                queue.push(next);
+            }
+        }
+        if (!target) {
+            shortestChain.set(root, null);
+            return null;
+        }
+        const path = [];
+        let n = target;
+        while (n) {
+            path.unshift(n);
+            n = prev.get(n) ?? null;
+        }
+        const chain = path.map((k) => {
+            const info = nodes.get(k);
+            return { repo: info.repo, path: info.path, mtime: info.mtime };
+        });
+        shortestChain.set(root, chain);
+        return chain;
+    }
+    const findings = [];
+    for (const [k, info] of nodes) {
+        if (direct.has(k)) {
+            findings.push({
+                kind: "direct",
+                repo: info.repo,
+                path: info.path,
+                mtime: info.mtime,
+            });
+            continue;
+        }
+        const chain = chainFor(k);
+        if (chain) {
+            findings.push({
+                kind: "transitive",
+                repo: info.repo,
+                path: info.path,
+                mtime: info.mtime,
+                staleChain: chain,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/audit/checks/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../../../src/audit/checks/staleness.ts"],"names":[],"mappings":"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"}

package/dist/audit/collect.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "../frontmatter/types.js";
+import type { AuditConfig, AuditError, RepoSnapshot } from "./types.js";
+export declare function collectRepos(config: AuditConfig): Promise<Result<RepoSnapshot[], AuditError>>;
+//# sourceMappingURL=collect.d.ts.map

package/dist/audit/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/audit/collect.ts"],"names":[],"mappings":"AAWA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAA2B,YAAY,EAAE,MAAM,YAAY,CAAC;AAoHjG,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,UAAU,CAAC,CAAC,CAa7C"}

package/dist/audit/collect.js

@@ -0,0 +1,134 @@
+// src/audit/collect.ts
+// The only IO stage of the audit pipeline. Per repo: glob docs, strip
+// frontmatter, extract headings (GitHub-slugged) and links, then batch
+// git log to populate mtimes; on any git failure, fall back to fs mtime.
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve as nodeResolve } from "node:path";
+import { glob } from "glob";
+import matter from "gray-matter";
+import { err, ok } from "../frontmatter/types.js";
+import { extractLinksFromBody } from "./links.js";
+import { runtimeError } from "./types.js";
+function slugify(heading) {
+    // GitHub slug: lowercase, strip non-alphanumeric (keep `-_`), whitespace -> `-`.
+    return heading
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9\-_]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function extractHeadings(body) {
+    const out = new Set();
+    for (const line of body.split(/\r?\n/)) {
+        const m = line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
+        if (m)
+            out.add(slugify(m[1]));
+    }
+    return out;
+}
+function gitMtimes(repoPath, docsGlob) {
+    const opts = {
+        cwd: repoPath,
+        maxBuffer: 256 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    };
+    try {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], opts);
+    }
+    catch {
+        return null;
+    }
+    let out;
+    try {
+        // Use the :(glob) pathspec magic so git's internal glob matcher handles
+        // "**/*.md" correctly on all platforms and git configurations, including
+        // matching top-level files (bare "**/*.md" without the magic prefix skips
+        // files at depth 0 on some git versions).
+        const pathspec = docsGlob.startsWith(":(") ? docsGlob : `:(glob)${docsGlob}`;
+        out = execFileSync("git", ["log", "--all", "--name-only", `--pretty=format:COMMIT %aI`, "--", pathspec], opts).toString();
+    }
+    catch {
+        return null;
+    }
+    const mtimes = new Map();
+    let currentIso = null;
+    for (const line of out.split("\n")) {
+        if (line.startsWith("COMMIT ")) {
+            currentIso = line.slice("COMMIT ".length).trim() || null;
+            continue;
+        }
+        const path = line.trim();
+        if (!path || !currentIso)
+            continue;
+        // First time we see a path is its newest commit (git log is newest-first).
+        if (!mtimes.has(path))
+            mtimes.set(path, currentIso);
+    }
+    return mtimes;
+}
+async function loadDoc(repoPath, relPath, mtimeFromGit) {
+    const absPath = nodeResolve(repoPath, relPath);
+    const text = await readFile(absPath, "utf-8");
+    const parsed = matter(text);
+    const body = parsed.content;
+    let mtime;
+    let mtimeSource;
+    if (mtimeFromGit) {
+        mtime = mtimeFromGit;
+        mtimeSource = "git";
+    }
+    else {
+        mtime = statSync(absPath).mtime.toISOString();
+        mtimeSource = "fs";
+    }
+    return {
+        relPath: relPath.split(/[\\/]/).join("/"),
+        absPath,
+        mtime,
+        mtimeSource,
+        headings: extractHeadings(body),
+        links: extractLinksFromBody(body),
+    };
+}
+async function collectOne(config) {
+    const files = await glob(config.docsGlob, {
+        cwd: config.path,
+        nodir: true,
+        posix: true,
+        dot: false,
+    });
+    const onlyMd = files.filter((f) => /\.(md|markdown)$/i.test(f));
+    const mtimes = gitMtimes(config.path, config.docsGlob);
+    const docs = new Map();
+    for (const rel of onlyMd) {
+        const posixRel = rel.split(/[\\/]/).join("/");
+        try {
+            const snap = await loadDoc(config.path, posixRel, mtimes?.get(posixRel));
+            docs.set(posixRel, snap);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`daftari audit: warning: unreadable doc ${posixRel}: ${msg}\n`);
+        }
+    }
+    return { config, docs };
+}
+export async function collectRepos(config) {
+    // Sequential per-repo; concurrency would help but is out of scope until the
+    // 30s budget gets squeezed (see plan §perf).
+    const out = [];
+    for (const r of config.repos) {
+        try {
+            out.push(await collectOne(r));
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            return err(runtimeError(`collect failed for repo ${r.name}: ${reason}`));
+        }
+    }
+    return ok(out);
+}
+//# sourceMappingURL=collect.js.map

package/dist/audit/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/audit/collect.ts"],"names":[],"mappings":"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"}

package/dist/audit/config.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "../frontmatter/types.js";
+import { type AuditConfig, type AuditError } from "./types.js";
+export declare function parseAuditConfig(argv: string[], yamlLoader?: (path: string) => string): Result<AuditConfig, AuditError>;
+//# sourceMappingURL=config.d.ts.map

package/dist/audit/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAQA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAgC,MAAM,YAAY,CAAC;AAsG7F,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACpC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAwFjC"}

package/dist/audit/config.js

@@ -0,0 +1,174 @@
+// src/audit/config.ts
+// Parses CLI argv + an optional audit.yaml into an AuditConfig. CLI wins on
+// overlap with YAML; for --output flags only, a stderr warning is emitted so
+// operators see when the file they expected to be written has been displaced.
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import yaml from "js-yaml";
+import { err, ok } from "../frontmatter/types.js";
+import { configError } from "./types.js";
+// Inner helpers throw tagged AuditError objects (not class instances). The
+// top-level parseAuditConfig wraps in try/catch and converts to Result.
+function isAuditError(e) {
+    return (typeof e === "object" &&
+        e !== null &&
+        (e.kind === "config" || e.kind === "runtime"));
+}
+const DEFAULTS = {
+    docsGlob: "**/*.md",
+    thresholdDays: 540,
+    failOn: { brokenRefs: 1, transitiveStaleness: 100 },
+};
+function readArg(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === flag)
+            return argv[i + 1];
+        const prefix = `${flag}=`;
+        if (argv[i]?.startsWith(prefix))
+            return argv[i]?.slice(prefix.length);
+    }
+    return undefined;
+}
+function readMulti(argv, flag) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === flag && argv[i + 1] !== undefined) {
+            out.push(argv[i + 1]);
+            i++;
+        }
+        else {
+            const prefix = `${flag}=`;
+            if (argv[i]?.startsWith(prefix))
+                out.push(argv[i].slice(prefix.length));
+        }
+    }
+    return out;
+}
+function validateRepoPath(p, label) {
+    if (!existsSync(p)) {
+        throw configError(`${label}: path does not exist: ${p}`);
+    }
+    if (!statSync(p).isDirectory()) {
+        throw configError(`${label}: not a directory: ${p}`);
+    }
+    return realpathSync(p);
+}
+function parseYamlRepos(raw) {
+    if (!raw)
+        return [];
+    return raw.map((r, i) => {
+        if (typeof r.name !== "string" || r.name.length === 0) {
+            throw configError(`repos[${i}]: missing name`);
+        }
+        if (typeof r.path !== "string" || r.path.length === 0) {
+            throw configError(`repos[${i}] (${r.name}): missing path`);
+        }
+        const path = validateRepoPath(resolve(r.path), `repos[${i}] (${r.name})`);
+        const docsGlob = typeof r.docs_glob === "string" ? r.docs_glob : DEFAULTS.docsGlob;
+        const urls = Array.isArray(r.urls)
+            ? r.urls.filter((u) => typeof u === "string")
+            : [];
+        return { name: r.name, path, docsGlob, urls };
+    });
+}
+function ensureUnique(repos) {
+    const seenName = new Set();
+    const seenPath = new Set();
+    for (const r of repos) {
+        if (seenName.has(r.name)) {
+            throw configError(`duplicate repo name: ${r.name}`);
+        }
+        if (seenPath.has(r.path)) {
+            throw configError(`duplicate repo path: ${r.path}`);
+        }
+        seenName.add(r.name);
+        seenPath.add(r.path);
+    }
+}
+function warn(msg) {
+    process.stderr.write(`daftari audit: warning: ${msg}\n`);
+}
+export function parseAuditConfig(argv, yamlLoader) {
+    try {
+        const configPath = readArg(argv, "--config");
+        let yamlRaw = {};
+        if (configPath !== undefined) {
+            const load = yamlLoader ?? ((p) => readFileSync(p, "utf-8"));
+            let text;
+            try {
+                text = load(configPath);
+            }
+            catch (e) {
+                const reason = e instanceof Error ? e.message : String(e);
+                throw configError(`cannot read --config ${configPath}: ${reason}`);
+            }
+            try {
+                const raw = yaml.load(text);
+                if (raw === null || raw === undefined) {
+                    yamlRaw = {};
+                }
+                else if (typeof raw !== "object" || Array.isArray(raw)) {
+                    throw configError(`${configPath}: expected a YAML map at top level, got ${Array.isArray(raw) ? "array" : typeof raw}`);
+                }
+                else {
+                    yamlRaw = raw;
+                }
+            }
+            catch (e) {
+                if (isAuditError(e))
+                    throw e;
+                const reason = e instanceof Error ? e.message : String(e);
+                throw configError(`malformed YAML in ${configPath}: ${reason}`);
+            }
+        }
+        const yamlRepos = parseYamlRepos(yamlRaw.repos);
+        const cliRepoPaths = readMulti(argv, "--repo");
+        const cliRepos = cliRepoPaths.map((rawPath, i) => {
+            const path = validateRepoPath(resolve(rawPath), `--repo ${rawPath}`);
+            return {
+                name: `repo-${i}`,
+                path,
+                docsGlob: DEFAULTS.docsGlob,
+                urls: [],
+            };
+        });
+        const repos = [...yamlRepos, ...cliRepos];
+        if (repos.length === 0) {
+            throw configError("no repos configured: pass --repo or --config");
+        }
+        ensureUnique(repos);
+        // Output handling: CLI wins, warn if it displaces YAML.
+        const yamlMd = typeof yamlRaw.output?.markdown === "string" ? yamlRaw.output.markdown : undefined;
+        const yamlJson = typeof yamlRaw.output?.json === "string" ? yamlRaw.output.json : undefined;
+        const cliMd = readArg(argv, "--output");
+        const cliJson = readArg(argv, "--output-json");
+        if (cliMd && yamlMd && cliMd !== yamlMd) {
+            warn(`--output overrides output.markdown from config (${yamlMd} → ${cliMd})`);
+        }
+        if (cliJson && yamlJson && cliJson !== yamlJson) {
+            warn(`--output-json overrides output.json from config (${yamlJson} → ${cliJson})`);
+        }
+        const output = {
+            markdown: cliMd ?? yamlMd,
+            json: cliJson ?? yamlJson,
+        };
+        const thresholdDays = typeof yamlRaw.staleness?.threshold_days === "number"
+            ? yamlRaw.staleness.threshold_days
+            : DEFAULTS.thresholdDays;
+        const failOn = {
+            brokenRefs: typeof yamlRaw.fail_on?.broken_refs === "number"
+                ? yamlRaw.fail_on.broken_refs
+                : DEFAULTS.failOn.brokenRefs,
+            transitiveStaleness: typeof yamlRaw.fail_on?.transitive_staleness === "number"
+                ? yamlRaw.fail_on.transitive_staleness
+                : DEFAULTS.failOn.transitiveStaleness,
+        };
+        return ok({ repos, output, staleness: { thresholdDays }, failOn });
+    }
+    catch (e) {
+        if (isAuditError(e))
+            return err(e);
+        throw e; // not ours; let it propagate
+    }
+}
+//# sourceMappingURL=config.js.map