@herbertgao/pi-extensions 2026.8.5 → 2026.8.6

package/node_modules/pi-lens/docs/word-index.md

@@ -42,6 +42,41 @@ HTTPServer    → httpserver, http, server
 each through `splitIdentifier`; queries are tokenized the same way so
 `"authenticate user"` matches `authenticateUser`, `auth_user`, etc.
 
+## Query prefix filters (#1450)
+
+The query string can mix plain terms with composable `key:value` filters,
+parsed by `parseWordIndexQuery` (`clients/word-index.ts`) before tokenization:
+
+- `lang:<kind>` — restrict to a file kind's extensions, drawn from
+  `KIND_EXTENSIONS` (`clients/file-kinds.ts`) — the single source of truth
+  (#894 invariant), so there is no second, hand-maintained language list here.
+- `file:<substr>` — path substring match against the index's own stored path,
+  normalized through `wordIndexKey` (case-folded on win32 only, matching how
+  the index's own path-keyed maps already fold win32 paths, #1025).
+- `ext:<ext>` — literal extension match (`ext:ts` and `ext:.ts` are
+  equivalent).
+- Any filter may be negated with a leading `-` (`-file:test`).
+
+Example: `lang:jsts file:clients/ -file:test rank`. Multiple positive filters
+of the SAME key OR together; different keys AND; negations always subtract.
+Filters are applied as a `fileFilter` predicate BEFORE BM25/priors/centrality
+scoring (same seam as the pre-existing `paths`/`lang` structured options,
+#771), so a surviving file's score is unaffected by filtering. An unrecognized
+`key:` token passes through as an ordinary search term (colon-bearing terms
+like `std::vector`, URLs, and Windows paths search normally). Only a
+recognized key with a bad value — an unrecognized `lang:` kind — throws
+`WordIndexQueryError`
+naming the supported list — never silently falls through as a literal search
+term. Both the pi `symbol_search` tool and the MCP `pilens_symbol_search`
+mirror inherit the syntax for free since both pass their `query` argument
+straight through to `searchWordIndex` (the entry point where parsing happens).
+
+DF-normalization: BM25's per-token `idf` is computed from the FULL,
+unfiltered posting for that token before `fileFilter` is applied per
+candidate file — a filtered query reuses the global, corpus-wide document
+frequency rather than recomputing it over the filtered subset. Documented as
+an acceptable approximation (see the doc comment on `searchWordIndex`).
+
 ## Lifecycle
 
 The index is built/refreshed in **every** startup mode: load the persisted

package/node_modules/pi-lens/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lens",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
   "repository": {

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-chained-type-assertions-test.yml

@@ -0,0 +1,8 @@
+id: no-chained-type-assertions
+valid:
+  - 'const v = x as A'
+  - 'const w = x as A as const'
+  - 'const u = x as unknown as Foo'
+invalid:
+  - 'const v = x as A as B'
+  - 'const v = foo.bar() as A as B;'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-conditional-empty-object-spread-js-test.yml

@@ -0,0 +1,9 @@
+id: no-conditional-empty-object-spread-js
+valid:
+  - 'const o = {...(cond ? {a: 1} : {b: 2})}'
+  - 'const o = {...base}'
+  - 'const o = {...(cond ? extra : other)}'
+invalid:
+  - 'const o = {...(cond ? {} : {x})}'
+  - 'const o = {...(cond ? {y} : {})}'
+  - 'const o = {...cond ? {} : {x}}'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-conditional-empty-object-spread-test.yml

@@ -0,0 +1,9 @@
+id: no-conditional-empty-object-spread
+valid:
+  - 'const o = {...(cond ? {a: 1} : {b: 2})}'
+  - 'const o = {...base}'
+  - 'const o = {...(cond ? extra : other)}'
+invalid:
+  - 'const o = {...(cond ? {} : {x})}'
+  - 'const o = {...(cond ? {y} : {})}'
+  - 'const o = {...cond ? {} : {x}}'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-apply-js-test.yml

@@ -0,0 +1,7 @@
+id: no-reflect-apply-js
+valid:
+  - 'fn.apply(obj, args)'
+  - 'fn(...args)'
+invalid:
+  - 'Reflect.apply(fn, obj, args)'
+  - 'const r = Reflect.apply(target[method], target, argumentsList);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-apply-test.yml

@@ -0,0 +1,7 @@
+id: no-reflect-apply
+valid:
+  - 'fn.apply(obj, args)'
+  - 'fn(...args)'
+invalid:
+  - 'Reflect.apply(fn, obj, args)'
+  - 'const r = Reflect.apply(target[method], target, argumentsList);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-get-js-test.yml

@@ -0,0 +1,8 @@
+id: no-reflect-get-js
+valid:
+  - 'obj.prop'
+  - 'obj[key]'
+  - 'Reflect.get(target, prop, receiver)'
+invalid:
+  - 'Reflect.get(obj, "key")'
+  - 'const v = Reflect.get(target, prop);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-get-test.yml

@@ -0,0 +1,8 @@
+id: no-reflect-get
+valid:
+  - 'obj.prop'
+  - 'obj[key]'
+  - 'Reflect.get(target, prop, receiver)'
+invalid:
+  - 'Reflect.get(obj, "key")'
+  - 'const v = Reflect.get(target, prop);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-unknown-laundering-test.yml

@@ -0,0 +1,11 @@
+id: no-unknown-laundering
+valid:
+  - 'const x: unknown = foo()'
+  - 'function f(x: unknown) {}'
+  - 'function isValidPayload(data: unknown): data is Foo { return true; }'
+  - 'function f(cause: unknown) {}'
+  - 'type X = { a: unknown }'
+  - 'type Y = Record<string, unknown>'
+invalid:
+  - 'type X = unknown'
+  - 'type LooseHandler = unknown'

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-chained-type-assertions.yml

@@ -0,0 +1,21 @@
+id: no-chained-type-assertions
+language: TypeScript
+severity: warning
+message: "Chained type assertion (x as A as B) — stacking assertions with no runtime check between them"
+note: |
+  `x as A as B` stacks two assertions with no runtime check between
+  them, so the compiler can't verify either hop. Narrow with a type
+  guard, or assert once to the type you actually need. `as const`
+  chains are allowed — they don't launder the value's type, they just
+  freeze a literal. `as unknown as B` chains are also allowed: routing
+  a cast through `unknown` (rather than through an unrelated concrete
+  type) is the standard, TypeScript-endorsed way to perform a cast that
+  the compiler can't otherwise verify as safe — see no-as-any.yml's own
+  note, which recommends this exact form as the safe replacement for
+  `as any`. An FP-scan of the pi-lens codebase found 22 chained-assertion
+  hits and all 22 were `as unknown as`; none were a genuine two
+  concrete-type stack.
+rule:
+  pattern: $X as $A as $B
+  not:
+    pattern: "$X as unknown as $B"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-conditional-empty-object-spread-js.yml

@@ -0,0 +1,21 @@
+id: no-conditional-empty-object-spread-js
+language: JavaScript
+severity: hint
+message: "Conditional empty-object spread — use an explicit if/else to omit fields"
+note: |
+  `{...(cond ? {} : {x})}` hides field omission behind a ternary — an
+  explicit `if` reads better. Matched structurally (spread of a ternary
+  whose consequence or alternative is an empty object literal), not by
+  exact source text, so it also catches the un-parenthesized form.
+
+  Kept at `hint` to match no-conditional-empty-object-spread.yml — see
+  that rule's note for the FP-scan finding (147 hits, all a deliberate
+  existing idiom).
+rule:
+  kind: spread_element
+  has:
+    stopBy: end
+    kind: ternary_expression
+    any:
+      - has: { field: consequence, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }
+      - has: { field: alternative, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-conditional-empty-object-spread.yml

@@ -0,0 +1,29 @@
+id: no-conditional-empty-object-spread
+language: TypeScript
+severity: hint
+message: "Conditional empty-object spread — use an explicit if/else to omit fields"
+note: |
+  `{...(cond ? {} : {x})}` hides field omission behind a ternary — an
+  explicit `if` reads better and lets the object's shape stay typed.
+  Matched structurally (spread of a ternary whose consequence or
+  alternative is an empty object literal), not by exact source text, so
+  it also catches the un-parenthesized and multi-property-spread forms.
+
+  FP-scan finding (pi-lens codebase, clients/ tools/ mcp/ index.ts): 147
+  hits, and every sampled hit is this exact shape used deliberately to
+  build an optional-field object (`...(hit.annotations ? {
+  annotations: hit.annotations } : {})`). That is a real, established
+  idiom here, not a shape mismatch — so the rule stays at `hint` rather
+  than `warning`: still discoverable in a scan, but it does not read as
+  a call to fix 147 existing sites.
+rule:
+  kind: spread_element
+  has:
+    # the ternary sits under a parenthesized_expression when the source
+    # parenthesizes it, so this needs stopBy: end — spread_element's
+    # DIRECT child is not the ternary in that (common) form.
+    stopBy: end
+    kind: ternary_expression
+    any:
+      - has: { field: consequence, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }
+      - has: { field: alternative, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-reflect-apply-js.yml

@@ -0,0 +1,9 @@
+id: no-reflect-apply-js
+language: JavaScript
+severity: warning
+message: "Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead"
+note: |
+  Reflect.apply reaches for reflection where a typed call already works.
+  Prefer Function#apply or a direct call with spread arguments.
+rule:
+  pattern: Reflect.apply($$$ARGS)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-reflect-apply.yml

@@ -0,0 +1,9 @@
+id: no-reflect-apply
+language: TypeScript
+severity: warning
+message: "Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead"
+note: |
+  Reflect.apply reaches for reflection where a typed call already works.
+  Prefer Function#apply or a direct call with spread arguments.
+rule:
+  pattern: Reflect.apply($$$ARGS)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-reflect-get-js.yml

@@ -0,0 +1,13 @@
+id: no-reflect-get-js
+language: JavaScript
+severity: warning
+message: "Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead"
+note: |
+  Reflect.get reaches for reflection where a typed property access
+  already works. Prefer dot or bracket access.
+
+  Scoped to the 2-argument form only — see no-reflect-get.yml's note:
+  the 3-argument receiver-forwarding form is the standard Proxy `get`
+  trap idiom.
+rule:
+  pattern: Reflect.get($OBJ, $KEY)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-reflect-get.yml

@@ -0,0 +1,16 @@
+id: no-reflect-get
+language: TypeScript
+severity: warning
+message: "Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead"
+note: |
+  Reflect.get reaches for reflection where a typed property access
+  already works. Prefer dot or bracket access.
+
+  Scoped to the 2-argument form only. The 3-argument form
+  (`Reflect.get(target, key, receiver)`) is the standard, correct way to
+  forward a `receiver` inside a Proxy `get` trap — an FP-scan of the
+  pi-lens codebase found 2 hits, both inside a Proxy trap using the
+  3-argument receiver-forwarding form, so that arity is excluded rather
+  than allowlisted by call site.
+rule:
+  pattern: Reflect.get($OBJ, $KEY)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-unknown-laundering.yml

@@ -0,0 +1,27 @@
+id: no-unknown-laundering
+language: TypeScript
+severity: warning
+message: "type alias to bare 'unknown' — give the alias real shape or inline 'unknown' at the one call site that needs it"
+note: |
+  `type X = unknown` adds a name but zero type information — every
+  consumer of X still has to narrow from scratch, so the alias only
+  launders the fact that nothing was typed. Give it real shape, or drop
+  the alias and let the (rare) genuine unknown-input site say so
+  directly.
+
+  FP-scan finding (pi-lens codebase, clients/ tools/ mcp/ index.ts):
+  the originally proposed wider fan-out — bare `unknown` return types,
+  `unknown` parameters, and `Record<string, unknown>` / index-signature
+  dictionaries — was dropped from this rule. Each of those arms fired
+  overwhelmingly on legitimate, idiomatic TypeScript already in this
+  codebase: `unknown` parameters on type-guard/validator functions
+  (`errorMessage(err: unknown)`, `asRecord(value: unknown)`), `unknown`
+  return types on parsers and a `ProxyHandler.get` trap (whose signature
+  TypeScript itself requires), and `Record<string, unknown>` on
+  telemetry/metadata bags (`metadata?: Record<string, unknown>`). A
+  declared `unknown` at those positions is the CORRECT contract — it
+  forces the caller to narrow — so it is not syntactically distinguishable
+  from a laundered one; only `type X = unknown` stayed a reliable
+  precision signal (zero hits in the same scan).
+rule:
+  pattern: "type $T = unknown"

package/node_modules/pi-lens/scripts/analyze-pi-lens-logs.mjs

@@ -12,6 +12,7 @@
  *   ~/.pi-lens/actionable-warnings*.log  JSONL advisory pipeline (inject/suppress)
  *   ~/.pi-lens/ast-grep-tools*.log   JSONL MCP ast-grep search/replace telemetry
  *   ~/.pi-lens/logs/*.jsonl          JSONL diagnostic findings
+ *   ~/.pi-lens/projects/<slug>/worklog.jsonl  JSONL fix worklog (rule/tool/model/provider, #1448)
  */
 
 import fs from "node:fs";
@@ -69,6 +70,7 @@ async function main() {
 		analyzeSessionStart(files.sessionStart, state),
 		analyzeActionableWarnings(files.actionableWarnings, state),
 		analyzeAstGrepTools(files.astGrepTools, state),
+		analyzeWorklog(files.worklog, state),
 	]);
 
 	const report = buildReport(state);
@@ -139,6 +141,13 @@ function discoverLogFiles(logRoot, archived) {
 		.filter((name) => name.endsWith(".jsonl"))
 		.map((name) => path.join(logsDir, name));
 
+	// worklog.jsonl lives per-project under projects/<slug>/ (getProjectDataDir),
+	// not at the log root — walk one level to find every project's file (#1448).
+	const projectsDir = path.join(logRoot, "projects");
+	const worklogs = safeReaddir(projectsDir)
+		.map((slug) => path.join(projectsDir, slug, "worklog.jsonl"))
+		.filter((file) => fs.existsSync(file));
+
 	const byPrefix = (prefix) =>
 		allRootFiles.filter((file) => {
 			const base = path.basename(file);
@@ -156,6 +165,7 @@ function discoverLogFiles(logRoot, archived) {
 		actionableWarnings: byPrefix("actionable-warnings"),
 		astGrepTools: byPrefix("ast-grep-tools"),
 		diagnostics: dailyLogs,
+		worklog: worklogs,
 	};
 }
 
@@ -263,6 +273,14 @@ function createState(files) {
 			errors: [],
 			slow: [],
 		},
+		worklog: {
+			// key: "<rule>||<model>" (model "" when the entry predates #1448 or the
+			// runtime didn't know it) -> { total, autoFixed }
+			byRuleModel: new Map(),
+			byModel: counter(),
+			byModelAutoFixed: counter(),
+			byProvider: counter(),
+		},
 	};
 }
 
@@ -737,6 +755,39 @@ async function analyzeAstGrepTools(files, state) {
 	}
 }
 
+/**
+ * Per-model rollup (#1448): rule × model counts and auto-fixed vs
+ * agent-required rates, from worklog.jsonl's optional `model`/`provider`
+ * fields. Entries predating #1448 (or written outside a live agent turn)
+ * have neither field — bucketed under the empty-string model/provider key so
+ * "unattributed" volume stays visible rather than silently dropped.
+ */
+async function analyzeWorklog(files, state) {
+	for (const file of files) {
+		await forEachJsonLine(file, "worklog", state, (entry) => {
+			const ts = dateOf(entry.timestamp);
+			if (!inWindow(ts)) return;
+			state.seen.inc("worklog");
+			const rule = entry.rule ?? "unknown";
+			const model = entry.model ?? "";
+			const provider = entry.provider ?? "";
+			const key = `${rule}||${model}`;
+			const row = state.worklog.byRuleModel.get(key) ?? {
+				rule,
+				model,
+				total: 0,
+				autoFixed: 0,
+			};
+			row.total += 1;
+			if (entry.autoFixed) row.autoFixed += 1;
+			state.worklog.byRuleModel.set(key, row);
+			state.worklog.byModel.inc(model || "(unknown)");
+			if (entry.autoFixed) state.worklog.byModelAutoFixed.inc(model || "(unknown)");
+			state.worklog.byProvider.inc(provider || "(unknown)");
+		});
+	}
+}
+
 async function forEachJsonLine(file, bucket, state, visitor) {
 	await forEachLine(file, async (line) => {
 		if (!line.trim()) return;
@@ -1259,6 +1310,17 @@ function buildReport(state) {
 			errors: state.astGrep.errors.slice(0, limit),
 			slow: state.astGrep.slow.slice(0, limit),
 		},
+		worklog: {
+			byModel: state.worklog.byModel.top(limit * 2),
+			byProvider: state.worklog.byProvider.top(limit * 2),
+			byRuleModel: [...state.worklog.byRuleModel.values()]
+				.map((row) => ({
+					...row,
+					autoFixedRate: row.total ? row.autoFixed / row.total : 0,
+				}))
+				.sort((a, b) => b.total - a.total)
+				.slice(0, limit * 3),
+		},
 	};
 }
 
@@ -1397,6 +1459,23 @@ function printReport(report) {
 			`  started=${ws.started} completed=${ws.completed} incomplete=${ws.incomplete} aborted=${ws.aborted} fileTimeouts=${ws.timedOutFilesTotal} (in ${ws.timedOutSweeps} sweeps)`,
 		);
 	}
+	const wl = report.worklog;
+	if (wl && (wl.byModel.length || wl.byRuleModel.length)) {
+		console.log("\nWorklog per-model rollup (#1448)");
+		console.log(
+			`  by model: ${wl.byModel.map((x) => `${x.key}=${x.count}`).join(", ")}`,
+		);
+		if (wl.byProvider.length)
+			console.log(
+				`  by provider: ${wl.byProvider.map((x) => `${x.key}=${x.count}`).join(", ")}`,
+			);
+		console.log("  rule × model (auto-fixed vs agent-required):");
+		for (const row of wl.byRuleModel.slice(0, limit))
+			console.log(
+				`    ${String(row.total).padStart(5)}  ${row.rule} [${row.model || "(unknown)"}]  autoFixed=${row.autoFixed} (${(row.autoFixedRate * 100).toFixed(0)}%)`,
+			);
+	}
+
 	const timeouts = Object.entries(report.latency.phaseTimeouts ?? {});
 	if (timeouts.length) {
 		console.log("\nPhase timeouts");

package/node_modules/pi-lens/skills/pi-lens-ast-grep/SKILL.md

@@ -52,12 +52,15 @@ Use `$$$` when you don't need the captured value; `$$$NAME` when you do.
 
 Use these instead of writing raw YAML:
 
-| Parameter | What it does |
-|---|---|
-| `insideKind` | Only match inside an ancestor of this node kind |
-| `hasKind` | Only match nodes that contain a descendant of this kind |
-| `follows` | Only match nodes preceded by a sibling matching this pattern |
-| `precedes` | Only match nodes followed by a sibling matching this pattern |
+| Parameter | Tool | What it does |
+|---|---|---|
+| `insideKind` | both | Only match inside an ancestor of this node kind (searches ALL ancestors, `stopBy: end`) |
+| `hasKind` | both | Only match nodes whose **immediate child** has this kind (`stopBy: neighbor` — NOT recursive) |
+| `hasDescendantKind` | both | Only match nodes containing this kind **anywhere in their descendants** (`stopBy: end`) — use this instead of `hasKind` when the target isn't a direct child |
+| `follows` | both | Only match nodes preceded by a sibling matching this pattern |
+| `precedes` | both | Only match nodes followed by a sibling matching this pattern |
+
+`hasKind` and `hasDescendantKind` are mutually exclusive on both tools — combining them errors.
 
 ```
 # console.log only inside functions
@@ -152,13 +155,9 @@ Use these as starting points, then scope `paths` tightly.
 
 | Task | Pattern / params |
 |---|---|
-| Find pi lifecycle handlers | `pattern: pi.on($EVENT, $HANDLER)` |
-| Find timers | `pattern: setTimeout($CALLBACK, $$$REST)` or `setInterval($CALLBACK, $$$REST)` |
-| Find immediate/deferred work | `pattern: setImmediate($CALLBACK)` |
-| Find promise callbacks | `pattern: $PROMISE.then($CALLBACK)` / `.catch($CALLBACK)` / `.finally($CALLBACK)` |
 | Find object-literal function dependency by name | `pattern: { resetLSPService: $FN, $$$REST }` |
-| Find fire-and-forget async calls | `pattern: void $CALL` |
 | Find empty catches | `pattern: try { $$$BODY } catch ($ERR) { }` |
+| Find fire-and-forget async calls | `pattern: void $CALL` |
 
 For lifecycle bugs, search first, then use the returned `details.matchLocations[].readSlice` handle for bounded context.
 

package/node_modules/pi-lens/skills/pi-lens-lsp-navigation/SKILL.md

@@ -13,39 +13,39 @@ Use `lsp_diagnostics` before builds/tests or after touching several files:
 
 | Need | Tool call |
 |---|---|
-| Check one file | `lsp_diagnostics({ filePath: "src/file.ts" })` |
-| Check a folder | `lsp_diagnostics({ filePath: "src/", severity: "error" })` |
-| Check exact touched files | `lsp_diagnostics({ filePaths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
-| Slow server (Rust, Java) | `lsp_diagnostics({ filePaths: files, waitMs: 2000 })` |
-| Include warnings | `lsp_diagnostics({ filePaths: files, severity: "all" })` |
+| Check one file | `lsp_diagnostics({ path: "src/file.ts" })` |
+| Check a folder | `lsp_diagnostics({ path: "src/", severity: "error" })` |
+| Check exact touched files | `lsp_diagnostics({ paths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
+| Slow server (Rust, Java) | `lsp_diagnostics({ paths: files, waitMs: 2000 })` |
+| Include warnings | `lsp_diagnostics({ paths: files, severity: "all" })` |
 
-Prefer explicit `filePaths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
+Prefer explicit `paths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
 
 ## Navigation (Code Intelligence)
 
 | Question | Operation | Parameters |
 |---|---|---|
-| Where is this defined? | `definition` | filePath, line, character |
-| Where is this symbol's *type* defined? | `typeDefinition` | filePath, line, character |
-| Where is this declared (vs defined)? | `declaration` | filePath, line, character |
-| Find all usages | `references` | filePath, line, character |
-| What type is this? | `hover` | filePath, line, character |
-| Call signature | `signatureHelp` | filePath, line, character (at arg position) |
-| Symbols in this file | `documentSymbol` | filePath |
-| Find symbol across project | `workspaceSymbol` | query + filePath (strongly recommended) |
-| Quick fixes available | `codeAction` | filePath, line, character, endLine, endCharacter |
-| Rename symbol safely | `rename` | filePath, line, character, newName |
-| Who implements this? | `implementation` | filePath, line, character |
-| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | filePath, line, character |
-| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | filePath, line, character |
-| What commands does the server offer? | `capabilities` | (optional filePath) — lists advertised commands |
+| Where is this defined? | `definition` | path, line, character |
+| Where is this symbol's *type* defined? | `typeDefinition` | path, line, character |
+| Where is this declared (vs defined)? | `declaration` | path, line, character |
+| Find all usages | `references` | path, line, character |
+| What type is this? | `hover` | path, line, character |
+| Call signature | `signatureHelp` | path, line, character (at arg position) |
+| Symbols in this file | `documentSymbol` | path |
+| Find symbol across project | `workspaceSymbol` | query + path (strongly recommended) |
+| Quick fixes available | `codeAction` | path, line, character, endLine, endCharacter |
+| Rename symbol safely | `rename` | path, line, character, newName |
+| Who implements this? | `implementation` | path, line, character |
+| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | path, line, character |
+| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | path, line, character |
+| What commands does the server offer? | `capabilities` | (optional path) — lists advertised commands |
 | Run a server command (e.g. organize imports) | `executeCommand` | command (+ commandArguments); dry-run unless `apply:true` |
 
 ## Call Hierarchy Pattern
 
 ```
 // Step 1
-lsp_navigation(operation="prepareCallHierarchy", filePath="src/api.ts", line=42, character=10)
+lsp_navigation(operation="prepareCallHierarchy", path="src/api.ts", line=42, character=10)
 // → returns callHierarchyItem
 
 // Step 2
@@ -56,7 +56,7 @@ lsp_navigation(operation="outgoingCalls", callHierarchyItem=<item from step 1>)
 ## Operational Notes
 
 - **`definition` returns nothing?** The file may not be open/indexed yet. Read it first, then retry.
-- **`workspaceSymbol` empty?** Always pass `filePath`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
+- **`workspaceSymbol` empty?** Always pass `path`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
 - **`references`** — query from the *definition site* for full cross-file coverage; usage-site queries can be partial.
 - **`signatureHelp`** — only valid at call-site argument positions; declaration positions return empty.
 - **`workspaceDiagnostics`** — tracked push snapshot only, not an active check. Use `lsp_diagnostics` when you need fresh results.