# SDD: arcrun Component Registry 正典化（Component Registry Canon）

> 2026-05-07 建立。狗糧發現的根本問題：registry 活著但 index 空的，AI 找不到零件就會繞回 Python。
> 範圍：**讓 registry 成為零件 metadata 的 SSOT**，含 u6u → arcrun rebrand。

---

## 1. 問題

### 1.1 表象
- `registry.arcrun.dev/components/search?q=*` 永遠回 0 結果
- MCP `u6u_search_components` 找不到任何零件
- `acr parts list` 同樣空

### 1.2 根因
`matrix/arcrun/registry/components/` 下 30+ 個零件已經部署成獨立 Worker（kbdb_ingest, claude_api, kbdb_create_block, kbdb_patch_block, http_request, string_ops, ⋯），但**它們的 contract.yaml 沒有透過 `POST /components/submit` 進 registry index**。

部署路徑：
```
registry/components/{name}/main.go     ← TinyGo 寫的零件
       ↓ tinygo build
.component-builds/{name}/component.wasm
       ↓ wrangler deploy
{name}.arcrun.dev (Worker)              ← 零件可被 HTTP 呼叫了

registry index?                         ← 這步從來沒做
```

### 1.3 影響（吃狗糧的觀察）
- 新 AI（Claude / Gemini / Codex）進來不知道有什麼零件 → 自己寫 Python 直打 API
- arcrun 想推「AI-first 自服務」整個破功
- 文件寫得再好都救不了 — 因為 README 只能寫概念，零件清單必須是 API 動態查

---

## 2. 目標

**Registry 是零件 metadata 的 SSOT**：

- 零件 Worker 在跑 ⇔ registry 有對應 entry（雙向綁定）
- AI 透過 MCP `search_components` 永遠找得到所有現役零件
- README 不寫死數量，動態 badge 即時反映
- 第三方裝完 MCP 30 秒內能找到第一個可用零件

---

## 3. 三層設計

### Layer 1: 一次性 backfill（Phase 1）

掃 `matrix/arcrun/registry/components/*/component.contract.yaml`，把每個 contract POST 進 registry index。

工具：`matrix/arcrun/registry/scripts/backfill-index.ts`
- 讀檔 → 解析 YAML → 呼叫 registry submit endpoint
- idempotent：已存在不重複寫（registry 端要支援 upsert）
- 跳過沙盒驗收（這些零件已驗過、已部署，不用重跑 gherkin tests）

### Layer 2: 部署即註冊（Phase 2）

改 `.github/workflows/deploy.yml`：
- 通用掃描掃到 `.component-builds/{name}/wrangler.toml` 部署成功後
- post-deploy step 自動呼叫 registry submit（contract 從 `registry/components/{name}/component.contract.yaml` 讀）

零件 Worker 部署 ⇒ registry 自動更新。沒有「零件部署了但 registry 不知道」的可能。

### Layer 3: Discoverability（Phase 3）

- README 移除「21 個零件」這種寫死數字，改「跑 search 看當前清單」
- 加 badge endpoint `registry.arcrun.dev/badge/components.svg` 即時顯示數量
- MCP `get_component_guide` 開頭加鐵律：「動工前必須先 search，不是猜」
- onboarding kit GitHub template：CLAUDE.md / .cursor/rules / AGENTS.md 三件套，all 強制 search 優先

### Layer 4: u6u → arcrun Rebrand（Phase 4）

把 `matrix/u6u-mcp/` 跟所有 `u6u_*` tool 名搬到 arcrun 命名空間。

理由：
- u6u 是申請 arcrun.dev 之前的暫名，現在已過時
- 命名混亂阻礙推廣（「為什麼 arcrun 文件叫 u6u_*?」）
- 第三方看到 u6u 不知道是同一個產品

