@ghostbyte/agent-docs-kit 4.0.2 → 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+Notable user-visible changes are recorded here. Versions follow semantic versioning.
+
+## 5.0.0 - 2026-10-14
+
+### Added
+
+- Configuration-aware documentation audits with text, Markdown, JSON, report, and strict modes.
+- Separate security and engineering worksheet schemas.
+- Five documentation templates and five new engineering review topics.
+- Seven canonical documentation guidance areas with CLI discovery and progressive skill references.
+- Package-installation smoke testing and monthly maintenance automation.
+
+### Changed
+
+- Node.js 22 is now the minimum supported runtime.
+- Catalog schema is version 2 and records review dates.
+- Security guidance uses current OWASP and NIST baselines and safer authorization boundaries.
+- Canonical commands are `security worksheet` and `engineering worksheet`; v4 aliases remain supported.
+
+### Fixed
+
+- Invalid options and installation targets are rejected.
+- Local report dates no longer use the previous UTC calendar day.
+- Repeated reports avoid accidental filename collisions.
+- Repeated templates support descriptive names and collision-safe filenames.
+- Generated worksheets pass the bundled schema-aware report validator.
+- Documentation audits validate required metadata fields, dates, same-document anchors, and exact persisted formats.
+- Forced skill updates replace the owned skill cleanly instead of retaining obsolete files.
+- Stale package metadata, legacy folder instructions, content paths, duplicate headings, and report validation gaps were removed.
+- Version-tag publishing verifies release identity and creates the matching GitHub Release.

package/README.md

@@ -1,82 +1,88 @@
 # Agent Docs & Quality Kit
 
