@driftdev/cli 1.11.0 → 1.12.1

package/dist/drift.js

@@ -51,8 +51,8 @@ function getGlobalConfigPath() {
 var init_global = () => {};
 
 // src/drift.ts
-import { readFileSync as readFileSync21 } from "node:fs";
-import * as path31 from "node:path";
+import { readFileSync as readFileSync23 } from "node:fs";
+import * as path34 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { Command } from "commander";
 
@@ -63,13 +63,37 @@ import {
   existsSync as existsSync2,
   mkdirSync as mkdirSync2,
   readdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   rmSync,
   statSync,
   writeFileSync
 } from "node:fs";
 import * as os2 from "node:os";
 import * as path2 from "node:path";
+
+// src/utils/version.ts
+import { readFileSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var cached;
+function getVersion() {
+  if (cached)
+    return cached;
+  for (const rel of ["../package.json", "../../package.json"]) {
+    try {
+      const pkg = JSON.parse(readFileSync(join2(__dirname2, rel), "utf-8"));
+      if (pkg.name === "@driftdev/cli" && typeof pkg.version === "string") {
+        cached = pkg.version;
+        return pkg.version;
+      }
+    } catch {}
+  }
+  cached = "0.0.0";
+  return cached;
+}
+
+// src/cache/spec-cache.ts
 var _noCache = false;
 function setNoCache(value) {
   _noCache = value;
@@ -141,7 +165,7 @@ function buildCacheKey(input) {
   const pkgJson = findPackageJson(absEntry);
   const pkgMtime = pkgJson ? getMtime(pkgJson) : 0;
   const srcMtime = getSourceMaxMtime(absEntry);
-  const parts = [absEntry, String(entryMtime), String(pkgMtime), String(srcMtime)];
+  const parts = [getVersion(), absEntry, String(entryMtime), String(pkgMtime), String(srcMtime)];
   if (input.configHash)
     parts.push(input.configHash);
   return hashString(parts.join("|"));
@@ -154,7 +178,7 @@ function getCachedSpec(input) {
   if (!existsSync2(cacheFile))
     return null;
   try {
-    const raw = JSON.parse(readFileSync(cacheFile, "utf-8"));
+    const raw = JSON.parse(readFileSync2(cacheFile, "utf-8"));
     return raw;
   } catch {
     return null;
@@ -177,7 +201,7 @@ function getConfigHash(configPath) {
   if (!configPath || !existsSync2(configPath))
     return;
   try {
-    const content = readFileSync(configPath, "utf-8");
+    const content = readFileSync2(configPath, "utf-8");
     return hashString(content);
   } catch {
     return;
@@ -633,13 +657,13 @@ function formatWarning(message) {
 }
 
 // src/utils/resolve-specs.ts
-import { readFileSync as readFileSync5 } from "node:fs";
+import { readFileSync as readFileSync6 } from "node:fs";
 import * as path7 from "node:path";
 import { extract as extract2 } from "@openpkg-ts/sdk";
 import { normalize as normalize2 } from "@openpkg-ts/spec";
 
 // src/config/loader.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
 import * as path4 from "node:path";
 
 // src/config/drift-config.ts
@@ -731,7 +755,7 @@ function loadConfig(cwd = process.cwd()) {
     if (!existsSync4(absPath)) {
       throw new Error(`Config file not found: ${absPath}`);
     }
-    const raw = JSON.parse(readFileSync2(absPath, "utf-8"));
+    const raw = JSON.parse(readFileSync3(absPath, "utf-8"));
     const result = validateConfig(raw);
     if (!result.ok) {
       throw new Error(`Invalid config at ${absPath}: ${result.errors.join(", ")}`);
@@ -744,7 +768,7 @@ function loadConfig(cwd = process.cwd()) {
     const driftConfigPath = path4.join(current, "drift.config.json");
     if (existsSync4(driftConfigPath)) {
       try {
-        const raw = JSON.parse(readFileSync2(driftConfigPath, "utf-8"));
+        const raw = JSON.parse(readFileSync3(driftConfigPath, "utf-8"));
         const result = validateConfig(raw);
         if (!result.ok) {
           throw new Error(`Invalid config at ${driftConfigPath}: ${result.errors.join(", ")}`);
@@ -760,7 +784,7 @@ function loadConfig(cwd = process.cwd()) {
     const pkgPath = path4.join(current, "package.json");
     if (existsSync4(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
         if (pkg.drift && typeof pkg.drift === "object") {
           const result = validateConfig(pkg.drift);
           if (!result.ok) {
@@ -781,7 +805,7 @@ function loadConfig(cwd = process.cwd()) {
   const globalPath = getGlobalConfigPath();
   if (existsSync4(globalPath)) {
     try {
-      const raw = JSON.parse(readFileSync2(globalPath, "utf-8"));
+      const raw = JSON.parse(readFileSync3(globalPath, "utf-8"));
       const result = validateConfig(raw);
       if (result.ok) {
         return { config: result.config, configPath: globalPath };
@@ -792,18 +816,18 @@ function loadConfig(cwd = process.cwd()) {
 }
 
 // src/utils/detect-entry.ts
-import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "node:fs";
 import * as path6 from "node:path";
 
 // src/utils/workspaces.ts
-import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "node:fs";
 import * as path5 from "node:path";
 function detectWorkspaces(cwd) {
   const pkgPath = path5.join(cwd, "package.json");
   if (!existsSync5(pkgPath))
     return null;
   try {
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     if (Array.isArray(pkg.workspaces))
       return pkg.workspaces;
     if (pkg.workspaces?.packages && Array.isArray(pkg.workspaces.packages))
@@ -847,7 +871,7 @@ function discoverPackages(cwd) {
     const pkgPath = path5.join(absDir, "package.json");
     if (existsSync5(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
         if (pkg.name)
           name = pkg.name;
         if (pkg.private === true)
@@ -878,7 +902,7 @@ function detectEntry(cwd = process.cwd()) {
   }
   if (existsSync6(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
       const typesField = pkg.types || pkg.typings;
       if (typesField && typeof typesField === "string") {
         const resolved = tryResolve("types", typesField);
@@ -1039,7 +1063,7 @@ function collectStringValues(value, depth = 0) {
 
 // src/utils/resolve-specs.ts
 function loadSpec(filePath) {
-  return JSON.parse(readFileSync5(path7.resolve(process.cwd(), filePath), "utf-8"));
+  return JSON.parse(readFileSync6(path7.resolve(process.cwd(), filePath), "utf-8"));
 }
 async function resolveSpecs(opts) {
   const { config } = loadConfig();
@@ -1086,23 +1110,6 @@ async function resolveSpecs(opts) {
   throw new Error("Provide two spec files, or use --base <ref>");
 }
 
-// src/utils/version.ts
-import { readFileSync as readFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join7 } from "node:path";
-import { fileURLToPath } from "node:url";
-var __dirname2 = dirname4(fileURLToPath(import.meta.url));
-var cached;
-function getVersion() {
-  if (cached)
-    return cached;
-  try {
-    cached = JSON.parse(readFileSync6(join7(__dirname2, "../../package.json"), "utf-8")).version ?? "0.0.0";
-  } catch {
-    cached = "0.0.0";
-  }
-  return cached ?? "0.0.0";
-}
-
 // src/commands/breaking.ts
 function registerBreakingCommand(program) {
   program.command("breaking [old] [new]").description("Detect breaking changes between two specs").option("--base <ref>", "Git ref for old spec").option("--head <ref>", "Git ref for new spec (default: working tree)").option("--entry <file>", "Entry file for git ref extraction").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").action(async (oldPath, newPath, options) => {
@@ -2651,9 +2658,358 @@ function registerDiffCommand(program) {
   });
 }
 
-// src/commands/examples.ts
-import { readFileSync as readFileSync14 } from "node:fs";
+// src/commands/docs-map.ts
+import { writeFileSync as writeFileSync5 } from "node:fs";
+import * as path21 from "node:path";
+import { collectTypeKeys, extractDocumentedKeys as extractDocumentedKeys2 } from "@driftdev/sdk";
+
+// src/config/docs-map.ts
+import { existsSync as existsSync13, readFileSync as readFileSync14 } from "node:fs";
 import * as path18 from "node:path";
+var ANNOTATIONS = new Set(["prose-documented", "internal-by-convention", "ignore"]);
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function validateDocsMap(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, errors: ["Docs map must be a JSON object"] };
+  }
+  const errors = [];
+  const obj = raw;
+  if (obj.version !== 1)
+    errors.push('"version" must be 1');
+  if (!Array.isArray(obj.pages)) {
+    errors.push('"pages" must be an array');
+    return { ok: false, errors };
+  }
+  obj.pages.forEach((p, i) => {
+    const at = `"pages[${i}]"`;
+    if (typeof p !== "object" || p === null) {
+      errors.push(`${at} must be an object`);
+      return;
+    }
+    const page = p;
+    if (typeof page.page !== "string" || !page.page)
+      errors.push(`${at}.page must be a string`);
+    if (typeof page.type !== "string" || !page.type)
+      errors.push(`${at}.type must be a string`);
+    if (page.spec !== undefined && typeof page.spec !== "string")
+      errors.push(`${at}.spec must be a string`);
+    if (page.entry !== undefined && typeof page.entry !== "string")
+      errors.push(`${at}.entry must be a string`);
+    if (page.spec !== undefined && page.entry !== undefined)
+      errors.push(`${at} must set at most one of "spec"/"entry" (omit both to use the scan target)`);
+    if (page.sectionRe !== undefined) {
+      if (typeof page.sectionRe !== "string") {
+        errors.push(`${at}.sectionRe must be a string`);
+      } else {
+        try {
+          new RegExp(page.sectionRe);
+        } catch {
+          errors.push(`${at}.sectionRe is not a valid regex: ${page.sectionRe}`);
+        }
+      }
+    }
+    for (const field of ["extraPages", "internal", "deprecated"]) {
+      if (page[field] !== undefined && !isStringArray(page[field]))
+        errors.push(`${at}.${field} must be an array of strings`);
+    }
+    if (page.replacements !== undefined) {
+      const r = page.replacements;
+      if (typeof r !== "object" || r === null || Array.isArray(r)) {
+        errors.push(`${at}.replacements must be an object of oldKey → newKey strings`);
+      } else if (!Object.values(r).every((v) => typeof v === "string")) {
+        errors.push(`${at}.replacements values must be strings`);
+      }
+    }
+    if (page.annotations !== undefined) {
+      const a = page.annotations;
+      if (typeof a !== "object" || a === null || Array.isArray(a)) {
+        errors.push(`${at}.annotations must be an object of key → annotation`);
+      } else {
+        for (const [k, v] of Object.entries(a)) {
+          if (typeof v !== "string" || !ANNOTATIONS.has(v))
+            errors.push(`${at}.annotations["${k}"] must be one of: ${[...ANNOTATIONS].join(", ")} (got ${JSON.stringify(v)})`);
+        }
+      }
+    }
+    if (page.baselineGaps !== undefined && (typeof page.baselineGaps !== "number" || page.baselineGaps < 0 || !Number.isInteger(page.baselineGaps)))
+      errors.push(`${at}.baselineGaps must be a non-negative integer`);
+  });
+  if (errors.length > 0)
+    return { ok: false, errors };
+  return { ok: true, map: obj };
+}
+function loadDocsMap(mapPath, cwd = process.cwd()) {
+  const absPath = path18.resolve(cwd, mapPath);
+  if (!existsSync13(absPath))
+    throw new Error(`Docs map not found: ${absPath}`);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync14(absPath, "utf-8"));
+  } catch {
+    throw new Error(`Invalid JSON in ${absPath}`);
+  }
+  const result = validateDocsMap(raw);
+  if (!result.ok) {
+    throw new Error(`Invalid docs map at ${absPath}: ${result.errors.join("; ")}`);
+  }
+  return { map: result.map, mapPath: absPath, dir: path18.dirname(absPath) };
+}
+
+// src/utils/docs-corpus.ts
+import { readFileSync as readFileSync15, statSync as statSync2 } from "node:fs";
+import * as path19 from "node:path";
+import { discoverMarkdownFiles } from "@driftdev/sdk";
+function resolveDocsCorpus(cwd, docsPatterns, configDocs) {
+  if (!docsPatterns || docsPatterns.length === 0) {
+    return discoverMarkdownFiles(cwd, configDocs);
+  }
+  const include = [];
+  for (const pattern of docsPatterns) {
+    if (isDirectory(path19.resolve(cwd, pattern))) {
+      include.push(path19.join(pattern, "**/*.md"), path19.join(pattern, "**/*.mdx"));
+    } else {
+      include.push(pattern);
+    }
+  }
+  const files = discoverMarkdownFiles(cwd, { include });
+  if (files.length === 0) {
+    formatWarning(`--docs matched no markdown files: ${docsPatterns.join(", ")}`);
+  }
+  return files;
+}
+function isDirectory(p) {
+  try {
+    return statSync2(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function readPackageName(cwd = process.cwd()) {
+  try {
+    const pkgJson = JSON.parse(readFileSync15(path19.resolve(cwd, "package.json"), "utf-8"));
+    return typeof pkgJson.name === "string" ? pkgJson.name : undefined;
+  } catch {
+    return;
+  }
+}
+
+// src/utils/key-coverage-runner.ts
+import { globSync, readFileSync as readFileSync16 } from "node:fs";
+import * as path20 from "node:path";
+import {
+  computeKeyCoverage,
+  DEFAULT_SECTION_RE,
+  extractDocumentedKeys
+} from "@driftdev/sdk";
+function resolvePages(page, dir) {
+  const files = [path20.resolve(dir, page.page)];
+  for (const pattern of page.extraPages ?? []) {
+    for (const match of globSync(pattern, { cwd: dir })) {
+      files.push(path20.resolve(dir, match));
+    }
+  }
+  return files.map((p) => ({ path: p, content: readFileSync16(p, "utf-8") }));
+}
+async function resolvePageSpec(page, dir, fallback) {
+  if (page.spec) {
+    const specPath = path20.resolve(dir, page.spec);
+    const raw = JSON.parse(readFileSync16(specPath, "utf-8"));
+    const spec = raw && typeof raw === "object" && "data" in raw && "ok" in raw ? raw.data : raw;
+    if (!Array.isArray(spec?.exports) && !Array.isArray(spec?.types)) {
+      throw new Error(`${page.spec}: not a spec file (no exports/types arrays)`);
+    }
+    return spec;
+  }
+  if (page.entry) {
+    const { apiSpec } = await resolveTruth({ entry: path20.resolve(dir, page.entry) });
+    return apiSpec;
+  }
+  if (!fallback) {
+    throw new Error(`page "${page.page}": no "spec"/"entry" in map and no scan target to fall back to`);
+  }
+  return fallback;
+}
+async function runDocsCoverage(loaded, fallbackSpec) {
+  const pages = [];
+  const errors = [];
+  const warnings = [];
+  for (const page of loaded.map.pages) {
+    const spec = await resolvePageSpec(page, loaded.dir, fallbackSpec);
+    const corpus = extractDocumentedKeys(resolvePages(page, loaded.dir), page.sectionRe ? new RegExp(page.sectionRe, "i") : DEFAULT_SECTION_RE);
+    const result = computeKeyCoverage(spec, page.type, corpus, {
+      internal: page.internal,
+      deprecated: page.deprecated,
+      replacements: page.replacements,
+      annotations: page.annotations
+    });
+    if (!result) {
+      throw new Error(`page "${page.page}": type "${page.type}" not found in spec`);
+    }
+    const baseline = page.baselineGaps ?? 0;
+    const failures = [];
+    const pageWarnings = [];
+    for (const ghost of result.ghosts) {
+      failures.push(`ghost option \`${ghost.key}\` — documented but not in ${page.type}`);
+      const loc = ghost.locations[0];
+      errors.push({
+        export: ghost.key,
+        issue: `ghost option \`${ghost.key}\` — documented but does not exist on ${page.type} (or any spec type)`,
+        filePath: loc?.file ?? path20.resolve(loaded.dir, page.page),
+        line: loc?.line
+      });
+    }
+    const gapCount = result.counts.gapsUserFacing;
+    if (gapCount > baseline) {
+      const newGaps = result.gaps.userFacing.slice(0, 10).map((g) => g.key);
+      failures.push(`${gapCount} undocumented options (baseline ${baseline}) — drift grew: ${newGaps.join(", ")}${gapCount > 10 ? "…" : ""}`);
+      errors.push({
+        export: page.type,
+        issue: `${gapCount} undocumented ${page.type} options (baseline ${baseline})`,
+        filePath: path20.resolve(loaded.dir, page.page)
+      });
+    } else if (gapCount > 0) {
+      pageWarnings.push(`${gapCount} known undocumented options (baseline ${baseline})`);
+    }
+    for (const inv of result.inversions) {
+      pageWarnings.push(`documents deprecated \`${inv.documented}\` but not its replacement \`${inv.replacement}\``);
+      warnings.push({
+        export: inv.documented,
+        issue: `documents deprecated \`${inv.documented}\` but not its replacement \`${inv.replacement}\``,
+        filePath: path20.resolve(loaded.dir, page.page)
+      });
+    }
+    pages.push({
+      page: page.page,
+      type: page.type,
+      baselineGaps: baseline,
+      status: failures.length > 0 ? "fail" : pageWarnings.length > 0 ? "warn" : "pass",
+      failures,
+      warnings: pageWarnings,
+      result
+    });
+  }
+  return {
+    pages,
+    pass: pages.every((p) => p.status !== "fail"),
+    annotations: { errors, warnings }
+  };
+}
+
+// src/commands/docs-map.ts
+var MATCH_ALL = /(?:)/;
+var MIN_PAGE_KEYS = 3;
+var MIN_OVERLAP = 3;
+function typeKeySets(spec) {
+  const out = new Map;
+  for (const entry of [...spec.exports, ...spec.types ?? []]) {
+    const keys = new Set(collectTypeKeys(entry).keys());
+    if (keys.size >= MIN_OVERLAP && !out.has(entry.name))
+      out.set(entry.name, keys);
+  }
+  return out;
+}
+function registerDocsMapCommand(program) {
+  const docsMap = program.command("docs-map").description("Docs-map lifecycle: scaffold and ratchet the page→type artifact");
+  docsMap.command("stub").description("Scaffold a docs map: option-doc pages + type candidates ranked by key overlap").option("--docs <patterns...>", "Docs corpus: glob patterns or directories").option("--lang <language>", "Source language (inferred otherwise)").option("--abi <path>", "ABI JSON file (Clarity)").option("--spec <path>", "OpenAPI document path or URL").option("--out <file>", "Write the stub map to a file (default: stdout only)").action(async (options) => {
+    const startTime = Date.now();
+    const version = getVersion();
+    try {
+      const lang = resolveLang({ lang: options.lang, spec: options.spec, abi: options.abi });
+      const { config } = loadConfig();
+      const entryFile = lang === "typescript" ? config.entry ? path21.resolve(process.cwd(), config.entry) : detectEntry() : undefined;
+      const { apiSpec } = await resolveTruth({
+        entry: entryFile,
+        lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      const types = typeKeySets(apiSpec);
+      const corpus = resolveDocsCorpus(process.cwd(), options.docs, config.docs);
+      const pages = [];
+      for (const file of corpus) {
+        const extraction = extractDocumentedKeys2([{ path: file.path, content: file.content ?? "" }], MATCH_ALL);
+        const pageKeys = new Set(extraction.documented.keys());
+        if (pageKeys.size < MIN_PAGE_KEYS)
+          continue;
+        const ranked = [...types.entries()].map(([name, keys]) => ({
+          type: name,
+          overlap: [...pageKeys].filter((k) => keys.has(k)).length,
+          keys: keys.size
+        })).filter((c2) => c2.overlap >= MIN_OVERLAP).sort((a, b) => b.overlap - a.overlap).slice(0, 3);
+        if (ranked.length === 0)
+          continue;
+        pages.push({
+          page: path21.relative(process.cwd(), file.path),
+          keys: pageKeys.size,
+          type: ranked[0].type,
+          candidates: ranked
+        });
+      }
+      const stub = {
+        $schema: "https://unpkg.com/@driftdev/cli/schemas/drift.docs-map.schema.json",
+        version: 1,
+        pages: pages.map((p) => ({
+          page: p.page,
+          type: p.type,
+          baselineGaps: 0
+        }))
+      };
+      if (options.out) {
+        writeFileSync5(path21.resolve(process.cwd(), options.out), `${JSON.stringify(stub, null, 2)}
+`);
+      }
+      formatOutput("docs-map stub", { candidates: pages, stub, ...options.out ? { written: options.out } : {} }, startTime, version, undefined, {
+        suggested: "drift-docs-map skill",
+        reason: "review type mappings, add sectionRe/annotations, then set baselines"
+      });
+    } catch (err) {
+      formatError("docs-map stub", err instanceof Error ? err.message : String(err), startTime, version);
+    }
+  });
+  docsMap.command("baseline").description("Tighten baselineGaps to current gap counts (ratchet — never raises)").argument("<map>", "Docs map file").action(async (mapArg) => {
+    const startTime = Date.now();
+    const version = getVersion();
+    try {
+      const loaded = loadDocsMap(mapArg);
+      let fallback;
+      try {
+        const { config } = loadConfig();
+        const entryFile = config.entry ? path21.resolve(process.cwd(), config.entry) : detectEntry();
+        fallback = (await resolveTruth({ entry: entryFile })).apiSpec;
+      } catch {}
+      const run = await runDocsCoverage(loaded, fallback);
+      const changes = [];
+      for (const result of run.pages) {
+        const entry = loaded.map.pages.find((p) => p.page === result.page);
+        if (!entry)
+          continue;
+        const current = result.result.counts.gapsUserFacing;
+        const existing = entry.baselineGaps;
+        if (existing === undefined || current < existing) {
+          changes.push({ page: result.page, from: existing ?? current, to: current });
+          entry.baselineGaps = current;
+        }
+      }
+      if (changes.length > 0) {
+        const out = {
+          $schema: loaded.map.$schema,
+          ...loaded.map
+        };
+        writeFileSync5(loaded.mapPath, `${JSON.stringify(out, null, 2)}
+`);
+      }
+      formatOutput("docs-map baseline", { changes, map: loaded.mapPath }, startTime, version);
+    } catch (err) {
+      formatError("docs-map baseline", err instanceof Error ? err.message : String(err), startTime, version);
+    }
+  });
+}
+
+// src/commands/examples.ts
+import { readFileSync as readFileSync17 } from "node:fs";
+import * as path22 from "node:path";
 import { validateExamples } from "@driftdev/sdk";
 
 // src/formatters/examples.ts
@@ -2732,16 +3088,16 @@ function renderExamples(data) {
 
 // src/commands/examples.ts
 function findPackagePath(entryFile) {
-  let dir = path18.dirname(entryFile);
-  while (dir !== path18.dirname(dir)) {
+  let dir = path22.dirname(entryFile);
+  while (dir !== path22.dirname(dir)) {
     try {
-      readFileSync14(path18.join(dir, "package.json"), "utf-8");
+      readFileSync17(path22.join(dir, "package.json"), "utf-8");
       return dir;
     } catch {
-      dir = path18.dirname(dir);
+      dir = path22.dirname(dir);
     }
   }
-  return path18.dirname(entryFile);
+  return path22.dirname(entryFile);
 }
 function registerExamplesCommand(program) {
   program.command("examples [entry]").description("Validate @example blocks on exports").option("--typecheck", "Type-check examples with TypeScript").option("--run", "Execute examples at runtime (implies --typecheck)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--min <n>", "Minimum presence threshold (exit 1 if below)").action(async (entry, options) => {
@@ -2809,7 +3165,7 @@ function registerExamplesCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      const entryFile = entry ? path18.resolve(process.cwd(), entry) : config.entry ? path18.resolve(process.cwd(), config.entry) : detectEntry();
+      const entryFile = entry ? path22.resolve(process.cwd(), entry) : config.entry ? path22.resolve(process.cwd(), config.entry) : detectEntry();
       const { spec } = await cachedExtract(entryFile);
       const exports = spec.exports ?? [];
       const packagePath = findPackagePath(entryFile);
@@ -2844,7 +3200,7 @@ function registerExamplesCommand(program) {
 }
 
 // src/commands/extract.ts
-import * as path19 from "node:path";
+import * as path23 from "node:path";
 import { Drift } from "@driftdev/sdk";
 import { normalize as normalize6 } from "@openpkg-ts/spec";
 
@@ -2883,8 +3239,8 @@ function registerExtractCommand(program) {
           abi: options.abi
         });
         if (options.output) {
-          const { writeFileSync: writeFileSync5 } = await import("node:fs");
-          writeFileSync5(options.output, JSON.stringify(apiSpec, null, 2));
+          const { writeFileSync: writeFileSync6 } = await import("node:fs");
+          writeFileSync6(options.output, JSON.stringify(apiSpec, null, 2));
           process.stderr.write(`drift extract: wrote ${options.output}
 `);
         } else {
@@ -2912,7 +3268,7 @@ function registerExtractCommand(program) {
         formatOutput("extract", { packages: specs, ...skipped.length > 0 ? { skipped } : {} }, startTime, version);
         return;
       }
-      const entryFile = entry ? path19.resolve(process.cwd(), entry) : detectEntry();
+      const entryFile = entry ? path23.resolve(process.cwd(), entry) : detectEntry();
       const hasFilters = !!(options.only || options.ignore);
       let spec;
       if (hasFilters) {
@@ -2937,8 +3293,8 @@ function registerExtractCommand(program) {
         spec = result.spec;
       }
       if (options.output) {
-        const { writeFileSync: writeFileSync5 } = await import("node:fs");
-        writeFileSync5(options.output, JSON.stringify(spec, null, 2));
+        const { writeFileSync: writeFileSync6 } = await import("node:fs");
+        writeFileSync6(options.output, JSON.stringify(spec, null, 2));
         process.stderr.write(`drift extract: wrote ${options.output}
 `);
       } else {
@@ -2951,8 +3307,8 @@ function registerExtractCommand(program) {
 }
 
 // src/commands/filter.ts
-import { readFileSync as readFileSync15 } from "node:fs";
-import * as path20 from "node:path";
+import { readFileSync as readFileSync18 } from "node:fs";
+import * as path24 from "node:path";
 import { filterSpec } from "@openpkg-ts/sdk";
 
 // src/formatters/filter.ts
@@ -2983,8 +3339,8 @@ function registerFilterCommand(program) {
     const startTime = Date.now();
     const version = getVersion();
     try {
-      const filePath = path20.resolve(process.cwd(), file);
-      const content = readFileSync15(filePath, "utf-8");
+      const filePath = path24.resolve(process.cwd(), file);
+      const content = readFileSync18(filePath, "utf-8");
       const spec = JSON.parse(content);
       const criteria = {};
       if (options.kind) {
@@ -3010,7 +3366,7 @@ function registerFilterCommand(program) {
 }
 
 // src/commands/get.ts
-import * as path21 from "node:path";
+import * as path25 from "node:path";
 import { getExport, listExports } from "@openpkg-ts/sdk";
 
 // src/formatters/get.ts
@@ -3261,7 +3617,7 @@ function registerGetCommand(program) {
       let entryFile;
       let exportName;
       if (name) {
-        entryFile = path21.resolve(process.cwd(), nameOrEntry);
+        entryFile = path25.resolve(process.cwd(), nameOrEntry);
         exportName = name;
       } else {
         entryFile = detectEntry();
@@ -3334,7 +3690,7 @@ function renderNotFound(exportName, suggestions, startTime, version) {
 }
 
 // src/commands/health.ts
-import * as path22 from "node:path";
+import * as path26 from "node:path";
 import { computeDrift as computeDrift3, isExternalExport as isExternalExport2 } from "@driftdev/sdk";
 
 // src/formatters/health.ts
@@ -3455,9 +3811,9 @@ function registerHealthCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      let entryFile = entry ? path22.resolve(process.cwd(), entry) : undefined;
+      let entryFile = entry ? path26.resolve(process.cwd(), entry) : undefined;
       if (lang === "typescript" && !entryFile) {
-        entryFile = config.entry ? path22.resolve(process.cwd(), config.entry) : detectEntry();
+        entryFile = config.entry ? path26.resolve(process.cwd(), config.entry) : detectEntry();
       }
       const {
         apiSpec: spec,
@@ -3522,8 +3878,8 @@ function registerHealthCommand(program) {
 
 // src/commands/init.ts
 init_global();
-import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync16, writeFileSync as writeFileSync5 } from "node:fs";
-import * as path23 from "node:path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync6, readFileSync as readFileSync19, writeFileSync as writeFileSync6 } from "node:fs";
+import * as path27 from "node:path";
 import { extract as extract6 } from "@openpkg-ts/sdk";
 import { normalize as normalize7 } from "@openpkg-ts/spec";
 
@@ -3829,14 +4185,14 @@ ${detailLine}`);
 
 // src/commands/init.ts
 async function scanPackage(cwd, pkgDir) {
-  const absDir = path23.join(cwd, pkgDir);
-  if (!existsSync13(absDir))
+  const absDir = path27.join(cwd, pkgDir);
+  if (!existsSync14(absDir))
     return null;
-  const pkgPath = path23.join(absDir, "package.json");
+  const pkgPath = path27.join(absDir, "package.json");
   let name = pkgDir;
-  if (existsSync13(pkgPath)) {
+  if (existsSync14(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync16(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
       if (pkg.name)
         name = pkg.name;
     } catch {}
@@ -3854,7 +4210,7 @@ async function scanPackage(cwd, pkgDir) {
     }
     const coverage = total > 0 ? Math.round(documented / total * 100) : 100;
     const health = Math.round(coverage * 0.5 + 100 * 0.5);
-    return { name, entry: path23.relative(cwd, entryFile), exports: total, coverage, health };
+    return { name, entry: path27.relative(cwd, entryFile), exports: total, coverage, health };
   } catch {
     return null;
   }
@@ -3891,13 +4247,13 @@ function registerInitCommand(program) {
         return;
       }
       const config = generateConfig(packages);
-      const configPath = opts.project ? path23.resolve(cwd, "drift.config.json") : getGlobalConfigPath();
+      const configPath = opts.project ? path27.resolve(cwd, "drift.config.json") : getGlobalConfigPath();
       if (!opts.project) {
         const globalDir = getGlobalDir();
-        if (!existsSync13(globalDir))
+        if (!existsSync14(globalDir))
           mkdirSync6(globalDir, { recursive: true });
       }
-      writeFileSync5(configPath, `${JSON.stringify(config, null, 2)}
+      writeFileSync6(configPath, `${JSON.stringify(config, null, 2)}
 `);
       ensureProjectDir(cwd);
       const data = {
@@ -3915,7 +4271,7 @@ function registerInitCommand(program) {
 }
 
 // src/commands/lint.ts
-import * as path25 from "node:path";
+import * as path28 from "node:path";
 import { buildExportRegistry, computeDrift as computeDrift4, detectProseDrift } from "@driftdev/sdk";
 
 // src/formatters/lint.ts
@@ -3972,44 +4328,6 @@ function emitAnnotations(issues, level = "error") {
   }
 }
 
-// src/utils/docs-corpus.ts
-import { readFileSync as readFileSync17, statSync as statSync2 } from "node:fs";
-import * as path24 from "node:path";
-import { discoverMarkdownFiles } from "@driftdev/sdk";
-function resolveDocsCorpus(cwd, docsPatterns, configDocs) {
-  if (!docsPatterns || docsPatterns.length === 0) {
-    return discoverMarkdownFiles(cwd, configDocs);
-  }
-  const include = [];
-  for (const pattern of docsPatterns) {
-    if (isDirectory(path24.resolve(cwd, pattern))) {
-      include.push(path24.join(pattern, "**/*.md"), path24.join(pattern, "**/*.mdx"));
-    } else {
-      include.push(pattern);
-    }
-  }
-  const files = discoverMarkdownFiles(cwd, { include });
-  if (files.length === 0) {
-    formatWarning(`--docs matched no markdown files: ${docsPatterns.join(", ")}`);
-  }
-  return files;
-}
-function isDirectory(p) {
-  try {
-    return statSync2(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
-function readPackageName(cwd = process.cwd()) {
-  try {
-    const pkgJson = JSON.parse(readFileSync17(path24.resolve(cwd, "package.json"), "utf-8"));
-    return typeof pkgJson.name === "string" ? pkgJson.name : undefined;
-  } catch {
-    return;
-  }
-}
-
 // src/commands/lint.ts
 function registerLintCommand(program) {
   program.command("lint [entry]").description("Cross-reference docs against the API surface for accuracy issues").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").option("--docs <patterns...>", "Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)").option("--annotations", "Emit GitHub Actions ::error annotations for findings").action(async (entry, options) => {
@@ -4064,9 +4382,9 @@ function registerLintCommand(program) {
         formatOutput("lint", { issues: [], count: 0 }, startTime, version, renderLint);
         return;
       }
-      let entryFile = entry ? path25.resolve(process.cwd(), entry) : undefined;
+      let entryFile = entry ? path28.resolve(process.cwd(), entry) : undefined;
       if (lang === "typescript" && !entryFile) {
-        entryFile = config.entry ? path25.resolve(process.cwd(), config.entry) : detectEntry();
+        entryFile = config.entry ? path28.resolve(process.cwd(), config.entry) : detectEntry();
       }
       const { apiSpec: spec } = await resolveTruth({
         entry: entryFile,
@@ -4132,7 +4450,7 @@ function registerLintCommand(program) {
 }
 
 // src/commands/list.ts
-import * as path26 from "node:path";
+import * as path29 from "node:path";
 import { computeDrift as computeDrift5 } from "@driftdev/sdk";
 import { listExports as listExports2 } from "@openpkg-ts/sdk";
 
@@ -4247,7 +4565,7 @@ function registerListCommand(program) {
       } else {
         let entryFile;
         if (searchOrEntry && looksLikeFilePath(searchOrEntry)) {
-          entryFile = path26.resolve(process.cwd(), searchOrEntry);
+          entryFile = path29.resolve(process.cwd(), searchOrEntry);
         } else if (searchOrEntry) {
           entryFile = detectEntry();
           searchTerm = searchOrEntry;
@@ -4323,7 +4641,7 @@ function truthFlags(args) {
   return out;
 }
 function runDrift(cliArgs, cwd) {
-  return new Promise((resolve19) => {
+  return new Promise((resolve22) => {
     const child = spawn(process.execPath, [process.argv[1], ...cliArgs, "--json"], {
       cwd: cwd ?? process.cwd(),
       env: { ...process.env, NO_COLOR: "1" },
@@ -4343,9 +4661,9 @@ function runDrift(cliArgs, cwd) {
       try {
         ok = JSON.parse(stdout).ok === true;
       } catch {}
-      resolve19({ text, ok });
+      resolve22({ text, ok });
     });
-    child.on("error", (err) => resolve19({ text: `Failed to run drift: ${err.message}`, ok: false }));
+    child.on("error", (err) => resolve22({ text: `Failed to run drift: ${err.message}`, ok: false }));
   });
 }
 function toResult({ text, ok }) {
@@ -4503,8 +4821,8 @@ function diffArgs(command, args) {
 
 // src/commands/release.ts
 import { execSync as execSync4 } from "node:child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync18 } from "node:fs";
-import * as path27 from "node:path";
+import { existsSync as existsSync15, readFileSync as readFileSync20 } from "node:fs";
+import * as path30 from "node:path";
 import { computeDrift as computeDrift6 } from "@driftdev/sdk";
 
 // src/formatters/release.ts
@@ -4552,11 +4870,11 @@ function getLastTag() {
   }
 }
 function getPackageVersion(cwd) {
-  const pkgPath = path27.join(cwd, "package.json");
-  if (!existsSync14(pkgPath))
+  const pkgPath = path30.join(cwd, "package.json");
+  if (!existsSync15(pkgPath))
     return null;
   try {
-    return JSON.parse(readFileSync18(pkgPath, "utf-8")).version ?? null;
+    return JSON.parse(readFileSync20(pkgPath, "utf-8")).version ?? null;
   } catch {
     return null;
   }
@@ -4568,7 +4886,7 @@ function registerReleaseCommand(program) {
     const cwd = process.cwd();
     try {
       const { config } = loadConfig();
-      const entryFile = entry ? path27.resolve(cwd, entry) : config.entry ? path27.resolve(cwd, config.entry) : detectEntry();
+      const entryFile = entry ? path30.resolve(cwd, entry) : config.entry ? path30.resolve(cwd, config.entry) : detectEntry();
       const { spec } = await cachedExtract(entryFile);
       const exports = spec.exports ?? [];
       const total = exports.length;
@@ -4692,8 +5010,8 @@ function renderReport(data) {
 
 // src/utils/scan-packages.ts
 import { execSync as execSync5 } from "node:child_process";
-import { existsSync as existsSync15, readFileSync as readFileSync19 } from "node:fs";
-import * as path28 from "node:path";
+import { existsSync as existsSync16, readFileSync as readFileSync21 } from "node:fs";
+import * as path31 from "node:path";
 import { computeDrift as computeDrift7 } from "@driftdev/sdk";
 function detectPackageDirs2(cwd) {
   const workspaces = detectWorkspaces(cwd);
@@ -4712,14 +5030,14 @@ async function scanAllPackages(cwd) {
   const packageDirs = detectPackageDirs2(cwd);
   const results = [];
   for (const dir of packageDirs) {
-    const absDir = dir === "." ? cwd : path28.join(cwd, dir);
-    if (!existsSync15(absDir))
+    const absDir = dir === "." ? cwd : path31.join(cwd, dir);
+    if (!existsSync16(absDir))
       continue;
     let name = dir;
-    const pkgPath = path28.join(absDir, "package.json");
-    if (existsSync15(pkgPath)) {
+    const pkgPath = path31.join(absDir, "package.json");
+    if (existsSync16(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync21(pkgPath, "utf-8"));
         if (pkg.name)
           name = pkg.name;
       } catch {}
@@ -4815,7 +5133,7 @@ function registerReportCommand(program) {
 }
 
 // src/commands/scan.ts
-import * as path29 from "node:path";
+import * as path32 from "node:path";
 import {
   buildExportRegistry as buildExportRegistry2,
   computeDrift as computeDrift8,
@@ -4851,6 +5169,20 @@ function renderScan(data, next) {
     }
     lines.push("");
   }
+  if (data.docsCoverage) {
+    lines.push(indent("Docs coverage"));
+    lines.push(indent(c.gray(separator())));
+    for (const page of data.docsCoverage.pages) {
+      const mark = page.status === "fail" ? c.red(sym.x) : page.status === "warn" ? c.yellow("!") : c.green(sym.ok);
+      const cts = page.counts;
+      lines.push(indent(`${mark} ${page.page}  ${c.dim(`${page.type}: ${cts.documented} documented, ${cts.code} in code, ${cts.gapsUserFacing} gaps, ${cts.ghosts} ghosts, ${cts.inversions} inversions`)}`));
+      for (const f of page.failures)
+        lines.push(indent(`  ${c.red(f)}`));
+      for (const w of page.warnings)
+        lines.push(indent(`  ${c.yellow(w)}`));
+    }
+    lines.push("");
+  }
   if (data.pass) {
     lines.push(indent(`${c.green(sym.ok)} Scan passed`));
   } else {
@@ -4884,7 +5216,7 @@ function renderBatchScan(data) {
 
 // src/commands/scan.ts
 function registerScanCommand(program) {
-  program.command("scan [entry]").description("Run coverage + lint + prose drift in one pass").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").option("--docs <patterns...>", "Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)").action(async (entry, options) => {
+  program.command("scan [entry]").description("Run coverage + lint + prose drift in one pass").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").option("--docs <patterns...>", "Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)").option("--docs-map <file>", "Docs map (page→type) activating key-coverage mode: gaps/ghosts/inversions per page").option("--annotations", "Emit GitHub Actions ::error/::warning annotations for findings").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -4898,6 +5230,10 @@ function registerScanCommand(program) {
         formatError("scan", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
         return;
       }
+      if (options.all && options.docsMap) {
+        formatError("scan", "--docs-map is not supported with --all", startTime, version);
+        return;
+      }
       if (lang === "clarity" && !options.abi) {
         formatError("scan", "--abi is required when --lang clarity", startTime, version);
         return;
@@ -4959,9 +5295,9 @@ function registerScanCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      let entryFile = entry ? path29.resolve(process.cwd(), entry) : undefined;
+      let entryFile = entry ? path32.resolve(process.cwd(), entry) : undefined;
       if (lang === "typescript" && !entryFile) {
-        entryFile = config.entry ? path29.resolve(process.cwd(), config.entry) : detectEntry();
+        entryFile = config.entry ? path32.resolve(process.cwd(), config.entry) : detectEntry();
       }
       const { apiSpec, packageName, packageVersion } = await resolveTruth({
         entry: entryFile,
@@ -5017,6 +5353,11 @@ function registerScanCommand(program) {
           formatWarning(`Prose drift skipped: ${err instanceof Error ? err.message : String(err)}`);
         }
       }
+      let docsCoverage;
+      if (options.docsMap) {
+        const loaded = loadDocsMap(options.docsMap);
+        docsCoverage = await runDocsCoverage(loaded, apiSpec);
+      }
       const healthIssues = issues.map((i) => ({ export: i.export, issue: i.issue }));
       const h = computeHealth(total, documented, healthIssues);
       let min = options.min ? parseInt(options.min, 10) : config.coverage?.min;
@@ -5024,7 +5365,7 @@ function registerScanCommand(program) {
         const ratchet = computeRatchetMin(min);
         min = ratchet.effectiveMin;
       }
-      const pass = min === undefined || h.health >= min;
+      const pass = (min === undefined || h.health >= min) && (docsCoverage?.pass ?? true);
       const data = {
         coverage: {
           score: coverageScore,
@@ -5037,7 +5378,26 @@ function registerScanCommand(program) {
         health: h.health,
         pass,
         packageName,
-        packageVersion
+        packageVersion,
+        ...docsCoverage ? {
+          docsCoverage: {
+            pass: docsCoverage.pass,
+            pages: docsCoverage.pages.map((p) => ({
+              page: p.page,
+              type: p.type,
+              status: p.status,
+              baselineGaps: p.baselineGaps,
+              counts: p.result.counts,
+              failures: p.failures,
+              warnings: p.warnings,
+              gaps: p.result.gaps,
+              ghosts: p.result.ghosts,
+              inversions: p.result.inversions,
+              documentedKeysFromOtherTypes: p.result.documentedKeysFromOtherTypes,
+              annotated: p.result.annotated
+            }))
+          }
+        } : {}
       };
       let next;
       if (issues.length > 0) {
@@ -5052,9 +5412,16 @@ function registerScanCommand(program) {
         };
       }
       formatOutput("scan", data, startTime, version, renderScan, next);
+      if (options.annotations && docsCoverage) {
+        emitAnnotations(docsCoverage.annotations.errors, "error");
+        emitAnnotations(docsCoverage.annotations.warnings, "warning");
+      }
+      if (options.annotations && issues.length > 0)
+        emitAnnotations(issues);
       if (!pass) {
         if (!shouldRenderHuman()) {
-          process.stderr.write(`scan failed: health ${h.health}%${min !== undefined ? ` (need ${min}%)` : ""}, ${issues.length} issues
+          const covFails = docsCoverage ? docsCoverage.pages.flatMap((p) => p.failures.map((f) => `${p.page}: ${f}`)) : [];
+          process.stderr.write(`scan failed: health ${h.health}%${min !== undefined ? ` (need ${min}%)` : ""}, ${issues.length} issues${covFails.length > 0 ? `; docs coverage: ${covFails.join(" | ")}` : ""}
 `);
         }
         process.exitCode = 1;
@@ -5105,8 +5472,8 @@ function registerSemverCommand(program) {
 }
 
 // src/commands/validate.ts
-import { readFileSync as readFileSync20 } from "node:fs";
-import * as path30 from "node:path";
+import { readFileSync as readFileSync22 } from "node:fs";
+import * as path33 from "node:path";
 import { validateSpec } from "@openpkg-ts/spec";
 
 // src/formatters/validate.ts
@@ -5132,8 +5499,8 @@ function registerValidateCommand(program) {
     const startTime = Date.now();
     const version = getVersion();
     try {
-      const filePath = path30.resolve(process.cwd(), file);
-      const content = readFileSync20(filePath, "utf-8");
+      const filePath = path33.resolve(process.cwd(), file);
+      const content = readFileSync22(filePath, "utf-8");
       const spec = JSON.parse(content);
       const result = validateSpec(spec);
       const data = {
@@ -5184,7 +5551,11 @@ var COMMAND_EXAMPLES = {
   validate: ["drift validate spec.json --json"],
   filter: ["drift filter spec.json --kind function --json"],
   report: ["drift report --json"],
-  cache: ["drift cache status", "drift cache clear"]
+  cache: ["drift cache status", "drift cache clear"],
+  "docs-map": [
+    "drift docs-map stub --docs docs/ --out drift.docs-map.json",
+    "drift docs-map baseline drift.docs-map.json"
+  ]
 };
 function extractCapabilities(program) {
   const commands = [];
@@ -5235,6 +5606,15 @@ function extractCapabilities(program) {
         name: "examples",
         description: "Example validation results",
         operations: { read: "examples" }
+      },
+      {
+        name: "docs-map",
+        description: "Committed page→type map for docs key-coverage mode",
+        operations: {
+          create: "docs-map stub",
+          update: "docs-map baseline",
+          read: "scan --docs-map <file>"
+        }
       }
     ],
     workflows: {
@@ -5251,6 +5631,10 @@ function extractCapabilities(program) {
       "pre-release": {
         steps: ["scan", "breaking", "release"],
         description: "Full pre-release quality gate"
+      },
+      "docs-key-coverage": {
+        steps: ["docs-map stub", "scan --docs-map", "docs-map baseline"],
+        description: "Gap/ghost/inversion gate: docs pages vs spec type keys"
       }
     }
   };
@@ -5258,13 +5642,13 @@ function extractCapabilities(program) {
 
 // src/drift.ts
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname3 = path31.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync21(path31.join(__dirname3, "../package.json"), "utf-8"));
+var __dirname3 = path34.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync23(path34.join(__dirname3, "../package.json"), "utf-8"));
 var program = new Command;
 program.name("drift").description("drift — detect when your docs drift from your code").version(packageJson.version).option("--json", "Force JSON output (default when piped)").option("--human", "Force human-readable output (default in terminal)").option("--config <path>", "Path to drift config file").option("--cwd <dir>", "Run as if started in <dir>").option("--no-cache", "Bypass spec cache").option("--tools", "List all available tools for agent use (JSON)").hook("preAction", (_thisCommand) => {
   const opts = program.opts();
   if (opts.cwd) {
-    process.chdir(path31.resolve(opts.cwd));
+    process.chdir(path34.resolve(opts.cwd));
   }
   setOutputMode({ json: opts.json, human: opts.human });
   setConfigPath(opts.config);
@@ -5276,6 +5660,7 @@ registerExtractCommand(program);
 registerListCommand(program);
 registerGetCommand(program);
 registerValidateCommand(program);
+registerDocsMapCommand(program);
 registerFilterCommand(program);
 registerCoverageCommand(program);
 registerExamplesCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "Drift CLI - detect when your docs drift from your code",
   "keywords": [
     "typescript",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@driftdev/clarity-adapter": "^1.0.1",
     "@driftdev/openapi-adapter": "^1.0.1",
-    "@driftdev/sdk": "^1.11.0",
+    "@driftdev/sdk": "^1.12.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openpkg-ts/sdk": "^0.43.0",
     "@openpkg-ts/spec": "^0.43.0",

package/schemas/drift.docs-map.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@driftdev/cli/schemas/drift.docs-map.schema.json",
+  "title": "Drift docs map",
+  "description": "Page→type mapping for docs key-coverage mode (drift scan --docs-map). The committed artifact of the LLM-writes-the-map / machine-runs-the-map split: an agent may propose it, a human commits it, CI runs it deterministically.",
+  "type": "object",
+  "required": ["version", "pages"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["page", "type"],
+        "properties": {
+          "page": {
+            "type": "string",
+            "description": "Docs page path, relative to this file's directory"
+          },
+          "extraPages": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Additional pages/globs merged into the same corpus (e.g. _snippets/*.mdx)"
+          },
+          "type": {
+            "type": "string",
+            "description": "Spec type whose property keys this page documents"
+          },
+          "spec": {
+            "type": "string",
+            "description": "Committed spec file to diff against (relative to this file). Mutually exclusive with entry; omit both to use the scan target."
+          },
+          "entry": {
+            "type": "string",
+            "description": "Entry file to extract the spec from. Mutually exclusive with spec."
+          },
+          "sectionRe": {
+            "type": "string",
+            "description": "Case-insensitive heading regex opening an options section (default: option|config)"
+          },
+          "internal": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Internal keys beyond the _-prefix convention (excluded from user-facing gaps)"
+          },
+          "deprecated": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Deprecated override — auto-derived from spec metadata when omitted"
+          },
+          "replacements": {
+            "type": "object",
+            "additionalProperties": { "type": "string" },
+            "description": "deprecatedKey → replacementKey override — auto-derived from spec deprecation reasons when omitted"
+          },
+          "annotations": {
+            "type": "object",
+            "additionalProperties": {
+              "enum": ["prose-documented", "internal-by-convention", "ignore"]
+            },
+            "description": "Agent-proposed, human-committed key classifications. prose-documented: genuinely documented in prose, excluded from gap FAIL; internal-by-convention: treated as internal; ignore: excluded entirely (state the reason in a nearby comment key)."
+          },
+          "baselineGaps": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Gap ratchet: CI fails when user-facing gaps exceed this committed count. Drift shrinks, never grows — use `drift docs-map baseline` to tighten."
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}