chore: refresh governance notes

Author: linhay

.agents/skills/gettokens-ops-governance/SKILL.md

@@ -12,6 +12,24 @@ This skill unifies the procedural rules for working on GetTokens, ensuring consi
 - **Readiness**: Sidecar `ready` status is required for account data flow. UI mount success does not guarantee data flow.
 - **Verification**: Only claim a fix is live after verifying it in the actual desktop app window, not just the browser.
 
+### 1.1 Browser Preview & Screenshot Loop
+- **When to use**:
+  - The page is a Wails surface, but most layout or interaction acceptance can be checked in a browser.
+  - The page depends on runtime bindings, yet you still need stable screenshots or quick iteration without a live desktop shell.
+- **Default pattern**:
+  1. Add an explicit preview entry such as `?preview=<page-key>` or a dedicated frame hash.
+  2. In preview mode, avoid hard dependency on `window.go.main.App`; provide stable preview data instead of crashing.
+  3. If the page still needs “real-ish” local data in browser dev, add a dev-only HTTP bridge in `vite.config.js` rather than faking Wails runtime globally.
+  4. Add a focused browser check script under `docs-linhay/scripts/` that opens the preview URL and writes deterministic screenshots into the matching `space`.
+- **Acceptance rule**:
+  - Browser screenshots are valid for layout/density review only after preview mode and fallback data are explicit and reproducible.
+  - If runtime bindings, sidecar readiness, or desktop-only capabilities are part of the requirement, browser acceptance does not replace the real Wails check.
+- **Cache rule**:
+  - For external status/data pages, prefer a small local cache plus a visible “live / cache / preview” source label, so repeated page entry does not look like a full refetch every time.
+- **Screenshot hygiene**:
+  - Keep the screenshot script near docs, not inside ad-hoc shell history.
+  - Reuse one stable output path per acceptance baseline instead of scattering `final/latest/temp` files.
+
 ## 2. Space Governance (`docs-linhay/spaces/`)
 - **Structure**: Each space must have `README.md`, `plans/`, `screenshots/`, and `debate/`.
 - **Naming**: Use English slugs. Prefer `YYYYMMDD-<topic>` for short tasks or stable feature names for milestones.
@@ -26,6 +44,14 @@ This skill unifies the procedural rules for working on GetTokens, ensuring consi
 - **Memory**: Keep entries concise and decision-oriented. Run `qmd update` and `qmd embed` after any write-back.
 - **Governance**: Read `AGENTS.md` first. Update it only for repo-wide, durable rules. Ensure `docs-linhay` is not ignored in `.gitignore`.
 
+### 3.1 Cleanup Before Claiming Done
+- If a long implementation session leaves tracked files still drifting after the “main” commit, do not stop at the first commit.
+- Keep reconciling residual tracked diffs that belong to the same rollout until the remaining worktree noise is clearly limited to:
+  - external reference submodules
+  - local research scratch files
+  - user-owned temporary artifacts that are intentionally not versioned
+- If generated screenshots or browser artifacts should not enter git, add or refine ignore rules before claiming cleanup is complete.
+
 ## 4. Subagent Delivery Loop
 - **Trigger**: Use this loop when a requirement will be implemented by delegated agents or when the user explicitly asks for `subagent` delivery.
 - **Controller Role**:

docs-linhay/memory/2026-04-30.md

@@ -201,6 +201,17 @@
 - 本地手工新增 model 仍保留，但只作为账号池目录之外的补充；删除最后一个本地自定义 model 也已允许，只要账号池目录本身仍非空即可。
 - 本轮验证已通过：`go test ./internal/wailsapp -run 'TestFetchOpenAICompatibleProviderModels|TestParseOpenAICompatibleModelsResponseSupportsCodexModelCatalogShape|TestListRelaySupportedModelsAggregatesRemoteLocalAndCodexKeyModels|TestApplyRelayServiceConfigToLocal'`、`go test .`、`node --test frontend/src/features/status/tests/relayModelCatalog.test.mjs frontend/src/features/accounts/tests/accountConfig.test.mjs`、`npm --prefix frontend run typecheck`。
 
+## 一键应用到本地改成保留式写入
+- 已确认旧版 `ApplyRelayServiceConfigToLocal` 会直接覆盖 `~/.codex/auth.json` 和 `~/.codex/config.toml`，会抹掉用户额外配置项，这对真实用户配置不安全。
+- 当前实现已改成 merge 写入：
+  - `config.toml` 走文本级最小补丁，只更新 `model / model_reasoning_effort / openai_base_url / model_provider / [model_providers.<id>]` 这些 GetTokens 负责的键位，尽量保持原有键顺序、无关 section 和注释不动。
+  - `auth.json` 走字段合并，只更新 `auth_mode = apikey` 和 `OPENAI_API_KEY`，保留其他未知字段。
+- 若现有 `auth.json` 不是有效 JSON，当前会直接报错停止，避免把坏文件静默覆盖成新文件。
+- 新增回归测试已覆盖：
+  - 保留现有 root key 顺序和 section
+  - 保留 provider section 里的额外字段
+  - 保留 auth.json 里的既有字段
+
 ## Session Management 浏览器开发态取数修复
 - 已确认 `http://localhost:34115/#frame=session-management` 首屏只有壳没有数据，不是列表组件本身坏掉，而是浏览器开发态取数链路不稳定。
 - 根因分三层：`34115` 当前 origin 不承接 `__dev/session-management/*`；前端最初只回退到错误端口 `4173`；即使回退端口修正后，跨域和首个无效候选请求的无超时等待仍会让页面长期停在“加载中”。

frontend/package.json.md5

@@ -1 +1 @@
-3e559fdda86d7af7141e6460aa0fdf50
+02f45356efd798649b1432564a4ff053