Merge branch 'main' into hotfix/fix-terminal-commit-click-upstream

Author: qianxunslimg

.claude/skills/add-icon/SKILL.md

@@ -43,9 +43,17 @@ pnpm run icons:svgo        # Optimize SVGs
 pnpm run build:icons       # Generate font (runs svgo + fantasticon + apply + export)
 ```
 
-### 4. Update Font References
+### 4. Verify Font Cache-Busting
 
-Copy the new `glicons.woff2?{hash}` URL from `src/webviews/apps/shared/glicons.scss` and search-replace the old URL across the codebase.
+`pnpm run build:icons` (via `scripts/applyIconsContribution.mjs`) now automatically propagates the new `glicons.woff2?{hash}` cache-bust hash into **both** `src/webviews/apps/shared/glicons.scss` **and** every per-app webview `*.html` file (each declares its own `@font-face`). No manual search-replace needed.
+
+Verify they're all unified (every reference must be the same hash):
+
+```bash
+grep -rho "glicons.woff2?[a-f0-9]*" src/ dist/ | sort | uniq -c
+```
+
+If any HTML file lags behind, re-run `pnpm run build:icons` — a stale hash leaves that webview pointing at a cached font without the new glyph.
 
 ### 5. Use the Icon
 

.claude/skills/live-inspect/SKILL.md

@@ -34,6 +34,12 @@ The server is auto-discovered via `.mcp.json` when Claude Code starts in this re
 | `resize_window`       | Resize VS Code window content area — only for explicit responsive-breakpoint testing |
 | `rebuild_and_reload`  | Build extension + restart extension host                                             |
 
+### Reading host logs (gotchas)
+
+- **`read_logs` uses `pattern`, NOT `filter`.** A wrong/unknown arg is silently ignored and it falls back to `pattern: "GitLens"` — so you only ever see the activation banner and wrongly conclude "no logs". Always: `read_logs({ pattern: "<tag>", last_n })`.
+- `read_logs` DOES capture extension-**host** `console.log/warn/error` and GitLens `Logger.warn`/`info`/`error` (info+). It reads the GitLens **LogOutputChannel**, also on disk at `.vscode-test/user-data/logs/<TS>/window1/exthost/eamodio.gitlens/GitLens.log`. `read_console` is webview-only (does not see host logs).
+- **`@debug`/`@trace` decorator logs are filtered out.** The channel defaults to `info`; GitLens' rich tracing is `debug`/`trace`. Console-mirroring (`Logger.isDebugging`) is gated on `ExtensionMode.Development`, but the inspector runs in **Test** mode → off. `gitlens.enableDebugLogging` (which runs `workbench.action.output.activeOutputLogLevel.debug`) does NOT take headless. So for ad-hoc host tracing, **instrument with `Logger.warn('[tag] …')`** (info+, always written) and read via `read_logs({ pattern: "[tag]" })`. `gitlens.outputLevel` is deprecated — don't rely on it.
+
 ### Typical Workflow
 
 1. Call `launch` (once per session — takes ~10s)

.claude/skills/worktree/SKILL.md

@@ -5,7 +5,14 @@ description: Use when starting feature work that needs isolation from current wo
 
 # GitLens Worktree Creation
 
-This project uses a custom worktree convention. The `WorktreeCreate` and `WorktreeRemove` hooks in `.claude/settings.json` handle automatic worktree creation. This skill documents the conventions for manual worktree operations.
+This project uses a custom worktree convention: worktrees live in a sibling `<repo-name>.worktrees/` directory (the layout the `worktree.mts` hook in `.claude/settings.json` is built around), **not** in the `EnterWorktree` default location.
+
+Because of that, the flow has two steps:
+
+1. **Create** the worktree with `git worktree add` following the convention below (so it lands in the sibling `.worktrees/` dir with the right name).
+2. **Switch into it** by calling the built-in `EnterWorktree` primitive with `path`. This moves the session's working directory into the worktree — a plain `cd` in Bash does not.
+
+> **Do not** call `EnterWorktree` with `name` to create the worktree. Inside a git repo it ignores the hook and places the worktree in `.claude/worktrees/` (which is not gitignored) on a branch off `origin/main`, breaking this project's convention. Always create first, then enter by `path`.
 
 ## Directory Convention
 
@@ -40,30 +47,46 @@ Follow the conventions in AGENTS.md:
 | Tech debt  | `debt/`      | `debt/library`                          |
 | With issue | include `#N` | `feature/#1234-search-natural-language` |
 
-## Manual Worktree Creation
-
-When creating a worktree manually (not via the hook):
+## Creating and Entering a Worktree
 
 ```bash
 # 1. Find the worktrees root
 REPO_ROOT=$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')
 REPO_NAME=$(basename "$REPO_ROOT")
 WORKTREES_ROOT="$REPO_ROOT/../$REPO_NAME.worktrees"
 
-# 2. Create the worktree
+# 2. Create the worktree (branch path segments map to directory nesting)
 git worktree add "$WORKTREES_ROOT/<type>/<name>" -b "<type>/<name>"
 
-# 3. Install dependencies (automatic when using the hook)
-cd "$WORKTREES_ROOT/<type>/<name>"
-pnpm install
+# 3. Install dependencies
+pnpm install --dir "$WORKTREES_ROOT/<type>/<name>"
+```
+
+Then switch the session into it with the **`EnterWorktree`** primitive, passing the path you just created:
+
+```
+EnterWorktree({ path: "<absolute path to $WORKTREES_ROOT/<type>/<name>>" })
 ```
 
-## Setup After Creation
+`EnterWorktree` requires an absolute path that already appears in `git worktree list` — which is why creation comes first. After this, all subsequent tool calls run inside the worktree.
+
+## Leaving a Worktree
+
+When the work is done (or you need to return to the original repo), call **`ExitWorktree`**:
+
+```
+ExitWorktree({ action: "keep" })
+```
+
+Use `action: "keep"` — `ExitWorktree` will **not** remove a worktree that was entered by `path` (only ones it created via `name`), so `keep` is the correct, non-destructive choice here. The worktree and its branch stay on disk; remove them later with `git worktree remove` if needed.
+
+## Setup Notes
 
-The `WorktreeCreate` hook automatically runs `pnpm install` in the new worktree. No manual setup is needed. Skip test baseline verification — builds are expensive in this project; verify after implementation instead.
+- Skip test baseline verification — builds are expensive in this project; verify after implementation instead.
 
 ## Key Differences from Default Superpowers Skill
 
 - Worktrees are **outside** the repo (sibling `.worktrees/` directory), not inside
 - No `.gitignore` verification needed — the directory is outside the repo
+- Create with `git worktree add` first, then enter via `EnterWorktree({ path })` — never create with `EnterWorktree({ name })` (it bypasses the convention)
 - Skip test baseline (build is too slow for setup)

.gitignore

@@ -1,3 +1,5 @@
+.agents
+.claude/plans/**
 !.claude/settings.json
 .claude/settings.local.json
 .claude/scheduled_tasks.lock
@@ -25,3 +27,6 @@ tsconfig*.tsbuildinfo
 *.code-workspace
 localdev*.instructions.md
 *.log
+
+# Build codegen skip-cache (input fingerprints for Docs/contributions/CEM generators)
+.codegen-cache/