# Documentation Roadmap

## Purpose

This roadmap defines the work required to bring Notarius documentation into
compliance with [`docs/policy/documentation.md`](../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:

```text
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:

```sh
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.