Documentation

## Example 09 — <what it demonstrates>

<1–3 sentences: what this shows and when you'd reach for it.>

```yaml
--8<-- "deploy/examples/09-<kebab-name>.yaml"
```

**Never** paste a literal multi-line manifest into a `.md` file. If you're about
to, stop and make it a file under `deploy/examples/` instead. (Short inline
`console`/`kubectl` snippets that aren't manifests are fine.)

### Example manifest conventions (match the existing files)

- Filename `NN-kebab-name.yaml`, `NN` zero-padded and ordered by complexity.
- A top-of-file comment block: what it demonstrates, the CRD type/field it maps
  to (verified against `crates/api`), and any caveats on field shapes.
- `REPLACE_ME` for secrets the user must supply; a real-looking but obviously-
  placeholder value otherwise.
- Inline comments on every non-obvious field — especially the "common values"
  above and any default being made explicit for teaching.
- Backends are **externally tagged** (`backend.s3`, not `backend: { kind: S3 }`)
  — see [[kopiur-design]]. Apply-ready and self-contained (Secret + CRs in one
  file) so `kubectl apply -f` just works after filling in `REPLACE_ME`.

### Adding an example: which of the two homes it belongs to

There are **two** conventions, and the number tells you which:

**01–20 — the `docs/examples.md` ladder.** A three-touch change:

1. Create `deploy/examples/NN-name.yaml`.
2. Add a `## Example NN — …` section in `docs/examples.md` with the
   `--8<-- "deploy/examples/NN-name.yaml"` snippet inside a `yaml` fence.
3. Add a row to the table at the top of `docs/examples.md`.

**21+ — capability-page inclusion.** The ladder is a *tutorial* sequence and
stops at 20 deliberately; everything after it is a per-capability example that
belongs beside the prose explaining that capability, not at the end of a
tutorial. So a two-touch change:

1. Create `deploy/examples/NN-name.yaml`, usually with
   `# --8<-- [start:…]` / `[end:…]` section markers so the page can pull just
   the CR that teaches the point.
2. Snippet-include it from the capability page that documents the field
   (`docs/replication.md` for 19's replication CR, `docs/repositories.md` for
   the `spec.seed` examples, `docs/backends/s3.md` for 38, …).

   **Do not** add a `docs/examples.md` row/section for a 21+ example — that is
   how the same manifest ends up documented twice and the two copies drift.

Either way the file must be reachable from *some* page: an example nothing
includes is an orphan, and nothing in the build catches it.

**Scenario bundles** are a third home: `deploy/examples/scenarios/NN-name.yaml`,
one per `docs/scenarios/*.md` page, pulled by that page (whole-file or by
section) and listed in the scenarios index table. They are typed-checked by
`crates/api/tests/examples_match_crd_shapes.rs` like everything else.

A new top-level **page** (not an example) also needs an entry in the `nav:` of
`mkdocs.yml`, or it builds unlinked (and `--strict` warns). A new **scenario**
page additionally needs its row in `docs/scenarios/index.md`.

## Docs change in the same PR as the behavior

**Whenever you change logic that affects how someone deploys, uses, or configures
Kopiur, update the docs in the same change.** This is not a follow-up task.

Triggers that REQUIRE a docs/examples update:

| You changed… | Update… |
|---|---|
| A CRD field / shape / default in `crates/api` | the relevant `docs/*.md` prose **and** any example manifest that uses it |
| A Helm value or install scope (`deploy/helm`) | `docs/install.md` |
| RBAC / SA / mover behavior | `docs/movers.md` |
| Maintenance defaults or projection | `docs/maintenance.md` |
| A webhook-enforced constraint | the affected page (state it as a `/// warning` admonition) + the example that would otherwise violate it |
| A reconciler UX change (status, print columns, phases) | wherever that surface is described |

Field shapes shown in docs/examples must be the real ones — the manifests are
apply-ready, so a wrong field is a user-facing bug, not a typo.

## Verify before claiming done

```bash
mise run docs   # mkdocs build --strict (broken link / missing nav file = build fail)