chore: 安裝契約 — scripts/install.sh + .dev.vars 整合測試慣例

KBDB_BASE_URL 由安裝時的 AI 自動填（查 CF subdomain 拼基本盤 URL），不寫死 toml、不叫人填。
- scripts/install.sh：whoami → 查 subdomain → wrangler secret put → wrangler deploy
- .dev.vars.example：整合測試本地基本盤慣例（.dev.vars 已 gitignore）

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

.dev.vars.example

@@ -0,0 +1,4 @@
+# 整合測試用 — 複製成 .dev.vars（已 gitignore，不進版控）。
+# 先在另一個終端起本地基本盤：cd ../arcrun/kbdb && wrangler dev
+# 單元測試（tests/*.test.ts 走 mock-client）不需要這個。
+KBDB_BASE_URL=http://localhost:8787

CLAUDE.md

@@ -87,3 +87,32 @@ src/
 - **部署**: wrangler 直推 Cloudflare，**不開 Actions**（避免再被 flag，見頂層鐵律）
 
 > 2026-06-14：按 leo 鐵律改寫完成。21 個違規直接 SQL action 全改走基本盤 API；刪除所有 migrations（插件零建表）；移除 D1/Vectorize/AI 綁定。基本盤規範歸 `arcrun/kbdb`。
+
+---
+
+## 安裝與 KBDB_BASE_URL（安裝契約，leo 2026-06-14）
+
+**KBDB_BASE_URL 由「安裝時的 AI」自動填，不是人填。** `wrangler.toml` 留 `""`，因為它因部署而異（每個 self-hosted 用戶的 workers.dev subdomain 不同）。值不寫死、不叫人填、不放 .env。
+
+### URL 是確定性的，AI 必然查得到
+- URL = `https://arcrun-kbdb.<subdomain>.workers.dev`
+- `arcrun-kbdb` 固定（基本盤 worker name）；`<subdomain>` 用 CF API `GET /accounts/{id}/workers/subdomain` 查（用戶已登入 wrangler → 查得到）。
+- **「能 deploy 就能查 URL」**：deploy 與查 subdomain 用同一套 CF 憑證，不存在「能裝卻查不到」。
+- 一律連 workers.dev（預設），**不要求用戶自訂域名**（自訂是進階選項，非安裝必填 → 安裝時不問人）。
+
+### 安裝流程（`scripts/install.sh`，AI 照跑；參考 arcrun `docs/3-specs/arcrun/sdk-and-website/self-hosted-init.md`）
+用戶給 github 網址 → AI：
+1. `wrangler whoami` → account_id（已登入用戶 CF）
+2. `GET /accounts/{id}/workers/subdomain` → 拼基本盤 URL
+3. `wrangler secret put KBDB_BASE_URL`（部署）— 不寫進 git
+4. `wrangler deploy` 插件
+→ **用戶全程零填寫、零 toml、零 .env**。
+
+## 測試的 base URL（兩層，分開放）
+
+| 測試 | base URL | 放哪 |
+|---|---|---|
+| **單元測試** `tests/*.test.ts` | 不需（走 `tests/mock-client.ts`，不打網路） | KBDB_BASE_URL 留空照跑。日常主力。 |
+| **整合測試**（驗證打通基本盤） | 本地起基本盤：`cd ../arcrun/kbdb && wrangler dev`（如 `http://localhost:8787`） | `.dev.vars`（gitignore，**不進版控**）寫 `KBDB_BASE_URL=http://localhost:8787` |
+
+**為何不用 .env**：這是 CF Worker，wrangler 本地讀 `.dev.vars` 不是 `.env`。本地測試值→`.dev.vars`；部署→`wrangler secret`；toml 只留空占位。三者各司其職。

docs/3-specs/plugin-install/design.md

