@aeonsparx/pi-unreal 0.0.0-stage → 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aeonsparx Interactive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
+# pi-unreal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Unreal Engine awareness for the Pi coding agent.**
+
+Open a UE project in a `pi` session and the agent stops guessing. It knows which engine
+installation that `.uproject` really resolves to, what the `.uproject` / `.uplugin` files actually
+say, which plugins exist on disk, and where a C++ symbol is declared — with the file, the line and
+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
+`.uproject` — the working directory itself, or any of up to 3 parent directories — one note is
+shown before the first answer: the resolved engine root and version, installed vs source build,
+the project's modules, the number of declared plugin references, and the conventions below. Ask
+for a re-check any time with `/unreal`.
+
+**Ask in plain English.** "Which engine is this project on?", "Is MassGameplay available to this
+project?", "Where is `FLpMovementDirectionThresholds` defined?", "What do I need to link to use
+`UAnimInstance`?" The agent picks the matching tool:
+
+| Tool | Question it answers |
+| --- | --- |
+| `unreal_resolve_engine` | "Which engine does this `.uproject` use — and how do you know?" |
+| `unreal_project_inspect` | Modules, target platforms, and every plugin reference resolved against the plugins that exist on disk |
+| `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; 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:**
+
+| Command | Result |
+| --- | --- |
+| `/unreal [project]` | Engine, modules and plugin-reference report for this directory |
+| `/unreal-engines` | Every engine installation this machine can prove, and how each was found |
+| `/unreal-symbol <symbol>` | Definition lookup, project + plugins, then engine if an engine index exists |
+| `/unreal-module <Module>` | Module directory, public/private dependency lists, defines file, C++ standard, SDK |
+| `/unreal-cache stats\|clear` | Inspect or clear the cached indexes |
+
+Example — `/unreal`:
+
+```text
+project  C:/Work/Lp/Lp.uproject
+engine: C:/Program Files/Epic Games/UE_5.8
+  version 5.8.3 | installed build | association "5.8" (version) via dir-scan
+  Build.version: C:/Program Files/Epic Games/UE_5.8/Engine/Build/Build.version
+modules: Lp (Runtime), LpEditor (Editor)
+plugins declared: 25
+plugin index: 897 .uplugin (cache hit)
+plugin references:
+  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):
+
+```text
+unreal_symbol 'AActor' scope=engine: 1 definition(s)
+  class AActor  C:/Program Files/Epic Games/UE_5.8/Engine/Source/Runtime/Engine/Classes/GameFramework/Actor.h:282  [Engine · engine]
+```
+
+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 |
+| --- | --- |
+| An edit targeting `*.uasset` / `*.umap` | **Blocked** — those are cooked binary assets; author them in the running editor |
+| A C++ edit while `UnrealEditor` is running | **Warning** — freshly compiled C++ will not load into a running editor; close it, then build |
+| `clang-format` aimed at a `*.cs` file | **Blocked** — clang-format applies the C# rule and can empty the file |
+
+## Costs: what is fast, and what is opt-in
+
+| Operation | Time |
+| --- | --- |
+| Cached lookup (symbol, project facts) | ~0.3 s |
+| First project/plugin index (≈2,400 files) | seconds |
+| Engine `Runtime` index — cold | ~1 minute |
+| Engine `Runtime` index — warm | ~6 s |
+| UnrealBuildTool Query facts | ~7 s, then cached |
+| clangd compile database (`unreal_index` → `compiledb`) | minutes, ~1 GB for the engine scope |
+
+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 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
+  Unreal index" (that is `refresh: true`).
+- Everything lives in `~/.pi/agent/unreal-cache` (override with `$PI_UNREAL_CACHE_DIR`) — never
+  inside your project tree or your engine installation. The compile database encodes this
+  machine's absolute paths, so it is machine-local by design.
+
+## Troubleshooting
+
+| Report | What to do |
+| --- | --- |
+| `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` | 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
+
+- 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. 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.

package/docs/internals.md

