feat: surface player routes for village needs

docs/ARCHITECTURE_OVERVIEW.md

@@ -48,7 +48,10 @@ would otherwise obscure that lifecycle:
   work wood consumers. It also derives one ephemeral `OpportunityHelperResult`
   from knowledge, directed relationships, inventory, action definitions, and
   finite-resource state without changing resources or assigning tasks. The
-  ordinary action selector consumes that result only for the matching idle NPC;
+  ordinary action selector consumes that result only for the matching idle NPC.
+  When no such helper exists, it can separately derive an ephemeral
+  `OpportunityPlayerResponseResult` from the real destination capacity and
+  enabled player-usable finite sources;
 - `simulation/persistence/` owns save-slot file safety;
 - `simulation/state/` owns versioned serialized record contracts;
 - `simulation/definitions/` owns stable IDs and immutable action/profession
@@ -98,8 +101,9 @@ improving ownership.
   Relationship cues, interested-villager concern, physical pantry stock, and
   refill feedback consume authoritative state or state-change signals and are
   intentionally absent from saves and checksums. The transient village-whisper
-  HUD likewise formats need, transfer, response, and resolution signals without
-  owning them. Stable visuals are rebuilt from state after restore; transient
+  HUD likewise formats need, player route, transfer, response, and resolution
+  signals without owning them. It drops the player route when a capable helper
+  emerges. Stable visuals are rebuilt from state after restore; transient
   reactions are not replayed.
 - Resource changes go through `ResourceStateRecord`, NPC inventory, and
   `VillageEconomy`; `village.food` and `village.wood` are synchronized views.

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -746,13 +746,17 @@ Completed:
     informed trusted helper to respond autonomously. One cardless warm-amber HUD
     ribbon gently rises, pulses, and fades through need, named report, response,
     and resolution beats while remaining separate from development overlays.
+31. Player response whisper: when no capable helper exists, the same ribbon now
+    derives one concise ordinary harvest route from current player-usable finite
+    resources and the real pantry or woodpile. It clears when help emerges or
+    the need closes, and adds no quest, waypoint, tracker, or saved UI state.
 
 Next:
 
-1. When no capable helper exists, show one contextual player response hint
-   derived from a current player-usable finite source and the real storage
-   target. Clear it as soon as help emerges or the need closes; do not add quest
-   acceptance, waypoint state, or a generic tracker, as sequenced in
+1. Begin Milestone 8 with a deterministic headless scaling baseline over
+   increasing NPC and event counts. Measure current tick throughput,
+   serialized-state growth, and retained history before choosing a target
+   population or adding spatial partitions and simulation LOD, as sequenced in
    `LEARNING_ROADMAP.md`.
 
 Do not start with GIS data, a full city, a large asset pack, or more NPC

docs/LEARNING_ROADMAP.md

@@ -822,12 +822,38 @@ The first direct information-to-help path is complete:
   helper response, and resolution. It is signal-driven, survives debug-overlay
   hiding, and neither serializes nor replays after restore.
 
