@ghostbyte/agent-docs-kit 4.0.3 → 5.0.0

package/src/commands/template.mjs

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { loadProjectConfig } from "../core/config.mjs";
+import { readTemplate, writeUnique } from "../core/files.mjs";
+import { localDate } from "./audit.mjs";
+
+export const templateTypes = Object.freeze({
+  adr: { file: "adr.md", directory: "02-project/decisions", label: "Architecture decision record" },
+  runbook: { file: "runbook.md", directory: "05-operations/runbooks", label: "Operational runbook" },
+  change: { file: "change-record.md", directory: "03-development/changes", label: "Change record" },
+  incident: { file: "incident-review.md", directory: "05-operations/incidents", label: "Blameless incident review" },
+  evidence: { file: "test-evidence.md", directory: "04-testing/evidence", label: "Test evidence record" }
+});
+
+export function listTemplates() {
+  for (const [type, value] of Object.entries(templateTypes)) console.log(`${type.padEnd(10)} ${value.label}`);
+  return templateTypes;
+}
+
+export async function createTemplate(type, options = {}) {
+  const selected = templateTypes[type];
+  if (!selected) throw new Error(`Unknown template '${type ?? ""}'. Run 'agent-docs template list'.`);
+  const { root, config } = await loadProjectConfig(options.cwd);
+  const date = localDate();
+  const due = new Date();
+  due.setDate(due.getDate() + 90);
+  const contents = await readTemplate(selected.file, { DATE: date, REVIEW_DUE: localDate(due), TITLE: selected.label });
+  const suffix = options.name ? `-${options.name}` : "";
+  const output = resolve(root, config.templateOutput, selected.directory, `${date}-${type}${suffix}.md`);
+  const result = await writeUnique(output, contents, options);
+  console.log(`${result.status} ${result.path}`);
+  return result;
+}

package/src/commands/validate.mjs

