# Documentation Pass: Stage 1 Audit Status: Completed (2026-05-23) ## Scope Reviewed - All non-policy documentation files under `docs/` - `README.md` - Documentation references to maintained `examples/` files - Documentation-related expectations in tests under `internal/**` ## File Inventory and Canonical Scope | File | Intended audience | Canonical scope (per policy) | Primary source-of-truth anchors | | --- | --- | --- | --- | | `README.md` | Users, operators | Project orientation and links | `cmd/narratio`, `internal/app/commands.go`, docs index files | | `docs/cli.md` | Users, operators | CLI syntax, flags, command workflows | `internal/app/*.go`, `internal/app/*_test.go` | | `docs/config.md` | Operators, advanced users | Config discovery, schema, defaults, examples | `internal/config/*.go`, `internal/config/*_test.go`, `examples/*` | | `docs/operations.md` | Operators | Run/resume/publish/restore/cleanup workflows | `internal/app/runner.go`, `internal/app/restore*.go`, `internal/stage/archive.go`, `internal/artifacts/*.go` | | `docs/troubleshooting.md` | Operators | Failure diagnosis and safe fixes | `internal/app`, `internal/stage`, related tests | | `docs/internal/README.md` | Developers, LLM coding agents | Internal docs index and scope boundaries | `docs/internal/*.md`, policy docs | | `docs/internal/adapters.md` | Developers, LLM coding agents | Adapter boundaries and ownership | `internal/adapters/*`, `internal/stage/*` | | `docs/internal/artifacts.md` | Developers, LLM coding agents | Artifact catalog and source resolution contracts | `internal/artifacts/*`, `internal/stage/analyze.go`, `internal/stage/prepare_previous.go` | | `docs/internal/command-restore.md` | Developers, LLM coding agents | Restore command architecture and contracts | `internal/app/restore*.go`, `internal/app/restore*_test.go` | | `docs/internal/manifest.md` | Developers, LLM coding agents | Session/run manifest contracts and transitions | `internal/manifest/*`, `internal/app/runner.go`, `internal/stage/*` | | `docs/internal/stage-prepare.md` | Developers, LLM coding agents | Prepare stage IO and invariants | `internal/stage/prepare.go`, `internal/stage/prepare*_test.go` | | `docs/internal/stage-transcribe.md` | Developers, LLM coding agents | Transcribe stage IO and invariants | `internal/stage/transcribe.go`, `internal/stage/transcribe_test.go` | | `docs/internal/stage-merge.md` | Developers, LLM coding agents | Merge stage IO and invariants | `internal/stage/merge.go`, `internal/stage/merge_test.go` | | `docs/internal/stage-polish.md` | Developers, LLM coding agents | Polish stage IO and invariants | `internal/stage/polish.go`, `internal/stage/polish_test.go` | | `docs/internal/stage-normalize.md` | Developers, LLM coding agents | Normalize stage IO and invariants | `internal/stage/normalize.go`, `internal/stage/normalize_test.go` | | `docs/internal/stage-trim.md` | Developers, LLM coding agents | Trim stage IO and invariants | `internal/stage/trim.go`, `internal/stage/trim_test.go` | | `docs/internal/stage-analyze.md` | Developers, LLM coding agents | Analyze stage artifact execution and selection | `internal/stage/analyze.go`, `internal/stage/analyze_test.go` | | `docs/internal/stage-publish.md` | Developers, LLM coding agents | Publish-stage commit/upload invariants | `internal/stage/archive.go`, `internal/stage/archive_test.go` | | `docs/internal/storage.md` | Developers, LLM coding agents | Storage adapter contracts and semantics | `internal/adapters/storage/*`, `internal/app/object_store.go` | | `docs/internal/workspace.md` | Developers, LLM coding agents | Local workspace/session/run path model | `internal/artifacts/*`, `internal/app/runner.go`, `internal/stage/run_local.go` | | `docs/integrations/README.md` | Developers, LLM coding agents | Integration docs index | `docs/integrations/*.md` | | `docs/integrations/audita.md` | Developers, integration maintainers | Audita adapter contract | `internal/adapters/audita/*`, `internal/stage/polish.go` | | `docs/integrations/seriatim.md` | Developers, integration maintainers | Seriatim adapter contract | `internal/adapters/seriatim/*`, `internal/stage/merge.go`, `internal/stage/normalize.go`, `internal/stage/trim.go` | | `docs/integrations/scriptorium.md` | Developers, integration maintainers | Scriptorium adapter contract | `internal/adapters/scriptorium/*`, `internal/stage/analyze.go`, `internal/stage/trim.go` | | `docs/roadmap/documentation.md` | Developers, maintainers | Planning and implementation sequencing for documentation pass | N/A (planning artifact) | | `docs/roadmap/documentation-stage1-audit.md` | Developers, maintainers | Stage-1 inventory and source-of-truth audit record | N/A (planning artifact) | ## Source-of-Truth Mapping Summary - CLI behaviors and command names are grounded in `internal/app/commands.go` and command handlers in `internal/app/*.go`. - Stage order and canonical stage names are grounded in `internal/stage/placeholders.go` (`prepare` -> `transcribe` -> `merge` -> `polish` -> `normalize` -> `trim` -> `analyze` -> `publish` -> `notify`). - Publish behavior and current-pointer commit semantics are grounded in `internal/stage/archive.go`. - Config schema/defaults/validation are grounded in `internal/config/*`. - Local/remote paths, publish keys, and workspace layout are grounded in `internal/artifacts/*`. - Restore behavior and report contracts are grounded in `internal/app/restore*.go`. - Maintained examples and schema compatibility are grounded in `examples/*` plus `internal/config/load_validate_test.go` (`TestExamplesLoadAndValidate`). ## Findings ### Broken or stale references 1. `README.md` linked to non-existent files: - `docs/development.md` - `docs/architecture.md` 2. `docs/internal/README.md` and `docs/integrations/README.md` linked to non-existent path: - `docs/documentation/policy.md` Stage-1 fix applied: - Updated those links to existing policy docs under `docs/policy/`. ### Stale terminology sweep Sweep terms used: `archive`, `promote`, `promoted`, `promote_artifacts`, `run-stage archive`. Findings: - User-facing docs in scope did not show obvious stale command examples requiring immediate correction. - Internal code and tests still contain historical `archive` identifiers while user-facing command/stage naming is `publish` (for example, `internal/stage/archive.go` type names). This is acceptable for now but should be normalized deliberately, not incidentally. Stage-1 fix applied: - Updated clearly stale publish-related wording in test expectation messages/comments: - `internal/app/commands_test.go` - `internal/app/operator_helpers_test.go` ### Example path validation - All `examples/...` paths referenced from non-policy docs resolve to existing files. - `internal/config/load_validate_test.go` includes `TestExamplesLoadAndValidate` and points to current example files. ### Roadmap leakage into current-behavior docs - No obvious roadmap-only behavior leakage found in non-roadmap docs during this sweep. ### Duplicate content and scope drift - No severe duplication requiring immediate rewrite in this stage. - Existing docs still need full content rewrite for 1.0 readiness in later stages (user/operator first, then internal/integrations), as planned. ### Canonical-home inconsistency to resolve in rewrite stages - Policy canonical-home language names `docs/architecture.md` and `docs/development.md`, while current repository stores those policy documents under `docs/policy/`. - Stage 1 preserves repository behavior by fixing broken links to existing files. Later rewrite stages should converge canonical-home paths and references consistently across docs. ## Stage-1 Completion Check Completed for this stage: - Full non-policy file inventory with audience and scope mapping. - Source-of-truth crosswalk to code/tests. - Stale-term, link, and example-path sweeps. - Documentation-related stale test wording corrections. - Minimal fixes only; broad rewrites intentionally deferred.