範圍：
1. 目錄：`matrix/u6u-mcp/` → `matrix/arcrun-mcp/`
2. Worker name：`u6u-mcp` → `arcrun-mcp`
3. Tool 前綴：`u6u_search_components` → `arcrun_search_components`（14 個 tool）
4. Hostname：`mcp.finally.click` → `mcp.arcrun.dev`（finally.click 保留 redirect 到 arcrun.dev 過渡期）
5. Repo / Worker 內部 ID：u6u-mcp-server → arcrun-mcp-server
6. README 全文：u6u → arcrun
7. user memory（CLAUDE.md / MEMORY.md）相關提及一併更新
8. inkstone-component-registry（舊 worker）廢止 → arcrun-registry 為唯一現役

**Rebrand 原則：**
- 用戶端 config（claude_desktop_config.json 等）給過渡期：兩個 URL 都活，舊的回 deprecation header 提示換新
- Tool 前綴 `u6u_*` → `arcrun_*` 沒有過渡期（一刀切，因為前綴是 AI 看的，不是用戶記憶肌肉）
- 文件 / repo 內所有 reference 立即改

---

## 4. 範圍邊界

**在本 SDD 範圍內：**
- ✅ Phase 1: backfill index
- ✅ Phase 2: 部署即註冊 hook
- ✅ Phase 3: README + badge + onboarding kit
- ✅ Phase 4: u6u → arcrun rebrand（含目錄 / worker / hostname / tool 前綴 / 文件）

**不在範圍內：**
- 新零件開發（這是 polaris 業務範圍）
- registry KV schema 改動（用既有結構）
- u6u-gui 的 rebrand（u6u-mcp 同 monorepo 但獨立 SDD）
- Phase 5（用戶自製零件 R2 上傳）— 等 Phase 4 完成後另開 SDD

**前置依賴（已完成）：**
- ✅ u6u-mcp Zod 4 → Zod 3 修復（2026-05-07）
- ✅ u6u-mcp service binding 改指 arcrun-registry（2026-05-07）
- ✅ arcrun-registry Worker 部署在 registry.arcrun.dev

---

## 5. 驗收標準

### Phase 1 驗收
- `u6u_search_components("kbdb")` 回非空結果，含 `kbdb_ingest` / `kbdb_create_block` / `kbdb_patch_block`
- `acr parts list` CLI 端對端能列出
- registry KV 內至少 30 entries

### Phase 2 驗收
- 部署任一既有零件後，registry 30 秒內 reflect 更新
- 部署一個全新零件，無需手動 publish，registry 自動有
- CI workflow 不會因 registry 寫入失敗就擋部署（degraded mode：寫入失敗 log warning 但不 fail）

### Phase 3 驗收
- README 沒有「21 個零件」「30 個零件」這種寫死數字
- badge SVG 渲染正確、數字跟 KV 一致
- onboarding kit clone 下來，照 README 跑能 30 秒內 list 到零件

### Phase 4 驗收
- `mcp.arcrun.dev/mcp/mcp` 通，回的 tool 名都是 `arcrun_*`
- 舊 `mcp.finally.click/mcp/mcp` 仍可用但回 deprecation header
- README / docs / GUIDE 全部 u6u 字樣消除
- `matrix/u6u-mcp/` 目錄不存在，改為 `matrix/arcrun-mcp/`
- 用戶記憶（`~/.claude/.../MEMORY.md`）arcrun MCP 設定範例已更新

---

## 6. 風險與緩解

| 風險 | 緩解 |
|---|---|
| backfill 把 contract 灌進去後，沙盒驗收覆蓋既有資料 | registry submit 加 `skip_acceptance=true` flag，僅 backfill 用 |
| 部署 hook 寫入失敗擋掉部署 | hook degraded mode：失敗只 warning，不 fail 部署 |
| Rebrand 把現役 client 弄壞 | 過渡期：舊 hostname 跟 worker 並存 1 個月 |
| Tool 前綴改名 AI 適應期 | 不過渡，一刀切（前綴是 system instruction 範圍，AI 一個 prompt 就學會）|
| 既有用戶 config 寫死 finally.click | 提前公告 + 過渡期 + 舊 endpoint 自動 redirect / proxy |

---

## 7. 變更紀錄

| 版本 | 日期 | 內容 |
|---|---|---|
| v1.0 | 2026-05-07 | 初版。吃狗糧發現 registry 空的，三層設計（backfill / auto-register / discoverability）+ u6u → arcrun rebrand 一併納入。 |