docs: complete repository rename operator handoff

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a049a4-ee9f-78e1-9d66-2cb0f9bea3e3

dashboard/src/docs/repos.md

@@ -27,6 +27,11 @@ be followed by classification registration.
 
 For the full onboarding journey see **[Repo Integration](/docs/repo-integration)**.
 
+For a lineage-preserving Forgejo coordinate change, see
+**[Repository Renames](/docs/repository-renames)**. The old repository route
+continues to resolve through a protected alias; the dashboard is verification,
+not the mutation surface.
+
 ---
 
 ## KPI row
@@ -86,4 +91,4 @@ Use the **Add Repo** form or:
 # 2. Register / reclassify
 make register-from-classification PATH=/path/to/repo
 statehub fix-consistency
-```
+```

dashboard/src/docs/repository-renames.md

@@ -0,0 +1,70 @@
+---
+title: Repository Renames — Operator Reference
+---
+
+# Repository renames
+
+State Hub preserves repository history across a Forgejo name change by keeping
+the repository UUID and Forge numeric ID unchanged. The new slug becomes
+canonical and the former slug remains a protected alias.
+
+The dashboard is a read surface. Execute and recover renames with the
+`statehub repo rename` CLI and the repository-owned migration workplan.
+
+## What to inspect here
+
+After the `statehub-rebound` phase:
+
+1. Open `/repos/<old-slug>`. An amber banner must identify the requested slug
+   as an alias and link to the canonical repository page.
+2. Open `/repos/<new-slug>`. Both pages must report the same repository UUID;
+   the canonical page lists the old alias.
+3. Review workplans/tasks, dispatch, token totals, SBOM, services,
+   capabilities, inbox, interface changes, and stale external references.
+4. Treat stale Fabric or external projections as owner handoffs. Their source
+   is not silently rewritten by State Hub.
+
+Matching dashboard counts are useful but insufficient. Final verification uses
+the per-record relationship checksums returned by:
+
+```text
+statehub repo rename verify <operation-id> --json
+```
+
+## Read the achieved phase
+
+```text
+statehub repo rename status <operation-id> --json
+```
+
+The `phase` is the last durable achievement. An `error_code` describes the last
+failed attempt and does not advance the phase. Follow `next_safe_action`; reuse
+the same operation UUID for retries.
+
+| Phase | Next normal action |
+| --- | --- |
+| `preflighted` | Apply `forge-renamed`. |
+| `forge-renamed` | Apply `statehub-rebound`; never register a replacement repository. |
+| `statehub-rebound` | Verify/register a fresh canonical clone, then apply `source-synced`. |
+| `source-synced` | Collect owner handoff evidence and apply `consumers-verified`. |
+| `consumers-verified` | Re-run verification and apply `completed`. |
+| `completed` | Soak, hand off residuals, then request cleanup approval. |
+| `rollback-preflight` | Review blockers and irreversible effects before `--execute`. |
+| `rolled-back` | Verify old canonical routes and affected consumers. |
+
+## Safety boundaries
+
+- Repository rename approval does not rename products, packages, APIs,
+  namespaces, environment variables, policies, or telemetry labels.
+- Forgejo credentials stay in their approved custodian; they never enter State
+  Hub commands or evidence.
+- External repositories own and close their own file-backed handoff tasks.
+- Rollback does not undo consumer commits, deployments, published artifacts,
+  external caches, or historical telemetry.
+- The old checkout is removed last, after terminal verification, soak, live
+  residual handoffs, and explicit path-specific approval.
+- The protected old alias remains. Alias retirement is a separate decision.
+
+The complete source runbook is `docs/repository-rename-operations.md`; its
+versioned handoff contract is
+`docs/schemas/repository-rename-handoff-v1.schema.json`.