@aeonsparx/pi-unreal 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version numbers follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every version bump in `package.json`
+adds an entry here; release notes stay auto-generated from commits.
+
+Rule for bump class (repo policy): new tools, new parameters and new answer types are **minor**;
+**patch** is fixes with the same surface; **major** is a breaking surface change — a removed tool,
+a renamed parameter, or answer text an existing consumer parses.
+
+## [Unreleased]
+
+## [1.1.0] - 2026-10-28
+
+Closes the field findings in `docs/field-findings-2026-10-27.md` (measured on a UE 5.8.3 installed
+engine against a project with 25 enabled plugin references).
+
+### Added
+
+- `unreal_index` `action: "headers"` — a path-only header index answering "does this header exist in
+  this engine version?": exact path, owning module, owning plugin, `EnabledByDefault`, and whether
+  the `.uproject` references it. Invented names come back as *not a file path* plus the closest real
+  file names, labelled as files and never as types. Never built implicitly; keyed by its own root set
+  (`lib/store.ts` `buildHeaderIndex`, `lookupHeaderPaths`, `suggestHeaderPaths`; `lib/tools.ts`
+  `headerReport`, `headerLookup`).
+- Engine-scope indexes include the project's enabled plugin roots, and `engineAreas` accepts engine
+  plugin dials: `["Plugins"]` (every `Engine/Plugins` source tree, ~2.8x the `Runtime` scan) or
+  `["Plugins/Animation/PhysicsControl"]` (one plugin).
+- Every answer states what it scanned. A 0-row symbol answer names the index keys, the root kinds
+  (`279 engine-source root(s), 62 engine-plugin root(s)`), the plugins the project does not reference
+  whose names match the query, and the exact next call (`lib/tools.ts` `zeroResultNotes`,
+  `indexCoverageNote`, `rootKindsNote`). `unreal_index` `action: "status"` reports the same per index,
+  plus the header indexes.
+- `unreal_context` `module: "X"` reports per-target availability: whether the target's module graph
+  contains it, its module directory, the declared module `Type`, its owning plugin with
+  `EnabledByDefault`, and the `.uproject` reference status as separate facts
+  (`lib/tools.ts` `moduleAvailability`).
+- `unreal_symbol` exposes `substring: true` (the substring pass already existed in `lookupSymbol`;
+  it was unreachable from the tool).
+- `unreal_project_inspect` / `unreal_plugin_inspect` name the modules a resolved plugin reference
+  buys — `Mover: resolved ← Engine · modules Mover(Runtime), MoverCVDData(Runtime),
+  MoverEditor(UncookedOnly)` — and list engine plugins available with **no** `.uproject` reference
+  (`EnabledByDefault: true`), separated from the references.
+
+### Changed
+
+- Index format v6 (`INDEX_VERSION = 6`): `meta.rootKinds` + `meta.areas`. Engine-scope index keys
+  change because engine roots now include enabled plugin roots, so v5 engine indexes are not reused
+  (one rebuild per machine; project indexes are unaffected).
+- Definitions-mode module attribution names modules after their `*.Build.cs` file, not the directory
+  leaf: `Engine/Plugins/Animation/PoseSearch/Source/Runtime` is module `PoseSearch`, not `Runtime`.
+  Multi-`Build.cs` directories are disambiguated by the `.uplugin` module names
+  (`store.ts` `moduleFromBuildCs`, `buildCsNames`, `pickModuleName`; `assembleRoots` root modules).
+  This is what makes `unreal_symbol module: "PoseSearch"` answer in `definitions` mode.
+- Index writes and whole-file passes are streamed: `buildIndex` sorts definition rows per 40 000-row
+  shard and k-way merges them into `defs.tsv`, and the linear passes (substring lookup,
+  symbols-in-file, module-scope recovery) read the TSV in 4 MB chunks. The whole-Plugins engine scope
+  is 1.24 M rows / ~250 MB and previously died in the allocator at 1.91 GB
+  (`ReachJSValueFormalMemoryCommit Allocation failed: out of memory`).
+- `unreal_context` `file:` derives scope from path shape (`Engine/Plugins/...` is engine scope), and
+  a miss falls back to the header index: "this file exists, in plugin X, `EnabledByDefault` false,
+  not referenced by your `.uproject`, here is the call that indexes it" — instead of "not in index".
+- `unreal_index` `action: "compiledb"` with `scope: "project+engine"` now includes `Engine/Plugins`
+  sources, where plugin `.cpp` bodies live.
+
+### Fixed
+
+- `engineAreas` schema wording: `["Runtime"]` is the engine's own gameplay code, not every gameplay
+  type — plugin-shipped types were unreachable and a 0 read as "the engine has no such type".
+- `test/live-check.ts` no longer defaults to a machine-local `.uproject` path (it resolved to
+  nothing on CI) and prints a usage line instead.
+
+### Documentation
+
+- `README.md` and `docs/internals.md`: engine/plugin coverage and its measured cost, the header index
+  and the path-vs-symbol distinction, "an empty clangd answer is evidence", and the asset boundary —
+  pi-unreal answers C++ declaration/module/include/dependency facts and does not answer UENUM index
+  order, UStruct field types, UCLASS/CDO values or Blueprint graphs (that needs the `unreal-engine`
+  editor MCP with the editor running).
+
+## [1.0.0]
+
+- Initial release: `unreal_resolve_engine`, `unreal_project_inspect`, `unreal_plugin_inspect`,
+  `unreal_symbol`, `unreal_symbol_list`, `unreal_context`, `unreal_index` (compiler-free symbol
+  index, UnrealBuildTool Query facts, clangd compile-database enrichment).
+
+[Unreleased]: https://github.com/Aeonsparx-Interactive/pi-unreal/commits/main
+[1.1.0]: https://github.com/Aeonsparx-Interactive/pi-unreal/releases/tag/v1.1.0
+[1.0.0]: https://github.com/Aeonsparx-Interactive/pi-unreal/releases/tag/v1.0.0

