# 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 named pipeline profiles as the primary
user-facing abstraction. Individual stage modules should be visible through
pipeline configuration and discovery commands, not through ad hoc structural
run flags.

Provisional command shape:

```sh
notarius run dnd-session --input ./source.json
notarius run dnd-session --input ./source.json --only spells,npcs
notarius config validate
notarius pipelines list
```

Once implemented, `docs/cli.md` should document:

- pipeline ID selection;
- required input path flags;
- `--only` artifact-lane selection;
- config path behavior;
- operational overrides such as output path, model, concurrency, and diagnostics
  directory;
- output path behavior;
- diagnostics and report behavior;
- exit codes.

### Config Docs Should Separate Framework And Plugin-Like Options

`docs/config.md` should describe named pipeline profiles and the resolved
pipeline model.

It should cover:

- config file locations and precedence;
- `llm_profiles`;
- `pipelines.<pipeline_id>.input`;
- `pipelines.<pipeline_id>.chunk`;
- `pipelines.<pipeline_id>.artifacts.<lane>.extract`;
- lane `merge`, `normalize`, and validator settings;
- output module selection;
- string shorthand versus inline module-binding object form;
- defaults for omitted slots;
- capability validation;
- pipeline digest and manifest provenance.

Module-specific config should stay inline with the pipeline slot that owns it.
Top-level named module instances should not be introduced until repeated inline
settings create real drift. `llm_profiles` are the cross-cutting exception.

### 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/dnd-session.config.yml
```

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?
- Do config examples use named pipeline profiles rather than ad hoc module
  flags?
- Are examples valid, maintained, and free of secrets?
- Did any architecture, config, CLI, stage module, validator, or artifact
  contract change require a docs update?