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