-Documentation governance, evidence-based security audits, and engineering-quality reviews in one installable CLI and one progressive Codex skill.
+Documentation governance, evidence-based security assurance, and engineering-quality reviews in one installable CLI and one progressive Codex skill.
 
 [![CI](https://github.com/ghostbyte1014/Agent_Docs_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ghostbyte1014/Agent_Docs_Kit/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@ghostbyte/agent-docs-kit.svg)](https://www.npmjs.com/package/@ghostbyte/agent-docs-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-## What each part is for
-
 | Workflow | Purpose | Result model |
 |---|---|---|
-| Documentation | Keep scope, architecture, decisions, operations, and change history navigable and current. | Current / Needs update / Reference / Archived |
-| Security | Test security controls with evidence and expose release risk. | Pass / Fail / Unverified / N/A |
-| Engineering | Review maintainability, reliability, performance, testing, operability, and cost tradeoffs. | Applied / Partial / Recommended / Unverified / N/A |
+| Documentation | Keep scope, architecture, decisions, operations, and history navigable and current. | Check results plus configurable templates and reports |
+| Security | Review security controls against evidence and expose release risk. | Pass / Fail / Unverified / N/A |
+| Engineering | Review reliability, maintainability, performance, testing, operability, and cost. | Applied / Partial / Recommended / Unverified / N/A |
+
+Security can block a release. Engineering advice is normally non-blocking. Documentation policy improves governance but is technically enforced only when CI or another control runs it.
 
-Security can block a release. Engineering advice is normally non-blocking. Documentation policy improves governance but becomes technically enforceable only when backed by hooks or CI.
+## Run without installing
 
-## Try it without installing
+Requires Node.js 22 or newer.
 
 ```bash
 npx @ghostbyte/agent-docs-kit@latest
+npx @ghostbyte/agent-docs-kit@latest setup --dry-run
+npx @ghostbyte/agent-docs-kit@latest list documentation
+npx @ghostbyte/agent-docs-kit@latest documentation guide system-documentation
+npx @ghostbyte/agent-docs-kit@latest audit documentation --strict
+npx @ghostbyte/agent-docs-kit@latest list security
+npx @ghostbyte/agent-docs-kit@latest security worksheet api-layer
+npx @ghostbyte/agent-docs-kit@latest list engineering
+npx @ghostbyte/agent-docs-kit@latest engineering worksheet reliability-slos
+npx @ghostbyte/agent-docs-kit@latest template create adr --name cache-policy
 ```
 
-The no-argument command opens a guided menu in an interactive terminal. Direct commands work well in scripts:
+The no-argument command opens a guided menu in an interactive terminal. Installation performs no setup and changes no project files.
+
+The canonical library contains seven documentation areas, 12 security phases, and 14 engineering topics under `content/`. The generated skill loads only the selected reference instead of placing all 33 areas in context.
+
+## Install the command
+
+Project-local installation:
 
 ```bash
-npx @ghostbyte/agent-docs-kit@latest setup --dry-run
-npx @ghostbyte/agent-docs-kit@latest setup
-npx @ghostbyte/agent-docs-kit@latest audit documentation
-npx @ghostbyte/agent-docs-kit@latest list security
-npx @ghostbyte/agent-docs-kit@latest audit security api-layer --style learning
-npx @ghostbyte/agent-docs-kit@latest review engineering testing-types
-npx @ghostbyte/agent-docs-kit@latest skill install --target project
+npm install --save-dev @ghostbyte/agent-docs-kit@latest
+npx agent-docs --version
+npx agent-docs setup --dry-run
 ```
 
-Installing the package performs no setup and changes no project files. Mutation happens only after an explicit command:
+Global installation:
 
 ```bash
-npm install --save-dev @ghostbyte/agent-docs-kit
-npx agent-docs setup
+npm install --global @ghostbyte/agent-docs-kit@latest
+agent-docs --version
+agent-docs setup --dry-run
 ```
 
-Existing files are skipped unless `--force` is supplied. Use `--dry-run` to preview owned writes.
-
-## Codex skill
+Setup files are skipped unless `--force` is explicit. Reports and templates preserve earlier records by selecting a numbered filename; use `--name <slug>` to name a template explicitly. Configure paths and required documents in `.agent-docs/config.json` after setup.
 
-The package contains `manage-project-quality`, a single router skill whose references are loaded by selected workflow and phase. Install it into the current project with:
+## Install the Codex skill
 
 ```bash
-npx agent-docs skill install --target project
+npx @ghostbyte/agent-docs-kit@latest skill install --target project
 ```
 
-This creates `.agents/skills/manage-project-quality`. For a user-level Codex installation, explicitly run `npx agent-docs skill install --target codex`.
-
-## Maintainer setup
-
-See [GitHub and npm setup](docs/GITHUB_AND_NPM_SETUP.md) for the commands to create/push the repository, enable GitHub Pages, verify the npm package name, publish the first version, and configure trusted publishing. The package name and repository URL are configured for `ghostbyte1014`; change them before release if the actual owner or repository differs.
+This creates `.agents/skills/manage-project-quality`. Use `--target codex` only when you intentionally want a user-level skill available to future projects.
 
-Further documentation:
+## Documentation
 
 - [Purpose and boundaries](docs/PURPOSE.md)
-- [Architecture and complete file structure](docs/ARCHITECTURE.md)
+- [Architecture and file structure](docs/ARCHITECTURE.md)
+- [Content maintenance](docs/CONTENT_MAINTENANCE.md)
+- [Security policy](SECURITY.md)
 - [Security model](docs/SECURITY_MODEL.md)
 - [Release process](docs/RELEASE_PROCESS.md)
-- [Legacy v3.2 compiled kit](docs/archive/AGENT_DOCS_KIT_v3.2.md)
+- [GitHub and npm setup](docs/GITHUB_AND_NPM_SETUP.md)
+- [Changelog](CHANGELOG.md)
 
 ## Development
 
 ```bash
 npm install
-npm test
-npm run validate
-npm run build
+npm run release:check
 npm run site:preview
-npm pack --dry-run
 ```
 
-There are no runtime dependencies and no lifecycle install script.
+There are no runtime dependencies and no install lifecycle script.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the current npm release. Upgrade with `npm install --global @ghostbyte/agent-docs-kit@latest` or use the version-pinned `npx` form.
+
+## Reporting a vulnerability
+
+Do not open a public issue for an exploitable vulnerability or include secrets, personal data, or live-target details in a report. Use GitHub private vulnerability reporting for `ghostbyte1014/Agent_Docs_Kit`. Include the affected version, impact, reproduction conditions, and a safe proof of concept.
+
+The project’s worksheets are review aids. They do not automatically scan targets, prove compliance, or replace professional security testing.

package/content/catalog.json

@@ -1,5 +1,72 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
+  "lastReviewed": "2026-10-14",
+  "reviewDue": "2027-01-14",
+  "documentation": [
+    {
+      "id": "01",
+      "slug": "system-documentation",
+      "title": "System Documentation",
+      "aliases": ["1", "system"],
+      "source": "content/documentation/01-system-documentation.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    },
+    {
+      "id": "02",
+      "slug": "project-governance",
+      "title": "Project Governance",
+      "aliases": ["2", "project"],
+      "source": "content/documentation/02-project-governance.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    },
+    {
+      "id": "03",
+      "slug": "development-records",
+      "title": "Development Records",
+      "aliases": ["3", "development"],
+      "source": "content/documentation/03-development-records.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    },
+    {
+      "id": "04",
+      "slug": "testing-evidence",
+      "title": "Testing & Evidence",
+      "aliases": ["4", "testing"],
+      "source": "content/documentation/04-testing-evidence.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    },
+    {
+      "id": "05",
+      "slug": "operations-runbooks",
+      "title": "Operations & Runbooks",
+      "aliases": ["5", "operations"],
+      "source": "content/documentation/05-operations-runbooks.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    },
+    {
+      "id": "06",
+      "slug": "future-proposals",
+      "title": "Future Proposals",
+      "aliases": ["6", "future"],
+      "source": "content/documentation/06-future-proposals.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    },
+    {
+      "id": "07",
+      "slug": "archive-governance",
+      "title": "Archive Governance",
+      "aliases": ["7", "archive"],
+      "source": "content/documentation/07-archive-governance.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
+    }
+  ],
   "security": [
     {
       "id": "01",
@@ -8,7 +75,9 @@
       "aliases": [
         "1"
       ],
-      "source": "content/security/01-design-architecture.md"
+      "source": "content/security/01-design-architecture.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "02",
@@ -17,7 +86,9 @@
       "aliases": [
         "2"
       ],
-      "source": "content/security/02-local-development.md"
+      "source": "content/security/02-local-development.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "03",
@@ -26,7 +97,9 @@
       "aliases": [
         "3"
       ],
-      "source": "content/security/03-database-backend.md"
+      "source": "content/security/03-database-backend.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "04",
@@ -35,7 +108,9 @@
       "aliases": [
         "4"
       ],
-      "source": "content/security/04-api-layer.md"
+      "source": "content/security/04-api-layer.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "05",
@@ -44,7 +119,9 @@
       "aliases": [
         "5"
       ],
-      "source": "content/security/05-frontend-ui.md"
+      "source": "content/security/05-frontend-ui.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "06",
@@ -53,7 +130,9 @@
       "aliases": [
         "6"
       ],
-      "source": "content/security/06-application-security-testing.md"
+      "source": "content/security/06-application-security-testing.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "07",
@@ -62,7 +141,9 @@
       "aliases": [
         "7"
       ],
-      "source": "content/security/07-cicd-release-engineering.md"
+      "source": "content/security/07-cicd-release-engineering.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "08",
@@ -71,7 +152,9 @@
       "aliases": [
         "8"
       ],
-      "source": "content/security/08-cloud-infrastructure.md"
+      "source": "content/security/08-cloud-infrastructure.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "09",
@@ -80,7 +163,9 @@
       "aliases": [
         "9"
       ],
-      "source": "content/security/09-edge-cdn-dns.md"
+      "source": "content/security/09-edge-cdn-dns.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "10",
@@ -89,7 +174,9 @@
       "aliases": [
         "10"
       ],
-      "source": "content/security/10-release-rollout.md"
+      "source": "content/security/10-release-rollout.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "11",
@@ -98,7 +185,9 @@
       "aliases": [
         "11"
       ],
-      "source": "content/security/11-post-release-monitoring-ir.md"
+      "source": "content/security/11-post-release-monitoring-ir.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     },
     {
       "id": "12",
@@ -107,7 +196,9 @@
       "aliases": [
         "12"
       ],
-      "source": "content/security/12-ongoing-operations.md"
+      "source": "content/security/12-ongoing-operations.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-01-14"
     }
   ],
   "engineering": [
@@ -118,7 +209,9 @@
       "aliases": [
         "1"
       ],
-      "source": "content/engineering/01-query-performance.md"
+      "source": "content/engineering/01-query-performance.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "02",
@@ -127,7 +220,9 @@
       "aliases": [
         "2"
       ],
-      "source": "content/engineering/02-networking-fundamentals.md"
+      "source": "content/engineering/02-networking-fundamentals.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "03",
@@ -136,7 +231,9 @@
       "aliases": [
         "3"
       ],
-      "source": "content/engineering/03-rate-limiting-algorithms.md"
+      "source": "content/engineering/03-rate-limiting-algorithms.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "04",
@@ -145,7 +242,9 @@
       "aliases": [
         "4"
       ],
-      "source": "content/engineering/04-production-debugging.md"
+      "source": "content/engineering/04-production-debugging.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "05",
@@ -154,7 +253,9 @@
       "aliases": [
         "5"
       ],
-      "source": "content/engineering/05-code-review-practices.md"
+      "source": "content/engineering/05-code-review-practices.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "06",
@@ -163,7 +264,9 @@
       "aliases": [
         "6"
       ],
-      "source": "content/engineering/06-data-modeling.md"
+      "source": "content/engineering/06-data-modeling.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "07",
@@ -172,7 +275,9 @@
       "aliases": [
         "7"
       ],
-      "source": "content/engineering/07-cloud-cost-saving.md"
+      "source": "content/engineering/07-cloud-cost-saving.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "08",
@@ -181,7 +286,9 @@
       "aliases": [
         "8"
       ],
-      "source": "content/engineering/08-testing-types.md"
+      "source": "content/engineering/08-testing-types.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     },
     {
       "id": "09",
@@ -190,7 +297,69 @@
       "aliases": [
         "9"
       ],
-      "source": "content/engineering/09-message-queues.md"
+      "source": "content/engineering/09-message-queues.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
+    },
+    {
+      "id": "10",
+      "slug": "api-design-compatibility",
+      "title": "API Design & Compatibility",
+      "aliases": [
+        "10",
+        "api-design"
+      ],
+      "source": "content/engineering/10-api-design-compatibility.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
+    },
+    {
+      "id": "11",
+      "slug": "reliability-slos",
+      "title": "Reliability, SLOs & Error Budgets",
+      "aliases": [
+        "11",
+        "reliability"
+      ],
+      "source": "content/engineering/11-reliability-slos.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
+    },
+    {
+      "id": "12",
+      "slug": "observability-telemetry",
+      "title": "Observability & Telemetry",
+      "aliases": [
+        "12",
+        "observability"
+      ],
+      "source": "content/engineering/12-observability-telemetry.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
+    },
+    {
+      "id": "13",
+      "slug": "deployment-change-safety",
+      "title": "Deployment & Change Safety",
+      "aliases": [
+        "13",
+        "deployment"
+      ],
+      "source": "content/engineering/13-deployment-change-safety.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
+    },
+    {
+      "id": "14",
+      "slug": "capacity-concurrency",
+      "title": "Capacity, Concurrency & Resource Management",
+      "aliases": [
+        "14",
+        "capacity"
+      ],
+      "source": "content/engineering/14-capacity-concurrency.md",
+      "lastReviewed": "2026-10-14",
+      "reviewDue": "2027-04-14"
     }
   ]
 }

package/content/documentation/01-system-documentation.md

@@ -0,0 +1,13 @@
+# System Documentation
+
+Use this area to explain what the system is, where its boundaries are, and how its important parts relate. Prefer durable facts over implementation narration.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-01-01 | System overview | Gives new contributors a reliable starting point. | Can a reader identify users, responsibilities, dependencies, and boundaries? |
+| DOC-01-02 | Architecture map | Shows major components and information flow. | Does the map match the deployed system and link to authoritative details? |
+| DOC-01-03 | Data ownership | Prevents ambiguous sources of truth. | Is each important data domain tied to an owner and authoritative store? |
+| DOC-01-04 | External dependencies | Makes operational and security assumptions visible. | Are critical third-party and platform dependencies named with their role? |
+| DOC-01-05 | Trust boundaries | Connects design documentation to security review. | Are identity, network, tenant, and data trust boundaries explicit? |
+| DOC-01-06 | Constraints | Preserves the reasons behind non-obvious architecture. | Are regulatory, performance, compatibility, and organizational constraints recorded? |
+| DOC-01-07 | Ownership | Gives readers a route to clarification. | Does every major subsystem have an accountable owner or team? |

package/content/documentation/02-project-governance.md

@@ -0,0 +1,13 @@
+# Project Governance
+
+Use this area to keep current scope, decisions, delivery status, and ownership separate from proposals and historical records.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-02-01 | Current scope | Prevents future ideas from being mistaken for commitments. | Are included outcomes, exclusions, and success criteria explicit? |
+| DOC-02-02 | Requirements | Connects implementation to accepted needs. | Can each active requirement be traced to an owner and validation method? |
+| DOC-02-03 | Decision records | Preserves context that code cannot explain. | Do material decisions record context, choice, alternatives, and consequences? |
+| DOC-02-04 | Delivery status | Gives readers one current project view. | Is the status dated, owned, and separated from historical updates? |
+| DOC-02-05 | Risk register | Keeps known uncertainty visible. | Are significant delivery risks assigned an owner and response? |
+| DOC-02-06 | Change history | Explains meaningful changes without duplicating Git history. | Are user-visible and operational changes summarized by release? |
+| DOC-02-07 | Authority map | Prevents conflicting sources of truth. | Is the authoritative document identified for each major project concern? |

package/content/documentation/03-development-records.md

@@ -0,0 +1,13 @@
+# Development Records
+
+Use this area for implementation guidance and review records that help contributors change the system safely.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-03-01 | Development setup | Makes a clean environment reproducible. | Can a contributor reach a verified local state from documented prerequisites? |
+| DOC-03-02 | Repository map | Reduces rediscovery and misplaced changes. | Are important directories, generated files, and ownership boundaries explained? |
+| DOC-03-03 | Coding conventions | Records project-specific rules rather than generic advice. | Are non-obvious conventions linked to automated enforcement where possible? |
+| DOC-03-04 | Change records | Captures intent, validation, and rollback for significant work. | Does each important change explain scope, risk, tests, and deployment result? |
+| DOC-03-05 | Engineering reviews | Retains evidence and recommendations over time. | Are reviews dated, scoped, owned, and linked to follow-up work? |
+| DOC-03-06 | Generated-content policy | Prevents manual edits from being overwritten. | Are source files and regeneration commands clear for every generated artifact? |
+| DOC-03-07 | Contribution workflow | Makes review expectations predictable. | Are branch, review, test, and merge requirements current and discoverable? |

package/content/documentation/04-testing-evidence.md

@@ -0,0 +1,13 @@
+# Testing and Evidence
+
+Use this area to connect quality claims to reproducible test plans, results, limitations, and retained evidence.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-04-01 | Test strategy | Explains which risks each test layer addresses. | Are unit, integration, contract, end-to-end, and manual responsibilities explicit? |
+| DOC-04-02 | Test plans | Defines scope and expected outcomes before execution. | Does each material test pass name environment, inputs, procedure, and acceptance criteria? |
+| DOC-04-03 | Evidence records | Makes results independently understandable. | Can a reviewer connect a claim to dated, reproducible evidence? |
+| DOC-04-04 | Security reviews | Separates generated worksheets from verified findings. | Are authorization, target, status, evidence, owner, and verification recorded? |
+| DOC-04-05 | Known limitations | Prevents incomplete coverage from appearing complete. | Are unavailable environments, skipped checks, and confidence limits explicit? |
+| DOC-04-06 | Defect traceability | Connects failures to remediation and retesting. | Can every material failure be traced to an owner and verification result? |
+| DOC-04-07 | Retention policy | Preserves useful evidence without retaining sensitive data indefinitely. | Are evidence location, access, redaction, and retention expectations defined? |

package/content/documentation/05-operations-runbooks.md

@@ -0,0 +1,13 @@
+# Operations and Runbooks
+
+Use this area for the procedures and context needed to deploy, observe, recover, and safely operate the system.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-05-01 | Deployment procedure | Makes releases repeatable and reviewable. | Are prerequisites, promotion, verification, rollback, and ownership documented? |
+| DOC-05-02 | Configuration guide | Prevents hidden environment assumptions. | Are required settings described without publishing secret values? |
+| DOC-05-03 | Observability guide | Helps operators connect signals to user impact. | Are dashboards, alerts, logs, traces, and known gaps discoverable? |
+| DOC-05-04 | Operational runbooks | Turns alerts and recurring tasks into safe procedures. | Does each runbook include access, steps, verification, rollback, and escalation? |
+| DOC-05-05 | Incident response | Establishes roles and communication before failure. | Are severity, command, escalation, evidence preservation, and review practices clear? |
+| DOC-05-06 | Recovery procedure | Converts backup claims into tested recovery capability. | Are recovery objectives, restore steps, dependencies, and test results current? |
+| DOC-05-07 | Support ownership | Avoids dead ends during urgent work. | Are service ownership, on-call expectations, and escalation contacts maintained safely? |

package/content/documentation/06-future-proposals.md

@@ -0,0 +1,13 @@
+# Future Proposals
+
+Use this area for ideas that have not entered current scope. A proposal is not a commitment until it is accepted through the project’s decision process.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-06-01 | Problem statement | Keeps proposals grounded in a real need. | Is the affected user, problem, and supporting evidence clear? |
+| DOC-06-02 | Proposed outcome | Describes value without prematurely fixing implementation. | Is the desired outcome measurable and distinct from a chosen solution? |
+| DOC-06-03 | Options | Preserves alternatives and tradeoffs. | Are credible alternatives, including doing nothing, compared fairly? |
+| DOC-06-04 | Dependencies | Exposes prerequisites and external decisions. | Are technical, organizational, data, and vendor dependencies named? |
+| DOC-06-05 | Risks and cost | Prevents benefits from hiding lifecycle costs. | Are delivery, operational, security, migration, and maintenance costs considered? |
+| DOC-06-06 | Decision state | Stops unapproved work from appearing committed. | Is the proposal clearly marked proposed, accepted, rejected, deferred, or superseded? |
+| DOC-06-07 | Promotion path | Defines how an accepted idea becomes current scope. | Does acceptance identify the decision record, owner, milestone, and documents to update? |

package/content/documentation/07-archive-governance.md

@@ -0,0 +1,13 @@
+# Archive Governance
+
+Use this area to retain useful history without allowing superseded material to compete with current documentation.
+
+| Documentation ID | Record | Purpose | Evidence question |
+|---|---|---|---|
+| DOC-07-01 | Archive criteria | Makes retirement consistent. | Is material archived only when it is superseded, obsolete, or retained for traceability? |
+| DOC-07-02 | Archive metadata | Explains why an old record remains. | Does each archived item identify archive date, reason, and responsible owner? |
+| DOC-07-03 | Replacement links | Routes readers back to current authority. | Does superseded material link to its replacement when one exists? |
+| DOC-07-04 | Search separation | Prevents stale guidance from dominating discovery. | Are archives clearly separated and labeled in navigation and search? |
+| DOC-07-05 | Decision retention | Preserves context for consequential choices. | Are material decisions retained according to legal and project needs? |
+| DOC-07-06 | Sensitive-data review | Prevents archives from becoming unmanaged exposure. | Are secrets, personal data, and unnecessary operational details removed or access-controlled? |
+| DOC-07-07 | Periodic review | Avoids permanent accumulation without purpose. | Are retention obligations and deletion candidates reviewed on a defined cadence? |

package/content/documentation/full-reference.md

@@ -0,0 +1,24 @@
+# Documentation Governance Reference
+
+This index routes documentation work to the smallest relevant area. The seven area files are canonical. Project-specific records are created from templates and checked against `.agent-docs/config.json`.
+
+## Governance contract
+
+- Identify one authoritative source for each important concern.
+- Record owner, status, last review date, and review due date when metadata is required.
+- Separate current facts and commitments from proposals and archives.
+- Link claims to repository or operational evidence instead of assuming completeness.
+- Prefer concise navigation and focused documents over one unbounded handbook.
+- Treat generated reports as evidence containers, not proof that checks passed.
+
+## Area index
+
+1. System documentation
+2. Project governance
+3. Development records
+4. Testing and evidence
+5. Operations and runbooks
+6. Future proposals
+7. Archive governance
+
+Run `agent-docs list documentation` to discover selectors. Use `agent-docs audit documentation --strict` to check the configured project record.