diff --git a/README.md b/README.md index 8ae4562..e573e55 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,41 @@ # narratio -Narratio is a stage-driven Go orchestrator for turning D&D session audio into polished transcripts and generated artifacts. +Narratio is a stage-driven Go orchestrator for turning D&D session audio into +polished transcripts and generated artifacts. -It runs a deterministic workflow across `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `render`, `analyze`, and `publish`, with manifest-driven continuation and restore support. +It runs a deterministic workflow with manifest-driven continuation, remote +publish, and restore support. -```bash +```sh narratio run 2026-04-04 ``` -This requires resolvable `pipeline.yml`, `campaign.yml`, and concrete `session.yml` (or explicit config flags). +This requires resolvable `pipeline.yml`, `campaign.yml`, and concrete +`session.yml` files or their explicit command-line alternatives. ## Documentation -- [CLI Reference](docs/cli.md) -- [Configuration](docs/config.md) -- [Operations](docs/operations.md) -- [Troubleshooting](docs/troubleshooting.md) -- [Internal Component Contracts](docs/internal/README.md) -- [Development Guide](docs/policy/development.md) -- [Architecture Principles](docs/policy/architecture.md) -- [Maintained Examples](examples/) +- [CLI reference](docs/cli.md) — commands, arguments, flags, and invocation + behavior. +- [Configuration](docs/config.md) — discovery, fields, defaults, and + validation. +- [Operations](docs/operations.md) — runtime workflow, state, publishing, + recovery, and cleanup. +- [Troubleshooting](docs/troubleshooting.md) — symptom-driven diagnosis and + safe remedies. +- [Integration contracts](docs/integrations/) — external tools, formats, and + compatibility expectations. +- [Maintained examples](examples/) — complete copyable configuration and input + files. + +## Maintainer Documentation + +- [Development guide](docs/development.md) — first-read orientation and + task-specific reading routes. +- [Internal overview](docs/internal/overview.md) — implemented component map. +- [Architecture](docs/policy/architecture.md) — normative boundaries and + invariants. +- [Documentation policy](docs/policy/documentation.md) — canonical ownership + and maintenance rules. +- [Testing policy](docs/policy/testing.md) — test value, boundaries, and + sufficiency. diff --git a/docs/internal/README.md b/docs/internal/README.md deleted file mode 100644 index 5c12387..0000000 --- a/docs/internal/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Internal Documentation Index - -## Audience -Developers and coding agents changing Narratio internals. - -## Scope -`docs/internal/` documents implemented internal contracts: stage boundaries, manifest/state behavior, artifact resolution, restore behavior, storage boundaries, and workspace invariants. - -User and operator behavior belongs in: -- `docs/cli.md` -- `docs/config.md` -- `docs/operations.md` -- `docs/troubleshooting.md` - -## Pipeline Stage Set -Canonical stage order from `internal/stage.All()`: -1. `prepare` -2. `transcribe` -3. `merge` -4. `polish` -5. `normalize` -6. `trim` -7. `render` -8. `analyze` -9. `publish` -10. `notify` (placeholder) - -`notify` is currently a placeholder stage with optional notifier call behavior; it has no persisted pipeline outputs. - -## Internal Component Docs -- `adapters.md`: external adapter boundaries and default runtime wiring. -- `artifacts.md`: canonical source IDs, runtime catalog behavior, and resolution rules. -- `manifest.md`: session and run manifest contracts. -- `storage.md`: object-store interface and S3 implementation behavior. -- `workspace.md`: local session layout, run-local layout, and cleanup guardrails. -- `command-restore.md`: restore discovery, planning, execution, and reporting. -- `stage-prepare.md` -- `stage-transcribe.md` -- `stage-merge.md` -- `stage-polish.md` -- `stage-normalize.md` -- `stage-trim.md` -- `stage-render.md` -- `stage-analyze.md` -- `stage-publish.md` diff --git a/docs/internal/overview.md b/docs/internal/overview.md new file mode 100644 index 0000000..c216410 --- /dev/null +++ b/docs/internal/overview.md @@ -0,0 +1,90 @@ +# Internal Overview + +This document is the implemented component map for Narratio. Normative system +boundaries and dependency direction belong in +[Architecture](../policy/architecture.md). User and operator contracts belong +in the [CLI](../cli.md), [Configuration](../config.md), +[Operations](../operations.md), and [Troubleshooting](../troubleshooting.md). +Externally observable tool and format contracts belong under +[Integrations](../integrations/). + +## Execution Path + +```text +cmd/narratio -> internal/app -> configuration and production composition + -> internal/stage -> adapters and external systems + -> manifests and artifact resolution -> durable local/remote output +``` + +The executable delegates process behavior to the application boundary. The +application resolves configuration, composes concrete collaborators, acquires +session safety controls, and runs commands. Pipeline commands execute the +canonical stage sequence through adapter interfaces, while manifests record +progress and artifact services resolve durable inputs and outputs. + +## Components + +| Area | Implemented owners | Responsibility | +| --- | --- | --- | +| Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. | +| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, cleanup gates, and user-facing reporting. | +| Configuration | `internal/config` | Strict YAML loading, discovery, defaults, normalization, session templating, and validation. | +| Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. | +| External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. | +| Manifests | `internal/manifest` | Durable session progress, invocation audit state, stage transitions, validation, and atomic persistence. | +| Artifacts and paths | `internal/artifacts`, `internal/pathsafe` | Artifact identities and resolution, local and remote path/key models, current-state discovery, and confined relative destinations. | +| Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. | +| Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. | +| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, `internal/fileops` | Transcript and artifact data contracts plus narrow atomic filesystem helpers. | +| Logging | `internal/logging` | Application logger construction and shared structured logging behavior. | + +The application boundary composes concrete implementations. Stages depend on +Narratio-level contracts; external transport and SDK details remain in +adapters. The normative rules for these relationships remain in +[Architecture](../policy/architecture.md). + +## Pipeline Stage Set + +The implemented canonical order is: + +1. [`prepare`](stage-prepare.md) +2. [`transcribe`](stage-transcribe.md) +3. [`merge`](stage-merge.md) +4. [`polish`](stage-polish.md) +5. [`normalize`](stage-normalize.md) +6. [`trim`](stage-trim.md) +7. [`render`](stage-render.md) +8. [`analyze`](stage-analyze.md) +9. [`publish`](stage-publish.md) +10. `notify` (placeholder) + +`notify` currently has optional notifier call behavior and no persisted pipeline +outputs. The focused stage documents own implementation mechanics. The +[CLI](../cli.md) and [Operations](../operations.md) own user-visible invocation +and execution semantics. + +## Focused Documentation + +- [Adapter Internals](adapters.md): external adapter boundaries, composition, + failure behavior, and test surfaces. +- [Artifact Internals](artifacts.md): source identities, runtime catalog, + resolution, previous requirements, and current-state helpers. +- [Manifest Internals](manifest.md): session and run records, persistence, and + execution transitions. +- [Storage Internals](storage.md): object-store interface and S3 behavior. +- [Workspace Internals](workspace.md): local layout, locking, and cleanup + guardrails. +- [Restore Internals](command-restore.md): discovery, planning, execution, and + reporting. +- [`prepare`](stage-prepare.md) +- [`transcribe`](stage-transcribe.md) +- [`merge`](stage-merge.md) +- [`polish`](stage-polish.md) +- [`normalize`](stage-normalize.md) +- [`trim`](stage-trim.md) +- [`render`](stage-render.md) +- [`analyze`](stage-analyze.md) +- [`publish`](stage-publish.md) + +Use this map to find an owner, then read its focused documentation and tests +before changing behavior. diff --git a/docs/roadmap/notarius-extract-stage.md b/docs/roadmap/notarius-extract-stage.md index b8dee0d..dba0d3c 100644 --- a/docs/roadmap/notarius-extract-stage.md +++ b/docs/roadmap/notarius-extract-stage.md @@ -306,14 +306,13 @@ feature: state transitions, failures, and focused tests; - update `docs/internal/adapters.md`, `docs/internal/artifacts.md`, `docs/internal/manifest.md`, and the internal stage inventory; -- update `docs/architecture.md` to list Notarius among isolated external +- update `docs/policy/architecture.md` to list Notarius among isolated external systems and preserve the adapter/stage boundary; - update `docs/config.md`, `docs/cli.md`, `docs/operations.md`, `docs/troubleshooting.md`, `README.md`, and maintained examples only to the extent their canonical scopes require; and -- add the missing `docs/development.md` required by the repository's - documentation policy, or track that repository-wide documentation gap in a - separate roadmap if it is intentionally outside the implementation scope. +- update `docs/development.md` only to the extent its canonical contributor + routing scope requires. Outside this roadmap, do not describe `extract`, Notarius configuration, or `narratio.extraction.*` sources as implemented until the code exists.