docs: define the zones, and standardise on "zone" over "area"

[qiuethan]

What this changes

Adds docs/CODE-OWNERSHIP.md as the single definition of the repo's zones, and standardises the vocabulary on that one word.

1. root is now a listed zone in the PR template and both issue templates. All three lists are byte-identical.
2. AGENTS.md stops enumerating the list and links the new doc instead.
3. "Area" is retired as a synonym — 42 occurrences across 5 files, comments and prose only.

Why

"Area" and "zone" were the same thing, used interchangeably across eight files and defined in none. The three places that enumerated the list disagreed: zone_for() has 14 buckets, CODEOWNERS named 11 plus a fallback, the templates listed the same 11, and AGENTS.md gave a fourth version.

That gap had a concrete cost. A PR editing README.md, AGENTS.md, Makefile, or pyproject.toml lands in the root zone, which no template offered — so the author picked a wrong zone or deleted the line. That's the most common kind of PR in this repo.

The rename is driven by a collision, not tidiness. The in-flight project-board revamp introduces area/* as an issue-label namespace grouping by kind of work (area/bot, area/service, area/tooling, …) — a different axis from these fourteen directory buckets. One area/service issue spans six zones. That branch also adds required "Area" dropdowns to the issue templates, the same templates that carry the zone list. Ship both and "area" means two things in one issue form.

"Zone" wins because the machinery already says it: pr-zone-check.yml, the zone-check job, zone_for(), the ## Zone heading. Standardising the other direction would rename a workflow file and its job — a bad trade once that job is a required status check.

Two "area" mentions are kept deliberately, in CODEOWNERS and the doc, noting that older comments and git history use it for the same concept. Keeps the word searchable without endorsing it.

One deliberate omission: services/other and packages/other stay off the template menus. They're transitional buckets — a PR landing in one means something was added that nobody registered, and the fix is to give it a real zone, not to pick a catch-all. root is different: a permanent destination.

Zone

docs · .github · root

Three zones, so pr-zone-check will warn. Expected rather than incidental: the change is the zone list, which inherently lives in docs/, .github/, and a root file.

How to verify

# All three template lists identical (prints 1) and 12 items long:
grep -h '^`discord-bot`' .github/PULL_REQUEST_TEMPLATE.md \
  .github/ISSUE_TEMPLATE/feature_request.md \
  .github/ISSUE_TEMPLATE/epic.md | sort -u | wc -l
grep -h '^`discord-bot`' .github/PULL_REQUEST_TEMPLATE.md | grep -o '`[^`]*`' | wc -l

# Only the two deliberate reserved-word notes still say "area":
grep -rni --include='*.md' --include='*.yml' --include='CODEOWNERS' '\barea' . \
  | grep -v '^./.git/' | grep -v '^./.claude/' | grep -v node_modules

# The workflow is untouched apart from one message string — prints exactly
# the ::warning:: line, nothing else:
git diff origin/staging -- .github/workflows/pr-zone-check.yml \
  | grep -E '^[+-]' | grep -vE '^[+-]{3}' | grep -vE '^[+-]\s*#'

# Still valid, and all 14 buckets intact (prints 14):
python -c "import yaml; yaml.safe_load(open('.github/workflows/pr-zone-check.yml'))"
grep -oP 'echo \K[a-z./-]+(?= ;;)' .github/workflows/pr-zone-check.yml | wc -l

I ran all of these. zone_for() also still passes bash -n, and every relative link in the new doc resolves.

Checklist

• Branched off staging and targeting staging.
• Ran the service's test suite locally — N/A, no service touched. Five Markdown files, CODEOWNERS, and one workflow comment block.
• uv run ruff check . / ruff format --check . — N/A, no Python touched. Markdown is hand-wrapped and the linters are scoped to Python and *.js, so make check has no surface here. I did not run it.
• Read the service's docs/CONTRIBUTING.md — N/A, no service touched.
• Docs updated where this makes them wrong — README.md's tree, AGENTS.md's "Where to look" table, and the new doc's closing section, which these fixes made obsolete twice over.

Deployment notes

None. No runtime, config, or CI behaviour changes — zone_for()'s fourteen buckets and every match pattern are byte-identical.

Anything you're unsure about

Conflict warning: the local docs/project-board-revamp branch rewrites the same CODEOWNERS and pr-zone-check.yml comment blocks. It's unpushed, so it's the one that rebases — and rebasing it onto this means it inherits settled vocabulary rather than propagating the ambiguity. Worth doing before it grows.

The root cause is still open. Five files hold the zone list and nothing checks they agree. Both drift incidents — deee002 and this one — trace to that. Correcting the copies resets the clock without changing the odds. A ~15-line CI step diffing zone_for() against CODEOWNERS would catch it mechanically; I'd keep it a separate PR since it's the only part with logic to get wrong.

Latent, not yet biting: root, services/other, and packages/other have no CODEOWNERS line and resolve through the * fallback. Invisible while every owner is @qiuethan.

🤖 Generated with Claude Code