package/README.md

@@ -10,6 +10,32 @@ the owning module. No compiler, no Visual Studio, no Rider, no clangd required.
 It is **read-only**: it never writes to your project, never touches the Windows registry, never
 launches the editor, and blocks three kinds of edit that damage Unreal work.
 
+## Usage
+
+### Requirements
+
+- **Windows**, with **PowerShell 7** (`pwsh`) for registry-based engine discovery. Without it the
+  extension still works: resolution falls back to `UNREAL_ENGINE` / `UE_ROOT` /
+  `PI_UNREAL_ENGINE_ROOT`, the Launcher's install list, and a scan of
+  `C:/Program Files/Epic Games`.
+- An Unreal Engine installation the project can resolve to (Launcher install or source build).
+  Descriptor field handling is transcribed from UE 5.8.
+- Nothing else. No compiler, no IDE language service. clangd is optional enrichment for
+  `compiledb` and the `clangd --check` acceptance step.
+
+
+### Installation
+
+```bash
+pi install npm:@aeonsparx/pi-unreal                              # optionally pin to a specific version, reproducible
+pi install git:github.com/Aeonsparx-Interactive/pi-unreal@v1.1   # follows patch releases on the v1.1 line
+```
+
+The `npm:` route installs from the registry and pins an exact version. The `git:` route clones the
+repository and checks out the ref: a line alias (`@v1.1`) is a moving tag that patch releases
+force-move, so `pi` picks up patches on update; pin `@v1.1.0` for a fixed snapshot. Loading straight
+from a clone still works and needs no install: `pi -e ./extensions/unreal/index.ts`.
+
 ## What you get in a session
 
 **Context is detected for you.** When the session starts in a directory that contains a
@@ -29,8 +55,8 @@ project?", "Where is `FLpMovementDirectionThresholds` defined?", "What do I need
 | `unreal_plugin_inspect` | One `.uplugin` as the engine parses it: modules, loading phases, version fields, plugin dependencies |
 | `unreal_symbol` | "Where is this class / struct / function / `UPROPERTY` / delegate declared?" One line per hit: kind, file:line, module |
 | `unreal_symbol_list` | "What does this project define?" Names by prefix — `ULp`, `ANiMy`, `UAnim` |
-| `unreal_context` | "What does this file/module include, define, and depend on?" Include paths, dependency lists, the real `WITH_*` defines |
-| `unreal_index` | Builds and reports the source index, and the clangd compile database on request |
+| `unreal_context` | "What does this file/module include, define, and depend on?" Include paths, dependency lists, the real `WITH_*` defines; for a module, also whether the target's module graph contains it and how the `.uproject` treats its plugin |
+| `unreal_index` | Builds and reports the source index, the path-only **header index** ("does this header exist in this engine version?"), and the clangd compile database on request |
 
 **Slash commands you can type yourself:**
 
