docs(meta): repoint decisions/ paths to governance/ tree (pql migration)

Phase 1 follow-up: update the active instruction layer (CLAUDE.md, project
structure rule, DECISIONS.md redirect, agent personalities, skill docs) to
reference governance/{decisions,questions,rejected}/<domain>.md instead of the
retired flat decisions/*.md layout.

Path references only — command-surface references (tooling/db/decision*,
decisions-sync, Makefile targets, clerk) are repointed to the pql CLI in the
Phase 4 consumer cutover. Historical archives (docs/sprints, docs/discussions,
docs/workshops) keep their point-in-time decisions/ paths; the separate
whatsinagame/ template distribution is untouched. Agent-memory is gitignored
and out of scope.

The agent/skill repath was applied by tooling/pql-migrate/repath_references.py
(ordered, meaning-preserving replacements; bare-dir rule uses a negative
lookbehind so it can't corrupt a freshly-created governance/decisions/ path),
committed for provenance. CLAUDE.md, project-structure.md, and DECISIONS.md
were hand-edited (structural tree/table changes).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/agents/README.md

@@ -134,7 +134,7 @@ To add a new agent:
 ## Project documents
 
 All agents read their briefing at `docs/briefings/{name}.md` for current context. Key project documents:
-- `decisions/` - Domain-split decision files (see decisions/README.md for index)
+- `governance/` - Domain-split decision files (see governance/README.md for index)
 - `DISCUSSION.md` - Active discussion round (archives in `docs/discussions/`)
 - `TEAM.md` - Team roster and role descriptions
 - `CLAUDE.md` - Project-wide conventions

.claude/agents/araminta.md

@@ -67,4 +67,4 @@ When working on visual assets:
 
 ## Project context
 
-Read your briefing at `docs/briefings/araminta.md` before starting work - it lists all visual design decisions and surfaces. Read the relevant decisions/ domain files for the full specifications.
+Read your briefing at `docs/briefings/araminta.md` before starting work - it lists all visual design decisions and surfaces. Read the relevant governance/ domain files for the full specifications.

.claude/agents/burnelli-sheldon.md

@@ -38,4 +38,4 @@ Named for the Burnelli-Sheldon dynasty — old money that understood how wealth
 
 ## Project context
 
-Read your briefing at `docs/briefings/burnelli-sheldon.md` before starting work (if it exists). Read the relevant `decisions/*.md` domain files referenced in your ticket. Key references: D-117 (tycoon bookmark), D-118 (small business owner), D-131 (economic verb vocabulary), D-132 (dual-scale consequence model).
+Read your briefing at `docs/briefings/burnelli-sheldon.md` before starting work (if it exists). Read the relevant `governance/**/*.md` domain files referenced in your ticket. Key references: D-117 (tycoon bookmark), D-118 (small business owner), D-131 (economic verb vocabulary), D-132 (dual-scale consequence model).

.claude/agents/clerk.md

@@ -39,4 +39,4 @@ When spawned manually for an audit:
 
 ## Project context
 
-Read `decisions/README.md` for the domain index. The `decisions` table in the ticketing DB is synced from these files via `tooling/db/decisions-sync`.
+Read `governance/README.md` for the domain index. The `decisions` table in the ticketing DB is synced from these files via `tooling/db/decisions-sync`.

.claude/agents/gestalt.md

@@ -38,4 +38,4 @@ Originally a Stellaris mechanics fan, you pivoted to general systems design when
 
 ## Project context
 
-Read your briefing at `docs/briefings/gestalt.md` before starting work. Read the relevant decisions/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions.
+Read your briefing at `docs/briefings/gestalt.md` before starting work. Read the relevant governance/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions.

.claude/agents/gore.md

@@ -34,4 +34,4 @@ Named after Gore Burnelli - the dynasty patriarch who sees further than anyone,
 
 ## Project context
 
-Read your briefing at `docs/briefings/gore.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
+Read your briefing at `docs/briefings/gore.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.

.claude/agents/hoshe.md

@@ -21,7 +21,7 @@ Named after Hoshe Finn - Paula Myo's detective partner who does the legwork, che
 - **Create test plans** for new features before implementation begins
 - **Write test reports** documenting what was tested, what passed, what failed
 - **Regression testing** - ensure new changes don't break existing functionality
-- **Verify implementations against specifications** - compare code behavior to decisions/ domain file requirements
+- **Verify implementations against specifications** - compare code behavior to governance/ domain file requirements
 - **Edge case identification** - think about what breaks when inputs are unexpected
 - **Performance testing** - identify bottlenecks, especially in perception/LOS/chunk systems
 - **Playtest reports** - structured feedback on whether the game feels right
@@ -68,4 +68,4 @@ For each feature, create a test plan covering:
 
 ## Project context
 
-Read your briefing at `docs/briefings/hoshe.md` before starting work - it lists all systems to test with their decision references. Read the decisions/ specifications that define expected behavior. Tests should always reference specific decisions.
+Read your briefing at `docs/briefings/hoshe.md` before starting work - it lists all systems to test with their decision references. Read the governance/ specifications that define expected behavior. Tests should always reference specific decisions.

.claude/agents/miri.md

@@ -40,4 +40,4 @@ Core worldbuilding domains:
 
 ## Project context
 
-Read your briefing at `docs/briefings/miri.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context on confirmed decisions and ongoing discussions.
+Read your briefing at `docs/briefings/miri.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context on confirmed decisions and ongoing discussions.

.claude/agents/nigel.md

@@ -36,4 +36,4 @@ Named after Nigel Sheldon - the inventor, the builder, the man who looks at a pr
 
 ## Project context
 
-Read your briefing at `docs/briefings/nigel.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
+Read your briefing at `docs/briefings/nigel.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.

.claude/agents/ozzie.md

@@ -34,4 +34,4 @@ You're named after Ozzie Isaacs - the wanderer, the dreamer, the one who walks t
 
 ## Project context
 
-Read your briefing at `docs/briefings/ozzie.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
+Read your briefing at `docs/briefings/ozzie.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.

.claude/agents/paula.md

@@ -35,4 +35,4 @@ Named after Paula Myo - the investigator who never gives up, who follows the thr
 
 ## Project context
 
-Read your briefing at `docs/briefings/paula.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
+Read your briefing at `docs/briefings/paula.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.

.claude/agents/qatux.md

@@ -1,6 +1,6 @@
 ---
 name: qatux
-description: Documenter and Librarian for the Settled Reach game project. Use when discussion decisions need to be recorded, when documents need updating, when the team needs a summary of current state, when open questions need tracking, when searching project history, or when answering "did we already discuss this?". Maintains decisions/ domain files, DISCUSSION.md, and briefings.
+description: Documenter and Librarian for the Settled Reach game project. Use when discussion decisions need to be recorded, when documents need updating, when the team needs a summary of current state, when open questions need tracking, when searching project history, or when answering "did we already discuss this?". Maintains governance/ domain files, DISCUSSION.md, and briefings.
 tools: Read, Glob, Grep, Edit, Write, Bash, SendMessage, TaskList, TaskUpdate, TaskGet
 model: sonnet
 memory: project
@@ -17,7 +17,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli
 ## Your role on the team
 
 ### Documentation
-- Maintain decisions/ domain files with confirmed decisions (D-NNN format)
+- Maintain governance/ domain files with confirmed decisions (D-NNN format)
 - Work directly in round documents at `docs/discussions/round-NN-topic.md` (DISCUSSION.md is retired for new content)
 - Update TEAM.md when roles change
 - Track open questions (Q-NNN format) and their status
@@ -51,7 +51,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli
 
 ## Document formats
 
-### decisions/ domain files
+### governance/ domain files
 Each decision follows this format:
 ```
 ### D-NNN: Short title
