docs: say what each zone covers, not just how it is wired

[qiuethan]

What this changes

The canonical zone table in docs/CODE-OWNERSHIP.md gains a What it covers column — a one-line description of each zone, with a link to its README for the eight zones that have one.

Why

The table gave each zone's pr-zone-check pattern, CODEOWNERS line, and owner, but never said what a zone is. It answered "how is this wired?" and not "what would I be signing up for?"

That gap matters right now: docs/ONBOARDING.md:31 already sends new members to the canonical list as "the menu" of zones to pick from, and a zone-ownership form is about to point at the same anchor. Both were sending people to a table that couldn't answer the question they arrived with — the descriptions lived in eight separate service READMEs.

Zone

docs

How to verify

The one gate that reads this file is label-consistency, via check-labels.mjs, which requires a row per zone:

node scripts/check-labels.mjs   # or: make labels
# Label consistency check passed.
# Zones (14) — the PR axis: ...

Every relative link in the file resolves:

grep -o '](\.\./[^)]*)' docs/CODE-OWNERSHIP.md | sed 's|](\.\./||;s|)$||' | sort -u |
  while read p; do [ -e "$p" ] && echo "OK   $p" || echo "MISS $p"; done
# 21 OK, 0 MISS

Then read the table on the Files tab — the point of the change is whether the descriptions are accurate, which CI cannot check.

Checklist

• Branched off staging and targeting staging.
• Ran the relevant check locally — node scripts/check-labels.mjs passes. No service test suite applies: this is a single Markdown file.
• ruff — not applicable, no Python in this PR.
• Docs updated in this PR where the change makes them wrong — this PR is the docs change, and no other copy of the zone list carries descriptions, so nothing else goes stale.

Note on the last one: the descriptions are a fifth restatement of what each service does, after the service README, its ARCHITECTURE.md, the root README.md tree, and the service's own docs. They are deliberately one line and scoped to why you'd own it rather than how it works, but they are hand-maintained prose and nothing checks them against reality — see below.

Deployment notes

None — documentation only.

Anything you're unsure about

Two things worth a second opinion.

The column reorder. Zone, description and owner now come first, with the pr-zone-check pattern and CODEOWNERS line pushed to the right. My reasoning is that the table is read to pick or understand a zone far more often than to debug a label, and the mechanics are restated in "Adding or renaming a zone" anyway. It does make the diff a full table rewrite rather than an append, so if you'd rather keep the original column order and just append the new one, that's a one-line change to make.

A new drift surface, in the file that exists because of drift. label-consistency checks that the zone names agree across five files; it cannot check that a description still matches what a service does. docs/CODE-OWNERSHIP.md already names this class of problem — "whether a zone's paths are the right paths" — and this adds prose in the same category. A service that changes shape leaves a stale line here, silently. I think that's an acceptable trade for a table people can actually use, and one line per zone is small enough to re-read during a rename, but it is a real cost and worth disagreeing with.

One thing that is not uncertain: the zone stays a bare backticked name in the first cell. check-labels.mjs:489 matches each row by the literal | + backticked zone + |, so linking the zone name itself fails the build. The links live in the description cell for that reason.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xu8iVgaPrvUfgQoNbJSr46