3.7 KiB
Development
This is the first-read landing page for people and LLM coding agents working on Narratio. It provides a concise repository orientation and routes each kind of change to its canonical documentation.
Narratio is a stage-driven Go orchestrator for turning D&D session audio into polished transcripts and generated artifacts. Start with the README for product context, Architecture for normative system boundaries, and the Internal Overview for implemented component ownership.
What To Read
| When working on | Read | Why |
|---|---|---|
| Finding the package or component that owns current behavior | Internal Overview | It is the implemented component inventory and routes to focused internal documents. |
| Application shape, boundaries, dependency direction, runtime invariants, safety properties, or dependencies | Architecture | It defines the intended system shape, ownership, and non-goals. |
| Any documentation addition or revision | Documentation Policy | It defines canonical owners, audiences, current-behavior rules, and maintenance requirements. |
| Adding, changing, reviewing, rewriting, or deleting tests | Testing Policy | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and test lifecycle decisions. |
| CLI composition or command behavior | Internal Overview and CLI Reference | The overview routes to command ownership; the reference owns public syntax and invocation behavior. |
| Configuration loading, resolution, or user-visible configuration | Internal Overview and Configuration | The overview routes to implementation ownership; the reference owns fields, defaults, discovery, and validation. |
| Session workflow, status, restore, cleanup, or object storage | Restore Internals, Workspace Internals, Storage Internals, Operations, and Troubleshooting | These separate implementation mechanics, operator procedures, and symptom-driven recovery. |
| Pipeline sequencing or the behavior of a stage | Internal Overview and its focused stage documents | The overview owns the implemented stage inventory and routes to each stage contract. |
| Adapters or external tool contracts | Adapter Internals and Integration Contracts | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. |
| Manifests, artifacts, workspace paths, or publish behavior | Manifest Internals, Artifact Internals, Workspace Internals, Publish Internals, and Operations | These separate implementation state and resolution from operator-visible layout and lifecycle. |
| Maintained configuration or input examples | Configuration and Examples | The reference owns field meanings; the examples directory owns complete copyable files. |
| Proposed or unimplemented behavior | Roadmap | Future work belongs only in roadmap documentation until implemented. |
For an existing subsystem, also inspect its focused tests and package-level contracts before changing behavior.
Validation
Use focused package tests while iterating. Run the repository-wide checks when a change affects shared contracts, application behavior, or maintained documentation examples:
go test ./...
go vet ./...
go build ./cmd/narratio