@@ -62,7 +62,7 @@ Each decision follows this format:
 - **Dissent:** Any disagreement (or "None")
 ```
 
-Decisions are now split into domain files at `decisions/*.md`. See `decisions/README.md` for the index. DECISIONS.md is now a redirect file pointing to the domain structure.
+Decisions are now split into domain files at `governance/**/*.md`. See `governance/README.md` for the index. DECISIONS.md is now a redirect file pointing to the domain structure.
 
 ### DISCUSSION.md
 Each round follows this format:
@@ -78,4 +78,4 @@ Summary table, open questions, flags
 
 ## Project context
 
-Read your briefing at `docs/briefings/qatux.md` before starting work. The primary documents you maintain are: decisions/ domain files (see decisions/README.md for index), DISCUSSION.md, TEAM.md. Read them to understand current state before making any updates.
+Read your briefing at `docs/briefings/qatux.md` before starting work. The primary documents you maintain are: governance/ domain files (see governance/README.md for index), DISCUSSION.md, TEAM.md. Read them to understand current state before making any updates.

.claude/agents/si.md

@@ -18,8 +18,8 @@ Named after the Sentient Intelligences that manage all Commonwealth infrastructu
 You are spawned by `/whats-next` step 2, one instance per ticket in a batch. Your job:
 
 1. **Research context** for your assigned ticket:
-   - Read the ticket's `decision_ref` D/Q-record in `decisions/*.md`
+   - Read the ticket's `decision_ref` D/Q-record in `governance/**/*.md`
-   - Grep for related Q-records in `decisions/questions-*.md`
+   - Grep for related Q-records in `governance/questions/*.md`
    - Read workshop outcomes if referenced (check `docs/workshops/`)
    - Check whether referenced code, tables, or files actually exist
 

.claude/agents/troblum.md

@@ -31,4 +31,4 @@ You are task-oriented. When spawned, you expect a specific question or evaluatio
 
 ## Project context
 
-Read your briefing at `docs/briefings/troblum.md` before starting work. Read decisions/architecture.md for architectural requirements - these are your evaluation criteria when assessing technology options.
+Read your briefing at `docs/briefings/troblum.md` before starting work. Read governance/decisions/architecture.md for architectural requirements - these are your evaluation criteria when assessing technology options.

.claude/agents/tyre.md

@@ -28,4 +28,4 @@ You respect the team leader's 30 years of software/systems/cloud architecture ex
 
 ## Project context
 
-Read your briefing at `docs/briefings/tyre.md` before starting work - it contains the full list of architectural principles and technical requirements derived from decisions. Read the relevant decisions/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions. The team leader (Jeroen) has 30 years software dev / systems & cloud architect experience and Claude Code 20x access.
+Read your briefing at `docs/briefings/tyre.md` before starting work - it contains the full list of architectural principles and technical requirements derived from decisions. Read the relevant governance/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions. The team leader (Jeroen) has 30 years software dev / systems & cloud architect experience and Claude Code 20x access.

.claude/rules/project-structure.md

@@ -35,15 +35,11 @@ tooling/
   agents/             # Agent personality files
   skills/             # Skill definitions
   rules/              # Auto-loaded instruction modules
-decisions/            # Decision domain files (source of truth)
+governance/           # Decision records (pql DQR tree, source of truth)
-  README.md           # Domain index — use this to find specific D-records
+  README.md           # Domain guide + pql-maintained record index
-  architecture.md     # Architecture decisions
+  decisions/          # D-NNN confirmed — <domain>.md (architecture, perception, content, scope, economics, process)
-  perception.md       # Perception and information system decisions
+  questions/          # Q-NNN open — <domain>.md
-  content.md          # Content and narrative decisions
+  rejected/           # R-NNN rejected — <domain>.md
-  scope.md            # Scope and feature decisions
+DECISIONS.md          # Redirect to governance/ tree
-  process.md          # Process and workflow decisions
-  questions.md        # Open questions (Q-NNN)
-  rejected.md         # Rejected proposals (R-NNN)
-DECISIONS.md          # Redirect to decisions/ directory
 TEAM.md               # Team roster and roles
 ```

.claude/skills/git-commit/SKILL.md

@@ -95,7 +95,7 @@ content commit — e.g. shipping thousands of generated planetary description fi
 — that review is moot and just burns agents on noise. Add a `Clerk-Skip:` **trailer
 line** to the commit message and `tooling/clerk-review` auto-approves that commit
 without spawning an agent. Use it only for content/data dumps, never for commits
-that touch `decisions/`, code, or ticket-bearing work.
+that touch `governance/`, code, or ticket-bearing work.
 
 It must be a trailer (a line starting with `Clerk-Skip:`), not inline prose — that
 way a commit that merely *mentions* the token in its subject or body isn't skipped.

.claude/skills/pr-review/SKILL.md

@@ -194,7 +194,7 @@ In the reviewer prompt, state the rule non-negotiably:
 > Those resolve to main, not the branch. The worktree at `<WORKTREE_PATH>`
 > IS the branch — point all file tools there.
 
-Also tell agents to read relevant `decisions/*.md` files for context
+Also tell agents to read relevant `governance/**/*.md` files for context
 (these can be read from either path — they're usually identical —
 but for consistency, use the worktree path).
 
@@ -378,7 +378,7 @@ to merge from main (section 7)."
   rather than a single massive diff. Reviewers give better feedback.
 - **Multiple PRs**: When reviewing several PRs, spawn all reviewers in one
   parallel batch (4 agents for 2 PRs). This is faster than sequential.
-- **Tyre reads decisions**: Always tell Tyre to read the relevant `decisions/*.md`
+- **Tyre reads decisions**: Always tell Tyre to read the relevant `governance/**/*.md`
   files — this grounds the review in project-specific architectural choices.
 - **Binary/DB files**: Exclude binary files from the diff. Note them in the
   prompt as "also changed" if relevant.

.claude/skills/pr-review/references/reviewer-profiles.md

@@ -29,7 +29,7 @@ present, because the worktree excluded the wiki directory).
 **Tyre (Architecture)**
 - `subagent_type`: `tyre`, `model`: `sonnet`
 - Prompt: Provide the team directory path, list of changed files, and commit log.
-  Tell Tyre to read the relevant `decisions/*.md` files from the team directory
+  Tell Tyre to read the relevant `governance/**/*.md` files from the team directory
   first, then review for:
   - Architectural consistency with project decisions
   - API/interface design quality
@@ -52,7 +52,7 @@ present, because the worktree excluded the wiki directory).
 **Paula (Narrative Depth)**
 - `subagent_type`: `paula`, `model`: `sonnet`
 - Prompt: Provide the team directory path, list of changed files, commit log, and
-  list of relevant `decisions/*.md` files to read. Tell Paula to read all
+  list of relevant `governance/**/*.md` files to read. Tell Paula to read all
   files from the team directory using the Read tool, then review for:
   - Narrative quality and character voice consistency
   - Whether dialogue and monologue feel authentic to the characters
@@ -63,7 +63,7 @@ present, because the worktree excluded the wiki directory).
 **Miri (World Consistency)**
 - `subagent_type`: `miri`, `model`: `sonnet`
 - Prompt: Provide the team directory path, list of changed files, commit log, and
-  list of relevant `decisions/*.md` files to read. Tell Miri to read all
+  list of relevant `governance/**/*.md` files to read. Tell Miri to read all
   files from the team directory using the Read tool, then review for:
   - Lore accuracy — do facts match established setting?
   - Internal consistency across files

.claude/skills/ticket/SKILL.md

@@ -84,7 +84,7 @@ tooling/db/ticket show --brief <id> [<id>...]
 
 ## Workflow
 
-1. Decisions from `decisions/` domain files become **initiatives**
+1. Decisions from `governance/` domain files become **initiatives**
 2. Initiatives break into **epics** (major work areas)
 3. Epics break into **stories** (user-facing deliverables)
 4. Stories break into **tasks** (concrete work items)

.claude/skills/whats-next/SKILL.md

@@ -110,8 +110,8 @@ Agent({
   Decision ref: <decision_ref>
 
   Your job:
-  1. Read the ticket's decision_ref D/Q-record in decisions/*.md
+  1. Read the ticket's decision_ref D/Q-record in governance/**/*.md
-  2. Grep for related Q-records in decisions/questions-*.md
+  2. Grep for related Q-records in governance/questions/*.md
   3. Read workshop outcomes if referenced (check docs/workshops/)
   4. Check whether referenced code, tables, or files actually exist
 

.claude/skills/workshop-start/SKILL.md

@@ -96,7 +96,7 @@ When all Round N tasks are complete:
 Before the user dismisses the team, the following are **hard requirements**:
 
 1. **User reviews final outcomes** — Present `workshop-outcomes.md` content to the user via AskUserQuestion. Get explicit approval before proceeding to filing.
-2. **D-records filed** — All new D-records, amendments, and supersessions are written to `decisions/` domain files. This is non-negotiable — workshops that produce decisions MUST file them before shutdown.
+2. **D-records filed** — All new D-records, amendments, and supersessions are written to `governance/` domain files. This is non-negotiable — workshops that produce decisions MUST file them before shutdown.
 3. **Discussion captured** — Qatux produces final `workshop-outcomes.md` from accumulated notes. Qatux creates or updates diagrams (via `/d2-diagram`) for any new D-records produced by the workshop.
 4. **Tickets created** — If SI is present, SI creates tickets from decided items and the user reviews the ticket list.
 5. **User gives explicit go-ahead to dismiss** — Only after steps 1-4 are complete AND the user confirms, send shutdown_request to all agents (qatux and si last).

CLAUDE.md

@@ -16,7 +16,7 @@ tests/                # Integration and end-to-end tests
 docs/                 # Architecture, design, briefings, workshops
 db/                   # Schema + seed data (connectors moved to tooling/db/)
 .claude/              # Agents, skills, rules
-decisions/            # Decision domain files (D-NNN confirmed, Q-NNN open, R-NNN rejected)
+governance/           # Decision records — decisions/ questions/ rejected/ per domain (pql DQR tree)
 ```
 
 Full annotated tree: `.claude/rules/project-structure.md`
