notarius/docs/roadmap/documentation.md

Documentation Roadmap

Purpose

This roadmap defines the work required to bring Notarius documentation into compliance with docs/policy/documentation.md and the current implementation. It is a planning document only. Future implementation agents should use it to rewrite documentation in stages without documenting unimplemented behavior outside docs/roadmap/.

Repository Documentation Inventory

• README.md: keep and rewrite. It still contains template text (go-application-template) and does not describe the implemented Notarius CLI.
• AGENTS.md: keep and lightly update if needed. It correctly directs agents to read docs/policy, and should stay short.
• docs/policy/documentation.md: keep and do not update. It is the controlling documentation policy.
• docs/policy/architecture.md: keep and do not update. It is the controlling architecture policy.
• docs/integrations/seriatim.md: keep and lightly update. It is close to the current Seriatim adapter behavior and belongs in docs/integrations/ because Seriatim minimal transcript JSON is an external file-format contract.
• docs/integrations/dnd-spells.md: split. It mixes implemented extractor internals, artifact payload details, and stale roadmap text claiming the CLI run workflow does not exist. Move module-internal behavior to docs/internal/modules.md or a module-specific internal doc; move durable spell artifact output shape to an integration/artifact contract doc.
• docs/roadmap/documentation.md: keep during the documentation migration. After the migration is complete, either delete it or reduce it to any remaining documentation work only.
• docs/roadmap/implementation.md: delete after migration. It is a completed MVP implementation plan and is no longer an active roadmap.
• docs/roadmap/initial-architecture.md: delete after migration. The implemented architecture now belongs in policy and internal docs; historical planning detail should not remain as active roadmap content.
• docs/roadmap/mvp.md: delete or rewrite after migration. It currently records implemented MVP behavior and deferred documentation work; once current-behavior docs exist, keep only genuine future work under docs/roadmap/.
• examples/dnd-spells.config.yml: keep and lightly update. It is a maintained example covered by CLI tests, but should be checked for user-facing clarity and secret-free LLM configuration.
• examples/seriatim-minimal-transcript.json: keep and lightly update. It is a maintained Seriatim input fixture covered by CLI tests.

Policy Compliance Assessment

Required documents missing under the documentation policy:

• docs/cli.md: required because Notarius is a CLI application.
• docs/config.md: required because Notarius is config-driven.
• docs/operations.md: required because Notarius runs multi-step workflows, writes durable artifacts, and maintains diagnostics directories.
• docs/internal/: required because Notarius is modular and orchestration-based.
• docs/policy/development.md: required because the project is maintained by humans and LLM coding agents.

Recommended documents that should be added:

• docs/troubleshooting.md: recommended because implemented commands have common failure modes: missing config, unknown pipeline, invalid lane selection, invalid Seriatim input, LLM configuration failures, provider failures, output write failures, and diagnostics retention behavior.
• Maintained examples under examples/: already present and should remain linked from README, CLI, config, and integration docs.

Documents that exist but are stale or in the wrong canonical home:

• README.md is stale template content.
• docs/integrations/dnd-spells.md includes stale limits and belongs partly in internal/module docs and partly in artifact integration docs.
• Completed roadmap documents describe implemented behavior and should not be the only source of current-behavior documentation after the migration.

Content describing deprecated, historical, planned, or unimplemented behavior outside docs/roadmap/:

• docs/integrations/dnd-spells.md says the CLI run workflow does not exist; that is now false.
• No other non-roadmap stale claims were found during this pass, but future implementation agents should grep before rewriting.

Examples:

• examples/dnd-spells.config.yml and examples/seriatim-minimal-transcript.json are covered by internal/cli/run_test.go.
• There is no maintained expected-output example under examples/. Do not add one unless it can be validated or regenerated from implemented behavior.

Links likely needing verification:

• New README links to docs/cli.md, docs/config.md, docs/operations.md, docs/troubleshooting.md, docs/internal/, and docs/integrations/ will need verification after those files are created.
• Existing roadmap links to old implementation documents should be removed or deleted with the roadmap cleanup stage.