-Milestone 7 is not complete. The immediate next slice should expose one bounded
-player response affordance when an open need has no capable helper: derive a
-concise contextual hint from the existing player-usable finite source and real
-storage target, then clear it when a helper emerges or the need closes. Reuse
-the current interaction/economy rules; do not add quest acceptance, waypoint
-state, or a generic objective tracker.
+The bounded Milestone 7 player-response affordance is complete:
+
+- an open need with no capable helper derives one ephemeral
+  `OpportunityPlayerResponseResult` only when its real storage target has room
+  and at least one matching enabled, stocked, player-usable finite source
+  exists;
+- the result exposes the ordinary gather action, resource, destination, source
+  count, opportunity, and trigger IDs without selecting a waypoint, accepting a
+  quest, drawing RNG, or mutating simulation state;
+- the existing cardless village-whisper ribbon says `YOU CAN HELP` and explains
+  the direct resource-to-storage interaction in one line, while the development
+  summary exposes the exact derived route;
+- knowledge, relationship, inventory, or village-resource changes track the
+  derived route in both directions: a newly unassisted need can surface the
+  hint once, a capable helper removes it immediately, and resolution or
+  invalidation replaces it with the existing close beat;
+- reserved resources remain honestly player-usable because the current player
+  extraction contract does not consume NPC reservations, while disabled,
+  depleted, wrong-resource, and capacity-blocked sources do not qualify;
+- unit, headless lifecycle, restore/checksum, real player extraction, and Jajce
+  runtime regressions cover the slice without persisting or replaying HUD state.
+
+This completes the bounded Milestone 7 simulation-garden proof. A known and
+cared-about shortage now produces an inspectable opportunity whose NPC and
+player responses both use the originating resource, relationship, knowledge,
+and event systems rather than quest-only duplicates.
+
+The immediate next slice should begin Milestone 8 with a deterministic headless
+scaling baseline: measure tick throughput, serialized-state growth, and retained
+history across increasing NPC/event counts using the current full-fidelity
+simulation. Set an evidence-backed target before adding spatial partitions,
+batching, or active/abstract LOD transitions.
 
 Recently completed:
 

docs/PROJECT_CONTEXT.md

@@ -935,11 +935,18 @@ re-derived and autonomously responds through ordinary action selection. A
 single cardless warm-amber HUD ribbon presents the real need, named report,
 helper response, and resolution without entering simulation or save state.
 
-Milestone 7 remains in progress. The immediate next slice should add one
-bounded player response hint only when no capable helper exists, derived from
-the current player-usable finite source and real destination. It should clear
-when help emerges or the need closes, without quest acceptance, waypoint state,
-or a generic tracker.
+The bounded Milestone 7 player response is complete. When no capable helper
+exists, an ephemeral query now proves an enabled player-usable finite source and
+real destination with capacity. The warm-amber whisper briefly explains the
+ordinary direct harvest route, then yields immediately when a helper emerges or
+the need closes. The result and HUD add no quest acceptance, waypoint, tracker,
+save field, RNG draw, or simulation mutation. This completes the Milestone 7
+simulation-garden exit proof.
+
+The next slice should start Milestone 8 with a deterministic headless scaling
+baseline over increasing NPC and event counts. Measure tick throughput,
+serialized-state growth, and retained history before selecting a target
+population or implementing spatial partitions and active/abstract LOD.
 
 The remaining simulation-garden target still aims for:
 

docs/SIMULATION_STATE_SCHEMA.md

@@ -196,10 +196,13 @@ lasting during deterministic memory maintenance. Resolution or invalidation
 releases that fact back to the normal bounded-retention rules; neither deletes
 objective event or opportunity history.
 
-`OpportunityHelperResult` is deliberately absent from this schema. It is
-re-derived from the open opportunity plus current NPC knowledge, directed
-relationship, inventory, action-definition, storage-capacity, and finite-
-resource records. Save/restore regressions require the same helper/action/route
+`OpportunityHelperResult` and `OpportunityPlayerResponseResult` are deliberately
+absent from this schema. The helper result is re-derived from the open
+opportunity plus current NPC knowledge, directed relationship, inventory,
+action-definition, storage-capacity, and finite-resource records. The player
+result additionally requires no capable helper and derives its ordinary gather
+action, real destination, and source count from current enabled player-usable
+finite resources. Save/restore regressions require the same applicable route
 result and an unchanged checksum before and after querying.
 
 When an idle derived helper chooses the reported supply action, only the
@@ -209,8 +212,8 @@ and independently re-derives current capability from restored facts.
 
 Active-need communication adds no schema fields. It persists through the
 existing `KnownEventStateRecord` event, listener, source NPC, direct source
-method, and acquisition-tick fields. Communication/HUD animations are transient
-and are cleared rather than replayed after restore.
+method, and acquisition-tick fields. Communication and player-response HUD
+animations are transient and are cleared rather than replayed after restore.
 
 ## Resource authority