narratio/docs/roadmap/documentation.md

Roadmap: 1.0 Documentation Pass

Status: Planned

Goal

Prepare Narratio documentation for a 1.0 release by reviewing and rewriting every non-policy document under docs/ against the implemented codebase.

The finished documentation set should be accurate, concise, complete for its audience, and compliant with:

• docs/policy/documentation.md
• docs/policy/architecture.md
• docs/policy/development.md

Do not modify files under docs/policy/ during this pass.

Current behavior belongs in canonical docs. Future, planned, aspirational, or unimplemented behavior belongs only under docs/roadmap/.

Scope

In scope:

• docs/*.md
• docs/internal/*.md
• docs/integrations/*.md
• docs/roadmap/*.md
• documentation references to files under examples/
• test expectation fixes when the documentation review exposes stale or incorrect doc/example/path expectations

Out of scope:

• product/runtime code changes
• feature implementation
• edits under docs/policy/
• adding roadmap behavior to current-behavior docs before that behavior is implemented

Implementation Stages

Stage 1: Inventory and Source-of-Truth Audit

Status: Planned

Create a file-by-file inventory of all non-policy docs before rewriting.

Implementation requirements:

• List every non-policy documentation file and assign its intended audience.
• Identify each document's canonical scope using docs/policy/documentation.md.
• Compare docs against the current code and tests, especially:
  • internal/app
  • internal/config
  • internal/stage
  • internal/artifacts
  • examples
  • relevant tests under internal/**
• Record stale terminology, broken links, stale example paths, duplicate content, and roadmap-only behavior that leaked into current-behavior docs.
• Record stale test expectations related to docs, examples, paths, or command text.
• Do not rewrite content in this stage except obvious broken links or test corrections needed to make documentation validation meaningful.

Acceptance criteria:

• The rewrite has a concrete file inventory and source-of-truth map.
• The team knows which docs are canonical and which should link elsewhere.
• Known stale terms and broken references are identified before broad edits.

Stage 2: User and Operator Docs

Status: Planned

Rewrite the user-facing and operator-facing docs first.

Implementation requirements:

• Rewrite these docs as fresh, concise current-behavior references:
  • README.md, if present
  • docs/cli.md
  • docs/config.md
  • docs/operations.md
  • docs/troubleshooting.md
• Verify every command, flag, config field, discovery rule, path, and workflow against implemented behavior.
• Cover implemented 1.0 behavior, including:
  • campaign registry selection;
  • concrete session loading and template-driven session init;
  • session-oriented helper commands;
  • clean, restore, analyze, and publish workflows;
  • artifact selection behavior;
  • locks and published output behavior;
  • workspace, spool, and cache behavior;
  • secrets loading and S3-backed operation.
• Keep examples short and link to maintained files under examples/ instead of duplicating large config blocks.
• Fix tests only when they assert stale doc paths, example paths, command names, or current-behavior text.

Acceptance criteria:

• User/operator docs are task-oriented and match actual CLI/config behavior.
• Current-behavior docs do not depend on roadmaps for normal usage.
• No current-behavior doc describes unimplemented roadmap items.

Stage 3: Internal Developer Docs

Status: Planned

Rewrite implemented internal component docs after public docs stabilize.

Implementation requirements:

• Rewrite:
  • docs/internal/README.md
  • docs/internal/adapters.md
  • docs/internal/artifacts.md
  • docs/internal/command-restore.md
  • docs/internal/manifest.md
  • docs/internal/stage-*.md
  • docs/internal/storage.md
  • docs/internal/workspace.md
• Verify stage docs against current stage names, stage ordering, manifest records, declared inputs/outputs, adapters, path helpers, storage behavior, publish/current-state behavior, restore behavior, cache behavior, and workspace cleanup.
• Keep implementation details in docs/internal/, not in user-facing docs.
• Avoid turning internal docs into duplicate config or CLI references; link to canonical docs when needed.

Acceptance criteria:

• Internal docs are accurate enough for developers and LLM coding agents to change the system safely.
• Stage and adapter boundaries match docs/policy/architecture.md.
• Manifest, path, storage, and publish invariants are explicit and current.

Stage 4: Integrations and Examples

Status: Planned

Review integration docs and maintained examples after core docs are rewritten.

Implementation requirements:

• Rewrite:
  • docs/integrations/README.md
  • docs/integrations/audita.md
  • docs/integrations/scriptorium.md
  • docs/integrations/seriatim.md
• Verify integration docs against current adapter contracts and expected downstream tool behavior.
• Confirm every referenced example file exists.
• Confirm examples match current schema and command usage.
• Run or rely on example validation tests.
• Fix tests when they reference moved, renamed, or intentionally retired examples.

Acceptance criteria:

• Integration docs describe only implemented adapter expectations.
• Maintained examples are valid, secret-free, and linked from canonical docs.
• Example validation tests reflect the documented example set.

Stage 5: Roadmap Cleanup and Final Sweep

Status: Planned

Clean up roadmap state and run final documentation validation.

Implementation requirements:

• Review docs/roadmap/** for implemented items that should be marked implemented, retired, or left planned.
• Keep historical and planned behavior in roadmaps only.
• Run final link/path/term sweeps.
• Run validation commands:
  • go test ./internal/config -run TestExamplesLoadAndValidate -v
  • go test ./internal/app -run TestExecute -v
  • go test ./...

Acceptance criteria:

• All non-policy docs are current for the 1.0 release.
• Roadmaps do not serve as required user/operator documentation.
• Tests pass after allowed documentation-related test expectation fixes.

Required Checks

Run searches for stale terminology and references during the pass.

Stale terminology:

• archive
• promote
• promoted
• promote_artifacts
• legacy campaign path/discovery language
• old transcript names and paths
• removed CLI commands or aliases

Broken or stale references:

• missing local doc links;
• stale examples/ paths;
• stale internal doc filenames;
• references to docs/policy/** as editable targets;
• command examples that no longer match the CLI.

Policy checks:

• Current-behavior docs mention only implemented behavior.
• Planned behavior appears only under docs/roadmap/.
• Docs do not expose raw secrets or recommend storing secrets in config.
• Docs use canonical homes:
  • docs/config.md for config schema;
  • docs/cli.md for command syntax;
  • docs/operations.md for operator workflows;
  • docs/troubleshooting.md for failure diagnosis;
  • docs/internal/ for implementation contracts;
  • docs/integrations/ for downstream tool integration notes;
  • docs/roadmap/ for future work.

Assumptions

• docs/policy/** is read-only for this documentation pass.
• This pass is for 1.0 release readiness, not feature implementation.
• Product and runtime code changes are out of scope.
• Test fixes are in scope when they correct stale documentation, example, path, command, or current-behavior expectations uncovered during the review.
• Roadmap files may remain as planning and historical records.
• Current-behavior docs must be sufficient for normal use without requiring readers to consult roadmaps.