Documents not applicable:

• docs/api.md is not needed because Notarius does not implement a public HTTP API.
• docs/consumers/ is not needed for this pass because the repository exposes a CLI, not a supported public package, SDK, plugin API, or HTTP consumer API.

Target Documentation Set

Desired final tree after the migration:

AGENTS.md
README.md
docs/cli.md
docs/config.md
docs/operations.md
docs/troubleshooting.md
docs/policy/architecture.md
docs/policy/development.md
docs/policy/documentation.md
docs/internal/overview.md
docs/internal/pipeline.md
docs/internal/modules.md
docs/internal/llm.md
docs/internal/diagnostics.md
docs/integrations/seriatim.md
docs/integrations/openai-compatible.md
docs/integrations/json-output.md
docs/integrations/dnd-spell-artifacts.md
docs/roadmap/mvp.md
examples/dnd-spells.config.yml
examples/seriatim-minimal-transcript.json

docs/roadmap/mvp.md should exist only if it contains genuine remaining future work after the migration. docs/roadmap/documentation.md exists to drive this migration and should be deleted or reduced when the migration is complete.

AGENTS.md

• Audience: LLM coding agents.
• Purpose: shortest repository-specific agent instruction.
• Canonical scope: policy files that agents must read before changes.
• Recommended outline: one or two sentences linking to policy docs.
• Source-of-truth areas: docs/policy/architecture.md, docs/policy/documentation.md.
• Acceptance criteria: stays short; no duplicated architecture or documentation policy; links remain accurate.

README.md

• Audience: users, administrators, operators.
• Purpose: concise outward-facing orientation.
• Canonical scope: project purpose, shortest useful command, and links to targeted docs.
• Recommended outline: description; elevator pitch; shortest useful command using maintained examples; where output appears; links.
• Source-of-truth areas: cmd/notarius/main.go, internal/cli/run.go, examples/dnd-spells.config.yml, examples/seriatim-minimal-transcript.json, internal/cli/run_test.go.
• Acceptance criteria: no template text; no long manual content; commands match real CLI syntax; links resolve; no unimplemented features.

docs/policy/architecture.md

• Audience: developers, LLM coding agents.
• Purpose: durable development architecture policy.
• Canonical scope: stable architecture invariants and boundaries.
• Recommended outline: keep the current concise policy shape.
• Source-of-truth areas: current architecture policy and actual package boundaries.
• Acceptance criteria: does not grow into CLI/config/reference documentation; no planned behavior outside roadmap language.

docs/policy/documentation.md

• Audience: developers, LLM coding agents.
• Purpose: controlling documentation policy.
• Canonical scope: documentation layout, audience, maintenance rules, and canonical homes.
• Recommended outline: keep current policy unless project-wide documentation rules change.
• Source-of-truth areas: current documentation policy and this migration.
• Acceptance criteria: remains policy-oriented; no project-specific current-behavior reference material that belongs elsewhere.

docs/cli.md

• Audience: users, administrators, operators.
• Purpose: canonical CLI reference.
• Canonical scope: implemented commands, flags, exit behavior, common workflows, and command output.
• Recommended outline: shortest useful command; command overview; help; run; config validate; pipelines list; exit codes; common workflows; diagnostics/output pointers.
• Source-of-truth areas: internal/cli/run.go, internal/cli/run_test.go, internal/cli/catalog.go.
• Acceptance criteria: documents only implemented commands and flags; explains --config, --input, --only, --output-dir, --diagnostics-dir, --llm-profile, --pipeline, and --json; does not duplicate full config reference; examples are covered by tests or are direct variants of tested commands.

docs/config.md

