docs: add CLAUDE.md — project instructions for Claude Code

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

CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 倉庫性質
+
+這是**純文件倉庫**（Markdown only），記錄 `192.168.42.127` 上 NetBird Self-Hosted 的部署、設定與營運經驗。沒有原始碼、沒有 build/test/lint 流程。實際的可執行設定檔（`docker-compose.yml`、`Caddyfile`、`config.yaml`、`dashboard.env`）住在**遠端主機** `192.168.42.127:/opt/netbird/`，本倉庫描述它們的內容與背後決策。
+
+修改文件時的工作流程：
+1. 在本機編輯 Markdown
+2. 任何需要驗證的步驟透過 `ssh root@192.168.42.127` 在遠端跑
+3. `git diff` / `git log` 看歷史；`git commit` 走一般流程
+
+## 部署上下文（寫文件時必須記住）
+
+- **IP-only / HTTP-only**：無域名、無 TLS，僅供內網使用。所有 issuer / endpoint 都是 `http://192.168.42.127`
+- **Proxmox 非特權 LXC**：必須用 `crun`（不是 `runc`），原因是 `/proc/sys` 唯讀
+- **STUN port 是 `3479/udp`**（非標準），因為 `3478` 被同主機的 Headscale 佔用
+- **內建 IdP**：使用 NetBird Server 內建 Dex，不接外部 OIDC
+- **Dashboard 是 Next.js SSG**：`/nb-auth` 與 `/nb-silent-auth` 路徑在新版 image 不存在，Caddy 用 rewrite 把這兩個 path 改寫到 `/` 讓 client router 接手；`config.yaml` 的 `dashboardRedirectURIs` 仍保留完整 URI（OIDC 嚴格比對）
+
+## 文件之間的關係（big picture）
+
+文件**不是平行**的，有明確分層：
+
+```
+README.md / QUICKSTART.md            ← 入口、抄走能跑
+SUMMARY.md                            ← 部署決策與疑難排解總表
+netbird-selfhosted-setup.md          ← 完整原理說明（QUICKSTART 的詳解版）
+
+# 主題拆檔（在 README 表格中編目）：
+npm-grpc-fix.md                      ← NPM 對外時的 gRPC 修復
+setup-keys-and-pat.md                ← Setup Key / PAT；setup_keys.name 改 store.db 的繞道
+stun-port-conflict.md                ← STUN 3478 → 3479 的原因
+client-troubleshooting.md            ← Force Relay / bufferbloat
+peer-deployment-ops.md               ← LXC Docker 部署 client、Tailscale iptables 衝突、daemon 重啟
+groups-and-policies.md               ← Groups + Access Control Policies
+network-routes.md                    ← Subnet Router (home-lan) + Exit Nodes (exit-ct100, exit-virmach-lax)
+ssh-access.md                        ← 一般 SSH vs NetBird 內建 SSH 的混淆
+```
+
+新增主題時：建獨立檔，更新 `README.md` 的表格與 `SUMMARY.md` 的疑難排解列。**不要**把細節塞回 README/SUMMARY。
+
+## 寫作慣例（閱讀現有文件可見的模式）
+
+- **語言**：繁體中文，台灣用語；技術名詞、CLI 指令、路徑、欄位名保留英文
+- **症狀 / 根因 / 解法**：疑難排解段固定走這三段；引言塊放實際 log 文字而不是改寫
+- **API 範例**：用 `curl` + `jq`，token 一律寫成 `TOKEN=<你的 PAT>` 變數，目標寫成 `https://netbird.timmy.us.kg/api/...`（從外部對外的網址，不是 `192.168.42.127`）
+- **本部署實例**：以「本部署的實例（YYYY-MM-DD）」段落記錄真實事件，便於日後回溯
+- **配置檔片段**：用 `cat > /opt/netbird/<file> << 'EOF'` 包起來，讓讀者能直接抄
+- **跨檔交叉引用**：用 markdown link 指到同目錄的 `.md`（例：`見 [npm-grpc-fix.md](./npm-grpc-fix.md)`）
+
+## 既有的角色 / 命名（出現在多份文件，新文件要對齊）
+
+- **Peers**：`mbp-13-pro`、`iphone-15-pro`、`CT100`（jump box / routing peer）、`CT101`、`CT124`、`virmach-lax`
+- **Groups**：`servers`（CT100、CT101）、`personal`（mbp、iphone）、預設 `All`（保留但 Default policy 已停用）
+- **Routes**：`home-lan`（CIDR `192.168.42.0/24`，via CT100）、`exit-ct100`、`exit-virmach-lax`（兩條 `0.0.0.0/0`）
+- **Tailscale 衝突**：CT100 是 userspace，CT124 是 kernel-mode（會踩 `iptables-legacy ts-input` 把 `100.64.0.0/10` drop 的雷）
+
+## 提交訊息風格
+
+`git log` 顯示偏好：`docs: <主題> — <一行原因/重點>`，必要時帶具體 case ID 或受影響的 peer 名稱（例：`docs: NetBird management DNS flap leaves daemon stuck (CT124 case)`）。