@@ -53,11 +79,12 @@ modules: Lp (Runtime), LpEditor (Editor)
 plugins declared: 25
 plugin index: 897 .uplugin (cache hit)
 plugin references:
-  MassGameplay: resolved ← Engine
-  ModularGameplay: resolved ← Engine
-  SomeLocalPlugin: resolved ← Project
+  Mover: resolved ← Engine · modules Mover(Runtime), MoverCVDData(Runtime), MoverEditor(UncookedOnly)
+  MassGameplay: resolved ← Engine · modules MassEntity(Runtime), MassCore(Runtime), MassSimulation(Runtime), …
+  SomeLocalPlugin: resolved ← Project · modules SomeLocalPlugin(Runtime)
   RetiredPlugin: missing
   totals: 22 resolved, 3 missing of 25 references
+  engine plugins available with NO .uproject reference (EnabledByDefault true): GameplayCameras, IKRig
 ```
 
 Example — `unreal_symbol` for an engine type (engine index already built):
@@ -70,6 +97,36 @@ unreal_symbol 'AActor' scope=engine: 1 definition(s)
 That is a definition line, not a grep dump: grepping a hot engine class name returns ~176 files of
 noise, which is exactly what burns a session's context.
 
+Example — `unreal_index` `action: "headers"`, the question a symbol index cannot answer:
+
+```text
+unreal_index headers → hdr-UE_5.8-1a40c1c3d516
+  37,788 header paths from 1,934 roots (1,655 engine-plugin root(s), 279 engine-source root(s))
+  'MoverState.h': does NOT exist as a file path in this engine version
+  closest real file names (files, not types):
+    Engine/Plugins/Experimental/Mover/Source/Mover/Public/MoverTypes.h   [Mover]
+    Engine/Plugins/Experimental/Mover/Source/Mover/Public/MoverSimulationTypes.h   [Mover]
+    Engine/Plugins/Experimental/Mover/Source/Mover/Public/MovementMode.h   [Mover]
+    Engine/Plugins/Experimental/Mover/Source/Mover/Public/MovementModeStateMachine.h   [Mover]
+```
+
+`MoverState.h` is the kind of name an agent invents. The answer says it is not a file, lists real
+files, and never presents a file name as a type. The same call on
+`PhysicsControlComponent.h` returns the path plus `plugin PhysicsControl [Engine] · EnabledByDefault
+false · .uproject reference NO` — the file exists, the project does not reference the plugin, and
+those are different facts.
+
+Example — the coverage lines a 0-row answer prints (nothing here says "the engine has no such type"):
+
+```text
+unreal_symbol 'PhysicsControlComponent' scope=engine: 0 definition(s)
+  · no definitions matched 'PhysicsControlComponent' in scope 'engine'
+  · scanned engine index idx-engine-defs-b8d82464af4a: 279 engine-source root(s), 62 engine-plugin root(s)
+  · engine plugins on disk: 897, referenced by this .uproject: 25; the engine index scans referenced plugins only
+  · a plugin the project does not reference is not in any index root: pass engineAreas ["Plugins"] (…2.8× the Runtime scan) or ["Plugins/Animation/PhysicsControl"]
+  · next: unreal_symbol query 'PhysicsControlComponent' scope "all" prefix true, or unreal_index action "headers" name "PhysicsControlComponent.h"
+```
+
 ## Guardrails (automatic, nothing to enable)
 
 | Situation | What happens |
@@ -94,8 +151,18 @@ Because of that model:
 - Symbol lookups never stall. If a question needs engine sources and no engine index exists, the
   agent reports the cost and how to pay it, and asks you. Say **yes** once per machine —
   `/unreal-cache stats` shows what you have. Engine scans default to `engineAreas: ["Runtime"]`,
-  which is enough for gameplay base classes (`AActor`, `UAnimInstance`, `USceneComponent`);
-  `Editor` and `Developer` are opt-in and roughly triple the scan.
+  which is the engine's **own** gameplay code (`AActor`, `UAnimInstance`, `USceneComponent`);
+  `Editor` and `Developer` are opt-in and roughly triple the scan. An engine-scope index always
+  includes the plugin roots your `.uproject` enables, so `UMoverComponent` and the PoseSearch types
+  are in it. Types shipped by plugins you do **not** reference (`PhysicsControl`, `BlendStack`,
+  `StateTree`, `GameplayAbilities`) need `engineAreas: ["Plugins"]` — every `Engine/Plugins`
+  source tree, ~2.8× the `Runtime` scan — or `engineAreas: ["Plugins/Animation/PhysicsControl"]`
+  for one plugin.
+- "Does this header exist in this engine version?" is a path question, not a symbol question:
+  `unreal_index` with `action: "headers"` (and `name: "MoverState.h"`) answers it in seconds from a
+  path walk, and says which plugin owns a header it finds, whether that plugin is
+  `EnabledByDefault`, and whether your `.uproject` references it. Invented names come back as
+  *not a file path* plus the closest real **file** names — never as types.
 - Ask for `unreal_index` with `action: "build"`, `scope: "engine"` when you want engine-wide
   navigation, and `action: "compiledb"` when you want clangd's references/call hierarchy.
 - After a branch switch, a rebase, adding a plugin, or an engine version change, say "rebuild the
@@ -104,17 +171,6 @@ Because of that model:
   inside your project tree or your engine installation. The compile database encodes this
   machine's absolute paths, so it is machine-local by design.
 
-## Requirements
-
-- **Windows**, with **PowerShell 7** (`pwsh`) for registry-based engine discovery. Without it the
-  extension still works: resolution falls back to `UNREAL_ENGINE` / `UE_ROOT` /
-  `PI_UNREAL_ENGINE_ROOT`, the Launcher's install list, and a scan of
-  `C:/Program Files/Epic Games`.
-- An Unreal Engine installation the project can resolve to (Launcher install or source build).
-  Descriptor field handling is transcribed from UE 5.8.
-- Nothing else. No compiler, no IDE language service. clangd is optional enrichment for
-  `compiledb` and the `clangd --check` acceptance step.
-
 ## Troubleshooting
 
 | Report | What to do |
@@ -122,82 +178,23 @@ Because of that model:
 | `engine: AMBIGUOUS — more than one valid installation matches` | Two roots match the association. Pass the one you want as `engineRootHint` (e.g. `engineRootHint: "C:/Program Files/Epic Games/UE_5.8"`). |
 | `engine: UNRESOLVED` with rejected candidates | Read the reasons — a stale registry key, a missing `Build.version`, a version mismatch. The report lists remediation steps; the extension never writes registry keys for you. |
 | `no .uproject within 4 levels above …` | The search walks up from the working directory. Pass the project explicitly: `project: "C:/Work/Lp/Lp.uproject"` (a directory containing one works too). |
-| `unreal_symbol` finds nothing in scope `engine` | Build the engine index first (`unreal_index` → `action: "build"`, `scope: "engine"`). |
+| `unreal_symbol` finds nothing in scope `engine` | Read the coverage lines the answer prints: they name the root kinds that were scanned. A plugin your `.uproject` does not reference is in no index root — `engineAreas: ["Plugins"]` (or one plugin subtree), then rebuild. |
+| `unreal_symbol` finds nothing and you are not sure the name exists | `unreal_index` → `action: "headers"`, `name: "ThatName.h"`: a seconds-long path answer with the closest real file names. |
 | Results look stale after a rebase or engine update | Re-run with `refresh: true`, or `/unreal-cache clear`. |
 | `no plugin named "X" in the index` | That reference is genuinely not on disk. `/unreal` shows which roots were scanned. |
 
-## What it deliberately does not do
+### What it deliberately does not do
 
 - It does not install, register, migrate, or "fix" an engine, and never writes registry keys.
 - It does not build, cook, package, launch the editor, or edit `.ini` files.
 - It does not hand-edit assets, and blocks attempts to.
 - Symbol lookup reports **declarations**. Type resolution, overloads, call sites, inheritance and
-  diagnostics are clangd's job when clangd is installed.
+  diagnostics are clangd's job when clangd is installed. An empty clangd answer is evidence: on an
+  installed engine the compile database has no engine translation units, so "clangd found nothing"
+  in engine code is a property of the setup, not a bug this package fixes.
+- A 0-row answer is a statement about **the roots that were scanned**, never about the engine. The
+  answer names its index keys and root kinds; `unreal_index` → `action: "status"` prints the same.
+- pi-unreal answers C++ **declaration, module, include-path and dependency** facts. It does not
+  answer asset questions — UENUM index order, UStruct field types, UCLASS/CDO instance values,
+  Blueprint graphs. Those need the `unreal-engine` editor MCP with the editor running.
 - `.ini` provenance, live-coding state, and asset metadata are out of scope for v1.
-
-## Install
-
-Published as **`@aeonsparx/pi-unreal`** on npmjs.
-
-```bash
-pi install npm:@aeonsparx/pi-unreal@1.0.0                        # pinned version, reproducible
-pi install git:github.com/Aeonsparx-Interactive/pi-unreal@v1.0   # follows patch releases on the v1.0 line
-```
-
-The `npm:` route installs from the registry and pins an exact version. The `git:` route clones the
-repository and checks out the ref: a line alias (`@v1.0`) is a moving tag that patch releases
-force-move, so `pi` picks up patches on update; pin `@v1.0.2` for a fixed snapshot. Loading straight
-from a clone still works and needs no install: `pi -e ./extensions/unreal/index.ts`.
-
-## Releasing (maintainers)
-
-| `package.json` bump | GitHub Release | npmjs |
-| --- | --- | --- |
-| `major` / `minor` | **new** release `v<major>.<minor>` | staged `<major>.<minor>.<patch>` |
-| `patch` | **updates** the existing `v<major>.<minor>` release | staged `<major>.<minor>.<patch>` |
-
-Merge a PR that bumps `version` into `main`. `.github/workflows/release.yml` runs `bun test` on
-Linux and Windows, pushes the immutable tag `v<major>.<minor>.<patch>`, moves the `v<major>.<minor>`
-alias, creates or updates that release, then stages the tarball with `npm stage publish`. **Nothing
-is public until a human approves it** (2FA, from any machine):
-
-```bash
-npm stage list @aeonsparx/pi-unreal     # stage ids (no 2FA)
-npm stage view <stage-id>              # metadata
-npm stage download <stage-id>          # inspect the exact tarball that will publish
-npm stage approve <stage-id>           # 2FA - this is the publish act
-npm stage reject <stage-id>            # 2FA - frees the staged version number
-```
-
-The same queue is on npmjs.com (Staged Packages tab). `npm stage` requires npm >= 11.15.0
-(`npm install -g npm@12`) and Node >= 22.14.0. `NPM_TOKEN` (repository secret) is a Granular Access
-Token with Read+Write and **no** 2FA bypass: CI can stage, only you can publish. Staged versions
-occupy their version number, so a rejected stage burns `x.y.z` until `npm stage reject` frees it.
-Provenance is deliberately off in v1 (`--provenance` needs a Provenance-scope token, and the
-attestation path through stage-then-approve is unverified).
-
-## Developers
-
-```bash
-bun test                      # 66 tests: resolver, descriptors, plugins, cache, gate, scanner, index, compile-db pipeline, fixture hygiene
-bun run typecheck             # tsc --noEmit
-bun test/live-check.ts "C:/path/to/Project.uproject"   # live machine smoke
-bun test/keys.census.mjs "C:/Program Files/Epic Games/UE_5.8/Engine/Plugins"
-bun run tmp/smoke.mjs project "C:/path/to/Project"     # symbol index against a real project
-bun run tmp/smoke.mjs query "C:/path/to/Project"       # UnrealBuildTool Query round trip
-bun run tmp/smoke.mjs engine "C:/path/to/Project"      # Engine/Source index (minutes, opt-in)
-bun run tmp/smoke.mjs compiledb "C:/path/to/Project"   # clangd database + `clangd --check` acceptance
-```
-
-From a clone, load the extension into a session without installing it:
-
-```bash
-pi -e ./extensions/unreal/index.ts
-```
-
-Layout: `extensions/unreal/index.ts` (tools, commands, context card, convention gate),
-`extensions/unreal/lib/` (resolver, descriptors, plugin index, symbol index, UBT Query, compile
-database), `prompts/unreal-context.md`, `skills/ue-engine-resolution/`, `test/`.
-
-Design notes and measured internals — engine resolution algorithm, descriptor fidelity, plugin
-discovery, the index and compile-database pipeline — are in [docs/internals.md](docs/internals.md).

package/docs/internals.md

@@ -17,19 +17,34 @@ compiler-free sources:
    through RiderLink, and both derive their context from the same UBT rules this layer reads.
 2. **A regex definition scanner** over the project, its enabled plugins, and the engine areas its
    modules actually depend on — `class`/`struct`/`enum`/`union`, `UFUNCTION`, `UPROPERTY`,
-   delegates, aliases, with `Owner:Member` qualified names and forward declarations marked.
+   delegates, aliases, with `Owner:Member` qualified names and forward declarations marked. In an
+   installed engine "engine areas" is not where the gameplay types are: `Engine/Source/Runtime` is the
+   engine's own code, and plugin-shipped types live under `Engine/Plugins/<Category>/<Plugin>/Source/`,
+   so an engine-scope index takes its plugin roots from the `.uproject` (plus an explicit
+   `engineAreas: ["Plugins"]` dial for the rest).
 
 Artifacts live in `$PI_UNREAL_CACHE_DIR/indexes/<key>/` (`meta.json`, `defs.tsv`, `files.tsv`,
 plus `includes.tsv` in `full` mode): plain TSV — greppable, inspectable, shared across sessions
 and projects — and never inside the project tree or the engine installation.
 
+Writes and whole-file passes are **streamed**, because the whole-Plugins engine index is 1.24 M rows
+(~250 MB of TSV): `buildIndex` sorts rows per 40 000-row shard and k-way merges them into `defs.tsv`
+(peak memory is one shard, output is identical to a single sorted pass), and the linear passes
+(substring lookup, symbols-in-file, module scope recovery) read the TSV in 4 MB chunks and stop when
+the answer is full. An earlier build accumulated every row in an array and died in the allocator at
+1.91 GB (`ReachJSValueFormalMemoryCommit Allocation failed: out of memory`) — which is the failure
+mode of "just load the index" at engine scale.
+
 Measured on this box (UE 5.8.3 installed engine; Lp project with 25 enabled plugins):
 
 | Scope | Files | Definitions | Cold build |
 | --- | --- | --- | --- |
 | Project + plugins | 2,405 | 38,901 | 6.7 s |
 | Engine `Runtime` (shipped default: 279 module roots) | 18,566 | 436,729 | 57.6 s cold, 5.7 s warm |
+| Engine `Runtime` + 62 enabled plugin roots | 20,966 | 476,327 | 122 s cold, 0.4 s warm |
+| Engine `Runtime` + every `Engine/Plugins` source | 71,004 | 1,240,246 | ~2 min cold (1,996 roots: 279 engine-source + 1,717 engine-plugin) |
 | Engine `Runtime/Core` + `Runtime/CoreUObject` | 3,094 | 70,548 | 16 s |
+| Header index (paths only, engine `Runtime` + all `Engine/Plugins`) | 37,788 headers | — | 4.5 s cold, 0.5 s warm |
 | Cached lookup | — | — | ~0.3 s |
 
 Cost discipline is the design. A lookup builds the project index (seconds) and uses an engine
@@ -43,8 +58,36 @@ Forward declarations rank last, so `unreal_symbol AActor` returns
 the `class AActor;` line in `PhysicsCollision.h`.
 `unreal_symbol LpGameModeBase` finds `ALpGameModeBase` (the UE prefix is added for you); `unreal_symbol FLpMovementDirectionThresholds:F` finds a single-letter `UPROPERTY` field; `unreal_context LpCharacterTypes.h` resolves a bare file name through the index. Engine areas are derived from module
 dependencies (`.uproject` modules → recursive `PublicDependencyModuleNames` → plugin-supplied
+modules → recursive `PublicDependencyModuleNames` → plugin-supplied
 modules → `Engine/Source/<area>/*`), so the index contains what this project can compile against,
-not the whole engine.
+not the whole engine. An **engine-scope** index is `Engine/Source/<area>` roots *plus the plugin
+roots the `.uproject` enables* — in UE 5.8 most gameplay types ship as plugins (`Mover`,
+`PoseSearch`, `SmartObjects`, `BlendStack`, `StateTree`, `GameplayAbilities`), and an index of
+`Engine/Source/Runtime` alone reports 0 rows for `UMoverComponent` while the project index already
+contains it. Engine plugins the project does **not** reference are in no root: `engineAreas:
+["Plugins"]` adds every `Engine/Plugins` source tree (~2.8× the `Runtime` scan),
+`["Plugins/Animation/PhysicsControl"]` adds one.
+
+Every answer states what it scanned: index key, root kinds (`279 engine-source root(s),
+62 engine-plugin root(s)`), and the `engineAreas` it was built with. A 0-row answer is a statement
+about those roots, never about the engine, and it prints the exact next call.
+
+## Header index (`unreal_index` action `headers`)
+
+"Does this header exist in this engine version?" is a path question that a definitions index cannot
+answer: absence of a symbol row is not absence of a file, and the index roots exclude every plugin
+the project does not enable. `buildHeaderIndex` walks file **paths** only — no content read — over
+the same root assembly (`Engine/Source/<area>`, `Engine/Plugins/...`, project sources), writes
+`headers.tsv` (`file \t module \t kind`) beside the symbol indexes, and answers exists / exact path
+/ owning module / owning plugin / `EnabledByDefault` / referenced-in-`.uproject`. Measured: 37,788
+header paths in 4.5 s on a UE 5.8 install (`Runtime` + all of `Engine/Plugins`).
+
+It is never built implicitly (a path answer must not cost a scan nobody asked for), its key encodes
+its own root set, and when the name does not exist the answer lists the closest real **file** names
+labelled as files. That is the discipline behind it: an invented name like `MoverState.h` must not
+become a confident type suggestion — the old workflow produced `Mover/Public/InputContainerStruct.h`
+(a real file, a bogus answer) for `FCharacterDefaultInputs`, and the types
+`FPoseSearchBlendPose(History)` do not exist in 5.8 at all.
 
 One engine fact worth knowing: UBT Query reports `"defines": []` for every module. The effective
 preprocessor set lives in a forced include —
@@ -169,7 +212,8 @@ Field names, host types, and loading phases are transcribed from the engine's se
   candidate, not a guarantee).
 - `moduleRefs` and `includePaths` come from UnrealBuildTool Query, which needs a buildable
   target for the project; when Query fails the index still builds and says so.
-- The engine index is never built implicitly: scans are opt-in through `unreal_index`.
+- The engine index is never built implicitly: scans are opt-in through `unreal_index`. The header
+  index is never built implicitly either, for the same reason: a path answer must not cost a scan.
 - `action: "compiledb"` needs UnrealBuildTool (so an engine installation) and, for the
   `clangd --check` acceptance step, a clangd binary — `CLANGD_PATH`, the Visual Studio LLVM
   toolset, the WinGet LLVM package, or `C:/Program Files/LLVM/bin`. Without clangd the database is
@@ -177,8 +221,25 @@ Field names, host types, and loading phases are transcribed from the engine's se
 - On an installed engine the compile database covers the project's translation units (engine
   modules are precompiled and contribute no compile actions). The engine-wide scope of
   `project+engine` is the source-built case, and there it is a ~1 GB artifact taking minutes.
+  `project+engine` now includes `Engine/Plugins` sources as well as `Engine/Source` — that is where
+  plugin `.cpp` bodies live, and a database without them silently drops every plugin implementation
+  file from clangd.
+- An empty clangd answer is **evidence, not a bug to route around**. On an installed engine the
+  database has no engine translation units, so "clangd found no references in
+  `MoverComponent.cpp`" describes the setup, not a defect pi-unreal fixes: it answers declaration,
+  module, include-path and dependency facts by a compiler-free route, and says what it scanned.
 - Engine area selection is a cost dial, not a completeness claim. `DEFAULT_ENGINE_AREAS =
-  ["Runtime"]` covers every gameplay type (`AActor`, `UAnimInstance`, `USceneComponent`) at
-  18,566 files; `Editor` and `Developer` are opt-in via `engineAreas` and roughly triple the scan.
+  ["Runtime"]` covers the engine's **own** gameplay code (`AActor`, `UAnimInstance`,
+  `USceneComponent`, 18,566 files) — in an installed engine that is not every gameplay type, because
+  the ones shipped by plugins (`Mover`, `PoseSearch`, `PhysicsControl`, `BlendStack`, `SmartObjects`,
+  `StateTree`, `GameplayAbilities`) live under `Engine/Plugins/<Category>/<Plugin>/Source/<module>`.
+  Engine-scope indexes add the plugin roots the `.uproject` enables; the rest are opt-in via
+  `engineAreas: ["Plugins"]` (~2.8× the `Runtime` scan) or `["Plugins/Animation/PhysicsControl"]`
+  for one plugin. `Editor` and `Developer` are opt-in and roughly triple the scan.
+- pi-unreal answers C++ **declaration, module, include-path and dependency** facts. It does not
+  answer asset questions: UENUM index order (Blueprint enumerators are stored in index order, so
+  `4 = OnGround` is an asset fact), UStruct field types, UCLASS/CDO instance values, component
+  lists, parent chains, Blueprint graphs. Those need the `unreal-engine` editor MCP with the editor
+  running; a C++ scan cannot see them and must not pretend to.
 - Index reuse requires the *same root set*: an index built over two modules is never used to answer
   a `Runtime`-wide query. Partial coverage reported as an answer is worse than a rebuild.

package/extensions/unreal/index.ts

@@ -131,12 +131,20 @@ function engineLines(resolution: EngineResolution): string[] {
 	return lines;
 }
 
-function pluginLines(results: PluginReferenceResult[], limit: number): string[] {
+/**
+ * One line per `.uproject` reference, plus the modules that reference buys: the status alone never
+ * said which C++ a plugin contributes, so 'resolved' answered nothing about `UCharacterMoverComponent`.
+ * `index` adds the plugins the project does NOT reference: availability and reference status are
+ * different facts, and conflating them is what made 'no Mover reference' read as 'no Mover'.
+ */
+function pluginLines(results: PluginReferenceResult[], limit: number, index?: PluginIndex): string[] {
 	const lines: string[] = [];
 	const shown = results.slice(0, limit);
 	for (const result of shown) {
 		const status = result.plugin ? `${result.status} ← ${result.plugin.source}` : result.status;
-		lines.push(`  ${result.name}: ${status}`);
+		const modules = result.plugin?.modules ?? [];
+		const moduleText = modules.length ? ` · modules ${modules.map((module) => `${module.moduleName}(${module.type ?? "Runtime"})`).join(", ")}` : "";
+		lines.push(`  ${result.name}: ${status}${moduleText}`);
 		for (const note of result.notes) lines.push(`      · ${note}`);
 	}
 	if (results.length > limit) lines.push(`  … ${results.length - limit} more references (raise pluginLimit)`);
@@ -144,6 +152,12 @@ function pluginLines(results: PluginReferenceResult[], limit: number): string[]
 	for (const result of results) counts.set(result.status, (counts.get(result.status) ?? 0) + 1);
 	const summary = [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(", ");
 	lines.push(`  totals: ${summary} of ${results.length} references`);
+	if (index) {
+		const referenced = new Set(results.map((result) => result.name.toLowerCase()));
+		const free = index.entries.filter((entry) => entry.source === "Engine" && entry.enabledByDefault && !referenced.has(entry.name.toLowerCase()));
+		const names = [...new Set(free.map((entry) => entry.name))].sort((a, b) => a.localeCompare(b));
+		lines.push(`  engine plugins available with NO .uproject reference (EnabledByDefault true): ${names.length ? names.join(", ") : "none"}`);
+	}
 	return lines;
 }
 
@@ -381,7 +395,7 @@ const projectInspectTool = defineTool({
 			pluginResults.push(...resolveProjectPlugins(descriptor, built.index, resolution.version));
 			lines.push(`plugin index: ${built.index.scannedFiles} .uplugin over [${built.index.scannedDirs.join(" | ")}] (cache ${built.cache})`);
 			lines.push("plugin references:");
-			lines.push(...pluginLines(pluginResults, params.pluginLimit ?? 40));
+			lines.push(...pluginLines(pluginResults, params.pluginLimit ?? 40, pluginIndex));
 		} else {
 			lines.push(`plugin references: ${descriptor.plugins.length} declared, not resolved against disk`);
 		}
@@ -514,7 +528,7 @@ async function reportProject(args: string, ctx: ExtensionCommandContext): Promis
 		if (resolution.status !== "unresolved") {
 			const built = await getIndexFor(resolution.engineRoot, projectDirOf(descriptor), descriptor, resolution.version);
 			lines.push(`plugin index: ${built.index.scannedFiles} .uplugin (cache ${built.cache})`);
-			lines.push(...pluginLines(resolveProjectPlugins(descriptor, built.index, resolution.version), 25));
+			lines.push(...pluginLines(resolveProjectPlugins(descriptor, built.index, resolution.version), 25, built.index));
 		}
 	}
 	ctx.ui.notify(truncateLines(lines.join("\n"), 40).text, "info");