# Contributing

Use British English. Read `AGENTS.md`, `ARCHITECTURE.md`, `DDD.md`,
`CLIENT-SUBSCRIPTIONS.md` and `TESTING.md` before architectural changes.

Identify the owner, aggregate and command/query before editing. Keep business
policy inside its context, inward dependencies explicit, and each service's
source independent. Use native types and typed outcomes; generated contracts
remain outside domain/application packages.

Create reviewable branches from the selected baseline. Use Conventional Commits,
for example `feat(metallo): add a context command`. Record notable changes in a
[PR changelog fragment](changelog.d/README.md). Release-preparation PRs assemble
`CHANGELOG.md`. Follow the [documentation scope](#documentation-scope) when
updating guides or recording architectural decisions.
Number a new decision after the highest number on `main` and in open pull requests.
Paginate the complete changed-file lists of open pull requests; large infrastructure
changes can place decisions beyond the first page.
`pnpm check:architecture` rejects two decisions with the same number; whichever
change reaches `main` second takes the next free number. The exact historical
0000 and 0007 pairs listed in the [ADR catalogue](docs/decisions/README.md) retain
their original identifiers and are the only exceptions.

Before hand-off, select checks using [Choosing checks](TESTING.md#choosing-checks).
Documentation- and instruction-only edits use the focused documentation lane.
Other changes require `pnpm verify` and the applicable real infrastructure lane.
Use the configured dev box for infrastructure-dependent checks; follow the
[dev-box testing workflow](TESTING.md#infrastructure-checks-on-the-dev-box).
Report omitted PostgreSQL, browser, UAT, Minikube/k3s and deployment checks.
Review generated diffs after `pnpm generate:contracts` and keep dependency locks
committed. Generated credentials, tool caches and build outputs stay ignored.

Checked-in generated web clients and schemas live beneath `generated/` directories
in their owning package. Update generators and imports when moving their outputs.
Next.js requires each project's `next-env.d.ts` bootstrap at the project root;
its transient route types and build output remain in ignored `.next/` directories.

## Large-file reviews

Review responsibilities before handwritten source or configuration exceeds 450
lines. This includes YAML, source schemas and deployment templates. Split only at
a clear capability/workflow boundary. Record each justified exception once in
`docs/large-file-review.json`, using its repository-relative path and a reason for
keeping its responsibilities together.

Markdown (`.md` and `.markdown`), dependency lockfiles and the frozen `legacy/`
archive are exempt from the size rule. Generated and vendored files are exempt
when Git attributes set `linguist-generated` or `linguist-vendored` to `true` or
the bare attribute. Register output paths or patterns in `.gitattributes`; keep
their source contracts, templates and generators subject to review. Recognised
lockfile names are listed in `scripts/large_file_review.py`.

`pnpm check:large-file-review` rejects missing reviews, duplicate entries and
obsolete entries. Remove an entry when its file disappears, becomes exempt or
shrinks to 450 lines or fewer. Size exemptions leave architecture, security,
generated-file drift and archive integrity checks in place. The JSON register
uses ordinary merge conflict resolution so each path retains one reviewed reason.

## Documentation site

Run `pnpm docs:check` for the root documentation site and `pnpm docs:preview` to
inspect it locally. Edit authoritative source documents; the site assembles them
into ignored build output. See [the maintenance guide](docs/README.md). Preserve
the exact relocation commit when merging documentation history.

## Documentation scope

Update the smallest set of documents whose purpose is affected by the change.
Keep each fact in one authoritative place and use links when another document
needs that information.

| Document | Responsibility |
| --- | --- |
| Root and scoped `AGENTS.md` files | Durable working rules for coding agents, limited to their directory scope. |
| Root `CLAUDE.md` | A one-line `@AGENTS.md` import of the shared root instructions. |
| `ARCHITECTURE.md` | Service boundaries, shared architectural patterns and the context ownership map, with links to context documentation. |
| `DDD.md` | Shared modelling principles and conventions. |
| `TESTING.md` and `CLIENT-SUBSCRIPTIONS.md` | Shared testing and browser-delivery policies and workflows. |
| Context READMEs | Commands, queries, behaviour, adaptor choices, mock limitations, implementation status and feature-specific verification. |
| Contract documentation | Published payloads, wire formats and compatibility requirements. |
| `docs/decisions/` | Architectural decisions, their rationale and consequences. |
| `changelog.d/` | Pending release notes, with one fragment per notable PR. |
| `CHANGELOG.md` | Assembled release notes and earlier change history. |

Record service-to-context ownership in `ARCHITECTURE.md`; link to the owning
context for its operations and implementation details. Keep top-level guides
focused on their shared responsibilities as contexts grow.

Service teams own their scoped agent guidance. Keep shared rules in the root
instructions and link to authoritative service documentation for local details.
Keep temporary rollout status and issue-specific gates in the owning operational
guide or issue, with an explicit removal condition. Preserve frozen instruction
files under `legacy/`.

Create or amend an architectural decision when a boundary, policy or shared
pattern changes intentionally. Adding a use case within an existing decision
belongs in its context and contract documentation. Update an operational guide
when its actual workflow changes.