07 環境建置

每一步只指向既有腳本或 skill，不重寫細節。Orca 為可選：沒有 Orca 時流程中「建 worktree」改用原生 git worktree add，但要知道 /issue-queue 與結案腳本看不到沒有 Orca 連結的 worktree（見 03）。

1. Skills

git clone https://github.com/ron03wlb/ron-skills ~/code/ron-skills
~/code/ron-skills/bin/sync-skills          # 同步到 ~/.claude/skills/
npx skills add tt-a1i/archify -g           # 產圖用，可選

專案層 skill（/issue-queue 等）隨 repo 一起 clone，不用另裝。

2. git hooks

在 repo 根目錄：

bash scripts/install-pre-push-hook.sh           # pre-push → check-before-push.sh
bash scripts/install-integration-guard-hook.sh  # reference-transaction → 守護整合分支

推送權限已寫在 repo 的 .claude/settings.json：放行 bash scripts/push-pinned.sh feature/ron/*，agent 可以自己推整合分支。換人使用、整合分支前綴不同時，這條規則要由人改（agent 不能編輯 settings）。

3. Docker Desktop

關閉 Resource Saver（Settings → Resources → Advanced）。
測試一律 bash scripts/run-docker-tests.sh <gradle args>；引擎凍住時先 bash scripts/docker-ensure.sh。
不要從 cmd.exe start 啟動 Docker，它會綁在那個終端 pane 上；docker-ensure.sh 已處理。

4. Orca（可選）

安裝 Orca 後在它的終端裡 ORCA_CLI_COMMAND 會自動設定；流程腳本只認這個變數。
可用性檢查看 ORCA_CLI_COMMAND，不要用 which orca（那是 GNOME 螢幕閱讀器）。
/issue-pilot 靠 Orca 終端派 worker 與交棒，沒有 Orca 只能用 /issue-run。
沒有 Orca：git worktree add ../feature-<you>-issue-<n> -b <you>/feature-<you>-issue-<n> <integration>，並接受看板與結案腳本不會自動處理它。

5. GitLab 登入

腳本透過 glab 讀寫；先 glab auth login 指向自建 GitLab（token 由 glab 保存，不寫進 repo 或文件）。
需要時用 GLAB_BIN 指定 glab 執行檔。

6. 產圖（只有要改本資料夾的圖才需要）

finalize 需要 Chrome／Chromium：export ARCHIFY_CHROME=<chrome 路徑>（例如 Playwright 快取裡的 chromium-*/chrome-linux/chrome）。
WSL 預設沒有中文字型，截圖時 SVG 內中文會變方框。不需要 sudo 的做法：把 Windows 的 NotoSansTC-VF.ttf 複製到 ~/.local/share/fonts/，在 ~/.config/fontconfig/fonts.conf 把 monospace、sans-serif、JetBrains Mono 的 fallback 加上 Noto Sans TC，再 fc-cache -f。

7. 發布流程導讀站到 Cloudflare Pages

公開網址：<https://spay2-workflow-docs.pages.dev/>。平常不用手動發布：Issue 分支動到 docs/workflow/ 時，close-issue.mjs 在 push 之後自動執行 publish-workflow-site.py --publish --skip-if-current（公開版已是最新就回 current 不重新部署），報告路徑附進結案留言；失敗停在 publish FAILED，修好授權或內容後重跑「結案」即可。以下是第一次建置與手動發布的做法。發布的是 docs/workflow 整個資料夾的公開副本（導讀站、互動圖、Markdown 原文），指向 repo 其他位置的連結（AGENTS.md、docs/agents/ 等）在公開版會停用為「公開版本未提供」。

Pages 專案 spay2-workflow-docs 由 Operator 在 Cloudflare 建一次（production branch main）；腳本只更新既有專案，不代建、不改設定。
授權與 GitLab（glab）無關，兩者各自登入。來源依序：shell 的 CLOUDFLARE_API_TOKEN → token 檔 ~/.config/spay2/cloudflare-token → npx --yes wrangler@4.145.0 login 留下的 OAuth 設定（會過期）。結案自動發布跑在 agent 的行程裡，讀不到你 shell 的環境變數，所以請用 token 檔：到 Cloudflare 建一個只有 Pages 編輯權限的 API token，存成該檔的唯一一行並 chmod 600（腳本拒絕 group／other 可讀的檔）。只有 Pages 權限的 token 列不出帳號，所以同目錄再放 cloudflare-account-id（唯一一行 32 位 hex，dashboard 任一網域或 Workers & Pages 總覽右側的 Account ID）；手動執行也可改用 --account-id 或 CLOUDFLARE_ACCOUNT_ID。token 只進 Cloudflare API 與 wrangler 子行程，不進報告、不進 repo。
在 repo 根目錄：

python3 -B scripts/publish-workflow-site.py                 # 預設 --prepare-only：重產檢查、機密掃描、打包到 repo 外，不連 Cloudflare
python3 -B scripts/publish-workflow-site.py --publish       # 更新既有專案，並以匿名 GET 逐檔比對部署結果

只想知道公開版是否已是 repo 這份內容：python3 -B scripts/publish-workflow-site.py --check-current（唯讀，不讀授權、不部署；current exit 0，stale exit 3 並附不符檔數）。
發布前腳本會先跑 node scripts/build-workflow-site.mjs --check，site/ 沒重產就停；機密掃描在既有樣式之外還擋私有 IP 與 git remote URL。
和 publish-spay4-docs.py 共用 scripts/lib/cloudflare_pages.py（快照、掃描、授權、專案確認、部署、公開驗證）；兩支腳本各自固定專案名稱與來源目錄。
驗證順序：固定網址逐檔比對通過才算 published，部署後 CDN 逐檔更新要一點時間，所以固定網址最多重試 6 次、每次間隔 20 秒；preview 網址（<hash>.spay2-workflow-docs.pages.dev）在新專案上要等憑證佈建，腳本最多重試 6 次、每次 30 秒，仍失敗只在報告記 previewVerification: pending，不推翻固定網址的結果。
結案流程跑發布時依上面的順序找授權，實際上用的是 token 檔（agent 的行程讀不到你 shell 的 CLOUDFLARE_API_TOKEN）；token 過期或被撤銷時結案會停在 publish FAILED，換新 token 後再結案一次。