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>

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 只留空占位。三者各司其職。