200 lines
6.0 KiB
Markdown
200 lines
6.0 KiB
Markdown
# 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?
|