notarius/docs/roadmap/documentation.md

# 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-stage modules;
- extraction-domain behavior belongs to extract-stage modules;
- 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;
- chunker;
- merger;
- normalizer;
- output encoder;
- 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 extract modules, artifact docs, or examples.

### Input Module Docs Own Source Formats

Each implemented input-stage module should have a canonical integration
document.

Likely future files:

```text
docs/integrations/seriatim-transcript.md
docs/integrations/markdown-source.md
```

Input module docs should cover:

- accepted external schema or file shape;
- mapping into `SourceDocument` and `SourceUnit`;
- metadata preserved by the module;
- validation rules and failure behavior;
- examples.

The Seriatim input module doc should reference the Seriatim schema it supports and
explain how transcript segment IDs become source-unit IDs.

### Stage Module Docs Own Business Logic

Each implemented stage-module family should have canonical internal or
integration docs.

Likely future files:

```text
docs/internal/stage-modules.md
docs/integrations/artifacts-dnd.md
```

Stage module docs should cover:

- module key;
- stage;
- 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 extract-module or artifact docs, not in
generic runner or framework docs.

### CLI Docs Should Reflect Extensibility

The CLI reference should present input modules, chunk modules, extract modules,
merge modules, normalize modules, and output modules as selectable or
configurable components as they become user-facing.

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 module selection;
- extract module selection;
- chunk/merge/normalize/output selection when configurable;
- 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 module selection and module-specific options;
- chunk module selection and module-specific options;
- extract module selection and module-specific options;
- merge module selection and module-specific options;
- normalize module selection and module-specific options;
- output module selection and module-specific options;
- LLM runtime;
- validation runtime;
- diagnostics.

Module-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/stage-modules.md`: stage contracts and implemented modules.
- `docs/internal/input-modules.md`: input adapter contract and implemented input modules.
- `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 input module or integration docs?
- Are D&D details isolated to extract module 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, stage module, validator, or artifact
  contract change require a docs update?