feat: add model-backed NPC society dialog

CHANGELOG.md

@@ -16,6 +16,30 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots.
 - Human-believable NPC agent design doc covering trait axes, relationship
   ledger, memory tiers, needs, mood, stress, proactive communication, and
   research anchors for LLM-driven NPC behavior.
+- NPC society multi-agent architecture research doc covering Convai-inspired
+  character product patterns, centralized society orchestration, shared
+  blackboard memory, per-agent memory, relationship ledgers, conversation
+  turn-taking, LLM scheduling, and Unity/Fusion/Nakama/api.dos.ai boundaries.
+- Nakama NPC decision prompts now include compact `KnowledgePack` context for
+  Vinh Hai Relay Ward public lore, early Nibirium era timing, BodyTime,
+  SECOND, Frames, Gates, factions, professions, quest hints, public rumors,
+  and selected private memory. Public packs are authored as versioned JSON
+  content, generated into the Nakama runtime registry, seeded into Nakama
+  storage on module load, and recorded by selected knowledge pack id in
+  PromptTrace. Private memory packs are assembled at runtime from bounded
+  per-body memory records.
+- Convai deep architecture audit covering its reactive plus reasoning mind
+  pattern, Live APIs, Mindview-style prompt tracing, Knowledge Bank context
+  packs, Narrative Design objectives, Action API discipline, External API
+  tool schemas, State of Mind observability, and contextual animation lessons
+  for SECOND SPAWN.
+- OpenClaw agent connection architecture covering onboarding, OAuth/device-code
+  auth, capability grants, actor binding, context pull and intent submit
+  contracts, rate limits, moderation, revocation, skill/plugin packaging,
+  failure modes, and phase plan.
+- Story bible defining the first playable narrative hook, Relay Yard hub, Ash
+  Underpass Gate, Tollkeeper boss, starting quest beats, factions, named NPC
+  archetypes, and LLM NPC story consistency rules.
 - Unity `NetworkPlayer` now carries prototype level, combat stats, BodyTime,
   lifecycle, SECOND balance, reincarnation count, visual key, and agent-control
   state as networked fields.
@@ -80,6 +104,70 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots.
   `secondspawn_npc_context_get` returns context plus interaction rules, and
   `secondspawn_npc_intent_submit` validates bounded `say` intents against
   distance, hostility, affinity, and repeated-interaction rules.
