Add roadmap documents for the initial architecture

docs/roadmap/documentation.md

@@ -0,0 +1,174 @@
+# Documentation Roadmap
+
+## Status
+
+This document captures planned documentation decisions for Notarius. It records
+policy choices while the application architecture is still being shaped. It does
+not describe implemented behavior.
+
+## Documentation Goals
+
+Notarius documentation should make three boundaries obvious:
+
+- source-format support belongs to input adapters;
+- extraction-domain behavior belongs to extractor packages;
+- core framework behavior is source-agnostic and domain-agnostic.
+
+Documentation should avoid making the MVP look more transcript-specific or
+D&D-specific than the architecture intends.
+
+## Current Policy Decisions
+
+### Planned Work Stays In Roadmap Docs
+
+Until code exists, planned behavior belongs under `docs/roadmap/`.
+
+Implemented behavior should later move into canonical docs. Roadmap files may
+then link to those docs or be reduced to remaining future work.
+
+### Core Docs Should Use Generic Terms
+
+Core architecture docs should prefer:
+
+- source document;
+- source unit;
+- source reference;
+- input adapter;
+- extractor;
+- artifact;
+- validator;
+- run manifest.
+
+Core docs should avoid transcript-specific terms such as segment, speaker,
+timestamp, and transcript range unless discussing an input adapter or an example.
+
+Core docs should avoid D&D-specific terms such as spell, NPC, item, combat, and
+encounter unless discussing extractor packages or examples.
+
+### Adapter Docs Own Source Formats
+
+Each implemented input adapter should have a canonical integration document.
+
+Likely future files:
+
+```text
+docs/integrations/seriatim-transcript.md
+docs/integrations/markdown-source.md
+```
+
+Adapter docs should cover:
+
+- accepted external schema or file shape;
+- mapping into `SourceDocument` and `SourceUnit`;
+- metadata preserved by the adapter;
+- validation rules and failure behavior;
+- examples.
+
+The Seriatim adapter doc should reference the Seriatim schema it supports and
+explain how transcript segment IDs become source-unit IDs.
+
+### Extractor Docs Own Domains
+
+Each implemented extractor family should have canonical internal or integration
+docs.
+
+Likely future files:
+
+```text
+docs/internal/extractors.md
+docs/integrations/artifacts-dnd.md
+```
+
+Extractor docs should cover:
+
+- extractor key;
+- artifact type;
+- schema version;
+- required source-reference behavior;
+- validator chain;
+- prompt and response-schema ownership;
+- examples.
+
+D&D concepts should be documented in D&D extractor docs, not in generic runner
+or framework docs.
+
+### CLI Docs Should Reflect Extensibility
+
+The CLI reference should present input adapters and extractors as selectable
+components.
+
+Provisional command shape:
+
+```sh
+notarius extract ./source.json --input seriatim --extractors dnd.spells --output ./artifacts.json
+```
+
+Once implemented, `docs/cli.md` should document:
+
+- positional source input path;
+- input adapter selection;
+- extractor selection;
+- config path behavior;
+- output path behavior;
+- diagnostics and report behavior;
+- exit codes.
+
+### Config Docs Should Separate Framework And Plugin-Like Options
+
+`docs/config.md` should group fields by responsibility:
+
+- input adapter selection and adapter-specific options;
+- extractor selection and extractor-specific options;
+- LLM runtime;
+- validation runtime;
+- source chunking;
+- output and diagnostics.
+
+Adapter-specific and extractor-specific config should not leak into unrelated
+core config sections.
+
+### Examples Should Stay Real
+
+Examples should be added only when the matching behavior exists and should be
+covered by tests where practical.
+
+Likely future examples:
+
+```text
+examples/seriatim-minimal-transcript.json
+examples/minimal-config.yml
+examples/dnd-spells.artifacts.json
+```
+
+Examples should be secret-free and should use the same command shapes documented
+in `docs/cli.md`.
+
+## Canonical Documentation Targets
+
+When the first vertical slice is implemented, add or update:
+
+- `README.md`: concise purpose, shortest useful command, links.
+- `docs/cli.md`: implemented command behavior.
+- `docs/config.md`: implemented config behavior.
+- `docs/operations.md`: diagnostics, retention, failure inspection.
+- `docs/troubleshooting.md`: common failures.
+- `docs/internal/overview.md`: implemented package map.
+- `docs/internal/pipeline.md`: implemented extraction flow.
+- `docs/internal/adapters.md`: adapter contract and implemented adapters.
+- `docs/internal/extractors.md`: extractor contract and built-ins.
+- `docs/internal/validators.md`: validator contract and built-ins.
+- `docs/integrations/seriatim-transcript.md`: Seriatim input contract.
+- `docs/integrations/artifacts.md`: output artifact envelope.
+
+## Review Checklist For Future Documentation Changes
+
+Before merging docs, check:
+
+- Does the document describe implemented behavior outside `docs/roadmap/`?
+- Are source-format details isolated to adapter docs?
+- Are D&D details isolated to extractor or artifact docs?
+- Is there one canonical home for the topic?
+- Do command examples match implemented CLI syntax?
+- Are examples valid, maintained, and free of secrets?
+- Did any architecture, config, CLI, adapter, extractor, validator, or artifact
+  contract change require a docs update?