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