feat(onboarding): redesign repo integration journey

custodian_cli.py:
- register-project now writes CLAUDE.custodian.md (suggestion) instead
  of overwriting CLAUDE.md; includes preamble with integration instructions
- registers repo via POST /repos/
- creates a "Repo Integration: {slug}" workstream in the domain's topic
  with 4 onboarding tasks (integrate CLAUDE.md, first workplan, SBOM,
  EPs/TDs); checks for existing workstream to be idempotent
- fixes {REPO_SLUG} template substitution (previously missing)

dashboard:
- repos.md: fetches workstreams; detects active repo-integration-* slugs;
  adds "Integrating" KPI card; shows ⚙ integrating badge per repo in
  coverage map and table; replaces "How to Ingest a Repo" with
  "Onboard a New Repo" 4-step panel with doc help button
- docs/repo-integration.md (new): full collaboration model doc — custodian
  as coach, repo agent as executor; journey, generated tasks, first session
  protocol, ongoing relationship
- docs/repos.md: links to new repo-integration doc; updates "What is a
  managed repo?" section; adds onboarding quick reference
- docs/reference.md: fix latent build error — code examples were in ```js
  fences (executed by OF); changed to ```javascript (display only)
- observablehq.config.js: adds "Repo Integration" to Reference nav

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dashboard/src/docs/reference.md

@@ -56,20 +56,20 @@ first automatically.
 
 The helper is exported from `src/components/doc-overlay.js`:
 
-```js
+```javascript
 import {withDocHelp} from "./components/doc-overlay.js";
 ```
 
 **On a page h1:**
 
-```js
+```javascript
 const _h1 = document.querySelector("#observablehq-main h1");
 if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/my-page"); }
 ```
 
 **On a sidebar card or other element** (must have `position: relative`):
 