• Audience: administrators, operators, advanced users.
• Purpose: canonical configuration reference.
• Canonical scope: config discovery, YAML version 1 structure, defaults, environment overrides, pipeline profiles, module bindings, LLM profiles, diagnostics settings, validation behavior, and secrets handling.
• Recommended outline: config discovery and precedence; minimal working config; production-oriented config; version; llm_profiles; pipelines; module-binding shorthand and object form; concurrency; diagnostics; environment overrides; validation and capability checks; examples.
• Source-of-truth areas: internal/core/config/*.go, internal/framework/pipeline/profile.go, internal/framework/pipeline/module.go, internal/cli/run.go, examples/dnd-spells.config.yml, config tests.
• Acceptance criteria: full config reference is here and not duplicated elsewhere; lists implemented defaults and supported env vars; explains that raw secrets should not be committed; examples load successfully.

docs/operations.md

• Audience: administrators, operators.
• Purpose: canonical operational behavior and recovery reference.
• Canonical scope: run output directory layout, diagnostics directory layout, retention behavior, manifests, warnings, failure inspection, safe cleanup, and operational caveats.
• Recommended outline: normal run workflow; output files; diagnostics files; retention modes; failure behavior; warnings; atomic writes and path safety; safe cleanup; what is not resumable yet.
• Source-of-truth areas: internal/cli/run.go, internal/core/diagnostics/*.go, internal/modules/output/json/encoder.go, output and diagnostics tests.
• Acceptance criteria: accurately names implemented durable files; states that resume/retry is not implemented as a command; explains when diagnostics are retained; does not describe unimplemented remote storage or archives.

docs/troubleshooting.md

• Audience: users, administrators, operators.
• Purpose: task-oriented fixes for recurring failure modes.
• Canonical scope: symptoms, likely causes, inspection steps, and safe fixes.
• Recommended outline: config not found; unsupported config version; unknown pipeline; invalid --only; Seriatim validation failure; missing LLM base URL or model; provider HTTP failures; output write failure; diagnostics retention surprise.
• Source-of-truth areas: internal/cli/run.go, internal/cli/run_test.go, internal/core/config/*_test.go, internal/modules/input/seriatim/*_test.go, internal/framework/llm/*_test.go.
• Acceptance criteria: every entry maps to implemented behavior; no speculative troubleshooting for future modules; links to CLI/config/operations docs instead of duplicating reference material.

docs/policy/development.md

• Audience: developers, LLM coding agents.
• Purpose: contributor workflow and change discipline.
• Canonical scope: repository layout, build/test commands, coding conventions, dependency policy, how to add config fields, CLI flags, modules, adapters, and examples.
• Recommended outline: repository layout; required policy reads; build/test commands; Go conventions; dependency policy; adding CLI flags; adding config; adding stage modules; adding examples; docs update rules.
• Source-of-truth areas: AGENTS.md, go.mod, internal/cli, internal/core/config, internal/framework/pipeline, internal/modules, docs/policy.
• Acceptance criteria: procedural and concise; links to architecture.md for invariants; does not restate full CLI/config reference.

docs/internal/overview.md

• Audience: developers, LLM coding agents.
• Purpose: high-level implemented internals map.
• Canonical scope: package roles and import/boundary expectations.
• Recommended outline: executable and CLI; core packages; framework packages; module packages; tests and fixtures; where not to put domain/source-specific logic.
• Source-of-truth areas: repository tree, docs/policy/architecture.md, internal/cli/catalog.go.
• Acceptance criteria: concise package map; reflects current code; does not become a generated file listing every source file.

docs/internal/pipeline.md

• Audience: developers, LLM coding agents.
• Purpose: implemented pipeline orchestration reference.
• Canonical scope: runner inputs/outputs, stage ordering, registries, resolved profiles, artifact lanes, validation, warnings, and manifest population.
• Recommended outline: stage flow; profile resolution; registries and module specs; runner execution; validator behavior; output encoder handoff; failure behavior; tests.
• Source-of-truth areas: internal/framework/contracts/contracts.go, internal/framework/pipeline/*.go, pipeline tests.
• Acceptance criteria: explains implemented serial execution; does not promise parallel execution or resume; links to config docs for profile syntax.

docs/internal/modules.md

• Audience: developers, LLM coding agents.
• Purpose: implemented stage modules and how to add new ones.
• Canonical scope: current production modules and their boundaries.
• Recommended outline: module contract pattern; seriatim; generic; dnd/spells; appendorder; noop; json; module registration; tests to add for new modules.
• Source-of-truth areas: internal/modules/**, internal/cli/catalog.go, module tests.
• Acceptance criteria: documents only implemented modules; moves relevant non-external content from docs/integrations/dnd-spells.md; keeps detailed external file-format contracts in docs/integrations/.

docs/internal/llm.md

• Audience: developers, LLM coding agents.
• Purpose: implemented LLM runtime internals.
• Canonical scope: structured LLM client contract, OpenAI-compatible adapter, scheduler, schema registry, retry/redaction behavior, and prompt boundary.
• Recommended outline: contract; provider request shape at a high level; scheduler; retries and timeouts; structured output decoding; secret redaction; tests.
• Source-of-truth areas: internal/framework/contracts/contracts.go, internal/framework/llm/*.go, internal/framework/prompt/*.go, internal/modules/extract/dnd/spells/assets.
• Acceptance criteria: no provider marketing claims; no API keys; links to OpenAI-compatible integration doc for the external wire contract.

docs/internal/diagnostics.md

• Audience: developers, LLM coding agents.
• Purpose: implemented diagnostics internals.
• Canonical scope: run directory creation, artifact writers, retention decision mechanics, and redacted effective config payloads.
• Recommended outline: purpose; inputs and outputs; files written; retention; failure behavior; tests; invariants.
• Source-of-truth areas: internal/core/diagnostics/*.go, internal/core/config/redaction.go, CLI diagnostics tests.
• Acceptance criteria: complements docs/operations.md; does not duplicate operator procedures.

docs/integrations/seriatim.md

• Audience: developers, LLM coding agents.
• Purpose: Seriatim minimal transcript input contract.
• Canonical scope: accepted JSON shape, validation, source mapping, metadata keys, capabilities, and compatibility limits.
• Recommended outline: adapter; accepted shape; validation; source mapping; metadata keys; capabilities; example; limits.
• Source-of-truth areas: internal/modules/input/seriatim/*.go, internal/modules/input/seriatim/*_test.go, examples/seriatim-minimal-transcript.json.
• Acceptance criteria: matches implemented validation exactly; clearly states only the minimal Seriatim shape is supported.

docs/integrations/openai-compatible.md

• Audience: administrators, developers, LLM coding agents.
• Purpose: external LLM provider wire contract currently used by Notarius.
• Canonical scope: OpenAI-compatible chat completions endpoint assumptions, structured output response format, request/response fields used, retry behavior, and secret handling.
• Recommended outline: provider type; base URL handling; endpoint path; request shape summary; response assumptions; retryable statuses; auth header; configuration links; limits.
• Source-of-truth areas: internal/framework/llm/openai_compatible_client.go, internal/framework/llm/openai_compatible_client_test.go, internal/core/config/effective_config.go.
• Acceptance criteria: documents only what the client implements; avoids copying external API docs wholesale; links to config docs for settings.

docs/integrations/json-output.md

• Audience: users, administrators, downstream developers, LLM coding agents.
• Purpose: durable JSON output file-format contract.
• Canonical scope: output directory contents and JSON file shapes produced by the json output module.
• Recommended outline: output encoder; file list; index.json; manifest.json; artifacts/<type>.json; rejected.json; warnings.json; artifact envelope; filename sanitization; limits.
• Source-of-truth areas: internal/modules/output/json/encoder.go, internal/core/artifacts/artifacts.go, output tests, internal/cli/run_test.go.
• Acceptance criteria: exactly matches implemented file names and shapes; does not document future output formats.

docs/integrations/dnd-spell-artifacts.md

• Audience: downstream developers, LLM coding agents.
• Purpose: D&D spell-cast artifact payload contract.
• Canonical scope: durable dnd.spell_cast payload fields, schema version, source-reference expectations, prompt/schema provenance in manifests, and validator rejection reasons.
• Recommended outline: artifact type; payload fields; source references; validators; manifest metadata; example payload; limits.
• Source-of-truth areas: internal/modules/extract/dnd/spells/*.go, internal/modules/extract/dnd/spells/assets/schemas/dnd_spells.v1.json, spell extractor tests.
• Acceptance criteria: replaces the external-contract parts of docs/integrations/dnd-spells.md; no stale statement that CLI run is missing; no item/NPC/combat claims outside limitations.

docs/roadmap/mvp.md

• Audience: maintainers, developers, LLM coding agents.
• Purpose: remaining roadmap work only, if any remains after the documentation migration.
• Canonical scope: future, planned, deferred, or unimplemented work.
• Recommended outline: remaining future work; deferred ideas; release checklist, if still useful.
• Source-of-truth areas: current code and this documentation roadmap.
• Acceptance criteria: contains no current-behavior reference material that belongs in README, CLI, config, operations, internal, or integration docs.

examples/dnd-spells.config.yml

• Audience: users, administrators, operators, LLM coding agents.
• Purpose: maintained minimal config example for the implemented spell extraction workflow.
• Canonical scope: one valid, secret-free config example.
• Recommended outline: YAML fixture only, with comments only if they do not interfere with tests.
• Source-of-truth areas: config parser/tests and CLI example-fixture tests.
• Acceptance criteria: remains loadable by tests; contains no secrets; is linked from README, CLI, and config docs.

examples/seriatim-minimal-transcript.json

• Audience: users, developers, LLM coding agents.
• Purpose: maintained minimal input example for the Seriatim adapter.
• Canonical scope: one valid minimal transcript JSON fixture.
• Recommended outline: JSON fixture only.
• Source-of-truth areas: Seriatim adapter/tests and CLI example-fixture tests.
• Acceptance criteria: remains valid; contains no private transcript data; is linked from README, CLI, and Seriatim integration docs.

File-by-File Rewrite Guidance

• README.md: cover what Notarius does, the shortest useful command, where outputs go, and links. Avoid package diagrams, full config reference, and roadmap content. Inspect internal/cli/run.go, examples/, and CLI tests. Do not carry forward go-application-template.
• docs/cli.md: cover implemented commands and flags. Avoid full YAML field reference and internal package details. Link to docs/config.md for config fields and docs/operations.md for output/diagnostics.
• docs/config.md: cover config schema, defaults, discovery, env overrides, validation, and secrets. Avoid command walkthroughs except minimal examples. Link to docs/cli.md for command syntax and integration docs for module contracts.
• docs/operations.md: cover output and diagnostics behavior, retention, and failure inspection. Avoid developer implementation details that belong in docs/internal/diagnostics.md.
• docs/troubleshooting.md: cover recurring implemented failures. Avoid generic LLM advice not grounded in Notarius errors or tests.
• docs/policy/development.md: cover contributor workflow. Avoid copying docs/policy/architecture.md; link to it for invariants.
• docs/internal/overview.md: cover package roles and boundaries. Avoid user-facing command details.
• docs/internal/pipeline.md: cover runner and registry mechanics. Avoid config syntax beyond linking to the canonical config doc.
• docs/internal/modules.md: cover implemented modules and how they fit stage contracts. Avoid external Seriatim schema detail and durable JSON output schemas beyond links to integration docs.
• docs/internal/llm.md: cover runtime internals. Avoid claiming support for non-implemented providers.
• docs/internal/diagnostics.md: cover diagnostics implementation. Avoid operator runbooks; link to operations.
• docs/integrations/seriatim.md: keep focused on Seriatim minimal transcript JSON. Avoid D&D extractor behavior.
• docs/integrations/openai-compatible.md: document the implemented external LLM contract. Avoid extensive copied provider docs.
• docs/integrations/json-output.md: document durable output files. Avoid diagnostics run-directory details except a link to operations.
• docs/integrations/dnd-spell-artifacts.md: document the spell artifact contract. Avoid extractor implementation details better covered internally.
• docs/integrations/dnd-spells.md: replace by split docs above, then delete or leave a temporary redirect-style note only if that is useful during migration.
• docs/roadmap/*.md: remove completed implementation history or rewrite it as future work. Do not leave implemented behavior solely in roadmap docs.

Examples Plan

examples/ exists and should remain because Notarius has non-trivial configuration and workflows.

• examples/dnd-spells.config.yml

  • Purpose: maintained minimal D&D spell extraction pipeline config.
  • Expected validity check: go test ./internal/cli currently validates this fixture with config validate, pipelines list, and fake-LLM run.
  • Documentation links: README, docs/cli.md, docs/config.md, docs/integrations/seriatim.md, docs/integrations/dnd-spell-artifacts.md.
  • Update guidance: keep secret-free; prefer environment-based API key behavior; preserve test coverage.

• examples/seriatim-minimal-transcript.json

  • Purpose: maintained minimal Seriatim transcript input.
  • Expected validity check: go test ./internal/cli uses it in the fake-LLM run acceptance tests; Seriatim adapter tests cover compatible shapes separately.
  • Documentation links: README, docs/cli.md, docs/integrations/seriatim.md.

Do not add an expected-output example unless it can be kept in sync by tests or a small documented regeneration procedure. Do not invent examples for NPC, item, combat, Markdown, or Obsidian extraction until those features exist.

Internal Documentation Plan

Pipeline Orchestration

• Path: docs/internal/pipeline.md
• Purpose: explain implemented runner orchestration.
• Inputs and outputs: pipeline.RunInput, pipeline.RunOutput, contracts.*Request, contracts.*Result, artifacts.RunManifest.
• Boundaries: orchestration and registries only; no source-format or D&D logic.
• Config fields used: resolved pipeline bindings and lane selection from internal/core/config.
• Adapters used: input, chunk, extract, merge, normalize, validator, output registries.
• Failure behavior: stage errors wrap module keys/lane/chunk context; partial manifest may be returned on failure.
• Tests to inspect before changing: internal/framework/pipeline/*_test.go, internal/framework/pipeline/walking_skeleton_test.go, internal/cli/run_test.go.
• Architectural invariants: fixed six-stage flow; generic source references; module selection via registries.

Stage Modules

• Path: docs/internal/modules.md
• Purpose: summarize implemented production modules and extension pattern.
• Inputs and outputs: module-specific contract methods under internal/framework/contracts.
• Boundaries: module logic under internal/modules/<stage>/...; CLI only wires production modules.
• Config fields used: module bindings, llm_profile, and options.
• Adapters used: Seriatim input, generic chunker, D&D spells extractor, append-order merger, noop normalizer, JSON output encoder.
• Failure behavior: module constructors and stage methods return contextual errors; validators reject candidates rather than panicking.
• Tests to inspect before changing: module package tests and internal/cli/catalog.go coverage in internal/cli/run_test.go.
• Architectural invariants: source/domain concerns stay in modules; framework remains source- and domain-agnostic.

LLM Runtime

• Path: docs/internal/llm.md
• Purpose: explain structured LLM execution internals.
• Inputs and outputs: StructuredCompletionRequest, StructuredCompletionResponse, schema registry entries, scheduler calls.
• Boundaries: provider wire details stay in internal/framework/llm; prompts and schemas are owned by modules or generic prompt helpers.
• Config fields used: llm_profiles, timeout, retries, concurrency, API key environment handling.
• Adapters used: OpenAI-compatible HTTP client and scheduler.
• Failure behavior: validation errors before calls; retryable provider errors; redacted error messages.
• Tests to inspect before changing: internal/framework/llm/*_test.go, internal/framework/prompt/*_test.go, spell prompt/schema tests.
• Architectural invariants: no secrets in errors/diagnostics; no domain prompt logic in provider adapters.

Diagnostics

• Path: docs/internal/diagnostics.md
• Purpose: explain diagnostics implementation.
• Inputs and outputs: invocation metadata, redacted effective config, resolved pipeline, run manifest, warnings, run report, error log.
• Boundaries: diagnostics writes inspection artifacts; durable user output is written by CLI/output modules.
• Config fields used: diagnostics work dir and retention mode.
• Adapters used: none external.
• Failure behavior: diagnostics write failures fail the CLI command with context; retention removes or preserves the run directory based on result and warnings.
• Tests to inspect before changing: internal/core/diagnostics/*_test.go, CLI diagnostics tests.
• Architectural invariants: diagnostics must not expose secrets; cleanup must use narrow paths.

Integration Documentation Plan

Seriatim Minimal Transcript JSON

• Path: docs/integrations/seriatim.md
• External system or contract: Seriatim minimal transcript JSON.
• Current usage: parsed by the seriatim input adapter into a generic source document.
• Version or compatibility notes: repository currently supports only the minimal shape implemented by internal/modules/input/seriatim.
• What should be documented: accepted fields, validation, source mapping, metadata keys, capabilities, example.
• What should not be documented: future Seriatim variants or D&D extraction behavior.

OpenAI-Compatible Structured Output

• Path: docs/integrations/openai-compatible.md
• External system or contract: OpenAI-compatible chat completions API with response_format.type=json_schema.
• Current usage: production LLM client posts to <base_url>/chat/completions and decodes assistant JSON content.
• Version or compatibility notes: compatibility is defined by the implemented request and response fields in internal/framework/llm.
• What should be documented: endpoint construction, auth header behavior, request shape summary, response assumptions, retry behavior, config links.
• What should not be documented: comprehensive provider API reference or unsupported providers.

Durable JSON Output

• Path: docs/integrations/json-output.md
• External system or contract: file-format contract for Notarius JSON output.
• Current usage: produced by the json output encoder and written by the CLI.
• Version or compatibility notes: manifest includes schema version and resolved pipeline provenance; exact envelope versioning should match implemented fields.
• What should be documented: file names, JSON shapes, artifact grouping, source references, rejected artifacts, warnings, filename sanitization.
• What should not be documented: future output formats or remote storage.

D&D Spell-Cast Artifacts

• Path: docs/integrations/dnd-spell-artifacts.md
• External system or contract: durable dnd.spell_cast artifact payload and validation contract.
• Current usage: produced by the dnd/spells extractor and serialized by JSON output.
• Version or compatibility notes: artifact type dnd.spell_cast, schema version v1; response schema asset dnd_spells.v1.json is internal to extraction.
• What should be documented: payload fields, source references, rejection reason codes, prompt/schema manifest metadata, limits.
• What should not be documented: unimplemented D&D item, NPC, combat, or rules extraction.

Recommended Implementation Sequence

Stage 1: Root Orientation And Core References

• Goal: make the project immediately understandable and add required public references.
• Files to create/update/delete/move: rewrite README.md; create docs/cli.md; create docs/config.md; update examples only if needed for clarity and tests.
• Repository areas to inspect: internal/cli/run.go, internal/cli/run_test.go, internal/core/config, examples/.
• Acceptance criteria: README is concise; CLI and config docs are canonical and describe only implemented behavior; maintained example commands match tests.
• Suggested validation commands: go test ./internal/cli ./internal/core/config; go test ./... if examples changed.
• One prompt? Yes, if kept focused on README, CLI, and config only.

Stage 2: Operations And Troubleshooting

• Goal: document durable output, diagnostics, retention, and common recovery paths.
• Files to create/update/delete/move: create docs/operations.md; create docs/troubleshooting.md.
• Repository areas to inspect: internal/cli/run.go, internal/core/diagnostics, internal/modules/output/json, internal/framework/llm, relevant tests.
• Acceptance criteria: operations doc names implemented output and diagnostics files; troubleshooting entries map to implemented errors; no remote storage, resume command, or archive behavior is documented.
• Suggested validation commands: go test ./internal/cli ./internal/core/diagnostics ./internal/modules/output/json ./internal/framework/llm.
• One prompt? Yes.

Stage 3: Developer Policy And Internal Docs

• Goal: add required developer workflow and internal component documentation.
• Files to create/update/delete/move: create docs/policy/development.md; create docs/internal/overview.md; create docs/internal/pipeline.md; create docs/internal/modules.md; create docs/internal/llm.md; create docs/internal/diagnostics.md.
• Repository areas to inspect: AGENTS.md, go.mod, docs/policy, internal/framework, internal/core, internal/modules, internal/cli/catalog.go.
• Acceptance criteria: docs preserve architecture-policy boundaries; internal docs cover implemented components only; development doc gives actionable commands and contribution patterns without duplicating reference docs.
• Suggested validation commands: go test ./...; go vet ./...; go build ./cmd/notarius.
• One prompt? Possibly too large. If needed, split into Stage 3A (development.md and overview.md) and Stage 3B (component docs).

Stage 4: Integration And Artifact Contracts

• Goal: place external and durable file-format contracts in canonical integration docs.
• Files to create/update/delete/move: update docs/integrations/seriatim.md; create docs/integrations/openai-compatible.md; create docs/integrations/json-output.md; create docs/integrations/dnd-spell-artifacts.md; delete or replace docs/integrations/dnd-spells.md after its content is split.
• Repository areas to inspect: internal/modules/input/seriatim, internal/framework/llm, internal/modules/output/json, internal/core/artifacts, internal/modules/extract/dnd/spells.
• Acceptance criteria: integration docs document actual external/file-format contracts; no stale claim that CLI run is unimplemented; D&D details are kept out of generic docs.
• Suggested validation commands: go test ./internal/modules/input/seriatim ./internal/framework/llm ./internal/modules/output/json ./internal/modules/extract/dnd/spells.
• One prompt? Yes.

Stage 5: Roadmap Cleanup And Link Verification

• Goal: remove completed planning clutter and verify the final documentation tree.
• Files to create/update/delete/move: delete completed roadmap files or reduce them to genuine future work; update links across README and docs; keep docs/roadmap/documentation.md only if remaining documentation work exists.
• Repository areas to inspect: all docs, examples, roadmap files.
• Acceptance criteria: future/planned behavior appears only under docs/roadmap/; completed MVP implementation details are documented in canonical current-behavior docs; links resolve; no stale template text remains.
• Suggested validation commands: go test ./...; go vet ./...; go build ./cmd/notarius; grep checks from the validation plan.
• One prompt? Yes.

Validation Plan

Run these checks during or after implementation:

• go test ./...
• go vet ./...
• go build ./cmd/notarius
• go test ./internal/cli after CLI docs or examples change.
• go test ./internal/core/config after config docs or examples change.
• go test ./internal/modules/input/seriatim after Seriatim docs/examples change.
• go test ./internal/modules/extract/dnd/spells after spell artifact docs change.
• go test ./internal/modules/output/json after JSON output docs change.
• go test ./internal/framework/llm after OpenAI-compatible docs change.

No automated documentation link checker currently exists in the repository. Future implementation agents should manually verify Markdown links or add a tool only if the project adopts one deliberately.

Recommended grep checks:

rg -n 'go-application-template|does not yet|not yet implemented|provisional|Likely future|CLI `run` workflow' README.md docs examples --glob '!docs/policy/**' --glob '!docs/roadmap/**'
rg -n 'NPC|item|combat|Obsidian|Markdown' README.md docs examples --glob '!docs/roadmap/**'
rg -n 'TODO|FIXME' README.md docs examples

Manual review items:

• Confirm README remains short and orientation-focused.
• Confirm docs/cli.md contains every implemented command and flag from internal/cli/run.go.
• Confirm docs/config.md contains every implemented file config field and env override from internal/core/config.
• Confirm examples are secret-free and covered by tests where practical.
• Confirm roadmap docs do not masquerade as current-behavior docs.
• Confirm no docs mention unimplemented NPC, item, combat, Markdown, Obsidian, remote storage, resume, or DAG behavior except under roadmap limitations or explicit out-of-scope notes.

Open Questions

None. The repository evidence is sufficient to plan the documentation migration.