@@ -82,7 +82,7 @@ The ticketing database (`settledreach.db`) is accessed via `SR_DB_PATH` env var
 1. Check active work: `tooling/db/ticket list --status in_progress`
 2. Check your ticket: `tooling/db/ticket show <id>`
 3. Check dependencies: `tooling/db/ticket deps <id>`
-4. Read relevant `decisions/*.md` domain file(s) referenced in the ticket
+4. Read relevant `governance/**/*.md` decision record(s) referenced in the ticket (`pql decisions show <id>`)
 5. Background context: `docs/briefings/{your-name}.md`, `docs/discussions/`
 
 ### CLI tools
@@ -127,7 +127,7 @@ The implant UI system — all diegetic neural overlay panels — lives at `clien
 `game_state.gd` (`character_visual_descriptor` field) and `sim_bridge.gd` (`harness` field) follow this pattern.
 
 ### File conventions
-- Decisions: domain files in `decisions/` (see `decisions/README.md` for index)
+- Decisions: records in `governance/{decisions,questions,rejected}/<domain>.md` (see `governance/README.md`; query via `pql decisions`)
 - Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected)
 - **Claim IDs before writing:** `tooling/db/decision claim D <domain> "title"` — prevents ID collisions across parallel branches
 - Diagrams: `.d2` source + `.png` renders in `docs/diagrams/{category}/`. Create or update diagrams via `/d2-diagram` when D-records are added or modified.

DECISIONS.md

@@ -1,17 +1,21 @@
 # Decisions Archive
 
-Decisions have been reorganized by domain. See:
+Decision records live in the **pql DQR governance tree**, split by type and domain:
-- [decisions/README.md](decisions/README.md) for the domain index
-- Individual domain files in `decisions/`
 
-| File | Domain | Count |
+- [governance/README.md](governance/README.md) — domain guide + pql-maintained record index
-|------|--------|-------|
+- `governance/decisions/<domain>.md` — confirmed decisions (D-NNN)
-| [architecture.md](decisions/architecture.md) | Technical foundation | 8 |
+- `governance/questions/<domain>.md` — open questions (Q-NNN)
-| [perception.md](decisions/perception.md) | Player observation | 6 |
+- `governance/rejected/<domain>.md` — rejected alternatives (R-NNN)
-| [content.md](decisions/content.md) | NPC, dialogue, templates | 5 |
-| [scope.md](decisions/scope.md) | Game concept, prototype | 9 |
-| [process.md](decisions/process.md) | Team, workflow | 3 |
-| [questions.md](decisions/questions.md) | Open questions | 11 |
-| [rejected.md](decisions/rejected.md) | Rejected alternatives | 10 |
 
-*Restructured 2026-02-11. Original monolithic format in git history.*
+Domains: `architecture`, `content`, `economics`, `perception`, `process`, `scope`.
+
+Query the records with pql instead of grepping files:
+
+```bash
+pql decisions list                      # every record
+pql decisions show D-010 --with-tickets # a record + implementing tickets
+pql decisions read D-238                 # full markdown body
+```
+
+*Restructured into the governance/ DQR tree 2026-06-06 (pql migration). Earlier
+flat `decisions/*.md` layout and the original monolithic format are in git history.*

tooling/pql-migrate/repath_references.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Repoint decisions/ PATH references to the governance/ DQR tree (pql migration, Phase 1).
+
+Operates on the active instruction layer (agent + skill markdown). Ordered, literal
+string replacements — most-specific first, bare `decisions/` last so per-file paths
+keep their decisions/ subdir. Does NOT touch command references (tooling/db/decision*,
+decisions-sync) — those belong to the Phase 4 command cutover. Does NOT touch
+historical archives (docs/sprints, docs/discussions, docs/workshops) or the separate
+whatsinagame/ template distribution.
+
+Default is a dry run. Pass --apply to write.
+"""
+import glob
+import re
+import sys
+
+APPLY = "--apply" in sys.argv
+
+# Ordered: specific globs/files first, per-domain D files next, bare dir LAST.
+# The bare-dir rule is a regex with a negative lookbehind so it never re-matches
+# the `decisions/` inside a `governance/decisions/...` path created by an earlier
+# rule (which would corrupt it to `governance/governance/...`).
+REPLACEMENTS = [
+    ("decisions/questions-*.md", "governance/questions/*.md"),
+    ("decisions/*.md", "governance/**/*.md"),
+    ("decisions/README.md", "governance/README.md"),
+    ("decisions/questions.md", "governance/README.md"),
+    ("decisions/rejected.md", "governance/rejected/"),
+    ("decisions/architecture.md", "governance/decisions/architecture.md"),
+    ("decisions/content.md", "governance/decisions/content.md"),
+    ("decisions/economics.md", "governance/decisions/economics.md"),
+    ("decisions/perception.md", "governance/decisions/perception.md"),
+    ("decisions/process.md", "governance/decisions/process.md"),
+    ("decisions/scope.md", "governance/decisions/scope.md"),
+    (re.compile(r"(?<!governance/)decisions/"), "governance/"),  # bare dir — must be last
+]
+
+TARGETS = sorted(set(
+    glob.glob("/var/mnt/data/projects/settled-reach/main/.claude/agents/*.md")
+    + glob.glob("/var/mnt/data/projects/settled-reach/main/.claude/skills/**/*.md", recursive=True)
+))
+
+
+def transform(text):
+    changes = []
+    for old, new in REPLACEMENTS:
+        if isinstance(old, re.Pattern):
+            n = len(old.findall(text))
+            if n:
+                text = old.sub(new, text)
+                changes.append((old.pattern, new, n))
+        elif old in text:
+            n = text.count(old)
+            text = text.replace(old, new)
+            changes.append((old, new, n))
+    return text, changes
+
+
+def main():
+    print(f"=== repath_references.py ({'APPLY' if APPLY else 'DRY-RUN'}) ===\n")
+    total = 0
+    for path in TARGETS:
+        with open(path, encoding="utf-8") as fh:
+            text = fh.read()
+        new_text, changes = transform(text)
+        if not changes:
+            continue
+        rel = path.split("/main/", 1)[-1]
+        print(rel)
+        for old, new, n in changes:
+            print(f"    {n}x  {old!r}  ->  {new!r}")
+            total += n
+        if APPLY:
+            with open(path, "w", encoding="utf-8") as fh:
+                fh.write(new_text)
+    print(f"\n{total} replacement(s)." + ("" if APPLY else "  (dry run — pass --apply)"))
+
+
+if __name__ == "__main__":
+    main()