@@ -1,20 +1,52 @@
-import { access, readFile } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
+import { basename } from "node:path";
 import { loadCatalog } from "../core/catalog.mjs";
 import { resolveFromPackage } from "../core/paths.mjs";
 
 export async function validatePackage() {
   const catalog = await loadCatalog();
   const errors = [];
-  for (const group of ["security", "engineering"]) {
+  const expectedGenerated = new Set();
+  for (const group of ["documentation", "security", "engineering"]) {
     for (const entry of catalog[group]) {
-      try { await access(resolveFromPackage(entry.source)); }
+      let source;
+      let generated;
+      const generatedName = `${group}-${basename(entry.source)}`;
+      expectedGenerated.add(generatedName);
+      try {
+        source = await readFile(resolveFromPackage(entry.source), "utf8");
+      }
       catch { errors.push(`Missing catalog source: ${entry.source}`); }
+      try {
+        generated = await readFile(resolveFromPackage("skills/manage-project-quality/references", generatedName), "utf8");
+      }
+      catch { errors.push(`Missing generated skill reference: ${generatedName}`); }
+      if (source !== undefined && generated !== undefined && source !== generated) errors.push(`Stale generated skill reference: ${generatedName}`);
     }
+    const fullName = `${group}-full-reference.md`;
+    expectedGenerated.add(fullName);
+    try {
+      const source = await readFile(resolveFromPackage(`content/${group}/full-reference.md`), "utf8");
+      const generated = await readFile(resolveFromPackage("skills/manage-project-quality/references", fullName), "utf8");
+      if (source !== generated) errors.push(`Stale generated skill reference: ${fullName}`);
+    } catch { errors.push(`Missing ${group} full reference or generated copy.`); }
+  }
+  for (const name of await readdir(resolveFromPackage("skills/manage-project-quality/references"))) {
+    if (/^(?:documentation|security|engineering)-(?:\d{2}-.+|full-reference)\.md$/.test(name) && !expectedGenerated.has(name)) errors.push(`Unexpected generated skill reference: ${name}`);
+  }
+  if (catalog.schemaVersion !== 2) errors.push("Catalog schemaVersion must be 2.");
+  if (catalog.documentation.length !== 7) errors.push("Catalog must contain 7 documentation areas.");
+  if (catalog.security.length !== 12) errors.push("Catalog must contain 12 security phases.");
+  if (catalog.engineering.length !== 14) errors.push("Catalog must contain 14 engineering topics.");
+  for (const template of ["adr.md", "runbook.md", "change-record.md", "incident-review.md", "test-evidence.md"]) {
+    try { await access(resolveFromPackage("templates", template)); }
+    catch { errors.push(`Missing template: ${template}`); }
   }
   const skill = await readFile(resolveFromPackage("skills/manage-project-quality/SKILL.md"), "utf8");
   if (!skill.includes("name: manage-project-quality")) errors.push("Skill name is invalid.");
   if (errors.length) throw new Error(errors.join("\n"));
-  console.log(`PASS catalog (${catalog.security.length} security phases, ${catalog.engineering.length} engineering topics)`);
+  console.log(`PASS catalog (${catalog.documentation.length} documentation areas, ${catalog.security.length} security phases, ${catalog.engineering.length} engineering topics)`);
+  console.log("PASS documentation templates");
   console.log("PASS unified skill");
   return true;
 }

package/src/core/config.mjs

@@ -0,0 +1,61 @@
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { exists } from "./files.mjs";
+
+export const defaultConfig = Object.freeze({
+  schemaVersion: 2,
+  documentationRoot: "docs",
+  documentationReports: "docs/03-development/audits",
+  securityReports: "docs/04-testing/security-audits",
+  engineeringReports: "docs/03-development/engineering-reviews",
+  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"]
+});
+
+const configKeys = new Set(Object.keys(defaultConfig));
+
+async function nearestExistingPath(path) {
+  let current = path;
+  while (!(await exists(current))) {
+    const parent = dirname(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+  return current;
+}
+
+async function safeRelativePath(root, value, label) {
+  if (typeof value !== "string" || !value.trim() || isAbsolute(value)) throw new Error(`${label} must be a non-empty project-relative path.`);
+  const resolved = resolve(root, value);
+  const rel = relative(root, resolved);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error(`${label} must stay inside the target project.`);
+  const [realRoot, realAncestor] = await Promise.all([realpath(root), realpath(await nearestExistingPath(resolved))]);
+  const realRelative = relative(realRoot, realAncestor);
+  if (realRelative === ".." || realRelative.startsWith(`..${sep}`) || isAbsolute(realRelative)) throw new Error(`${label} resolves through a link outside the target project.`);
+  return value.replaceAll("\\", "/");
+}
+
+export async function loadProjectConfig(cwd = process.cwd()) {
+  const root = resolve(cwd);
+  if (!(await exists(root))) throw new Error(`Target project does not exist: ${root}`);
+  const configPath = resolve(root, ".agent-docs/config.json");
+  let user = {};
+  if (await exists(configPath)) {
+    try { user = JSON.parse(await readFile(configPath, "utf8")); }
+    catch (error) { throw new Error(`Invalid ${configPath}: ${error.message}`); }
+  }
+  if (!user || typeof user !== "object" || Array.isArray(user)) throw new Error(`${configPath} must contain a JSON object.`);
+  for (const key of Object.keys(user)) if (!configKeys.has(key)) throw new Error(`Unknown agent-docs configuration key '${key}'.`);
+  const config = { ...defaultConfig, ...user };
+  if (![1, 2].includes(config.schemaVersion)) throw new Error("Unsupported agent-docs configuration schemaVersion.");
+  if (!Number.isInteger(config.maxAgeDays) || config.maxAgeDays < 1) throw new Error("maxAgeDays must be a positive integer.");
+  if (typeof config.requireMetadata !== "boolean") throw new Error("requireMetadata must be a boolean.");
+  if (!["standard", "learning"].includes(config.interactionStyle)) throw new Error("interactionStyle must be standard or learning.");
+  if (!Array.isArray(config.requiredDocuments)) throw new Error("requiredDocuments must be an array.");
+  for (const key of ["documentationRoot", "documentationReports", "securityReports", "engineeringReports", "templateOutput"]) config[key] = await safeRelativePath(root, config[key], key);
+  config.requiredDocuments = await Promise.all(config.requiredDocuments.map((value, index) => safeRelativePath(root, value, `requiredDocuments[${index}]`)));
+  return { root, config, configPath };
+}

package/src/core/files.mjs

@@ -1,5 +1,6 @@
-import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, relative, resolve } from "node:path";
+import { access, cp, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, extname, relative, resolve } from "node:path";
 import { resolveFromPackage } from "./paths.mjs";
 
 export async function exists(path) {
@@ -15,16 +16,56 @@ export async function writeSafe(path, contents, { force = false, dryRun = false
   if (!force && await exists(path)) return { path, status: "skipped" };
   if (!dryRun) {
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, contents, "utf8");
+    try { await writeFile(path, contents, { encoding: "utf8", flag: force ? "w" : "wx" }); }
+    catch (error) {
+      if (!force && error.code === "EEXIST") return { path, status: "skipped" };
+      throw error;
+    }
   }
   return { path, status: dryRun ? "planned" : "created" };
 }
 
+export async function availablePath(base, { force = false } = {}) {
+  if (force || !(await exists(base))) return base;
+  const extension = extname(base);
+  const stem = extension ? base.slice(0, -extension.length) : base;
+  for (let index = 2; index < 1000; index += 1) {
+    const candidate = `${stem}-${index}${extension}`;
+    if (!(await exists(candidate))) return candidate;
+  }
+  throw new Error(`Unable to select an unused path for ${base}.`);
+}
+
+export async function writeUnique(base, contents, options = {}) {
+  if (options.force) return writeSafe(base, contents, options);
+  if (options.dryRun) return writeSafe(await availablePath(base), contents, options);
+  const extension = extname(base);
+  const stem = extension ? base.slice(0, -extension.length) : base;
+  for (let index = 1; index < 1000; index += 1) {
+    const candidate = index === 1 ? base : `${stem}-${index}${extension}`;
+    const result = await writeSafe(candidate, contents, options);
+    if (result.status === "created") return result;
+  }
+  throw new Error(`Unable to create an unused path for ${base}.`);
+}
+
 export async function copySafe(source, destination, options = {}) {
   if (!options.force && await exists(destination)) return { path: destination, status: "skipped" };
-  if (!options.dryRun) {
-    await mkdir(dirname(destination), { recursive: true });
-    await cp(source, destination, { recursive: true, force: Boolean(options.force) });
+  if (options.dryRun) return { path: destination, status: "planned" };
+  await mkdir(dirname(destination), { recursive: true });
+  const nonce = `${process.pid}-${Date.now()}-${randomUUID()}`;
+  const staged = `${destination}.agent-docs-stage-${nonce}`;
+  const backup = `${destination}.agent-docs-backup-${nonce}`;
+  await cp(source, staged, { recursive: true, force: false, errorOnExist: true });
+  const replacing = await exists(destination);
+  try {
+    if (replacing) await rename(destination, backup);
+    await rename(staged, destination);
+    if (replacing) await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(staged, { recursive: true, force: true });
+    if (replacing && await exists(backup) && !(await exists(destination))) await rename(backup, destination);
+    throw error;
   }
   return { path: destination, status: options.dryRun ? "planned" : "created" };
 }

package/templates/adr.md

@@ -0,0 +1,20 @@
+---
+owner: unassigned
+status: proposed
+lastReviewed: {{DATE}}
+reviewDue: {{REVIEW_DUE}}
+---
+
+# {{TITLE}}
+
+## Context
+
+Describe the problem, constraints, and decision drivers.
+
+## Decision
+
+Record the chosen option and why it was selected.
+
+## Consequences
+
+List benefits, costs, risks, and follow-up work.

package/templates/change-record.md

@@ -0,0 +1,18 @@
+---
+owner: unassigned
+status: planned
+lastReviewed: {{DATE}}
+reviewDue: {{REVIEW_DUE}}
+---
+
+# {{TITLE}}
+
+## Intent
+
+## Scope and dependencies
+
+## Validation plan
+
+## Deployment and rollback
+
+## Result

package/templates/incident-review.md

@@ -0,0 +1,20 @@
+---
+owner: unassigned
+status: draft
+lastReviewed: {{DATE}}
+reviewDue: {{REVIEW_DUE}}
+---
+
+# {{TITLE}}
+
+## Summary and impact
+
+## Timeline
+
+## Contributing conditions
+
+## Detection and response
+
+## Corrective actions
+
+Focus on system improvements, not individual blame.

package/templates/runbook.md

@@ -0,0 +1,18 @@
+---
+owner: unassigned
+status: draft
+lastReviewed: {{DATE}}
+reviewDue: {{REVIEW_DUE}}
+---
+
+# {{TITLE}}
+
+## Purpose and scope
+
+## Preconditions and access
+
+## Procedure
+
+## Verification
+
+## Rollback and escalation

package/templates/test-evidence.md

@@ -0,0 +1,18 @@
+---
+owner: unassigned
+status: unverified
+lastReviewed: {{DATE}}
+reviewDue: {{REVIEW_DUE}}
+---
+
+# {{TITLE}}
+
+## Claim under test
+
+## Environment and inputs
+
+## Procedure
+
+## Evidence
+
+## Result and limitations

package/tests/cli.test.mjs

@@ -0,0 +1,226 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setupProject } from "../src/commands/setup.mjs";
+import { auditSecurity, reviewEngineering } from "../src/commands/audit.mjs";
+import { browserCommand, openWebsite, websiteUrl } from "../src/commands/website.mjs";
+import { helpText } from "../src/cli/help.mjs";
+import { parseArguments, optionsFromFlags } from "../src/cli/arguments.mjs";
+import { auditDocumentation } from "../src/commands/audit.mjs";
+import { createTemplate } from "../src/commands/template.mjs";
+import { validateReport } from "../skills/manage-project-quality/scripts/check-report.mjs";
+import { showDocumentationGuide } from "../src/commands/guide.mjs";
+import { installSkill } from "../src/commands/skill.mjs";
+import { main } from "../src/cli/main.mjs";
+
+test("setup is explicit, non-destructive, and repeatable", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    const preview = await setupProject({ cwd: root, dryRun: true });
+    assert.ok(preview.every((item) => item.status === "planned"));
+    const created = await setupProject({ cwd: root });
+    assert.ok(created.every((item) => item.status === "created"));
+    const repeated = await setupProject({ cwd: root });
+    assert.ok(repeated.every((item) => item.status === "skipped"));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("security and engineering reports use distinct semantics", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    const security = await auditSecurity("04", { cwd: root });
+    const engineering = await reviewEngineering("08", { cwd: root });
+    assert.match(await readFile(security.path, "utf8"), /Security worksheet: API Layer/);
+    assert.match(await readFile(security.path, "utf8"), /Scope and authorization/);
+    assert.deepEqual(validateReport(await readFile(security.path, "utf8")), []);
+    const engineeringText = await readFile(engineering.path, "utf8");
+    assert.match(engineeringText, /Engineering worksheet: Testing Types/);
+    assert.match(engineeringText, /Review context/);
+    assert.doesNotMatch(engineeringText, /Authorization: _Required/);
+    assert.deepEqual(validateReport(engineeringText), []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("CLI reports inherit the configured interaction style when no flag is supplied", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await mkdir(join(root, ".agent-docs"), { recursive: true });
+    await writeFile(join(root, ".agent-docs", "config.json"), JSON.stringify({ schemaVersion: 2, documentationRoot: "docs", documentationReports: "docs/audits", securityReports: "docs/security", engineeringReports: "docs/engineering", templateOutput: "docs", interactionStyle: "learning", maxAgeDays: 30, requireMetadata: false, requiredDocuments: [] }));
+    const result = await main(["security", "worksheet", "04", "--cwd", root]);
+    assert.match(await readFile(result.path, "utf8"), /- Style: learning/);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("arguments reject unknown options, styles, and installation targets", () => {
+  assert.throws(() => parseArguments(["setup", "--mystery"]), /Unknown option/);
+  assert.throws(() => optionsFromFlags({ style: "verbose" }), /Invalid style/);
+  assert.throws(() => optionsFromFlags({ target: "elsewhere" }), /Invalid target/);
+  assert.deepEqual(parseArguments(["audit", "documentation", "--strict"]).positionals, ["audit", "documentation"]);
+});
+
+test("documentation audit consumes config and detects broken local links", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await mkdir(join(root, ".agent-docs"), { recursive: true });
+    await mkdir(join(root, "knowledge"), { recursive: true });
+    await writeFile(join(root, ".agent-docs", "config.json"), JSON.stringify({ schemaVersion: 2, documentationRoot: "knowledge", documentationReports: "reports", securityReports: "reports/security", engineeringReports: "reports/engineering", templateOutput: "knowledge", maxAgeDays: 30, requireMetadata: false, requiredDocuments: ["knowledge/index.md"] }));
+    await writeFile(join(root, "knowledge", "index.md"), "# Index\n\n[Missing](missing.md)\n");
+    const result = await auditDocumentation({ cwd: root, format: "json" });
+    assert.equal(result.pass, false);
+    assert.ok(result.checks.some((row) => row.rule === "broken-link"));
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("templates are explicit and protect existing files", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    const first = await createTemplate("adr", { cwd: root });
+    const second = await createTemplate("adr", { cwd: root });
+    const named = await createTemplate("adr", { cwd: root, name: "cache-policy" });
+    assert.equal(first.status, "created");
+    assert.equal(second.status, "created");
+    assert.match(second.path, /-adr-2\.md$/);
+    assert.match(named.path, /-adr-cache-policy\.md$/);
+    assert.match(await readFile(first.path, "utf8"), /# Architecture decision record/);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("documentation guidance is discoverable from the canonical catalog", async () => {
+  const result = await showDocumentationGuide("system");
+  assert.equal(result.entry.id, "01");
+  assert.match(result.contents, /DOC-01-01/);
+  assert.match(result.contents, /# System Documentation/);
+});
+
+test("report validation rejects unknown statuses and unsupported claims", () => {
+  assert.ok(validateReport("| Check | Status | Evidence | Owner | Verification |\n|---|---|---|---|---|\n| A | Definitely fine | proof | Sam | retest |").length > 0);
+  assert.ok(validateReport("| Check | Status | Evidence | Owner | Verification |\n|---|---|---|---|---|\n| A | Pass | | Unassigned | Not verified |").length >= 3);
+  assert.deepEqual(validateReport("| Check | Status | Evidence | Owner | Verification |\n|---|---|---|---|---|\n| A | Pass | test output | Sam | rerun test |") , []);
+  assert.deepEqual(validateReport("| Check | Status | Evidence | Owner | Verification |\n|---|---|---|---|---|\n| A | Pass | command \\| output | Sam | rerun test |") , []);
+  assert.ok(validateReport("| Control ID | Status | Evidence | Owner | Verification |\n|---|---|---|---|---|\n| SEC-01-01 | Applied | proof | Sam | retest |").some((error) => /invalid status/.test(error)));
+  assert.ok(validateReport("| Practice ID | Status | Evidence | Owner | Verification |\n|---|---|---|---|---|\n| ENG-01-01 | Pass | proof | Sam | retest |").some((error) => /invalid status/.test(error)));
+});
+
+test("documentation audit enforces metadata, same-document anchors, and exact report formats", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await mkdir(join(root, ".agent-docs"), { recursive: true });
+    await mkdir(join(root, "docs"), { recursive: true });
+    await writeFile(join(root, ".agent-docs", "config.json"), JSON.stringify({ schemaVersion: 2, documentationRoot: "docs", documentationReports: "reports", securityReports: "reports/security", engineeringReports: "reports/engineering", templateOutput: "docs", interactionStyle: "standard", maxAgeDays: 30, requireMetadata: true, requiredDocuments: ["docs/index.md"] }));
+    await writeFile(join(root, "docs", "index.md"), "---\nowner: Docs\nstatus: current\nlastReviewed: 2026-99-99\n---\n# Index\n\n[Missing](#missing)\n\n```text\nTODO\n# Not a heading\n```\n");
+    const result = await auditDocumentation({ cwd: root, report: true, format: "text" });
+    assert.equal(result.pass, false);
+    assert.match(result.reportPath, /\.txt$/);
+    assert.ok(result.checks.some((row) => row.rule === "metadata" && /reviewDue/.test(row.detail)));
+    assert.ok(result.checks.some((row) => row.rule === "metadata-date"));
+    assert.ok(result.checks.some((row) => row.rule === "broken-anchor"));
+    assert.ok(!result.checks.some((row) => row.rule === "placeholder"));
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("dry runs select the same collision-safe report path as a real write", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await auditSecurity("04", { cwd: root });
+    const preview = await auditSecurity("04", { cwd: root, dryRun: true });
+    const created = await auditSecurity("04", { cwd: root });
+    assert.equal(preview.status, "planned");
+    assert.equal(preview.path, created.path);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("concurrent report creation is collision safe", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    const reports = await Promise.all(Array.from({ length: 8 }, () => auditSecurity("04", { cwd: root })));
+    assert.equal(new Set(reports.map((report) => report.path)).size, reports.length);
+    assert.ok(reports.every((report) => report.status === "created"));
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("malformed link encoding becomes an audit finding instead of a runtime error", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await mkdir(join(root, ".agent-docs"), { recursive: true });
+    await mkdir(join(root, "docs"), { recursive: true });
+    await writeFile(join(root, ".agent-docs", "config.json"), JSON.stringify({ schemaVersion: 2, documentationRoot: "docs", documentationReports: "reports", securityReports: "reports/security", engineeringReports: "reports/engineering", templateOutput: "docs", interactionStyle: "standard", maxAgeDays: 30, requireMetadata: false, requiredDocuments: ["docs/index.md"] }));
+    await writeFile(join(root, "docs", "index.md"), "# Index\n\n[Malformed](bad%ZZ.md)\n");
+    const result = await auditDocumentation({ cwd: root });
+    assert.ok(result.checks.some((row) => row.rule === "invalid-link"));
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("forced skill installation removes stale owned files", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await installSkill("project", { cwd: root });
+    const stale = join(root, ".agents", "skills", "manage-project-quality", "references", "stale.md");
+    await writeFile(stale, "stale");
+    await installSkill("project", { cwd: root, force: true });
+    await assert.rejects(access(stale));
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("CLI rejects extra positional arguments and command-inapplicable options", async () => {
+  await assert.rejects(main(["doctor", "unexpected"]), /Invalid arguments/);
+  await assert.rejects(main(["website", "--report"]), /not valid here/);
+  await assert.rejects(main(["audit", "worksheet", "04"]), /Unknown command/);
+  await assert.rejects(main(["engineering", "engineering", "08"]), /Unknown command/);
+  assert.throws(() => optionsFromFlags({ name: "Not valid" }), /Invalid name/);
+});
+
+test("website command opens the documented URL without a shell dependency", () => {
+  let invocation;
+  const child = { once() {}, unref() {} };
+  const returned = openWebsite({
+    platform: "darwin",
+    spawnProcess(executable, arguments_, options) {
+      invocation = { executable, arguments_, options };
+      return child;
+    }
+  });
+  assert.equal(returned, websiteUrl);
+  assert.equal(invocation.executable, "open");
+  assert.deepEqual(invocation.arguments_, [websiteUrl]);
+  assert.equal(invocation.options.detached, true);
+  assert.equal(browserCommand("win32").executable, "cmd.exe");
+  assert.equal(browserCommand("linux").executable, "xdg-open");
+});
+
+test("help distinguishes no-install, local, and global command forms", () => {
+  assert.match(helpText, /npx @ghostbyte\/agent-docs-kit@latest \[command\]/);
+  assert.match(helpText, /npx agent-docs \[command\]/);
+  assert.match(helpText, /agent-docs \[command\]/);
+  assert.match(helpText, /agent-docs --version/);
+  assert.match(helpText, /npm view @ghostbyte\/agent-docs-kit version/);
+  assert.match(helpText, /npm install --global @ghostbyte\/agent-docs-kit@latest/);
+});
+
+test("website provides a complete installation guide without a GitHub header button", async () => {
+  const site = await readFile(new URL("../site/index.html", import.meta.url), "utf8");
+  assert.match(site, /Installation guide/);
+  assert.match(site, /node --version/);
+  assert.match(site, /Run without installing/);
+  assert.match(site, /Install the global command/);
+  assert.match(site, /<dt>33<\/dt><dd>Review areas<\/dd>/);
+  assert.match(site, /documentation guide/);
+  assert.match(site, /role="tab" aria-selected="true" aria-controls="code-panel-setup"/);
+  assert.match(site, /If <code>agent-docs<\/code> is not recognized/);
+  assert.doesNotMatch(site, /View on GitHub/);
+  assert.doesNotMatch(site, /git clone https:\/\/github\.com\/ghostbyte1014\/Agent_Docs_Kit\.git/);
+  assert.doesNotMatch(site, /Run the repository source/);
+
+  const commandOverview = site.indexOf('id="commands"');
+  const installationGuide = site.indexOf('id="quick-start"');
+  const packageContents = site.indexOf('id="contents"');
+  const cliReference = site.indexOf('id="command-reference"');
+  assert.ok(commandOverview < installationGuide, "installation should follow the command-mode overview");
+  assert.ok(installationGuide < packageContents, "package details should follow installation");
+  assert.ok(packageContents < cliReference, "the complete CLI reference should be the final main section");
+});

package/tests/content.test.mjs

@@ -0,0 +1,18 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { access, readFile } from "node:fs/promises";
+import { loadCatalog } from "../src/core/catalog.mjs";
+import { resolveFromPackage } from "../src/core/paths.mjs";
+
+test("catalog exposes all migrated review areas", async () => {
+  const catalog = await loadCatalog();
+  assert.equal(catalog.documentation.length, 7);
+  assert.equal(catalog.security.length, 12);
+  assert.equal(catalog.engineering.length, 14);
+  for (const entry of [...catalog.documentation, ...catalog.security, ...catalog.engineering]) {
+    await access(resolveFromPackage(entry.source));
+    const value = await readFile(resolveFromPackage(entry.source), "utf8");
+    assert.match(value, /^# /);
+    assert.equal((value.match(/^#\s+/gm) ?? []).length, 1);
+  }
+});