+- Unity now has a nearby NPC chat box that sends player lines to local NPC
+  brains, adds recent player speech into the model decision context, and keeps
+  NPC talk visuals facing the addressed actor while temporarily hiding weapons.
+- Nearby player chat now shows a speech bubble over the local player and
+  interrupts NPC cooldowns when a fresh nearby player message arrives.
+- Nearby player chat now also records a Nakama `player_chat_nearby_npc`
+  society event and writes heard-player-chat memories onto nearby permanent
+  NPC profiles, giving the future `NpcSocietyOrchestrator` a server-owned event
+  feed instead of only local Unity context.
+- Nakama now exposes a prototype `secondspawn_npc_society_tick` RPC that reads
+  recent society events and returns eligible NPC decision candidates without
+  mutating world state or bypassing validated intent RPCs.
+- The society tick now creates a server-owned `ConversationSession` scaffold
+  for nearby player chat, including participants, trigger event, objective, and
+  turn cap for later multi-turn NPC coordination.
+- Unity nearby NPC chat now consumes the `secondspawn_npc_society_tick` queue,
+  so NPCs only receive the player line after Nakama has accepted the society
+  event and selected eligible responders. Local delivery remains as a fallback
+  if the prototype backend path fails.
+- Nakama NPC `say` intents now write `npc_speech` society events and advance
+  the associated `ConversationSession` transcript and turn counter, giving the
+  society orchestrator durable conversation state instead of a one-shot event
+  queue.
+- Local Fusion dev-build tooling now builds a Windows development client and
+  launches a second local process as host, client, or server with unique local
+  Nakama prototype identity flags.
+- Prototype visual hotkeys now reserve `E` for talking to the nearest NPC and
+  move pickup animation to `F`; the network `Interact` input remains on `E`.
+- Nakama reactive fallback now answers nearby player chat before choosing a
+  movement fallback, and movement fallback uses each NPC's behavior tendency
+  instead of sending every NPC along the same patrol offset.
+- Nakama model prompts now include a compact `persona_card` with each NPC's
+  role, faction, home base, voice anchor, conflict, rumor, memory hook, and
+  behavior hints so DOS.AI has stronger per-NPC context without loading the
+  whole GDD.
+- Reactive fallback speech now varies by NPC greeting tone, home base, idle
+  action, and memory hook, so degraded mode still sounds like different Frames.
+- Prototype HUD now surfaces the inhabited body's name, profession, age, home
+  base, and first memory hook so login visibly feels like entering a specific
+  existing Frame.
+- Roadmap now converts the Convai-pattern research into concrete backlog lanes
+  for PromptTrace, Knowledge Packs, ConversationObjective, State of Mind, and
+  debug inspection while keeping Nakama, Fusion, and `api.dos.ai` as the
+  long-term backbone.
+- Roadmap and character docs now require stable per-NPC `voice_profile`
+  assignment and scoped `api.dos.ai` voice sessions so each important NPC can
+  keep a distinct voice without exposing provider keys to Unity.
+- Nakama now records redacted `PromptTrace` logs for `secondspawn_agent_decide`
+  calls, including model, source, source reason, action, latency, validation
+  result, selected memory ids, and prompt component metadata without storing
+  raw hidden prompts.
+- Unity HUD can fetch and show the latest prompt-trace summary from Nakama so
+  Play Mode debugging can distinguish model, fallback, backoff, and validation
+  behavior without opening backend logs.
+- Nakama now updates a prototype State of Mind on each agent decision, with
+  mood, stress, dominant need, last trigger, and last plan summary surfaced in
+  the Unity HUD.
+- Nakama now enforces a prototype per-player DOS.AI decision budget for
+  `secondspawn_agent_decide`, with daily request and estimated-token caps that
+  degrade to deterministic fallback instead of calling the model.
+- Nakama `ConversationSession` now includes a structured
+  `ConversationObjective` with section, trigger, priority, allowed intents,
+  turn cap, and completion state for NPC society turns.
+- Roadmap now tracks a browser/WebGL demo build lane for external playtests.
 - Unity now has a Persistent NPC Debug panel for seeding, listing, and
   smoke-testing LLM-style NPC context and say-intent submission between
   permanent NPC Frames.
@@ -90,9 +178,50 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots.
 - Gate, dungeon, and Pioneer Charter design doc for ranked Gates,
   server-issued first-clear rights, common Tower/Gate genre mechanics, and
   in-game-only Clearance Royalty loops.
+- Story bible for the first playable narrative foundation, including the Relay
+  Yard hub, Ash Underpass Gate, Tollkeeper boss, first five quest beats, faction
+  tensions, named NPC archetypes, and LLM NPC consistency rules.
+- Gate and story docs now explicitly separate persistent real-world exterior
+  spaces from distorted Portal Dungeon interiors with their own instance rules,
+  memory residue, impossible geometry, and TIME pressure.
+- Gate interior direction now allows fantasy-readable dungeon themes such as
+  orc-like warbands, troll-like brutes, castle ruins, forests, caves, towers,
+  constructs, and boss guardians while keeping the global explanation sci-fi.
+- Gate system docs now include reference takeaways from portal, Gate, Tower,
+  floor, and scenario manhwa patterns so dungeon interiors are designed as
+  fantasy-readable rule-spaces rather than ordinary sci-fi corridors.
+- Manhwa market reference ranking doc comparing public reach signals for
+  Solo Leveling, Tower of God, Omniscient Reader, The Gamer, Hardcore Leveling
+  Warrior, Tutorial Tower, The World After the Fall, Return to Player, Second
+  Life Ranker, SSS-Class Revival Hunter, and Level Up with the Gods.
+- Story bible now defines a recommended pre-MetaDOS demo direction in the early
+  Nibirium era, internally around 2033-2038, in `Vinh Hai Relay Ward`, a small
+  near-future coastal logistics ward where DOS Labs is still piloting early
+  AMB, Frame transfer, BodyTime accounting, Gate response, and the systems that
+  later become public MetaDOS spectacle.
+- Demo lore and story direction doc defining the 2028 Nibiru timeline revision,
+  Vinh Hai Relay Ward hub, MetaDOS-derived faction set, player origin, theme
+  rules, Gate fantasy rules, first permanent NPC set, and Chapter 1 arc.
+- Unity permanent NPC brains now propagate validated model-backed NPC speech to
+  nearby target NPC brains, allowing NPC-to-NPC conversations to continue
+  through the Nakama decision boundary instead of local hardcoded lines.
+- Unity now uses a shared local NPC decision request scheduler so autonomous
+  NPCs do not burst all model requests at once, while direct player-chat
+  responses keep priority slots.
+- Player nearby chat now reaches permanent NPC brains through the Nakama society
+  event and tick path, then requests model-backed replies with player-chat
+  context and visible model/fallback status.
+- NPC-to-NPC response propagation now respects conversation session turn caps
+  and per-NPC response cooldowns to avoid runaway local conversation loops.
+- `PrototypeAgentBrain` now uses a shared speech-stimulus path for player and
+  NPC speech, reducing drift between player-chat and NPC-hears-NPC handling.
 
 ### Changed
 
