docs: document simulation readability layer

docs/ACTION_SYSTEM_ARCHITECTURE.md

@@ -23,7 +23,8 @@ SimulationManager tick
 - reads NPC and village state;
 - evaluates current utility scores;
 - consumes the NPC's deterministic decision RNG;
-- returns an action ID and optional urgent-duration override;
+- returns an action ID, optional urgent-duration override, branch reason, and
+  compared utility scores;
 - does not mutate targets, navigation, or visuals.
 
 ### ActionExecutionSystem
@@ -60,6 +61,8 @@ SimulationManager tick
 SimulationManager remains the orchestrator and event boundary. It owns
 simulation records, invokes the focused systems, stores selected actions and
 targets, and translates presentation callbacks into simulation transitions.
+It also publishes the latest `ActionSelectionResult` for presentation; the UI
+does not recompute decisions.
 Further decomposition should follow measured pressure rather than splitting it
 into managers for their own sake.
 

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -460,6 +460,13 @@ Add presentation for systems that already exist:
 Do not fake activity that contradicts simulation state. A farmer icon should
 represent a real chosen task.
 
+**Status: core readability complete.** Profession definitions now drive
+distinct NPC colors and props, world labels identify each villager, and the
+Tab-cycled inspector shows authoritative need values, task state, destination,
+decision branch, and utility scores. The existing carried-food prop and village
+panel expose immediate consequences. A cinematic/debug toggle and repeatable
+demo reset remain Phase 6 capture tooling.
+
 ### Exit condition
 
 A viewer can distinguish at least three professions and understand one NPC's
@@ -617,7 +624,7 @@ Completed:
 Next:
 
 1. Capture and visually review “Jajce Lookdev 01.”
-2. Add profession/readability presentation and the reason inspector.
+2. Add the cinematic/debug toggle and repeatable demo reset.
 3. Capture “Simulation Garden 01.”
 
 Do not start with GIS data, a full city, a large asset pack, or more NPC

docs/LEARNING_ROADMAP.md

@@ -647,12 +647,14 @@ Completed after the architecture gate:
 - an integrated Jajce beauty baseline with shaped Terrain3D data, a bounded
   six-layer palette, atmospheric lighting, shader water, foliage motion,
   building blockouts, and visible smoke/mist.
+- definition-driven profession colors/props and a selected-NPC inspector fed
+  by real decision branches, destinations, needs, and utility scores.
 
 The practical next sequence is:
 
-1. Capture and visually review the bounded Jajce look-development shot.
+1. Replace the remaining generic activity markers with typed world sites,
-2. Add stylized character and profession readability plus the reason
+   beginning with the pantry/storage presentation.
-   inspector.
+2. Add a cinematic/debug toggle and repeatable simulation-garden demo reset.
 3. Expand persistence only when schedules, player state, or a real save menu
    creates a concrete requirement.
 

docs/PROJECT_CONTEXT.md

@@ -342,8 +342,11 @@ A small village panel displays:
 - knowledge;
 - starving NPC count;
 - selected village modifiers.
+- a Tab-cycled NPC inspector with profession, needs, task state, destination,
+  decision reason, and utility scores.
 
-Most deeper reasoning is currently visible only through verbose debug output.
+NPC name/profession labels, definition-driven colors and props, and the
+carried-food visual make active simulation state readable in the world.
 
 ## Runtime architecture
 
@@ -518,7 +521,8 @@ These are expected prototype constraints, not necessarily isolated bugs:
   and the village pantry.
 - NPCs do not have homes, schedules, possessions, memories, relationships,
   goals, or social knowledge.
-- NPC reasoning is logged but not presented through an in-game inspector.
+- The reason inspector exposes current decisions, but deeper historical traces
+  and rejected preconditions are not yet retained.
 - Active navigation is used as if all agents are local; no simulation LOD exists.
 - Unloaded traveling NPCs preserve their state but do not yet advance through
   abstract travel time.

docs/SIMULATION_DEFINITIONS.md

@@ -32,8 +32,9 @@ instead of maintaining a separate gather-action map.
 
 ## Current profession contract
 
-Each profession definition contains a stable `profession_id` and display name.
+Each profession definition contains a stable `profession_id`, display name,
-The current professions are farmer, woodcutter, guard, scholar, and wanderer.
+body color, and prop color. The current professions are farmer, woodcutter,
+guard, scholar, and wanderer.
 
 NPC generation chooses from the registry's stable IDs. NPC state stores and
 restores those IDs as `StringName`, and rejects records that reference an
@@ -67,7 +68,7 @@ the prototype. They do not yet own:
 - reservation strategy;
 - detailed target-selection policy beyond current resource/activity/free
   metadata;
-- presentation hints beyond target type.
+- richer presentation hints beyond the current profession palette.
 
 Selection, execution, target resolution, and visual travel are now separate
 responsibilities. The remaining concerns should move into definitions only