@@ -0,0 +1,50 @@
+# KBDB-graph 插件安裝 — Design
+
+## 目標
+
+用戶給一個 github 網址，AI 就能把 KBDB-graph 插件裝到用戶自己的 CF 帳號，**全程零填寫**。
+類比：像裝 Postgres 的 AGE 擴充——掛在已有的基本盤（arcrun/kbdb）上。
+
+## 核心原則：KBDB_BASE_URL 由 AI 自動填，不是人填
+
+| 反例（不要） | 正解 |
+|---|---|
+| 叫人填 wrangler.toml | toml 留 `""`，AI 安裝時填 |
+| 叫人填 .env | 不用 .env；部署用 `wrangler secret`，本地測試用 `.dev.vars` |
+| 叫人去查自己 worker URL | AI 用 CF API 自動查 subdomain 拼出來 |
+
+## URL 確定性論證（為何 AI 必然查得到）
+
+- URL = `https://arcrun-kbdb.<subdomain>.workers.dev`
+  - `arcrun-kbdb`：基本盤 worker name，固定。
+  - `<subdomain>`：用戶 CF 帳號的 workers.dev 子域，`GET /accounts/{id}/workers/subdomain` 查得到。
+- **能 deploy ⟹ 能查 URL**：兩者用同一套 CF 憑證（wrangler 登入）。AI 要 deploy 插件就必然已能操作用戶 CF，故必然查得到 subdomain。不存在「能裝卻查不到」。
+- 預設 workers.dev，不要求自訂域名 → 安裝時**不問人**。自訂域名是進階選項，另走 config。
+
+## 安裝流程（`scripts/install.sh`）
+
+```
+輸入：github 網址（用戶提供）
+前提：用戶已 wrangler login（自己的 CF 帳號）
+
+1. git clone <插件網址>
+2. wrangler whoami                                  → account_id
+3. GET /accounts/{account_id}/workers/subdomain     → subdomain
+4. BASE = https://arcrun-kbdb.<subdomain>.workers.dev
+   （或：若基本盤這次一起裝，直接取其 wrangler deploy 輸出的 URL）
+5. wrangler secret put KBDB_BASE_URL  ← 填 BASE（不寫進 git）
+6. wrangler deploy                                  → 插件上線
+輸出：插件 workers.dev URL（AI 回報給用戶）
+```
+
+參考既有實作：arcrun `docs/3-specs/arcrun/sdk-and-website/self-hosted-init.md`（同套路：CF API 查 subdomain + 注入 config + workers_dev 對外）。
+
+## 測試 base URL（兩層）
+
+- **單元測試**：`tests/mock-client.ts`，不打網路，KBDB_BASE_URL 留空。日常主力。
+- **整合測試**：本地起基本盤 `cd ../arcrun/kbdb && wrangler dev`（如 localhost:8787），插件 `.dev.vars`（gitignore）寫 `KBDB_BASE_URL=http://localhost:8787`。
+
+## 不變條件（守 KBDB 鐵律）
+
+- 安裝過程**不建表、不跑 migration**（插件零 migration）。基本盤的表由 arcrun/kbdb 維護。
+- 插件只透過 `KBDB_BASE_URL` 的 HTTP API 與基本盤互動，安裝後亦然。

scripts/install.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# KBDB-graph 插件安裝器 — AI 照著跑，用戶零填寫。
+#
+# 設計（leo 2026-06-14，比照 arcrun self-hosted-init）：
+#   KBDB_BASE_URL 是插件對外唯一通道，因部署而異（每個 self-hosted 用戶 subdomain 不同），
+#   所以【不寫死 toml、不叫人填】。URL 是確定性的：能 deploy 就能查 subdomain（同一套 CF 憑證）。
+#
+# 流程：whoami → 查 subdomain → 拼基本盤 URL → wrangler secret put → wrangler deploy。
+#   - 基本盤一律連 workers.dev 預設域名：https://arcrun-kbdb.<subdomain>.workers.dev
+#   - 部署繞開 GitHub（wrangler 直推），不開 Actions（避免再被 flag）。
+#
+# 用法：bash scripts/install.sh
+#   選用環境變數：
+#     KBDB_BASE_URL  — 直接指定基本盤網址（跳過自動推算，例如自訂域名）
+#     BASE_WORKER    — 基本盤 worker 名（預設 arcrun-kbdb）
+
+set -euo pipefail
+
+BASE_WORKER="${BASE_WORKER:-arcrun-kbdb}"
+
+command -v wrangler >/dev/null 2>&1 || { echo "✗ 需先安裝 wrangler（Cloudflare CLI）"; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "✗ 需先安裝 jq"; exit 1; }
+
+# 1. 確認已登入 wrangler
+echo "▸ 確認 Cloudflare 登入..."
+wrangler whoami >/dev/null 2>&1 || { echo "✗ 未登入，請先 'wrangler login'"; exit 1; }
+
+# 2. 算出基本盤 URL（除非已由環境變數指定）
+if [ -z "${KBDB_BASE_URL:-}" ]; then
+  echo "▸ 查 workers.dev subdomain..."
+  # wrangler 內部 API 可查 subdomain；用 `wrangler subdomain` 或 CF API 皆可。
+  # 這裡用最穩的：部署後讀回 URL。先嘗試從 whoami/CF API 取 subdomain。
+  SUBDOMAIN="$(wrangler subdomain 2>/dev/null | grep -oE '[a-z0-9-]+\.workers\.dev' | sed 's/\.workers\.dev//' | head -1 || true)"
+  if [ -z "$SUBDOMAIN" ]; then
+    echo "✗ 無法自動取得 subdomain。請改用：KBDB_BASE_URL=https://${BASE_WORKER}.<你的subdomain>.workers.dev bash scripts/install.sh"
+    exit 1
+  fi
+  KBDB_BASE_URL="https://${BASE_WORKER}.${SUBDOMAIN}.workers.dev"
+fi
+echo "▸ 基本盤 URL = ${KBDB_BASE_URL}"
+
+# 3. 注入為 secret（不寫進 git；toml 只留空占位）
+echo "▸ 設定 KBDB_BASE_URL secret..."
+printf '%s' "$KBDB_BASE_URL" | wrangler secret put KBDB_BASE_URL
+
+# 4. 部署插件（wrangler 直推，不開 Actions）
+echo "▸ 部署 kbdb-graph-plugin..."
+wrangler deploy
+
+echo "✓ 完成。/health 應回 base_url_set:true"