# 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.