From 3c9d5c9cb3418b69060487a8d561c5c6b2ded0dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=94=A1=E5=8F=8A?= <522caiji@gmail.com>
Date: Fri, 28 Aug 2026 22:31:38 +0800
Subject: [PATCH] docs: record worktree merge and frontend sync gotchas

Leave the notes agents actually missed this cycle: sync embedded console
assets, merge via GitHub when main is in another worktree, and keep the
add-account wizard from flattening login back onto step one.
---
 AGENTS.md           | 2 ++
 CONTRIBUTING.md     | 4 ++++
 docs/DESIGN.md      | 2 +-
 docs/DEVELOPMENT.md | 8 ++++++++
 4 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a11253fb..a4c238ec 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,6 +16,8 @@ Do not add new `TODO.md`, `NOTES.md`, or extra plan files. The only extra design
 ## Do
 
 - Pull latest `main` and merge it into the current branch before starting any feature work (skip only when already on up-to-date `main`)
+- After console UI changes, run `cd frontend && npm run sync` so `internal/webui/static` matches `frontend/dist`. Do not commit a stale hashed JS/CSS pair.
+- When `main` is checked out in another worktree, merge PRs with `gh api` / GitHub; do not `git checkout main` here.
 - Keep architecture: auth / endpoint / executor / translate / api
 - Prefer direct HTTP/SSE to Qoder cloud APIs
 - Pin qodercli / qoderclicn hooks in `worker/src/compat.mjs`; fail loudly on mismatch. Qoder CN is `provider=qoder` + `region=cn`, not a new family
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 259c3b74..0c05a06c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,6 +28,10 @@ After frontend changes:
 cd frontend && npm run sync
 ```
 
+`npm run build` only writes `frontend/dist`. Go embeds `internal/webui/static`, so a console change is not in the binary until `sync` runs. Commit the new hashed JS/CSS and `index.html` together; do not leave an old `index-*.js` next to a new `index.html`.
+
+This repo often has `main` checked out in another worktree. Merge from GitHub (`gh pr merge` / the pulls API) instead of `git checkout main` in a busy worktree.
+
 ## Static assets & favicon suite
 
 The favicon set and OG social card live in `frontend/public/`. After editing them:
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index ca742d23..d0ae573b 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -123,7 +123,7 @@
 - 圆角 8px 或更小，除非现有组件已用更大值
 - 账号/资源列表卡片优先使用浅边框和平面表面，不强制最小高度，不额外叠加强阴影
 - 账号卡片保持操作台密度：单行身份（名称可直接改 + provider/auth/UID），状态 Chip 只出现一次，运行状态用 12 格短柱、额度用 `scaleX` 填充条；并发和优先级可在卡片上改，重启次数仍是只读辅助数字
-- 添加账号是两步向导：第一步选类型、名称和可选高级选项，第二步再选登录方式。类型 ≤ 6 用两列 tile，超过则用下拉；未知 provider 直接用后端 descriptor 的 label，不要静默丢掉
+- 添加账号是两步向导：第一步选类型、名称和可选高级选项，第二步再选登录方式。不要把登录方式再摊回第一步。类型 ≤ 6 用两列 tile，超过则用下拉；未知 provider 直接用后端 descriptor 的 label，不要静默丢掉。登录方式按 `capabilities` 隐藏，只有一种时不要再渲染选择器。
 - 账号网格用 `lg:grid-cols-2 xl:grid-cols-3`，卡片间距 `gap-2.5`，内边距约 12px
 - 主卡片只有在确实需要抬升层级时才用 `shadow-card`
 - 边框克制使用；避免边框 + 阴影 + 有色背景同时出现
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 5603f3b3..2e3dd99a 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -35,6 +35,8 @@ cd frontend
 npm run sync
 ```
 
+`vite build` writes `frontend/dist`. The Go binary embeds `internal/webui/static`. Shipping a console change without `sync` leaves the previous hashed bundle in the image. Commit the new `index-*.js` / `index-*.css` and `index.html` in the same change; Git will show the old hashed files as deletions.
+
 Build and start the container from source:
 
 ```bash
@@ -71,6 +73,12 @@ Freeze by PR, not by re-running the release workflow:
 3. Open a `docs: freeze changelog for v0.x.y` PR. If `CHANGELOG.md` conflicts, keep post-tag features in Unreleased.
 4. Merge the PR. Do not run `release.yml` again to fix the freeze — a second run would mint the next patch.
 
+If this checkout cannot switch to `main` because another worktree already has it, merge with the GitHub API instead of `git checkout main`:
+
+```bash
+gh api -X PUT repos/caigee-cmd/cli2api/pulls/<n>/merge -f merge_method=merge
+```
+
 Expected artifacts for a published tag:
 
 | Kind | Names |