+- GDD continuity now treats SECOND SPAWN's demo as the early Nibirium era before
+  MetaDOS becomes a 2050 public tournament spectacle, while preserving MetaDOS
+  as the later commercialization of local Frame, BodyTime, Gate, and agent
+  systems.
 - GDD and system docs now anchor SECOND SPAWN to the MetaDOS technology stack:
   AMB cocoons, bio-synthetic Frames, Hunter Frames, TIME as the life medium,
   SECOND as the unit/currency, manga/manhwa system-story progression tone, and
@@ -231,6 +360,31 @@ versioned release tag yet, so entries are organized as pre-alpha snapshots.
   the fixed body variant, avoiding duplicate startup prefab/animator warmup.
 - Prototype agent brain now avoids duplicate fallback HTTP calls; Nakama returns
   either a model-backed decision or a deterministic fallback in one RPC.
+- Architecture and character-profile docs now define the
+  `behavior_tendencies` adapter that maps identity, soul, traits, story, memory,
+  and relationship context into compact runtime hints for talk cadence, social
+  range, idle behavior, tone, conflict response, movement style, and decision
+  cadence.
+- Nakama model decisions now use a larger JSON budget and stricter short-output
+  prompt so DOS.AI responses are less likely to be truncated mid-intent.
+- Unity permanent NPC brains now share a small global DOS.AI request gate so 10
+  NPCs queue model decisions instead of bursting into 429 model backoff.
+- Model-backed NPC speech persistence now skips non-permanent or unknown
+  targets, avoiding noisy `unknown target NPC actor` warnings for player or
+  landmark-directed speech bubbles.
+- Permanent NPC prototype spacing now uses a wider spawn grid, smaller patrol
+  radius, and local personal-space separation so model-driven social movement
+  does not visually stack NPC bodies into one cluster.
+- Nearby NPC interaction now enters a prototype dialog mode: the local player
+  and target NPC stop free movement, face each other, and keep a short dialog
+  focus window while player chat continues.
+- Dialog mode now keeps the local player and focused NPC facing each other
+  every frame during the chat focus window, preventing movement or rotation
+  updates from breaking the conversation pose.
+- Nakama NPC prompt rules now push direct player answers toward natural
+  in-scene speech instead of menu-like or support-bot phrasing.
+- Nearby NPC chat now shows an `Esc` hint and exits Chat Mode on Escape,
+  clearing the dialog input lock and releasing the focused NPC.
 
 ### Verification
 

ROADMAP.md

@@ -1,7 +1,7 @@
 # SECOND SPAWN Roadmap
 
 Status: Pre-alpha, vertical slice foundation in development.
-Last updated: 2026-05-19.
+Last updated: 2026-05-20.
 
 This roadmap tracks implementation status. Detailed design remains in `docs/`,
 especially `docs/design/02-vertical-slice-spec.md` and
@@ -132,6 +132,12 @@ Recommended views:
 - [x] Permanent NPC brains send nearby actor context to the model-backed
   decision path and persist model-selected `say` intents through Nakama memory
   and relationship records.
+- [x] Permanent NPC brains can now hear validated nearby NPC speech and answer
+  through the same model-backed Nakama decision path, with local request
+  scheduling, NPC speech cooldowns, and conversation turn-cap checks.
+- [x] Player nearby chat now reaches permanent NPC brains through the Nakama
+  society event and tick path, then produces model-backed replies when
+  `api.dos.ai` is healthy.
 - [ ] Real combat damage, enemy rewards, loot drops, quest progress, and player
   time-loot from other users are not implemented yet.
 
@@ -173,10 +179,16 @@ MVP, and a visible offline-agent prototype.
   actions while Nakama validates range, hostility, affinity, and intent shape.
 - [x] Add model-backed proactive NPC social decisions with nearby actor context
   and validated Nakama memory or relationship persistence.
