# 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](../README.md) for product context,
[Architecture](policy/architecture.md) for normative system boundaries, and the
[Internal Overview](internal/overview.md) for implemented component ownership.

Agents must read [Agent Policy](policy/agents.md) before recommending, planning,
or implementing changes. It owns implementation discipline and the default
commit-after-completed-work rule; it does not authorize pushing or releasing.

## Go Prerequisite

Maintained development and verification require Go 1.26. Use the official Go
1.26 toolchain before running repository commands.

## Policy Reading Guide

| Policy | Read before… |
| --- | --- |
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |

- Read applicable policies before making decisions they govern; multiple policies
  may apply.
- Select policies using the task triggers above. Follow cross-references to
  relevant sections when needed to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer
  available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere
  affected by the revision.

## What To Read

| When working on | Read | Why |
| --- | --- | --- |
| Finding the package or component that owns current behavior | [Internal Overview](internal/overview.md) | It is the implemented component inventory and routes to focused internal documents. |
| Application shape, boundaries, dependency direction, runtime invariants, safety properties, or dependencies | [Architecture](policy/architecture.md) | It defines the intended system shape, ownership, and non-goals. |
| Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical owners, audiences, current-behavior rules, and maintenance requirements. |
| Adding, changing, reviewing, rewriting, or deleting tests | [Testing Policy](policy/testing.md) | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and test lifecycle decisions. |
| CLI composition or command behavior | [Internal Overview](internal/overview.md) and [CLI Reference](cli.md) | The overview routes to command ownership; the reference owns public syntax and invocation behavior. |
| Configuration loading, resolution, or user-visible configuration | [Internal Overview](internal/overview.md) and [Configuration](config.md) | The overview routes to implementation ownership; the reference owns fields, defaults, discovery, and validation. |
| Session workflow, status, restore, cleanup, or object storage | [Restore Internals](internal/command-restore.md), [Workspace Internals](internal/workspace.md), [Storage Internals](internal/storage.md), [Operations](operations.md), and [Troubleshooting](troubleshooting.md) | These separate implementation mechanics, operator procedures, and symptom-driven recovery. |
| Pipeline sequencing or the behavior of a stage | [Internal Overview](internal/overview.md) 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](internal/adapters.md) and [Integration Contracts](integrations/README.md) | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. |
| Manifests, artifacts, workspace paths, or publish behavior | [Manifest Internals](internal/manifest.md), [Artifact Internals](internal/artifacts.md), [Workspace Internals](internal/workspace.md), [Publish Internals](internal/stage-publish.md), and [Operations](operations.md) | These separate implementation state and resolution from operator-visible layout and lifecycle. |
| Maintained configuration or input examples | [Configuration](config.md) and [Examples](../examples/README.md) | The reference owns field meanings; the examples directory owns complete copyable files. |
| Preparing, validating, or publishing a release | [Release Policy](policy/release.md) and [Release Procedure](release.md) | Policy owns requirements; the procedure owns concrete validation, guarded publication, and optional later inspection. |
| 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. Push and pull-request CI runs these
repository-wide checks and cross-builds the declared targets:

```sh
go test ./...
go test -race ./...
go vet ./...
go build ./...
```

The full suite includes documentation-link and Woodpecker dependency checks
and loads maintained pipeline and session examples. For focused diagnosis,
run `go test ./internal/doccheck` or
`go test ./internal/config -run '^TestExamplesLoadAndValidate$'` directly;
these are available developer tools, not additional CI steps. Tag CI
independently revalidates the tagged source before asynchronous asset delivery;
it is not a second synchronous release prerequisite. The normal maintainer
entry point is the single publication command in the
[Release Procedure](release.md).

Woodpecker also runs `go test -race -shuffle=on -count=3 ./...` on its scheduled
job to expose ordering and repeatability defects. Current runners cross-compile
the supported Linux amd64 and arm64 targets and the best-effort macOS arm64
target. The macOS cross-build establishes compilation only, not native runtime
evidence. Add a native check only when an official runner label and successful
native-run evidence are available.