@ghostbyte/agent-docs-kit 4.0.2 → 5.0.0

package/skills/manage-project-quality/scripts/check-report.mjs

@@ -1,23 +1,74 @@
 #!/usr/bin/env node
 
 import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 
-const file = process.argv[2];
-if (!file) throw new Error("Usage: node check-report.mjs <report.md>");
-const text = await readFile(file, "utf8");
-const allowed = new Set(["Pass", "Fail", "Unverified", "N/A", "Applied", "Partial", "Recommended"]);
-const errors = [];
-for (const [index, line] of text.split(/\r?\n/).entries()) {
-  if (!line.startsWith("|") || /^\|[-: |]+\|$/.test(line)) continue;
-  const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
-  const status = cells.find((cell) => allowed.has(cell));
-  if (status && status !== "Unverified" && !cells.some((cell, cellIndex) => cellIndex > 1 && cell.length > 3)) {
-    errors.push(`Line ${index + 1}: status '${status}' has no supporting detail.`);
+const statuses = {
+  security: new Set(["Pass", "Fail", "Unverified", "N/A"]),
+  engineering: new Set(["Applied", "Partial", "Recommended", "Unverified", "N/A"]),
+  documentation: new Set(["Pass", "Fail", "Unverified", "N/A"]),
+  generic: new Set(["Pass", "Fail", "Unverified", "N/A", "Applied", "Partial", "Recommended"])
+};
+const placeholders = /^(?:|_|-+|none|not verified|unassigned)$/i;
+
+function splitRow(line) {
+  const cells = [];
+  let cell = "";
+  for (let index = 1; index < line.length - 1; index += 1) {
+    if (line[index] === "|" && line[index - 1] !== "\\") {
+      cells.push(cell.trim());
+      cell = "";
+    } else {
+      cell += line[index];
+    }
+  }
+  cells.push(cell.trim());
+  return cells;
+}
+
+export function validateReport(text) {
+  const errors = [];
+  let header;
+  let allowed = statuses.generic;
+  let foundFindings = false;
+  const lines = text.split(/\r?\n/);
+  for (const [index, line] of lines.entries()) {
+    if (!line.startsWith("|")) { header = undefined; continue; }
+    if (/^\|[-: |]+\|$/.test(line)) continue;
+    const cells = splitRow(line);
+    if (/^\|[-: |]+\|$/.test(lines[index + 1] ?? "")) {
+      header = cells.map((cell) => cell.toLowerCase());
+      if (!header.includes("status")) { header = undefined; continue; }
+      foundFindings = true;
+      allowed = header.includes("control id") ? statuses.security : header.includes("practice id") ? statuses.engineering : statuses.generic;
+      continue;
+    }
+    if (!header) continue;
+    const statusIndex = header.indexOf("status");
+    const status = cells[statusIndex];
+    if (!status) { errors.push(`Line ${index + 1}: status is empty.`); continue; }
+    if (!allowed.has(status)) { errors.push(`Line ${index + 1}: invalid status '${status}'.`); continue; }
+    if (!["Unverified", "N/A"].includes(status)) {
+      for (const name of ["evidence", "owner", "verification"]) {
+        const column = header.findIndex((cell) => cell === name || cell.includes(name));
+        if (column >= 0 && placeholders.test(cells[column] ?? "")) errors.push(`Line ${index + 1}: status '${status}' requires ${name}.`);
+      }
+    }
   }
+  if (!foundFindings) errors.push("No findings table with a Status column was found.");
+  return errors;
 }
-if (errors.length) {
-  console.error(errors.join("\n"));
-  process.exitCode = 1;
-} else {
-  console.log("Report structure check passed.");
+
+export async function checkReport(file) {
+  const errors = validateReport(await readFile(file, "utf8"));
+  if (errors.length) throw new Error(errors.join("\n"));
+  return true;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const file = process.argv[2];
+  if (!file) throw new Error("Usage: node check-report.mjs <report.md>");
+  try { await checkReport(file); console.log("Report structure check passed."); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
 }

package/src/api/index.mjs

@@ -1,4 +1,8 @@
 export { setupProject } from "../commands/setup.mjs";
 export { auditDocumentation, auditSecurity, reviewEngineering } from "../commands/audit.mjs";
 export { installSkill } from "../commands/skill.mjs";
+export { createTemplate, listTemplates, templateTypes } from "../commands/template.mjs";
+export { showDocumentationGuide } from "../commands/guide.mjs";
+export { openWebsite, websiteUrl } from "../commands/website.mjs";
 export { loadCatalog } from "../core/catalog.mjs";
+export { loadProjectConfig, defaultConfig } from "../core/config.mjs";

package/src/cli/arguments.mjs

@@ -1,3 +1,8 @@
+const booleanFlags = new Set(["dry-run", "force", "report", "strict", "help", "version"]);
+const valueFlags = new Set(["cwd", "style", "target", "phase", "topic", "format", "type", "name"]);
+const allowedStyles = new Set(["standard", "learning"]);
+const allowedFormats = new Set(["text", "markdown", "json"]);
+
 export function parseArguments(argv) {
   const positionals = [];
   const flags = {};
@@ -8,10 +13,16 @@ export function parseArguments(argv) {
       continue;
     }
     const [rawKey, inline] = token.slice(2).split("=", 2);
+    if (!booleanFlags.has(rawKey) && !valueFlags.has(rawKey)) {
+      throw new Error(`Unknown option '--${rawKey}'. Run 'agent-docs --help'.`);
+    }
     if (inline !== undefined) {
+      if (booleanFlags.has(rawKey)) throw new Error(`Option '--${rawKey}' does not accept a value.`);
       flags[rawKey] = inline;
-    } else if (argv[index + 1] && !argv[index + 1].startsWith("--")) {
+    } else if (valueFlags.has(rawKey) && argv[index + 1] && !argv[index + 1].startsWith("--")) {
       flags[rawKey] = argv[++index];
+    } else if (valueFlags.has(rawKey)) {
+      throw new Error(`Option '--${rawKey}' requires a value.`);
     } else {
       flags[rawKey] = true;
     }
@@ -20,11 +31,24 @@ export function parseArguments(argv) {
 }
 
 export function optionsFromFlags(flags) {
+  const style = flags.style;
+  const format = flags.format ?? "text";
+  if (style !== undefined && !allowedStyles.has(style)) throw new Error(`Invalid style '${style}'. Use standard or learning.`);
+  if (!allowedFormats.has(format)) throw new Error(`Invalid format '${format}'. Use text, markdown, or json.`);
+  if (flags.target && !["project", "codex"].includes(flags.target)) {
+    throw new Error(`Invalid target '${flags.target}'. Use project or codex.`);
+  }
+  if (flags.name && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(flags.name)) {
+    throw new Error(`Invalid name '${flags.name}'. Use a lowercase hyphenated slug.`);
+  }
   return {
     cwd: flags.cwd,
     dryRun: Boolean(flags["dry-run"]),
     force: Boolean(flags.force),
-    style: flags.style ?? "standard",
-    report: Boolean(flags.report)
+    style,
+    format,
+    report: Boolean(flags.report),
+    strict: Boolean(flags.strict),
+    name: flags.name
   };
 }

package/src/cli/help.mjs

@@ -1,24 +1,59 @@
 export const helpText = `Agent Docs & Quality Kit
 
-Usage:
-  agent-docs                         Open the guided menu (TTY only)
-  agent-docs setup [--dry-run]       Install the documentation workspace
-  agent-docs audit documentation     Check documentation health
-  agent-docs audit security [phase]  Create an evidence-based security worksheet
-  agent-docs review engineering [topic]
-                                     Create an engineering review worksheet
-  agent-docs list [security|engineering]
-  agent-docs skill install [--target project|codex] [--dry-run]
-  agent-docs validate                Validate this package's catalog and skill
-  agent-docs doctor                  Check local prerequisites
-  agent-docs --version               Show the package version
+Run without installing:
+  npx @ghostbyte/agent-docs-kit@latest [command] [options]
+
+After installing in a project:
+  npx agent-docs [command] [options]
+
+After installing globally:
+  agent-docs [command] [options]
+
+Commands:
+  (no command)                       Open the guided menu (TTY only)
+  setup [--dry-run]                  Create the documentation workspace
+  audit documentation [--strict]     Check documentation health
+  documentation guide <area>         Print one documentation guidance area
+  security worksheet <phase>         Create a scoped security worksheet
+  engineering worksheet <topic>      Create a scoped engineering worksheet
+  audit security <phase>              Legacy alias for security worksheet
+  review engineering <topic>          Legacy alias for engineering worksheet
+  list [documentation|security|engineering]
+                                     List available areas, phases, or topics
+  template list                      List reusable documentation templates
+  template create <type> [--name <slug>]
+                                     Create a uniquely named documentation record
+  skill install --target project|codex
+                                     Install the unified quality skill
+  validate                           Validate the distributed library
+  doctor                             Check Node.js and Git prerequisites
+  website                            Open the documentation website
+  --version                          Show the package version
+
+Examples:
+  npx @ghostbyte/agent-docs-kit@latest setup --dry-run
+  npx @ghostbyte/agent-docs-kit@latest audit documentation --strict --format text
+  npx @ghostbyte/agent-docs-kit@latest documentation guide system-documentation
+  npx @ghostbyte/agent-docs-kit@latest security worksheet api-layer
+  npx @ghostbyte/agent-docs-kit@latest engineering worksheet testing-types
+  npx @ghostbyte/agent-docs-kit@latest template create adr --name cache-policy
+  npx @ghostbyte/agent-docs-kit@latest skill install --target project
+  npx @ghostbyte/agent-docs-kit@latest website
+
+Check or update a global installation:
+  agent-docs --version
+  npm view @ghostbyte/agent-docs-kit version
+  npm install --global @ghostbyte/agent-docs-kit@latest
 
 Options:
-  --cwd <path>             Target project (default: current directory)
-  --style standard|learning
-  --dry-run                Preview writes without changing files
-  --force                  Replace files that this command owns
-  --report                 Write documentation audit results
-  --help                   Show this help
+  --cwd <path>                Target project (default: current directory)
+  --style standard|learning   Select concise or teaching-oriented output
+  --format text|markdown|json Select documentation-audit output
+  --name <slug>               Give a template a lowercase hyphenated name
+  --dry-run                   Preview writes without changing files
+  --force                     Replace files owned by the command
+  --report                    Persist documentation audit results
+  --strict                    Fail when documentation checks fail
+  --help                      Show this help
 
 Installing the npm package performs no project setup. Run a command explicitly.`;

package/src/cli/main.mjs

@@ -8,13 +8,26 @@ import { listCatalog } from "../commands/list.mjs";
 import { installSkill } from "../commands/skill.mjs";
 import { doctor } from "../commands/doctor.mjs";
 import { validatePackage } from "../commands/validate.mjs";
+import { openWebsite } from "../commands/website.mjs";
+import { createTemplate, listTemplates } from "../commands/template.mjs";
+import { showDocumentationGuide } from "../commands/guide.mjs";
 import { readFile } from "node:fs/promises";
 import { resolveFromPackage } from "../core/paths.mjs";
 
+function assertInvocation(positionals, flags, { counts, allowedFlags = [], usage, exclusive = [] }) {
+  if (!counts.includes(positionals.length)) throw new Error(`Invalid arguments. Usage: ${usage}`);
+  const allowed = new Set(allowedFlags);
+  const unexpected = Object.keys(flags).filter((flag) => !allowed.has(flag));
+  if (unexpected.length) throw new Error(`Option '--${unexpected[0]}' is not valid here. Usage: ${usage}`);
+  for (const [positionalIndex, flag] of exclusive) {
+    if (positionals[positionalIndex] && flags[flag]) throw new Error(`Choose either '${positionals[positionalIndex]}' or '--${flag}', not both.`);
+  }
+}
+
 async function menu() {
   const ui = createInterface({ input: stdin, output: stdout });
   try {
-    console.log(`\nAgent Docs & Quality Kit\n\n1. Set up documentation\n2. Audit documentation\n3. Start security audit\n4. Start engineering review\n5. Install project skill\n6. Validate package\n0. Exit`);
+    console.log(`\nAgent Docs & Quality Kit\n\n1. Set up documentation\n2. Audit documentation\n3. Create security worksheet\n4. Create engineering worksheet\n5. Install project skill\n6. Validate package\n7. Open documentation website\n8. List documentation templates\n0. Exit`);
     const choice = await ui.question("\nChoose an action: ");
     if (choice === "1") return setupProject();
     if (choice === "2") return auditDocumentation();
@@ -28,6 +41,8 @@ async function menu() {
     }
     if (choice === "5") return installSkill("project");
     if (choice === "6") return validatePackage();
+    if (choice === "7") return openWebsite();
+    if (choice === "8") return listTemplates();
     if (choice !== "0") throw new Error("Unknown menu choice.");
   } finally {
     ui.close();
@@ -37,27 +52,69 @@ async function menu() {
 export async function main(argv) {
   const { positionals, flags } = parseArguments(argv);
   const [command, subject, selector] = positionals;
-  const options = optionsFromFlags(flags);
   if (flags.version || command === "version") {
+    if (!flags.version) assertInvocation(positionals, flags, { counts: [1], usage: "agent-docs version" });
     const metadata = JSON.parse(await readFile(resolveFromPackage("package.json"), "utf8"));
     return console.log(metadata.version);
   }
   if (flags.help || command === "help") return console.log(helpText);
+  const options = optionsFromFlags(flags);
   if (!command) {
+    assertInvocation(positionals, flags, { counts: [0], usage: "agent-docs" });
     if (!stdin.isTTY) {
       console.log(helpText);
       return;
     }
     return menu();
   }
-  if (command === "setup") return setupProject(options);
-  if (command === "audit" && subject === "documentation") return auditDocumentation(options);
-  if (command === "audit" && subject === "security") return auditSecurity(selector ?? flags.phase, options);
-  if (command === "review" && subject === "engineering") return reviewEngineering(selector ?? flags.topic, options);
-  if (command === "list") return listCatalog(subject);
-  if (command === "skill" && subject === "install") return installSkill(flags.target ?? "project", options);
-  if (command === "validate") return validatePackage();
+  if (command === "setup") {
+    assertInvocation(positionals, flags, { counts: [1], allowedFlags: ["cwd", "dry-run", "force"], usage: "agent-docs setup [--cwd <path>] [--dry-run] [--force]" });
+    return setupProject(options);
+  }
+  if (command === "audit" && subject === "documentation") {
+    assertInvocation(positionals, flags, { counts: [2], allowedFlags: ["cwd", "dry-run", "force", "report", "strict", "format"], usage: "agent-docs audit documentation [--strict] [--report] [--format text|markdown|json]" });
+    const result = await auditDocumentation(options);
+    if (options.strict && !result.pass) process.exitCode = 1;
+    return result;
+  }
+  if ((command === "audit" && subject === "security") || (command === "security" && subject === "worksheet")) {
+    assertInvocation(positionals, flags, { counts: [2, 3], allowedFlags: ["cwd", "dry-run", "force", "style", "phase"], usage: "agent-docs security worksheet <phase>", exclusive: [[2, "phase"]] });
+    return auditSecurity(selector ?? flags.phase, options);
+  }
+  if ((command === "review" && subject === "engineering") || (command === "engineering" && subject === "worksheet")) {
+    assertInvocation(positionals, flags, { counts: [2, 3], allowedFlags: ["cwd", "dry-run", "force", "style", "topic"], usage: "agent-docs engineering worksheet <topic>", exclusive: [[2, "topic"]] });
+    return reviewEngineering(selector ?? flags.topic, options);
+  }
+  if (command === "list") {
+    assertInvocation(positionals, flags, { counts: [2], usage: "agent-docs list documentation|security|engineering" });
+    return listCatalog(subject);
+  }
+  if (command === "documentation" && subject === "guide") {
+    assertInvocation(positionals, flags, { counts: [3], usage: "agent-docs documentation guide <area>" });
+    return showDocumentationGuide(selector);
+  }
+  if (command === "skill" && subject === "install") {
+    assertInvocation(positionals, flags, { counts: [2], allowedFlags: ["cwd", "dry-run", "force", "target"], usage: "agent-docs skill install --target project|codex" });
+    return installSkill(flags.target ?? "project", options);
+  }
+  if (command === "template" && subject === "list") {
+    assertInvocation(positionals, flags, { counts: [2], usage: "agent-docs template list" });
+    return listTemplates();
+  }
+  if (command === "template" && subject === "create") {
+    assertInvocation(positionals, flags, { counts: [2, 3], allowedFlags: ["cwd", "dry-run", "force", "type", "name"], usage: "agent-docs template create <type> [--name <slug>]", exclusive: [[2, "type"]] });
+    return createTemplate(selector ?? flags.type, options);
+  }
+  if (command === "validate") {
+    assertInvocation(positionals, flags, { counts: [1], usage: "agent-docs validate" });
+    return validatePackage();
+  }
+  if (command === "website") {
+    assertInvocation(positionals, flags, { counts: [1], usage: "agent-docs website" });
+    return openWebsite();
+  }
   if (command === "doctor") {
+    assertInvocation(positionals, flags, { counts: [1], usage: "agent-docs doctor" });
     if (!doctor()) process.exitCode = 1;
     return;
   }

package/src/commands/audit.mjs

@@ -1,49 +1,164 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, extname, relative, resolve } from "node:path";
 import { loadCatalog, selectEntry } from "../core/catalog.mjs";
-import { exists, writeSafe } from "../core/files.mjs";
+import { loadProjectConfig } from "../core/config.mjs";
+import { exists, writeUnique } from "../core/files.mjs";
 import { resolveFromPackage } from "../core/paths.mjs";
 
-const date = () => new Date().toISOString().slice(0, 10);
+export function localDate(value = new Date()) {
+  const year = value.getFullYear();
+  const month = String(value.getMonth() + 1).padStart(2, "0");
+  const day = String(value.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
 
 async function reportFor(kind, selector, options = {}) {
   const catalog = await loadCatalog();
-  const entries = catalog[kind];
-  const entry = selectEntry(entries, selector);
+  const entry = selectEntry(catalog[kind], selector);
   if (!entry) throw new Error(`Unknown ${kind} selection '${selector ?? ""}'. Run 'agent-docs list ${kind}'.`);
+  const { root, config } = await loadProjectConfig(options.cwd);
   const source = await readFile(resolveFromPackage(entry.source), "utf8");
-  const status = kind === "security" ? "Unverified" : "Unverified";
-  const heading = kind === "security" ? "Security audit" : "Engineering review";
-  const destinationRoot = kind === "security"
-    ? "docs/04-testing/security-audits"
-    : "docs/03-development/engineering-reviews";
-  const output = resolve(options.cwd ?? process.cwd(), destinationRoot, `${date()}-${entry.slug}.md`);
-  const body = `# ${heading}: ${entry.title}\n\n- Date: ${date()}\n- Style: ${options.style ?? "standard"}\n- Overall status: ${status}\n- Reviewer: _Unassigned_\n\n## Scope and authorization\n\n- Target: _Describe the code, configuration, or authorized environment_\n- Authorization: _Required before active security testing_\n- Exclusions: _List exclusions_\n\n## Findings\n\n| Check | Status | Evidence | Action |\n|---|---|---|---|\n| Add each applicable check | ${status} | File/line, command output, or external evidence | Required follow-up |\n\n## Reference checklist\n\n${source}\n`;
-  const result = await writeSafe(output, body, options);
-  console.log(`${result.status} ${output}`);
+  const reference = source.replace(/^#\s+(.+)$/m, "### $1");
+  const isSecurity = kind === "security";
+  const heading = isSecurity ? "Security worksheet" : "Engineering worksheet";
+  const destinationRoot = isSecurity ? config.securityReports : config.engineeringReports;
+  const output = resolve(root, destinationRoot, `${localDate()}-${entry.slug}.md`);
+  const context = isSecurity
+    ? `## Scope and authorization\n\n- Target: _Describe the code, configuration, or authorized test environment_\n- Authorization: _Required before active testing_\n- Exclusions: _List exclusions_\n- Test safety: _Record rate limits, test data, and stop conditions_`
+    : `## Review context\n\n- System or change: _Describe the reviewed scope_\n- Goal: _State the desired engineering outcome_\n- Constraints: _List material technical or delivery constraints_`;
+  const columns = isSecurity
+    ? "| Control ID | Priority | Status | Evidence | Remediation | Owner | Verification |\n|---|---|---|---|---|---|---|\n| Add each applicable control | Medium | Unverified | File/line, command output, or approved observation | Required follow-up | Unassigned | Not verified |"
+    : "| Practice ID | Status | Evidence | Impact | Recommendation | Owner | Verification |\n|---|---|---|---|---|---|---|\n| Add each applicable practice | Unverified | File/line, metric, trace, or test output | State the measurable impact | Recommended follow-up | Unassigned | Not verified |";
+  const body = `# ${heading}: ${entry.title}\n\n- Date: ${localDate()}\n- Style: ${options.style ?? config.interactionStyle}\n- Overall status: Unverified\n- Reviewer: _Unassigned_\n\n${context}\n\n## Findings\n\n${columns}\n\n## Reference checklist\n\n${reference.trim()}\n`;
+  const result = await writeUnique(output, body, options);
+  console.log(`${result.status} ${result.path}`);
   return result;
 }
 
 export const auditSecurity = (selector, options) => reportFor("security", selector, options);
 export const reviewEngineering = (selector, options) => reportFor("engineering", selector, options);
 
+async function markdownFiles(directory) {
+  if (!(await exists(directory))) return [];
+  const found = [];
+  for (const item of await readdir(directory, { withFileTypes: true })) {
+    const path = resolve(directory, item.name);
+    if (item.isDirectory()) found.push(...await markdownFiles(path));
+    else if (item.isFile() && extname(item.name).toLowerCase() === ".md") found.push(path);
+  }
+  return found;
+}
+
+function anchors(markdown) {
+  return new Set([...markdown.matchAll(/^#{1,6}\s+(.+)$/gm)].map(([, heading]) => heading.toLowerCase().trim().replace(/[^\p{L}\p{N}\s-]/gu, "").replace(/\s+/g, "-")));
+}
+
+function validDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? "")) return false;
+  const parsed = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+
+function frontMatterValues(block) {
+  return Object.fromEntries([...block.matchAll(/^([A-Za-z][\w-]*):\s*(.*?)\s*$/gm)].map((match) => [match[1], match[2].replace(/^['"]|['"]$/g, "")]));
+}
+
+function withoutFencedCode(value) {
+  return value.replace(/^(```|~~~)[\s\S]*?^\1\s*$/gm, "");
+}
+
+async function inspectMarkdown(file, root, config, cache) {
+  const readCached = async (path) => {
+    if (!cache.has(path)) cache.set(path, await readFile(path, "utf8"));
+    return cache.get(path);
+  };
+  const value = await readCached(file);
+  const inspectable = withoutFencedCode(value);
+  const issues = [];
+  const frontMatter = value.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  const h1Count = (inspectable.match(/^#\s+/gm) ?? []).length;
+  if (h1Count !== 1) issues.push({ rule: "single-h1", path: relative(root, file), detail: `Expected one H1; found ${h1Count}.` });
+  const headingCounts = new Map();
+  for (const [, heading] of inspectable.matchAll(/^#{1,6}\s+(.+)$/gm)) {
+    const key = heading.toLowerCase().trim();
+    headingCounts.set(key, (headingCounts.get(key) ?? 0) + 1);
+  }
+  for (const [heading, count] of headingCounts) {
+    if (count > 1) issues.push({ rule: "duplicate-heading", path: relative(root, file), detail: `Heading '${heading}' appears ${count} times.` });
+  }
+  if (/\b(?:TODO|TBD|FIXME)\b/i.test(inspectable)) issues.push({ rule: "placeholder", path: relative(root, file), detail: "Contains TODO, TBD, or FIXME outside a fenced code block." });
+  if (config.requireMetadata && !frontMatter) issues.push({ rule: "metadata", path: relative(root, file), detail: "Required front matter is missing." });
+  if (frontMatter) {
+    const metadata = frontMatterValues(frontMatter[1]);
+    if (config.requireMetadata) {
+      for (const key of ["owner", "status", "lastReviewed", "reviewDue"]) {
+        if (!metadata[key]) issues.push({ rule: "metadata", path: relative(root, file), detail: `Required front matter field '${key}' is missing.` });
+      }
+    }
+    for (const key of ["lastReviewed", "reviewDue"]) {
+      if (metadata[key] && !validDate(metadata[key])) issues.push({ rule: "metadata-date", path: relative(root, file), detail: `Front matter field '${key}' is not a valid YYYY-MM-DD date.` });
+    }
+    const { lastReviewed, reviewDue } = metadata;
+    if (validDate(reviewDue) && reviewDue < localDate()) issues.push({ rule: "review-overdue", path: relative(root, file), detail: `Review was due ${reviewDue}.` });
+    if (validDate(lastReviewed)) {
+      const ageDays = Math.floor((Date.now() - new Date(`${lastReviewed}T00:00:00`).getTime()) / 86400000);
+      if (ageDays > config.maxAgeDays) issues.push({ rule: "stale-document", path: relative(root, file), detail: `Last reviewed ${ageDays} days ago; limit is ${config.maxAgeDays}.` });
+    }
+  }
+  for (const match of inspectable.matchAll(/\[[^\]]+\]\((<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\)/g)) {
+    const rawTarget = match[1].trim().replace(/^<|>$/g, "");
+    if (!rawTarget || /^(?:https?:|mailto:)/i.test(rawTarget)) continue;
+    const [target, fragment] = rawTarget.split("#", 2);
+    let decodedTarget;
+    let decodedFragment;
+    try {
+      decodedTarget = target ? decodeURIComponent(target) : "";
+      decodedFragment = fragment ? decodeURIComponent(fragment).toLowerCase() : "";
+    } catch {
+      issues.push({ rule: "invalid-link", path: relative(root, file), detail: `Invalid URL encoding: ${rawTarget}` });
+      continue;
+    }
+    const linked = decodedTarget ? resolve(dirname(file), decodedTarget) : file;
+    if (!(await exists(linked))) issues.push({ rule: "broken-link", path: relative(root, file), detail: `Missing target: ${rawTarget}` });
+    else if (fragment && extname(linked).toLowerCase() === ".md") {
+      const targetValue = await readCached(linked);
+      if (!anchors(targetValue).has(decodedFragment)) issues.push({ rule: "broken-anchor", path: relative(root, file), detail: `Missing anchor: ${rawTarget}` });
+    }
+  }
+  return issues;
+}
+
+function renderAudit(result, format) {
+  if (format === "json") return JSON.stringify(result, null, 2);
+  if (format === "markdown") {
+    const rows = result.checks.map((row) => `| ${row.pass ? "PASS" : "FAIL"} | ${row.rule} | ${row.path} | ${row.detail} |`).join("\n");
+    return `# Documentation audit\n\n- Checked: ${result.checkedAt}\n- Result: ${result.pass ? "PASS" : "FAIL"}\n\n| Status | Rule | Path | Detail |\n|---|---|---|---|\n${rows}\n`;
+  }
+  return result.checks.map((row) => `${row.pass ? "PASS" : "FAIL"} ${row.rule} ${row.path}${row.detail ? ` — ${row.detail}` : ""}`).join("\n");
+}
+
 export async function auditDocumentation(options = {}) {
-  const root = resolve(options.cwd ?? process.cwd());
-  const required = [
-    ".agent-docs/config.json",
-    "docs/README.md",
-    "docs/01-system/overview.md",
-    "docs/02-project/README.md",
-    "docs/05-operations/README.md"
-  ];
-  const rows = await Promise.all(required.map(async (path) => ({ path, present: await exists(resolve(root, path)) })));
-  for (const row of rows) console.log(`${row.present ? "PASS" : "FAIL"} ${row.path}`);
-  const result = { checkedAt: new Date().toISOString(), pass: rows.every((row) => row.present), files: rows };
-  if (options.report && !options.dryRun) {
-    const output = resolve(root, "docs/03-development/audits", `${date()}-documentation.json`);
-    await mkdir(resolve(output, ".."), { recursive: true });
-    await writeFile(output, `${JSON.stringify(result, null, 2)}\n`, "utf8");
-    console.log(`created ${output}`);
+  const { root, config, configPath } = await loadProjectConfig(options.cwd);
+  const checks = [];
+  checks.push({ rule: "configuration", path: relative(root, configPath), pass: await exists(configPath), detail: "Project audit configuration" });
+  for (const path of config.requiredDocuments) {
+    let pass = false;
+    try { pass = (await stat(resolve(root, path))).isFile(); } catch {}
+    checks.push({ rule: "required-document", path, pass, detail: "Required file from configuration" });
+  }
+  const cache = new Map();
+  for (const file of await markdownFiles(resolve(root, config.documentationRoot))) {
+    for (const issue of await inspectMarkdown(file, root, config, cache)) checks.push({ ...issue, pass: false });
+  }
+  const result = { checkedAt: new Date().toISOString(), pass: checks.every((row) => row.pass), checks };
+  console.log(renderAudit(result, options.format));
+  if (options.report) {
+    const extension = options.format === "json" ? "json" : options.format === "markdown" ? "md" : "txt";
+    const output = resolve(root, config.documentationReports, `${localDate()}-documentation.${extension}`);
+    const body = `${renderAudit(result, options.format)}\n`;
+    const written = await writeUnique(output, body, options);
+    console.log(`${written.status} ${written.path}`);
+    result.reportPath = written.path;
   }
   return result;
 }

package/src/commands/doctor.mjs

@@ -1,7 +1,7 @@
 import { execFileSync } from "node:child_process";
 
 export function doctor() {
-  const checks = [{ name: "Node.js >=20", pass: Number(process.versions.node.split(".")[0]) >= 20, value: process.version }];
+  const checks = [{ name: "Node.js >=22", pass: Number(process.versions.node.split(".")[0]) >= 22, value: process.version }];
   try {
     checks.push({ name: "Git", pass: true, value: execFileSync("git", ["--version"], { encoding: "utf8" }).trim() });
   } catch {

package/src/commands/guide.mjs

@@ -0,0 +1,12 @@
+import { readFile } from "node:fs/promises";
+import { loadCatalog, selectEntry } from "../core/catalog.mjs";
+import { resolveFromPackage } from "../core/paths.mjs";
+
+export async function showDocumentationGuide(selector) {
+  const catalog = await loadCatalog();
+  const entry = selectEntry(catalog.documentation, selector);
+  if (!entry) throw new Error(`Unknown documentation area '${selector ?? ""}'. Run 'agent-docs list documentation'.`);
+  const contents = await readFile(resolveFromPackage(entry.source), "utf8");
+  console.log(contents.trim());
+  return { entry, contents };
+}

package/src/commands/list.mjs

@@ -2,7 +2,7 @@ import { loadCatalog } from "../core/catalog.mjs";
 
 export async function listCatalog(kind) {
   const catalog = await loadCatalog();
-  const groups = kind ? [kind] : ["security", "engineering"];
+  const groups = kind ? [kind] : ["documentation", "security", "engineering"];
   for (const group of groups) {
     if (!catalog[group]) throw new Error(`Unknown catalog '${group}'.`);
     console.log(`\n${group.toUpperCase()}`);

package/src/commands/setup.mjs

@@ -3,11 +3,16 @@ import { displayResults, writeSafe } from "../core/files.mjs";
 
 const files = {
   ".agent-docs/config.json": `{
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "documentationRoot": "docs",
+  "documentationReports": "docs/03-development/audits",
   "securityReports": "docs/04-testing/security-audits",
   "engineeringReports": "docs/03-development/engineering-reviews",
-  "interactionStyle": "standard"
+  "templateOutput": "docs",
+  "interactionStyle": "standard",
+  "maxAgeDays": 180,
+  "requireMetadata": false,
+  "requiredDocuments": ["docs/README.md", "docs/01-system/overview.md", "docs/02-project/README.md", "docs/05-operations/README.md"]
 }\n`,
   "docs/README.md": `# Project documentation
 
@@ -18,7 +23,7 @@ This directory is the maintained project record. Keep decisions and system facts
 - \`03-development/\`: implementation notes and engineering reviews
 - \`04-testing/\`: test plans, security audits, and evidence
 - \`05-operations/\`: setup, deployment, runbooks, and agent operations
-- \`06-future-enhancements/\`: proposals that are not current commitments
+- \`06-future-proposals/\`: proposals that are not current commitments
 - \`archive/\`: superseded material retained for traceability
 `,
   "docs/01-system/overview.md": "# System overview\n\nStatus: Needs update\n\nDescribe the system boundary, users, dependencies, and authoritative sources.\n",
@@ -27,7 +32,7 @@ This directory is the maintained project record. Keep decisions and system facts
   "docs/04-testing/security-audits/.gitkeep": "",
   "docs/04-testing/evidence/.gitkeep": "",
   "docs/05-operations/README.md": "# Operations\n\nDocument setup, deployment, observability, incident response, and recovery procedures.\n",
-  "docs/06-future-enhancements/README.md": "# Future enhancements\n\nIdeas here are proposals, not part of the current scope until accepted.\n",
+  "docs/06-future-proposals/README.md": "# Future proposals\n\nIdeas here are proposals, not part of the current scope until accepted.\n",
   "docs/archive/README.md": "# Archive\n\nKeep superseded documents here with replacement links and archive dates.\n"
 };
 

package/src/commands/skill.mjs

@@ -4,6 +4,7 @@ import { copySafe } from "../core/files.mjs";
 import { resolveFromPackage } from "../core/paths.mjs";
 
 export async function installSkill(target = "project", options = {}) {
+  if (!["project", "codex"].includes(target)) throw new Error(`Invalid target '${target}'. Use project or codex.`);
   const root = resolve(options.cwd ?? process.cwd());
   const destination = target === "codex"
     ? resolve(homedir(), ".codex", "skills", "manage-project-quality")