+- [x] Add model-backed NPC-to-NPC response propagation in Unity after Nakama
+  accepts a validated `say` intent.
+- [x] Add local prototype LLM request scheduling so 10 NPCs do not burst
+  requests into `api.dos.ai` at the same instant.
+- [x] Add player-chat priority handling so direct player messages do not wait
+  behind normal autonomous NPC ticks.
 - [x] Add Nakama channel-based basic chat for the vertical slice.
 - [x] Surface agent runtime stats and recent activity in an in-editor or
   prototype debug UI.
-- [ ] Add per-player LLM rate limit and token-budget enforcement in Nakama for
+- [x] Add per-player LLM rate limit and token-budget enforcement in Nakama for
   `secondspawn_agent_decide`.
 - [ ] Add server-owned Nakama storage collection boundaries, permissions, and
   optimistic concurrency for sensitive body, inventory, economy, memory, and
@@ -185,6 +197,17 @@ MVP, and a visible offline-agent prototype.
   and agent activity so snapshots are auditable.
 - [ ] Add Nakama metrics and structured observability for AI decisions,
   fallback reasons, storage conflicts, reward claims, and BodyTime mutations.
+- [x] Add redacted `PromptTrace` records for NPC decisions, inspired by
+  Convai Mindview, showing which persona, memory, objective, knowledge pack,
+  world snapshot, source, latency, and validation result shaped each turn.
+- [x] Add NPC knowledge packs for `zone_lore`, `profession_lore`,
+  `faction_lore`, `quest_lore`, and `private_memory` so NPC prompts retrieve
+  compact context instead of stuffing whole design docs into every call.
+- [x] Add `ConversationObjective` records with objective, trigger, section,
+  priority, turn cap, allowed intents, and completion state to reduce generic
+  repeated NPC chatter.
+- [x] Add NPC State of Mind runtime fields for mood, stress, dominant need,
+  last trigger, and last plan summary, then surface them in the Unity debug UI.
 - [ ] Separate client, internal worker, and admin RPC namespaces with explicit
   auth and secret boundaries.
 - [ ] Define shard-ready account routing and database-per-shard operations
@@ -193,7 +216,15 @@ MVP, and a visible offline-agent prototype.
   offline-agent and NPC simulation instead of long-running Nakama request loops.
 - [ ] Add the future voice-session Nakama RPC that mints short-lived
   `api.dos.ai` voice tokens without exposing provider keys to Unity.
-- [ ] Wire Convai phase 1 NPC dialogue through the server-side intent boundary.
+- [ ] Add per-NPC `voice_profile` assignment for permanent NPCs, including
+  voice id, language, speaking style, pitch/rate hints, emotional range, and
+  fallback text-only behavior. Each important NPC should keep a stable voice
+  across sessions and body respawns unless lore explicitly changes it.
+- [ ] Add NPC TTS playback in Unity through scoped `api.dos.ai` voice sessions:
+  Nakama owns authorization, `api.dos.ai` owns provider routing, and Unity only
+  receives short-lived playback/session material.
+- [ ] Decide whether Convai remains a phase 1 spike for one boss or hub NPC.
+  The default long-term backbone stays Nakama plus Fusion plus `api.dos.ai`.
 - [x] Add BodyTime meter MVP with one earn source and one spend sink.
 - [x] Add reincarnation placeholder flow: death -> SECOND token check ->
   respawn with current-body reset.
@@ -217,6 +248,8 @@ MVP, and a visible offline-agent prototype.
 - [ ] Add one Hunter NFT skin equip placeholder with DOS Chain escrow design
   still server-authoritative.
 - [ ] Run Multiplayer Play Mode smoke for 2-4 local clients.
+- [ ] Add a browser/WebGL demo build lane so external playtesters can try the
+  vertical slice without installing the Unity editor or a native client.
 - [ ] Resolve Unity Fusion CodeGen Play Mode smoke blocker tracked in issue #7.
 - [ ] Prepare Linux headless dedicated server build path.
 
@@ -229,7 +262,8 @@ MVP, and a visible offline-agent prototype.
 - [ ] Add multiple zones with travel.
 - [ ] Add marketplace and NFT trade.
 - [ ] Add guild system before PvP.
-- [ ] Add voice NPC if ephemeral-token cost and reliability are acceptable.
+- [ ] Add higher-quality NPC voice and interruption once ephemeral-token cost,
+  latency, reliability, and per-NPC voice identity are acceptable.
 
 ## Beta