diff --git a/.claude/skills/contributing-to-loopover/SKILL.md b/.claude/skills/contributing-to-loopover/SKILL.md
index 304bbf17f2..f1c8cacf51 100644
--- a/.claude/skills/contributing-to-loopover/SKILL.md
+++ b/.claude/skills/contributing-to-loopover/SKILL.md
@@ -215,7 +215,7 @@ Migrations must use the **next free number** (contiguous, no gaps, no reuse) and
 
 ```sh
 git diff --check                          # no trailing whitespace / conflict markers
-npm run test:ci                           # the entire CI gate, in one command (see below)
+npm run test:ci                           # nearly the entire CI gate, in one command (one exception, see below)
 npm audit --audit-level=moderate          # the dependency-review job's local equivalent
 ```
 
@@ -228,6 +228,9 @@ npm audit --audit-level=moderate          # the dependency-review job's local eq
 `command-reference:check`, `ui:lint`, `ui:typecheck`, `ui:test`, `ui:build`. If any step fails, fix it
 and re-run — do not push a red tree. (Full per-check table in `reference.md`; check `package.json`'s
 own `test:ci` script if this list and that script ever disagree — the script is the source of truth.)
+One CI-gating exception `test:ci` does **not** run: the extension lint/typecheck checks
+(`extension:lint`, `extension:typecheck`, `miner-extension:lint`, `miner-extension:typecheck`), gated in
+CI's `validate-code` on `push || ui==true` — run them separately if you touch the VS Code / miner extensions.
 
 If `ui:lint` fails on formatting, run `npm --workspace @loopover/ui run format`. If
 `ui:openapi:check` fails, you forgot Phase 4's `ui:openapi`.
diff --git a/.claude/skills/contributing-to-loopover/reference.md b/.claude/skills/contributing-to-loopover/reference.md
index a370438d1b..3cab16d09c 100644
--- a/.claude/skills/contributing-to-loopover/reference.md
+++ b/.claude/skills/contributing-to-loopover/reference.md
@@ -47,12 +47,20 @@ path filter matched; on push to `main`, everything runs.
 | ui → typecheck | `tsc --noEmit` (UI) | `npm run ui:typecheck` | UI type error |
 | ui → tests | vitest jsdom (UI) | `npm run ui:test` | failing UI component test |
 | ui → build | UI build | `npm run ui:build` | build failure (note: it re-runs `ui:openapi` internally) |
+| ui → extension lint | `eslint` (VS Code + miner extensions) | `npm run extension:lint && npm run miner-extension:lint` | extension ESLint error (same `push \|\| ui==true` trigger as the `ui →` rows) |
+| ui → extension typecheck | `tsc --noEmit` (extensions) | `npm run extension:typecheck && npm run miner-extension:typecheck` | extension type error (same `push \|\| ui==true` trigger) |
 | security (PR only) | dependency-review (moderate+) | `npm audit --audit-level=moderate` | a **newly added** dep has a moderate+ advisory |
 
-**One command for everything except `security`:** `npm run test:ci`. There is **no** CodeQL/Analyze
+**One command for *almost* everything except `security`:** `npm run test:ci`. There is **no** CodeQL/Analyze
 workflow in this repo. There is **no** root-level Prettier gate — Prettier is enforced only inside
 `ui:lint` (so it only bites `apps/loopover-ui/**`).
 
+**One CI-gating exception `test:ci` does NOT cover:** the four extension lint/typecheck checks
+(`extension:lint`, `extension:typecheck`, `miner-extension:lint`, `miner-extension:typecheck`) run in CI's
+`validate-code` job (gated on `push || ui==true`, the `ui →` rows above) but are **absent from the `test:ci`
+chain** — so a green local `test:ci` does not exercise them. Run them separately (or rely on CI) if your
+change touches `apps/loopover-extension/**` or `apps/loopover-miner-extension/**`.
+
 **Local-only checks with no separate named CI status — `npm run test:ci` is the only thing that catches
 these for a normal PR:**