notarius/docs/roadmap/documentation.md

Documentation Policy Migration

The documentation ownership policy has been revised to assign each topic to one canonical document. This roadmap organizes the likely migration work into three ordered passes.

This is a planning inventory, not a review of the current documents. Each item must be verified before content is moved, removed, or rewritten. Complete the passes in order so canonical content is established before non-owning copies are removed.

Pass 1: User And Operator Contracts

Establish the canonical externally observable facts first. These documents will become the targets linked from developer and internal documentation in the next pass.

Product And CLI

• Audit README.md so it owns product orientation and the single minimal end-to-end quickstart without becoming a command or configuration reference.
• Audit docs/cli.md for material owned by the README, configuration reference, or operations guide.
• Keep commands, arguments, flags, invocation semantics, and exit codes canonical in docs/cli.md.

Configuration And Examples

• Audit docs/config.md for complete example files, CLI syntax, runtime state lifecycle, or implementation detail.
• Keep fields, defaults, precedence, environment overrides, validation, and user-selectable module and validator keys canonical in docs/config.md.
• Audit minimal and production-oriented configuration examples, moving complete copyable files under examples/ and leaving only small illustrative fragments in reference documentation.
• Inventory complete configuration, input, command, and output examples embedded in prose documents.
• Select one maintained copy for each complete artifact under examples/ where practical, and verify important examples through automated tests.

Operations And Integrations

• Audit docs/operations.md for duplicated CLI syntax, configuration field definitions, logical output schemas, or implementation mechanics.
• Keep runtime workflows, physical state, retention, recovery, permissions, and operational limits canonical in docs/operations.md.
• Audit docs/integrations/ so external formats, protocols, logical output paths, schemas, media types, and compatibility rules have one canonical home.
• Separate logical output bundle contracts from physical runtime placement and lifecycle.

Pass 1 Completion

• Confirm that README, CLI, configuration, operations, integrations, and examples have non-overlapping ownership.
• Validate user-facing commands, fields, defaults, keys, schemas, paths, and maintained examples against implemented behavior.
• Validate links among the user and operator documents.

Pass 2: Developer And Internal Documentation

Use the canonical contracts established in Pass 1 to remove duplicated facts from contributor and implementation documentation.

Orientation And Architecture

• Audit docs/development.md so it routes contributors without maintaining a parallel package inventory or architectural description.
• Audit docs/internal/overview.md so it owns the implemented component map without restating normative architecture.
• Audit docs/policy/architecture.md so it contains current normative architecture without implementation inventory, decision history, or future behavior.

Internal Components

• Audit internal component documents for repeated configuration definitions, external input or output schemas, operator procedures, and global architectural invariants.
• Replace duplicated external schemas or field definitions with links to the canonical configuration or integration contracts from Pass 1.
• Keep implementation flow, internal collaborators, state transitions, package-local guarantees, failures, and relevant tests in focused internal documents.
• Identify task-specific contributor recipes that need a focused internal home rather than the developer landing page.
• Retain production module and validator implementation details in module internals while linking user-selectable keys to docs/config.md.

Pass 2 Completion

• Confirm that development routes, architecture governs, internal overview inventories, and focused internal docs explain implementation.
• Confirm that developer documents link to configuration, operations, and integration contracts rather than redefining them.
• Validate developer-facing links and relevant focused tests.

Pass 3: Lifecycle And Final Deduplication

Finish the migration by reconciling historical and future documentation, then perform a repository-wide ownership audit.

ADR And Roadmap Lifecycle

• Audit roadmap files for implemented behavior or completed status summaries that should be removed or replaced with links to current canonical docs.
• Ensure ADRs own architectural rationale and supersession history without becoming current behavior references or implementation trackers.
• Ensure accepted but unimplemented ADR decisions link to roadmap-owned implementation status where appropriate.
• Distinguish rejected architectural alternatives in ADRs from rejected product ideas in roadmap files.

Repository-Wide Audit

• Inventory repeated commands, flags, defaults, module keys, validator keys, file names, paths, schemas, retry semantics, and runtime guarantees.
• Assign each repeated fact to the canonical owner defined by the policy.
• Replace non-owning copies with short summaries and links where navigation is useful.
• Retain only minimal illustrative snippets in prose and link them to maintained examples.
• Validate local links and remove references to deleted or relocated material.

Pass 3 Completion

• Confirm that every contractual or volatile fact has one canonical owner.
• Confirm that roadmap files contain future work and implementation status, ADRs contain decision rationale, and current docs contain implemented behavior.
• Run final link, example, and documentation consistency checks.