feat: add nearby villager field notes

docs/ACTION_SYSTEM_ARCHITECTURE.md

@@ -171,6 +171,24 @@ State restore clears active feedback and re-derives the prompt from current
 simulation and loaded-world facts. The HUD is separate from development
 overlays so the embodied action remains legible in cinematic mode.
 
+## Player villager-inspection contract
+
+`WorldViewManager.find_nearest_active_npc_id()` resolves only loaded, living
+NPC presentations within the player's bounded range. It compares presentation
+positions and uses stable NPC ID order for equal distances; it does not inspect
+tasks or choose actions. `Player.get_nearby_villager_inspection()` reacquires
+that ID from the manager's current `SimNPC` records and constructs one
+ephemeral `VillagerInspectionResult` from the authoritative name, action, task
+state, exact target ID, and carried inventory.
+
+The optional decision reason is honest only when the current transient
+`ActionSelectionResult` still names the NPC's live action. A missing or stale
+trace renders `Awaiting the next decision`. `VillagerFieldNoteHud` formats that
+result in a separate player-facing layer, so observation never changes `E`
+priority or execution. Visual unload removes the context, while restore
+reacquires the newly reconstructed NPC record and derives saved facts again;
+neither the selection, result, nor HUD enters simulation state or checksums.
+
 ## Compound animal-care delivery contract
 
 NPC `feed_animal` remains one task and one exact animal claim across two travel

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -829,15 +829,22 @@ Completed:
     food sack; delivery consumes that unit and records the inventory-to-animal
     fact. One-unit contention, both route legs, and post-pickup continuation
     prove conservation without adding a saved phase field.
+45. `Jajce Villager Field Note 12`: a quiet bottom-left field note now selects
+    the nearest loaded living villager with stable-ID tie order and presents
+    their authoritative name, current action and task state, exact target, and
+    carried inventory. A decision reason appears only while it matches the live
+    action; unload clears the note and restore re-derives saved facts while
+    awaiting the next transient reason. The note coexists with the `E` prompt,
+    remains in cinematic mode, and adds no saved state or simulation mutation.
 
 Next:
 
-1. Give the player one restrained nearby-villager inspection context backed by
-   the authoritative task, exact target, carried item, and recorded decision
-   reason when it currently exists.
-2. Prove that the field note follows live task changes and, after restore,
-   re-derives the persistent facts while honestly awaiting the next decision
-   reason. It must not become dialogue, quest, or saved presentation state.
+1. Let an inspected villager who owns an open opportunity surface that exact
+   village need plus the authoritative direct-help route, capable helper, or
+   honest unavailable state that currently exists.
+2. Prove that the ordinary finite-resource-to-storage harvest resolves an
+   available player route and updates the context without dialogue branching,
+   acceptance state, rewards, a quest log, or saved presentation state.
 
 Do not start with GIS data, a full city, a large asset pack, or more NPC
 mechanics. The next proof is a beautiful stage for the systems that already

docs/LEARNING_ROADMAP.md

@@ -965,16 +965,33 @@ the losing claim. A post-pickup restore preserves the inventory, exact goat,
 destination, event count, and final checksum without a new saved phase field
 or RNG draw.
 
-The next bounded slice should advance Milestone 9 with player-facing villager
-inspection. One nearby-person context should show the authoritative name,
-current action, exact target, carried item, and current recorded decision reason
-when available. After restore it should honestly say that it is awaiting the
-next decision while the other facts re-derive. Do not add dialogue, trade,
-reputation, quest state, breeding, products, herd scheduling, animal indexing,
-or active/abstract animal LOD in that slice.
+Player-facing villager inspection now advances Milestone 9 without stealing the
+existing `E` action. A quiet cardless field note chooses the nearest loaded,
+living villager with stable-ID tie order, then re-reads that NPC's authoritative
+name, action, exact target, task state, and carried inventory. It includes the
+latest decision reason only while that trace still matches the live action.
+Presentation unload clears the note; restore reacquires the replacement NPC
+record, re-derives every saved fact, and honestly awaits the next ephemeral
+decision reason. The query and HUD add no mutation, RNG draw, or saved state.
+
+The next bounded slice should move from observation to one honest social
+affordance. When the nearby inspected villager is the interested person for an
+open village opportunity, surface that exact need. Show the already-proven
+finite-resource-to-storage route only when the authoritative player-response
+query can currently derive it; otherwise name the capable helper or honestly
+say why direct help is unavailable. Let the ordinary finite-resource harvest
+resolve the need without adding a dialogue tree, quest acceptance, rewards, a
+quest log, reputation, a generic conversation framework, or saved presentation
+state in that slice.
 
 Recently completed:
 
+- `Jajce Villager Field Note 12`: a separate player-facing note selects the
+  nearest loaded living villager and shows live name, action, task state, exact
+  target, carried inventory, and a currently matching decision reason. It
+  coexists with the `E` prompt, survives cinematic mode, clears on visual
+  unload, and re-derives saved facts after restore without reviving transient
+  reasoning or changing the schema.
 - `Jajce Care Delivery 11`: NPC `feed_animal` is now one compound, two-leg
   action from the real pantry through caretaker inventory to the exact reserved
   goat. Carried presentation, ordered transfer facts, late contention,

docs/PROJECT_CONTEXT.md

@@ -491,10 +491,11 @@ that receives the command.
 The UI subscribes to village, task, event, knowledge, relationship, and
 opportunity changes. It formats aggregate state and resolves known facts,
 relationship causes, and opportunity lifecycle details through manager queries
-without owning or recomputing simulation facts. `village_whisper_hud.gd` and
-`player_interaction_hud.gd` are separate transient player layers that format
-authoritative signals or the current exact context and remain independent of
-the development overlays.
+without owning or recomputing simulation facts. `village_whisper_hud.gd`,
+`player_interaction_hud.gd`, and `villager_field_note_hud.gd` are separate
+transient player layers. They format authoritative signals, the current exact
+action context, or one nearby villager's current facts while remaining
+independent of the development overlays.
 
 ## Current runtime flow
 
@@ -1023,11 +1024,17 @@ Milestone 9 context-action result shared by prompt and execution, with exact
 pantry feedback and no persistent UI state. NPC care now completes that
 physical proof with one compound pantry-to-inventory-to-goat action, exact
 claim continuity, visible carrying, late-contention safety, and post-pickup
-deterministic continuation. The next bounded proof should let the player
-inspect one nearby villager's real action, target, carried item, and recorded
-decision reason when available. After restore it should re-derive persistent
-facts and honestly await the next decision reason without introducing dialogue
-or saved UI state.
+deterministic continuation. Nearby villager inspection now selects one loaded
+living presentation, reacquires its authoritative simulation record, and shows
+the live action, task state, exact target, carried inventory, and only a
+currently matching decision reason. It remains separate from `E`, clears on
+presentation unload, and after restore re-derives saved facts while awaiting a
+new transient decision trace. The next bounded proof should let an inspected
+interested villager surface their exact open opportunity and whichever
+authoritative response currently exists: a finite-resource-to-storage player
+route, a capable helper, or an honest unavailable state. An available player
+route should resolve through the ordinary harvest path without dialogue
+branching, quest acceptance, rewards, or saved UI state.
 
 The remaining simulation-garden target still aims for: