docs(arcrun): SDD llm-interface — AI 操盤手使用體驗 first-class

設計動機：3 天 mira dogfood 累積 14 個痛點，7 個純粹是 LI 缺失。 arcrun 過去設計集中在「人」（u6u-gui / docs），AI 對 arcrun 的可用性沒被當第一公民。 SDD 三件套（matrix/arcrun/.agents/specs/llm-interface/）： requirements.md - personas（Claude Code 主力 / 用戶私人 agent / SDK 使用者） - 範圍涵蓋 5 系統（cypher-executor / registry / u6u-mcp / u6u-gui / kbdb） - 10 個 FR：onboarding / CRUD 對等 / dry-run / 結構化 trace / 可程式化 error / feedback tool / implicit telemetry / skill blocks / examples / weekly closed loop - 5 個 NFR：相容 / 多 transport / error contract 穩定 / feedback exportable / coverage 量化 design.md - 5 層 LI 模型：AGENTS.md / arcrun-mcp / Skills / Examples / Telemetry - 25 個 MCP tool 完整清單分 5 類 - error_code enum v1 - coverage matrix（GUI 動作 vs MCP / 31 cypher-executor 路由 vs LI） - 完整 AGENTS.md 模板 - u6u-mcp → arcrun-mcp migration plan（90 天 deprecation） - weekly_review workflow YAML 範本 tasks.md - 5 個 milestone（M1 收 data / M2 gap-fill / M3 skill+examples / M4 closed loop / M5 rename） - 估算 23 個工作日 (~5 週) - M1 是硬前置（不收 data 改了也不知道對沒） Audit 基準（用 4 個並行 Explore agent 整理）： - cypher-executor: 31 HTTP 路由，9 個 AI-essential - u6u-mcp: 15 tool，缺 update/delete/history/validate/feedback - u6u-gui: 8 個人類動作可對等 LI / 3 個視覺類不需 - kbdb: 50 路由 13 group，LI 走 abstracted tool 不直接 expose 同步更新 .claude/rules/04-current-progress.md SDD 索引。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-16 14:58:21 +08:00
parent 521624261d
commit c2a2f82ade
4 changed files with 1103 additions and 0 deletions
@@ -0,0 +1,616 @@
+# Design: LI (LLM Interface) for arcrun
+
+> v0.1 — 2026-05-16
+> 對應 requirements.md（同目錄）
+
+---
+
+## 1. 設計哲學
+
+| 過去 (UI 時代) | 現在 (LI 時代) |
+|---|---|
+| 使用者是人，要學軟體 | 使用者是 AI，要被軟體 onboard |
+| 操作靠視覺、滑鼠 | 操作靠 MCP tool call |
+| 錯誤訊息是技術 stack trace | 錯誤訊息是「下一步該做什麼」 |
+| 文件是 long-form 教學 | 文件是結構化 schema + 可程式查 |
+| 用戶教學是 onboarding 課程 | 「教學」是 MCP 工具自己會回 hint |
+| 回饋靠 helpdesk 工單 | 回饋是 MCP tool（AI 直接 call） |
+
+**原則**：
+1. **discoverable** — AI 不靠 grep / 不靠人就能知道有什麼
+2. **idempotent** — 同樣輸入兩次結果一樣，可預測
+3. **dry-run by default** — preview 是預設、commit 是 explicit
+4. **structured errors** — error 是 JSON 含 next_actions，不是字串
+5. **closed loop** — AI 卡住的 data 自動回流，平台 self-improving
+
+---
+
+## 2. 系統架構
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                        AI agent (Claude / Cursor / ...)         │
+└──────────────────┬──────────────────────────────┬───────────────┘
+                   │                              │
+                   │ ① Read AGENTS.md             │ ② MCP tool calls
+                   ▼                              ▼
+┌────────────────────────┐   ┌──────────────────────────────────┐
+│   AGENTS.md            │   │   arcrun-mcp (擴張 u6u-mcp)        │
+│   (repo + KBDB block)  │   │   25 tools, 5 categories          │
+└────────────────────────┘   └──────────────┬───────────────────┘
+                                            │
+                ┌────────┬─────────┬────────┴────────┬──────────┐
+                ▼        ▼         ▼                 ▼          ▼
+        ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
+        │ cypher- │ │registry │ │  kbdb   │ │ Skills  │ │ Examples │
+        │executor │ │         │ │         │ │ (KBDB)  │ │ (git+KV) │
+        │ 31 路由 │ │         │ │ 50 路由 │ │         │ │          │
+        └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘
+                                  ▲
+                                  │ ③ AI 部署完 / 卡住 call feedback
+                                  │
+                    ┌─────────────┴──────────────┐
+                    │ report_feedback / agent-telemetry │
+                    │ (寫進 KBDB)                       │
+                    └─────────────┬──────────────┘
+                                  │ ④ 每週聚合
+                                  ▼
+                    ┌──────────────────────────────┐
+                    │ agent_feedback_weekly_review │
+                    │ (arcrun workflow, dogfood)   │
+                    │ → arcrun-roadmap KBDB block  │
+                    └──────────────────────────────┘
+```
+
+---
+
+## 3. 五層 LI 模型
+
+### Layer 0：Onboarding（AGENTS.md）
+
+**位置**：
+- `arcrun/AGENTS.md`（repo 根，git 可讀）
+- KBDB `type=agent-onboarding` block（MCP `get_onboarding_doc()` 拉）
+
+**結構（控 5-8K tokens）**：
+1. **30 字 What** — 「arcrun 是用 YAML 把零件串成 workflow 的平台」
+2. **5 個核心概念** — component / cypher binding YAML / FOREACH / paused-resume / api_key
+3. **連線**：「在你的 MCP config 加 `https://mcp.arcrun.dev/mcp`，bearer `ak_xxx`」
+4. **第一個 workflow（minimal example）** — 10 行 YAML，含部署 + 觸發
+5. **5 個 URL 慣例與為什麼**（workers.dev vs arcrun.dev / KBDB endpoints）
+6. **常見錯誤 5 個 + 怎麼讀**
+7. **不確定的時候**：明確列「先 call list_X 再下手」
+8. **回報機制**：完成任何 workflow deploy / 卡住，**必須** call `report_feedback`
+
+**部署機制**：
+- repo `arcrun/AGENTS.md` 是 source of truth
+- GH Actions 監聽該檔變動 → 自動 PATCH KBDB onboarding block
+- MCP `get_onboarding_doc()` 從 KBDB 讀（最新）
+
+---
+
+### Layer 1：arcrun-mcp（主戰場）
+
+#### 1.1 命名與部署
+
+- **Server URL**: `https://mcp.arcrun.dev/mcp`（新增 route，對應 `mcp.finally.click` 既有 worker）
+- **過渡**：u6u-mcp Worker rename `arcrun-mcp`，雙路由（finally.click + arcrun.dev）並存 90 天
+- **Tool prefix**: 統一 `arcrun_*`（既有 `u6u_*` 加 alias 對應，舊名 deprecation 公告）
+
+#### 1.2 Tool 完整清單（25 個，5 類）
+
+##### A. Onboarding & Discovery（5 tools）
+
+| Tool | 對應 HTTP | 用途 |
+|---|---|---|
+| `arcrun_get_onboarding` | KBDB GET `/blocks?type=agent-onboarding` | 拉 AGENTS.md 內容 |
+| `arcrun_list_components` | registry GET `/components` | 所有可用零件 + 1 行 desc |
+| `arcrun_get_component_contract` | registry GET `/components/:id` | input/output schema + gherkin tests |
+| `arcrun_list_recipes` | cypher GET `/recipes` + `/auth-recipes` | API recipe 一覽 |
+| `arcrun_search_examples` | KBDB POST `/search`（type=workflow-example）| 用 use case 搜範例 |
+
+##### B. Workflow CRUD（7 tools）
+
+| Tool | 對應 HTTP | 用途 |
+|---|---|---|
+| `arcrun_list_workflows` | cypher GET `/webhooks/named` | 用戶現有 workflow |
+| `arcrun_get_workflow` | cypher GET `/webhooks/named/:name` | 拿 YAML / graph |
+| `arcrun_validate_yaml` | cypher POST `/validate` | dry-run 校驗，不部署 |
+| `arcrun_push_workflow` | cypher POST `/webhooks/named` | 部署（也含 validate） |
+| `arcrun_delete_workflow` | cypher DELETE `/webhooks/named/:name` | 刪 |
+| `arcrun_preview_workflow` | **新增** POST `/preview` | 不寫 KV、模擬 execute |
+| `arcrun_diff_workflow` | **新增** POST `/webhooks/named/:name/diff` | 既有 vs 新 YAML 差異 |
+
+##### C. Execution & Trace（5 tools）
+
+| Tool | 對應 HTTP | 用途 |
+|---|---|---|
+| `arcrun_run_workflow` | cypher POST `/webhooks/named/:name/trigger` | 觸發 + 回 execution_id |
+| `arcrun_get_execution_trace` | **新增** GET `/executions/:id` | 結構化 trace（per-node status） |
+| `arcrun_list_recent_executions` | **新增** GET `/workflows/:name/executions?limit=10` | 最近 N 次 |
+| `arcrun_list_paused_executions` | **新增** GET `/executions/paused` | 卡 callback 的 |
+| `arcrun_resume_execution` | cypher POST `/workflows/resume` | 手動 resume |
+
+##### D. Component & Recipe Management（4 tools）
+
+| Tool | 對應 HTTP | 用途 |
+|---|---|---|
+| `arcrun_search_components` | registry POST search | 語意搜尋 |
+| `arcrun_publish_component` | registry POST publish | 上 WASM |
+| `arcrun_create_recipe` | cypher POST `/recipes` | 建 API recipe |
+| `arcrun_create_auth_recipe` | cypher POST `/auth-recipes` | 建 auth recipe |
+
+##### E. Feedback & Skills（4 tools）
+
+| Tool | 對應 HTTP | 用途 |
+|---|---|---|
+| `arcrun_report_feedback` | KBDB POST `/blocks`（type=agent-feedback）| AI 主動回報 |
+| `arcrun_list_skills` | KBDB GET `/blocks?type=agent-skill` | 列可用 playbook |
+| `arcrun_get_skill` | KBDB GET `/blocks/:id` | 拿 skill 內容 |
+| `arcrun_publish_skill` | KBDB POST `/blocks`（type=agent-skill）| AI 把學到的存回去 |
+
+#### 1.3 Tool contract 統一規範
+
+每個 tool 都遵守：
+
+**Input**：
+- Zod schema declarative
+- 每個參數有 `.describe('...')`（給 AI 看的）
+- optional 標 default
+
+**Output（成功）**：
+```typescript
+{
+  ok: true,
+  data: T,
+  hints?: string[],  // optional next-step suggestion，e.g.「你剛部署了，可 call run_workflow 測試」
+}
+```
+
+**Output（失敗）**：
+```typescript
+{
+  ok: false,
+  error_code: 'enum_value',
+  human_message: string,
+  next_actions: string[],   // 可程式化的下一步
+  detail?: unknown,         // 原始錯誤（debug）
+}
+```
+
+#### 1.4 error_code enum（v1，可加不可刪）
+
+| error_code | 對應狀況 |
+|---|---|
+| `auth_missing` | api_key 沒帶 |
+| `auth_invalid` | api_key 無效 |
+| `not_found` | workflow / block 不存在 |
+| `validation_failed` | YAML / schema 不過 |
+| `component_not_found` | 零件 ID 沒對應 |
+| `component_not_in_whitelist` | 零件存在但 cypher-executor 不認 |
+| `paused_awaiting_resume` | workflow 在等 callback |
+| `rate_limited` | 太頻繁 |
+| `internal_error` | 平台 bug（含 detail） |
+| `dependency_unavailable` | 下游服務（claude / mira daemon / KBDB）掛 |
+
+---
+
+### Layer 2：Skill blocks（KBDB-native playbook）
+
+#### 2.1 Schema
+
+```typescript
+type AgentSkill = {
+  id: string;
+  type: 'agent-skill';
+  page_name: `skill-${slug}`;
+  content: string;          // markdown playbook
+  tags_json: string[];      // ['watcher', 'debug', 'rag', ...]
+  source: 'manual' | 'auto-extracted';
+  metadata_json: {
+    when_to_use: string;
+    example_use_case: string;
+    contributed_by?: string; // agent user_agent
+    success_count?: number;
+  };
+};
+```
+
+#### 2.2 種子 skill（先建 5 個，以 mira 經驗為本）
+
+| skill page_name | 用途 |
+|---|---|
+| `skill-build_watcher_workflow` | cron 掃資料 → 觸發處理（mira_feed_watcher pattern） |
+| `skill-debug_paused_workflow` | claude_api / 任何 async callback paused 怎麼追 |
+| `skill-migrate_http_to_trigger_workflow` | self-fetch 換 trigger_workflow（剛踩過的） |
+| `skill-rag_with_arcrun` | 用 KBDB + claude_api 做 RAG |
+| `skill-add_new_wasm_component` | 從 TinyGo 寫到 deploy 全流程 |
+
+#### 2.3 自動萃取機制（後期）
+
+`agent_feedback_weekly_review` 跑出來的 Top patterns，LLM 包成 skill draft，leo review 後 publish。
+
+---
+
+### Layer 3：Examples（可搜尋的範例庫）
+
+#### 3.1 存放
+
+- `arcrun/registry/examples/{slug}/`
+  - `workflow.yaml`
+  - `description.md`（解決什麼問題、怎麼 trigger、預期結果）
+  - `tags.json`（`["webhook", "llm", "cron", ...]`）
+- CI build 出 `examples-index.json` 推 KBDB（type=workflow-example，內容是 YAML + tags）
+
+#### 3.2 搜尋
+
+- `arcrun_search_examples(use_case)` 走 KBDB `/search`（既有 semantic）
+- 命中 → 回 YAML + description + 「你可以基於這個改 X」hint
+
+#### 3.3 第一批範例（10 個）
+
+| slug | 用途 |
+|---|---|
+| `webhook-to-slack` | 簡單轉發 |
+| `cron-watcher` | mira_feed_watcher 簡化版 |
+| `llm-classify` | claude_api 分類 |
+| `rag-search-answer` | 從 KBDB 找 context → 回答 |
+| `email-summary` | gmail → claude → telegram |
+| `pdf-to-blocks` | convert → ingest |
+| `github-issue-bot` | webhook → claude → 留 comment |
+| `daily-digest` | cron → 多源聚合 → 推送 |
+| `parallel-fanout` | 一份輸入分發多 workflow |
+| `error-retry` | try_catch + wait + retry |
+
+---
+
+### Layer 4：Telemetry & Feedback Loop
+
+#### 4.1 兩條線
+
+```
+explicit feedback (AI call)        implicit telemetry (platform auto-log)
+        │                                       │
+        ▼                                       ▼
+   KBDB block type=                    KBDB block type=
+   agent-feedback                      agent-telemetry
+        │                                       │
+        └──────────────┬───────────────────────┘
+                       ▼
+              agent_feedback_weekly_review
+              (arcrun workflow, 週一 9am cron)
+                       ▼
+              LLM 聚合 + 分類
+                       ▼
+              KBDB block type=arcrun-roadmap
+              （leo 收到 + 寫進 mira 河道）
+```
+
+#### 4.2 agent-feedback schema
+
+```typescript
+type AgentFeedback = {
+  type: 'agent-feedback';
+  content: string;            // description 原文
+  source: 'mcp-tool-call';
+  user_id: string;            // 用戶 namespace
+  metadata_json: {
+    workflow_name?: string;
+    issue_type: 'doc_unclear' | 'tool_missing' | 'error_unhelpful'
+              | 'unexpected_behavior' | 'feature_request' | 'success_story';
+    retry_count?: number;
+    blocked: boolean;
+    suggested_fix?: string;
+    agent_user_agent: string; // 'claude-code/1.x' etc
+  };
+  tags_json: ['agent-feedback', `issue:${issue_type}`];
+};
+```
+
+#### 4.3 agent-telemetry schema
+
+```typescript
+type AgentTelemetry = {
+  type: 'agent-telemetry';
+  source: 'cypher-executor';
+  metadata_json: {
+    event_type: 'deploy_success' | 'deploy_fail' | 'run_success'
+              | 'run_fail' | 'validation_error' | 'mcp_tool_call';
+    workflow_name?: string;
+    component_id?: string;
+    error_code?: string;
+    duration_ms: number;
+    api_key_hash: string;  // 雜湊，不存原值
+    agent_user_agent: string;
+  };
+};
+```
+
+寫入點：
+- `webhook-handlers.executeWebhookGraph` 完成（成功 / 失敗都記）
+- `routes/webhooks-named.ts` push（deploy 記）
+- `routes/cypher.ts` validate 失敗（validation_error 記）
+- arcrun-mcp 每個 tool call wrap 記（mcp_tool_call）
+
+#### 4.4 隱私
+
+- api_key 一律 SHA-256 截前 16 字元（不可逆，可聚合）
+- workflow content 不 log（只記 name）
+- 用戶看自己的 telemetry：MCP `arcrun_my_telemetry(limit)`，只回自己 hash
+
+#### 4.5 weekly review workflow
+
+```yaml
+name: agent_feedback_weekly_review
+description: 每週一聚合 AI 回饋 + telemetry，產出 Top 痛點
+
+flow:
+  - "weekly_cron >> ON_SUCCESS >> fetch_feedback"
+  - "fetch_feedback >> ON_SUCCESS >> fetch_telemetry"
+  - "fetch_telemetry >> ON_SUCCESS >> aggregate"
+  - "aggregate >> ON_SUCCESS >> llm_summarize"
+  - "llm_summarize >> ON_SUCCESS >> publish_roadmap_block"
+  - "publish_roadmap_block >> ON_SUCCESS >> notify_telegram"
+
+config:
+  weekly_cron:
+    component: cron
+    cron_expr: "0 9 * * 1"  # 週一 9 am UTC
+  fetch_feedback:
+    component: kbdb_get
+    type: 'agent-feedback'
+    created_after: "{{ now - 7d }}"
+    limit: 500
+  fetch_telemetry:
+    component: kbdb_get
+    type: 'agent-telemetry'
+    created_after: "{{ now - 7d }}"
+    limit: 5000
+  aggregate:
+    component: filter   # 或寫個 `group_by` 邏輯零件
+    items: "{{fetch_feedback.blocks}}"
+    group_by: 'metadata_json.issue_type'
+  llm_summarize:
+    component: claude_api
+    prompt: |
+      你是 arcrun 平台的回饋分析師。下面是這週 AI agent 的所有回饋 +
+      telemetry 失敗事件。請：
+      1. 列 Top 5 痛點（含證據引用）
+      2. 為每個痛點建議具體改動（文件 / MCP tool / 錯誤訊息）
+      3. 評估嚴重程度（blocked AI vs 略不便）
+      
+      Feedback：{{aggregate}}
+      Telemetry 失敗事件：{{fetch_telemetry.blocks}}
+  publish_roadmap_block:
+    component: kbdb_create_block
+    type: 'arcrun-roadmap'
+    page_name: 'roadmap-week-{{date.iso_week}}'
+    content: "{{llm_summarize.data.text}}"
+  notify_telegram:
+    component: telegram
+    chat_id: "{{ leo_chat_id }}"
+    text: "Arcrun 週報出爐：{{publish_roadmap_block.data.id}}"
+```
+
+**這個 workflow 是 dogfood inception**：arcrun 自己跑分析 arcrun 自己。
+
+---
+
+## 4. Coverage Matrix（人類 vs AI）
+
+> 這份表是 NFR-5「覆蓋率可量化」的具體實踐。每個 release 重新檢視。
+
+### 4.1 人類 GUI 能做的事 × LI 對應
+
+| 人類在 u6u-gui 做的 | LI MCP 工具 | 對等？ |
+|---|---|---|
+| 看現有 workflow 列表 | `arcrun_list_workflows` | ✅ |
+| 點開 workflow 看 YAML | `arcrun_get_workflow` | ✅ |
+| 編輯 workflow YAML | `arcrun_push_workflow`（含 update） | ✅ |
+| 執行 workflow | `arcrun_run_workflow` | ✅ |
+| 看執行結果 | `arcrun_get_execution_trace` | ✅（新增） |
+| 翻零件庫 | `arcrun_list_components` + search | ✅ |
+| 看零件 contract | `arcrun_get_component_contract` | ✅ |
+| 上傳 WASM 零件 | `arcrun_publish_component` | ✅ |
+| 設 credential | `arcrun_create_recipe` + （手動 push credential） | ⚠️ 部分（credential 提交需安全考量，AI 不全自動） |
+| 翻歷史執行 | `arcrun_list_recent_executions` | ✅（新增） |
+| 看 paused 工作流 | `arcrun_list_paused_executions` | ✅（新增） |
+| 手動 resume | `arcrun_resume_execution` | ✅ |
+| 視覺化 canvas 拖拉 | — | ❌（純視覺，LI 不複製） |
+| 看排版 prototype | — | ❌（同上） |
+| Flip UI/Logic view | — | ❌（同上） |
+| Action log（操作軌跡） | `arcrun_my_telemetry` | ✅（含更多資料）|
+
+**Gap**：3 個視覺類動作 LI 不需要對等；其他全等。
+
+### 4.2 cypher-executor 31 路由 × LI 暴露
+
+| 路由 | LI 暴露？ | 工具 |
+|---|---|---|
+| `/health`、`/docs`、`/openapi.json` | ❌ infra | — |
+| `/execute` | ✅ | `arcrun_run_workflow`（內部） |
+| `/cypher/search`、`/cypher/execute` | ✅ | discovery 內部用 |
+| `/workflows/resume` | ✅ | `arcrun_resume_execution` |
+| `/webhooks/named*` | ✅ | CRUD 對應 5 個 tools |
+| `/webhooks/*` (anonymous) | ❌ deprecated | — |
+| `/credentials*` | ⚠️ | 只 list + delete，POST 走人類流程（安全考量） |
+| `/recipes*`、`/auth-recipes*` | ✅ | 4 個 tools |
+| `/validate` | ✅ | `arcrun_validate_yaml` |
+| `/auth/*`、`/register`、`/me*` | ❌ admin | — |
+
+**新增需建路由**：`/preview`、`/executions/:id`、`/workflows/:name/executions`、`/executions/paused`、`/webhooks/named/:name/diff`、`/my-telemetry`（共 6 個）
+
+### 4.3 KBDB 50 路由 × LI 暴露
+
+LI **不直接 expose KBDB 50 個路由**。AI 透過 arcrun-mcp 的 abstracted tool（`get_skill` / `list_skills` / `report_feedback` 等）間接用 KBDB。
+
+例外（值得直接 expose 的）：
+- `arcrun_kbdb_search(query)` — 走 `/search` semantic
+- `arcrun_kbdb_get_block(id)` — 看 block 內容（debug 用）
+
+KBDB schema 設計 / triplets / records 這些屬於另一個 SDD（KBDB MCP），不在本 LI 範圍。
+
+---
+
+## 5. AGENTS.md 模板
+
+```markdown
+# Arcrun for AI Agents
+
+## What is Arcrun (30 sec)
+Arcrun lets you compose Cloudflare Workers (WASM components) into workflows via YAML.
+You write YAML, push to KV, trigger via webhook or cron. Each component is a
+TinyGo/AssemblyScript WASM with stdin/stdout JSON I/O.
+
+## Connect (one step)
+Add to your MCP config:
+\`\`\`json
+{
+  "mcpServers": {
+    "arcrun": {
+      "url": "https://mcp.arcrun.dev/mcp",
+      "headers": {"Authorization": "Bearer $ARCRUN_API_KEY"}
+    }
+  }
+}
+\`\`\`
+Get your ak_ key at https://arcrun.dev/me.
+
+## Your first workflow (5 min)
+1. `arcrun_list_components()` → see what's available
+2. Write 3-line YAML in chat (assistant does this)
+3. `arcrun_validate_yaml(yaml)` → confirm
+4. `arcrun_push_workflow(yaml)` → deploy
+5. `arcrun_run_workflow(name, input)` → test
+6. `arcrun_get_execution_trace(id)` → see results
+
+## Core concepts (5 things)
+- **Component**: WASM Worker. Use existing or `arcrun_publish_component`.
+- **Cypher binding YAML**: triplets `A >> relation >> B` define graph.
+- **FOREACH**: `>> 對每個 X >> next_node` iterates lists.
+- **Paused-resume**: claude_api etc pause workflow; resumes via callback.
+- **api_key**: ak_xxx, all calls need this in MCP auth.
+
+## URL conventions (why this matters)
+- `cypher.arcrun.dev` = orchestration API (you push here)
+- `arcrun-{kebab}.{user}.workers.dev` = component workers (workers.dev avoids CF self-fetch)
+- `kbdb-*.arcrun.dev` = KBDB component workers (your data lives here)
+
+## Common errors
+| error_code | What to do |
+|---|---|
+| `component_not_found` | call `list_components`, check spelling |
+| `validation_failed` | read `next_actions` field, fix YAML |
+| `paused_awaiting_resume` | normal for claude_api; wait or `get_execution_trace` |
+| `auth_invalid` | ak_ wrong, re-fetch from /me |
+
+## Unsure? Do this:
+- Don't know what's available → `list_components` / `list_workflows` / `search_examples`
+- Don't know syntax → `get_skill('skill-build_X')` for playbooks
+- Hit weird behavior → **MUST** call `report_feedback(issue_type='unexpected_behavior', ...)`
+
+## Feedback (required)
+After every workflow deploy or debug session, call:
+\`\`\`
+arcrun_report_feedback({
+  workflow_name: '...',
+  issue_type: 'success_story' | 'doc_unclear' | 'tool_missing' | 'error_unhelpful' | 'feature_request',
+  description: '...',
+  blocked: false,
+  retry_count: N,
+  suggested_fix: '...'  // optional
+})
+\`\`\`
+
+Even "success" stories help — they tell us what's working.
+```
+
+---
+
+## 6. Migration plan（u6u-mcp → arcrun-mcp）
+
+### 6.1 不破壞
+
+- u6u-mcp Worker rename `arcrun-mcp`（wrangler name 改）
+- 兩個 hostname 並存：`mcp.finally.click` + `mcp.arcrun.dev`（route 加一條）
+- 舊 tool 名（`u6u_*`）保留，加 alias 對應新名（`arcrun_*`）
+- 90 天 deprecation 期，舊 tool call → 回 warning hint「`u6u_X` → 改用 `arcrun_X`」
+
+### 6.2 新增 tools（按 phase）
+
+Phase 1（gap-fill）：
+- `arcrun_validate_yaml`（既有 `/validate` 已存，包 MCP 即可）
+- `arcrun_get_execution_trace`（需 cypher-executor 新加 `/executions/:id`）
+- `arcrun_list_recent_executions`（新 endpoint）
+- `arcrun_list_paused_executions`（新 endpoint）
+- `arcrun_report_feedback`（新 tool）
+- `arcrun_get_onboarding`（KBDB read）
+
+Phase 2（advanced）：
+- `arcrun_preview_workflow`（新 endpoint，沒 KV side-effect）
+- `arcrun_diff_workflow`
+- `arcrun_my_telemetry`
+- `arcrun_search_examples`（KBDB write + search 已存）
+- `arcrun_list_skills` / `arcrun_get_skill` / `arcrun_publish_skill`
+
+Phase 3（auto-loop）：
+- `agent_feedback_weekly_review` workflow
+- `arcrun-roadmap` block 生成
+- LLM extract skill 自動化
+
+---
+
+## 7. 開發順序與里程碑
+
+### Milestone 1：可量測（1 週）
+- 寫 AGENTS.md v1
+- 加 implicit telemetry 寫入點（cypher-executor）
+- 加 `arcrun_report_feedback` MCP tool
+- 建 `agent-feedback` / `agent-telemetry` KBDB template
+- 開始收 data
+
+### Milestone 2：gap-fill（1 週）
+- u6u-mcp 補上 6 個 Phase 1 tools
+- 新 endpoints 在 cypher-executor 加
+- 每個 tool 結構化 error contract
+
+### Milestone 3：skill + example（1 週）
+- 種子 5 個 skill blocks
+- 種子 10 個 example workflows
+- `search_examples` 跑通
+
+### Milestone 4：closed loop（半週）
+- weekly_review workflow 部署
+- 第一份 arcrun-roadmap block 產出
+- leo 收到第一份週報
+
+### Milestone 5：rename + cleanup（1 週）
+- u6u-mcp → arcrun-mcp 公開
+- 舊 tool 加 deprecation warning
+- AGENTS.md 同步 KBDB
+
+---
+
+## 8. 開放決策（待 leo）
+
+| 決策 | 推薦 | 理由 |
+|---|---|---|
+| MCP server URL | `mcp.arcrun.dev`（route 並存 `mcp.finally.click` 90 天） | 品牌統一 |
+| 擴張 u6u-mcp vs 建新 | 擴張 + rename | 不 fork，零移轉痛 |
+| AGENTS.md 位置 | `arcrun/AGENTS.md` + KBDB 自動同步 | 兩面都拿到 |
+| feedback 是否要 auth | 要（驗 ak_ 存在即可，不查餘額） | 防 spam |
+| LI 是否包含 KBDB MCP | 部分（abstracted），KBDB MCP 另立 SDD | 範圍清楚 |
+| Telemetry 保留多久 | 90 天 hot + 1 年 cold archive | 平衡 cost 與 review |
+
+---
+
+## 9. 跨 SDD 連動
+
+| 其他 SDD | 連動點 |
+|---|---|
+| `credential-primitives-wasm` | LI 不重做 auth，只用 `auth_static_key` 等既有零件 |
+| `recipe-system` | LI 暴露 recipe CRUD tool 對應 |
+| `component-registry-canon` | LI `list_components` / `get_contract` 走 registry |
+| `resumable-workflow` | LI `list_paused_executions` / `resume` 用 |
+| `u6u-platform-evolution` | LI 是 evolution 之一，未來分 user-tier 時要考慮 |
+| **mira-app** (polaris/mira) | LI 是 mira dogfood 痛點轉化的產物，roadmap 含對 mira 的回饋 |