narratio/docs/development.md

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	docs/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. Every pull request and push runs the following repository-wide checks before it can be accepted:

go test ./...
go test -race ./...
go vet ./...
go build ./...
go test ./internal/doccheck
go test ./internal/config -run '^TestExamplesLoadAndValidate$'

The documentation check verifies local Markdown links and the dependency graph of the Woodpecker workflows. The configuration check loads every maintained pipeline and session example. Release automation repeats these checks and cross-compiles the CLI before it builds release assets; publishing depends on that validation path, so a failure cannot publish a release.

Woodpecker also runs go test -race -shuffle=on -count=3 ./... on its scheduled job to expose ordering and repeatability defects. Current runners cross-compile for macOS and Windows, but do not provide native macOS or Windows execution. Those cross-builds establish compilation only, not platform-equivalent runtime evidence. Add native checks only when official runner labels and successful native-run evidence are available.