-```js
+```javascript
 const _card = html`<div class="kpi-infobox" style="position:relative">…</div>`;
 withDocHelp(_card, "/docs/my-page");
 ```

dashboard/src/docs/repo-integration.md

@@ -0,0 +1,167 @@
+---
+title: Repo Integration — Reference
+---
+
+# Repo Integration
+
+This page describes how a new repository is onboarded into the Custodian
+ecosystem and how the custodian and the repo's own Claude agent collaborate
+during and after integration.
+
+---
+
+## The Collaboration Model
+
+The custodian acts as a **coach**: it registers the repo, writes an
+integration suggestion, and generates a structured set of onboarding tasks.
+The repo's own Claude agent acts as the **executor**: it reads those tasks,
+makes all changes to the repo, and closes out the onboarding workstream.
+
+| Role | Responsibility |
+|------|---------------|
+| **Custodian** | Registers the repo, generates `CLAUDE.custodian.md`, creates the onboarding workstream and tasks, monitors integration status via the dashboard |
+| **Repo agent** | Integrates `CLAUDE.custodian.md` → `CLAUDE.md`, writes the first workplan, ingests the SBOM, catalogues EPs/TDs, closes the onboarding workstream |
+
+The custodian never writes files into another repo directly. All changes to
+the target repo are made from inside that repo by its own agent. This upholds
+the [repo boundary rule](/docs/inter-repo-communication).
+
+---
+
+## The Registration Journey
+
+### Step 1 — Clone the repo locally
+
+```bash
+git clone <remote-url> /path/to/repo
+```
+
+### Step 2 — Register from the repo root
+
+```bash
+cd /path/to/repo
+custodian register-project --domain <slug>
+```
+
+The `--domain` flag is required. Run `custodian status` to list valid domain
+slugs. The command takes about five seconds and produces no interactive
+prompts.
+
+What happens automatically:
+1. The API is health-checked
+2. The domain is validated; the domain's topic ID is resolved
+3. `CLAUDE.custodian.md` is written to the repo root — the integration suggestion
+4. The repo is registered in the State Hub (`POST /repos/`)
+5. A **Repo Integration** workstream is created in the domain's topic with 4
+   onboarding tasks
+6. A progress event is logged
+
+### Step 3 — Open the repo in Claude Code
+
+```bash
+cd /path/to/repo
+claude
+```
+
+The repo agent starts, calls `get_domain_summary("<domain>")`, and sees the
+Repo Integration workstream. It works through the 4 onboarding tasks
+autonomously. No human interaction is needed unless the agent has a question.
+
+### Step 4 — Monitor on the Repos page
+
+The [Repos](/repos) page shows each repo's integration status. An **integrating**
+badge appears on repos with an active Repo Integration workstream. The badge
+clears when the workstream is marked completed.
+
+---
+
+## What the Registration Creates
+
+### `CLAUDE.custodian.md`
+
+A suggestion file written to the repo root. It contains the full State Hub
+session protocol, First Session Protocol, workplan convention, contribution
+tracking instructions, and SBOM guidance — pre-filled with the repo's domain,
+topic ID, and slug.
+
+The repo agent integrates this content into the existing `CLAUDE.md` (or
+creates a new one) and deletes the suggestion file. It is not meant to persist.
+
+### Repo Integration workstream
+
+A workstream titled **Repo Integration: `<repo-slug>`** is created in the
+target domain's topic. It is visible via `get_domain_summary()` at the repo
+agent's next session start.
+
+> **ADR-001 note:** This workstream is a DB-first bootstrapping exception.
+> The file-first principle does not apply here because the repo has no
+> `workplans/` directory yet. Writing the first workplan file is task T2.
+
+### 4 Onboarding tasks
+
+| # | Title | Priority | What it means |
+|---|-------|----------|---------------|
+| T1 | Integrate `CLAUDE.custodian.md` → `CLAUDE.md` | high | Merge the suggestion into the existing CLAUDE.md; delete the suggestion file; commit |
+| T2 | Write first workplan and initialise `workplans/` | high | Create `workplans/` and write the first workplan file per ADR-001; register the workstream in the hub |
+| T3 | Ingest SBOM | medium | Run `make ingest-sbom REPO=<slug> SCAN=1 REPO_PATH=<path>` from the state-hub dir |
+| T4 | Register known EPs and TDs | low | Catalogue extension points and technical debt using the MCP tools |
+
+---
+
+## Repo Agent: First Session Protocol
+
+When `get_domain_summary()` returns a **Repo Integration** workstream, the
+repo agent should:
+
+1. Read `CLAUDE.custodian.md` alongside the existing `CLAUDE.md`
+2. Execute T1 first — merge and delete the suggestion file, commit
+3. Execute T2 — create `workplans/<DOMAIN>-WP-0001-<slug>.md` covering the
+   primary near-term work; register the workstream in the hub via MCP
+4. Execute T3 — ingest the SBOM so the repo appears green on the Repos page
+5. Execute T4 — a quick scan for obvious EPs/TDs; defer if nothing obvious
+6. Mark each task `done` in the hub as completed
+7. Mark the Repo Integration workstream `completed`
+8. Log a progress event summarising the integration
+
+The agent should resolve each task independently and in order. It does not
+need human approval for any of these steps unless it encounters an ambiguous
+merge conflict in CLAUDE.md.
+
+---
+
+## After Integration
+
+Once the onboarding workstream is closed, the repo participates in the full
+custodian ecosystem:
+
+- **Session start:** `get_domain_summary("<domain>")` shows active workstreams,
+  blocking decisions, and recent progress — the standard orientation
+- **Ecosystem todos:** tasks with `[repo:<slug>]` in their title created by
+  other agents appear in the domain summary and signal cross-repo work
+- **Contributions:** outbound upstream work is tracked in `contrib/` and
+  registered via `register_contribution()`
+- **SBOM:** re-ingest after dependency updates with `make ingest-sbom`
+- **Session close:** `add_progress_event()` keeps the hub's episodic memory
+  current
+
+See the [Inter-Repo Communication](/docs/inter-repo-communication) reference
+for task routing conventions.
+
+---
+
+## Troubleshooting
+
+**`custodian: command not found`**
+The CLI is installed via `make install-cli` from the state-hub directory.
+Ensure `~/.local/bin` is on your `PATH`.
+
+**`ERROR: Cannot reach API`**
+The state hub API must be running: `cd ~/the-custodian/state-hub && make api`
+
+**`CLAUDE.custodian.md` already exists**
+Re-running `custodian register-project` overwrites it with a fresh
+suggestion. The repo agent should integrate and delete it.
+
+**Repo already registered (slug conflict)**
+The command is idempotent for the repo row. Onboarding tasks are re-created
+only if no active Repo Integration workstream already exists.

dashboard/src/docs/repos.md

@@ -12,9 +12,13 @@ their SBOM ingestion status, and a domain-grouped coverage map.
 ## What is a managed repo?
 
 A managed repo is a git repository that has been registered with the state hub
-via `make add-repo` or `register_repo()`. Registration records the repo's slug,
-domain, local path, and optional remote URL. Once registered, the repo can
-receive SBOM ingestion and is eligible for the ADR-001 workplan validator.
+via `custodian register-project` or `register_repo()`. Registration records the
+repo's slug, domain, local path, and optional remote URL. Once registered, the
+repo receives a `CLAUDE.custodian.md` integration suggestion, an onboarding
+workstream with 4 tasks for the repo agent, and is eligible for SBOM ingestion
+and the ADR-001 workplan validator.
+
+For the full onboarding journey see **[Repo Integration](/docs/repo-integration)**.
 
 ---
 
@@ -52,14 +56,22 @@ Rows with no SBOM are highlighted in amber.
 
 ---
 
+## Onboarding a new repo
+
+See **[Repo Integration](/docs/repo-integration)** for the full journey.
+
+Quick reference:
+
+```bash
+# From the repo root — registers, writes CLAUDE.custodian.md, creates onboarding tasks
+custodian register-project --domain <slug>
+```
+
 ## Ingesting a repo's SBOM
 
 ```bash
-# Register a new repo
+# Auto-detects lockfile at repo root
 cd ~/the-custodian/state-hub
-make add-repo DOMAIN=<slug> SLUG=<repo-slug> NAME="Display Name" PATH=/absolute/path
-
-# Ingest SBOM (auto-detects lockfile at repo root)
 make ingest-sbom REPO=<slug> REPO_PATH=/absolute/path
 
 # Multi-ecosystem repo — scan all lockfiles recursively