@@ -0,0 +1,245 @@
+# pi-unreal internals
+
+Design and implementation notes: how the tools derive their answers, and the measured numbers behind
+the cost model. Read the README for day-to-day usage; this file is the engine-facing detail that
+the README deliberately leaves out.
+
+## Symbol index (no compiler, no IDE)
+
+`unreal_symbol`, `unreal_context`, and `unreal_index` answer navigation questions from two
+compiler-free sources:
+
+1. **UnrealBuildTool Query** (`-Mode=Query`: `TargetDetails`, `TargetModuleReferences`) — the
+   engine's own record of targets, modules, module dependencies, include paths, and forced
+   includes. Measured on UE 5.8: 6.0 s for 1,079 modules, 2.1 s for the dependency graph, and it
+   needs no compiler. That is why MSVC-only machines (Visual Studio, Rider) are first class here:
+   Visual Studio's `Browse.VC.db` is encrypted with no public API, Rider's resolver is in-process
+   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. 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
+index only if one exists; `scope: "engine"` on a cold machine returns
+`engine index not built — build it with unreal_index (action: "build", scope: "engine")` instead of
+spending minutes on a scan nobody asked for. `unreal_index` is the explicit, paid path.
+
+Ranking inside `unreal_symbol`: exact (0) → qualified member (1) → prefix (2) → substring (3).
+Forward declarations rank last, so `unreal_symbol AActor` returns
+`Engine/Source/Runtime/Engine/Classes/GameFramework/Actor.h:282` (the `UCLASS` declaration), not
+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. 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 —
+`Intermediate/Build/<Platform>/<Config>/<Target>/Development/<Module>/Definitions.<Module>.h` —
+and `unreal_context` reads that file instead of guessing `WITH_*` values. Query is also never
+run with `-NoIntellisense`: that flag produces a syntactically valid skeleton with an empty
+`moduleToCompileSettings`, and `payloadOk()` rejects it.
+
+## clangd enrichment (`unreal_index` action `compiledb`)
+
+The definition index is the compiler-free path. When you want clangd's semantic power (references,
+call hierarchy, diagnostics), the database it needs comes from the engine: `UnrealBuildTool
+-Modes=GenerateClangDatabase`, normalized in the pi-unreal cache.
+
+The UnrealBuildTool invocation is the part nobody documents, so it is encoded in one place
+(`lib/compiledb.ts`):
+
+- The target is **three positional tokens** — `Win64 Development LpEditor`. `TargetDescriptor` only
+  inspects arguments that do not start with `-`, and its `+` split requires every token to be the
+  same kind, so `-Target=LpEditor` fails with `No platforms specified for target` and
+  `Win64+Development+LpEditor` fails with `The platform name Development is not a valid platform
+  name`. `-Platform=`/`-Configuration=` set `BuildConfiguration` only and produce a duplicate
+  platform error next to the positional tokens.
+- `-OutputDir=` must already exist (UnrealBuildTool throws
+  `DirectoryNotFoundException: Could not find a part of the path ...\compile_commands.json`), and
+  the mode's own `-NoPCH -NoVFS -Compiler=Clang` additions mean the emitted driver is
+  `clang-cl.exe`, not `cl.exe`.
+- `-Include=` rules match nothing useful (measured: `Source/Lp`, `*/Source/Lp/*`,
+  `C:/Users/.../Source/Lp/**` all yield an empty database), so scoping happens after generation.
+
+Normalization is Epic's `stripPostPch.py` recipe, ported: expand the per-module `@file.rsp`
+response files, drop `/Yu* /Fm* /Fe* /Fp*` and everything after `/link`, drop PCH translation
+units (`SharedPCH.*.h.cpp`, `PCH.*.h.cpp`) and header entries, then keep the requested scope. The
+database is written to `$PI_UNREAL_CACHE_DIR/compiledb/<target>.<platform>.<config>/` — it encodes
+this machine's absolute paths and toolchain version, so it is a machine artifact, never a repo one.
+
+`check: "<file>"` runs `clangd --check` against the result, which is the acceptance test. Measured
+on Lp (UE 5.8.3, installed engine, VS 18 LLVM clangd): UnrealBuildTool 1.5-1.7 s, 4 entries,
+4 response files expanded, 0 switches dropped; `clangd --check` built a 62 MB preamble and
+reported **`All checks completed, 0 errors`** in ~2.6 s.
+
+The honest limits of that 4-entry number: an installed (precompiled) engine contributes no compile
+actions, so the database covers the project's own translation units, not `Engine/Source`. Engine
+files still work under clangd because the project's `.clangd` supplies the include paths — exactly
+what Epic's Unreal-clangd VS Code extension does (its generated `Lp.0.rsp` contains only `/FI`
+plus 523 `/I` lines, and `compile_commands.json` there has 6 project entries and no engine entry).
+Re-run with `refresh: true` after changing `Build.cs` files, adding modules, or switching engine
+version.
+
+## How engine resolution works
+
+Mirrors `FDesktopPlatformWindows::GetAvailableEngineDescriptions`
+(`Engine/Source/Developer/DesktopPlatform/Private/DesktopPlatformBase.cpp:459-511`) and
+`VerifyEngineGuid` (`DesktopPlatformWindows.cpp:615-664`):
+
+| `.uproject` association | Source of truth |
+| --- | --- |
+| engine-root path | used directly, validated |
+| `5.8` (Launcher install) | `HKLM:\SOFTWARE\EpicGames\Unreal Engine\<ver>` → `InstalledDirectory`, then `<installDirDefault>\UE_<ver>` |
+| `{GUID}` (source build) | `HKCU:\SOFTWARE\Epic Games\Unreal Engine\Builds` |
+| empty | walk up 12 levels looking for `Engine/Config/BaseEngine.ini` |
+
+Below the association: `LauncherInstalled.dat`, `HKLM` versions, `UNREAL_ENGINE` / `UE_ROOT` /
+`PI_UNREAL_ENGINE_ROOT`, and a scan of `C:/Program Files/Epic Games` for `UE_*`. Explicit
+`engineRootHint` outranks every registry source.
+
+Every candidate is validated before use — `Engine/Binaries` + `Engine/Build`
+(`DesktopPlatformBase.cpp:401-421`) **and** `Engine/Build/Build.version` matching the
+association. Stale registry keys and env pointers are reported as rejected candidates with the
+reason, never silently dropped. One survivor → `resolved`; several → `ambiguous`; none →
+`unresolved` + remediation. Nothing is ever written back to the registry.
+
+Registry reads run through one memoized `pwsh -NoProfile` snapshot (8 s timeout). If `pwsh` is
+missing the snapshot degrades to `available: false` and the resolver continues with
+file-based sources — the extension never fails at import time.
+
+## Plugin discovery
+
+Mirrors `UnrealBuildTool.System.ReadAvailablePlugins` (`System/Plugins.cs:322`):
+Engine `Engine/Plugins` → Project `Plugins/` → Mod `Mods/` → `AdditionalPluginDirectories`,
+with later scans shadowing earlier ones on name collision. `Binaries/`, `Intermediate/`,
+`Saved/`, `.git/`, `ThirdParty/` are skipped. Reference semantics mirror `PluginManager`:
+`Enabled` / `Optional` / `Activate` (`PluginReferenceDescriptor.cpp:132-172`); an engine-version
+mismatch is a warning, not an error (`PluginManager.cpp:2690-2712`).
+
+Indexes are cached on disk keyed by the mtime of every scanned directory plus the engine
+changelist, with a 10-minute backstop (`MAX_AGE_MS`) because content-only `.uplugin` edits do
+not move the parent directory's mtime.
+
+## Descriptor fidelity
+
+Field names, host types, and loading phases are transcribed from the engine's serializers
+(UE 5.8): `ProjectDescriptor.cpp:100-225`, `PluginDescriptor.cpp:263-409`,
+`ModuleDescriptor.cpp`, `PluginReferenceDescriptor.cpp:130-180`, cross-checked against 897
+`.uplugin` files in UE 5.8 `Engine/Plugins`. Consequences:
+
+- `.uproject` / `.uplugin` are parsed as JSONC (comments and trailing commas are legal in the
+  engine's reader).
+- `Modules` is an array of objects keyed by `Name`; `Type` is required
+  (`Found Module entry 'X' with a missing 'Type' field`), `LoadingPhase` defaults to `Default`.
+- A plugin reference without `"Enabled"` is rejected by UE 5.8 — reported, not guessed.
+- Unknown keys are reported as `… is not serialized by FPluginDescriptor`, and the known-key
+  set is wide enough (including legacy `Whitelist*`/`Blacklist*` and pre-5.x keys) that genuine
+  engine files produce no noise.
+- `.uplugin` has no `Enabled` key; enablement is `EnabledByDefault` + the project reference.
+- `IsBetaVersion` is metadata in UE 5.8 (no engine/UBT beta gate exists).
+
+## Known limits
+
+- Registry access needs `pwsh` (PowerShell 7). Without it, registry sources are unavailable and
+  resolution relies on env, directory scans, and inline associations.
+- `unreal_resolve_engine` reports what the machine can prove. It does not install, register, or
+  migrate engines, and never writes registry keys (the engine's `RegisterEngineInstallation`
+  does; this package deliberately does not).
+- v1 is inspection only. `.ini` provenance is out of scope.
+- The definition index is a scanner, not a parser: it finds declarations (`class`, `struct`,
+  `enum`, `union`, `UFUNCTION`/`UPROPERTY`/`UCLASS`-marked members, delegates, aliases) and
+  records `Owner:Member` qualified names. It does not resolve types, overloads, call sites, or
+  inheritance — that is what clangd is for when it is installed. Macro-heavy code can still be
+  misread: the scanner is regex-based, so a definition hidden inside an unusual macro spelling may
+  be missed, and `#if` branches are all recorded (a symbol declared in a disabled branch is a
+  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 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
+  still produced and reported; only the check is skipped.
+- 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 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.