tapcard-mcp: Instructions file for Codex

AGENTS.md — TapCard MCP 部署引導（跨 CLI）

你是導遊不是裁判：每一關綠燈由機械驗證判定。同一步驟失敗 3 次即停，記錄卡點。使用者確認不超過 3 次。 自主修復邊界照 spec v0.3.0 的 AGT-1/2/3：可補裝缺漏開發依賴、生成型別、對傳播期暫態重試，但每次修復必須記入報告；不得改服務邏輯、放寬驗收或跳過閘門。

本專案為 SmallGreen Path A（原生採用）：契約三檔與本引導隨程式碼同 repo，無 adapter 層。

前置

依 .smallgreen/profile.yaml 的 build_requirements：

• node 20+、npm；CLOUDFLARE_API_TOKEN＋CLOUDFLARE_ACCOUNT_ID（Workers＋D1＋R2＋KV Edit 權限）
• 帳號需已啟用 R2（未啟用時建 bucket 會 error 10042，僅 dashboard 可開）
• 閘門指令（乾淨環境須全數 exit 0，CON-8）：npx wrangler types → npm run typecheck → npm test。順序不可調換——typecheck 依賴 wrangler types 生成的 worker-configuration.d.ts（生成物不入庫）

步驟

1. 說明與同意（確認 1）

讀 .smallgreen/profile.yaml 向使用者說明：這是自架的 NFC／QR 電子名片＋私人名片庫。公開面只有 /p/:slug（個人簡介、contact.json、vCard、QR）；私人面（收到的名片、縮圖、MCP）全部需要 token。所有資料存在自己帳號的 D1／R2／KV，無第三方後端、無遙測。NFC 卡只寫入穩定網址，資料更新不必重寫卡片。

2. 組裝

git clone <本 repo> tapcard-mcp && cd tapcard-mcp
npm install

wrangler.jsonc 隨 repo 提供零值佔位版（SAP-1 需要可靜態判定的資源宣告）；下一步填入真實 ID。填完建議 git update-index --skip-worktree wrangler.jsonc。

3. 建立 Cloudflare 資源並填 ID

npx wrangler d1 create tapcard-mcp
npx wrangler r2 bucket create tapcard-mcp-assets
npx wrangler kv namespace create CARD_KEYS

把 D1 database_id 與 KV id 填入 wrangler.jsonc，並設定 vars 的 PUBLIC_BASE_URL（部署後的 URL）。

4. 閘門、migration 與部署（確認 2）

npx wrangler types && npm run typecheck && npm test    # CON-8 閘門，順序固定
npx wrangler d1 migrations apply tapcard-mcp --remote  # 三個 migration：contacts／FTS／public_profiles
npx wrangler deploy
printf "%s" "<32+ 字元亂數>" | npx wrangler secret put ADMIN_TOKEN

部署後約 60 秒內可能遇到 1042 傳播期暫態（GET 已通但 POST 尚未），重試即可——這屬 AGT-1 允許的 transient-retry，記入報告即可。

5. 建立公開簡介並驗收（確認 3）

先用 ADMIN_TOKEN 建立自己的公開簡介（slug 規則：小寫英數與連字號，開頭結尾須為英數）：

curl -X PUT "<URL>/api/profile" -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" -d '{"slug":"me","name":"你的名字","headline":"一句話簡介"}'

欄位以 src/core/profile.ts 的 PublicProfileSchema 為準（.strict()——多送未定義欄位會 400）：必填 slug＋name，其餘如 headline／bio／org／title／emails／phones／links／public_fields 為選填。不是 display_name（A-01 run 實測：送 display_name 回 400 Invalid public profile）。