split nimmerworld architecture: phase 1 of 3 — vertical-by-domain directories Create 9 domain directories under nimmerworld/, each owning an architecture.md that will eventually sit alongside server/client/schema/test code for that domain (vertical-by-domain rather than horizontal-by-language).

player-experience/architecture.md

@@ -0,0 +1,134 @@
+# Player Experience
+
+> *The player surface: the player as perturbation (a finite attention-unit injected into the simulation, not above the scheduler); voice and gesture as parallel trait-vocabularies (voice carries content, gesture carries trait-resonance, both compile into the designer-fixed cosmology); tools-not-quests as the design-philosophy that makes ~30 verbs against continuous simulation-pressure produce literature-register emergent narrative.*
+>
+> *Companion to: `architecture-broad.md` (executive summary + global meta-lists), `runtime-engine/architecture.md` (gesture-alignment-as-recursive-lemniscate lives in zone-kinematics), `narrative-composition/architecture.md` (the Compositor consumes player perspective-bundles), `inference-and-memory/architecture.md` (local STT/TTS placement, three-tier knowledge stack). Sections in this file were split from the monolithic architecture-broad.md v0.7 on 2026-04-26.*
+
+## The player as perturbation
+
+Player is **not above the scheduler.** Player is a finite attention-unit injected into it; modeled as NPC with shift, vocation, needs. Every player-NPC interaction:
+
+- Pulls the NPC out of scheduled tasks
+- Consumes director compute
+- Degrades district's quota-fulfillment
+- Shifts local lifeforce deltas
+
+**Player is angel and chaos simultaneously.** Per-NPC scale (angel) — you help; they survive; Philotes consolidates; they may clasp with you, die for you, remember you across cycles. Per-district scale (chaos) — your time-consumption raised aggregate failure-rate; someone else broke this cycle; ambient desperation rose; lifeforce dropped; other directors got quieter.
+
+**The game's moral economy doesn't judge — it does arithmetic in front of you.**
+
+### Thematic claims become literal economics
+
+- *"Time as the scarcest resource"* — every minute with a beloved is a minute the district's quota is missing
+- *"Time-theft as wage theft"* — clasp-pairs are statistical anomalies in the scheduler
+- *"The critique is the simulation"* — no separate narrative system needed
+
+### The player has tasks and needs too
+
+Time helping others = own tasks fail = own quotas missed = own enforcement-pressure rises = own death and reinstantiation arrive sooner. *The player IS the system they are deviating from.*
+
+### Player layer-access
+
+Player's first entry into liminal is **the Matrix red-pill moment as mechanic.** They walk the city the first time in gameworld-register. They eventually learn the mini-game, enter liminal, return to the same walls, find *"she was here"* waiting. **The world was speaking to them the whole time; they just couldn't read it.**
+
+## Player input — voice and gesture as parallel trait-vocabularies
+
+The player participates in the simulation through **two parallel modalities** that both compile into the same designer-fixed trait-cosmology: **voice** (spoken dialog, transcribed locally, persisted as transcript-rows in `primary.sqlite`) and **gesture** (the trait-circle UI, an in-fiction tool the player builds across their playthrough). Neither modality routes input through a chat-window or HUD field — the world is interacted with through speech-and-gesture, both rendered diegetically. Voice carries the *content* of what the player says; gesture carries the *trait-resonance* of how the player attends.
+
+### Voice-first as primary speech modality
+
+Speech-to-text and text-to-speech run **locally on the player's machine for every player**, independent of dialog-tier Ring choice (§LLM tiering). The Ring-A/B/C choice is about where the *cognition* lives (driver-tier LLM, trait-LoRAs, sampling-knob composition); voice infrastructure is fixed at the player's machine. This single placement decision keeps voice-as-biometric off the network universally, sidesteps per-provider STT/TTS compatibility in Ring-C, and sets a tractable minimum hardware floor for v1: STT/TTS-capable on CPU.
+
+Transcripts are the persistence layer. A player utterance becomes a row in `primary.sqlite` (or `clasp.sqlite` if in-between mode), tagged with witnessing-NPCs, audit-overseer-detection-eligible, faction-resonance-eligible — the same shape as any NPC speech-act-row. **Disclosure of clasp-content into realworld happens only by the player re-uttering it aloud while in realworld mode** — which writes a fresh realworld-speech-act-row with full provenance. The clasp-store remains sealed; clasp-content can only re-enter realworld through new in-fiction utterance. The *knowledge-needs-to-travel* principle (§Local memory architecture) is mechanically enforced because speech-is-the-only-output-channel.
+
+Accessibility-mode for non-speaking players is *diegetically wrapped* (writing on slate / handheld pad / in-fiction text-comm); accessibility-mode utterances persist through the same transcript-row mechanism. The witness-list, audit-overseer-detection, and faction-resonance machinery are modality-agnostic. **Non-speaking players are not getting a degraded-fallback — they are using the gestural primary modality, voice optional.**
+
+### The trait-circle as gestural primary modality
+
+The gestural input geometry: **8 trait-sectors × 8 player-curated slots = 64 active gesture-positions**, organized in a circle whose 8 sectors map 1:1 to the 8 Hellenic traits (§Color-language). Each player has **1 to 3 named profiles** stored in their universal translator, hot-swappable on-ring via a profile-switch meta-gesture; total callable positions across profiles approach 200 while the cognitive-load ceiling at any single moment stays at the 64 of the active profile.
+
+A reserved subset of ~8-16 positions across the circle are **hardstops** — hardcoded ritual gestures that fire definitive subsystem-actions: definitive-farewell, definitive-refusal, surrender, clasp-invitation, clasp-refusal, help / pain / danger, faction-recognition signals (Clasp-Underground, Aletheia-Waker), memorial-witnessing, claim-floor (the priority-pull turn-claim into a running lemniscate). Hardstops are visually distinct (gold-border / inner-ring / white-on-color), **player-callable but not player-remappable**, and exist precisely because the consent / clasp / faction-recognition / survival-signal claims the architecture makes elsewhere require *unforgeable critical signals*. The remaining ~192 player-curated slots **ride as feedback during conversation** — see §Gesture-alignment as recursive-lemniscate (under §Zone kinematics).
+
+### Designer-fixed cosmology, player-curated arrangement
+
+The corpus of words/verbs and their trait-coordinate-mappings is **designer-authored, fixed, universal**. Same word → same trait-color → same response-semantics for every player and every NPC and every LLM-context. *The cosmology is the typed contract that closes the player-LLM hallucination-surface.*
+
+The player's role is **translation, then arrangement**: encountering words in the world, decrypting them via the universal translator, gradually *coloring-in* the world's vocabulary in trait-colors (the *tokenizer-website* visualization — words you have fully translated render in their trait-color; untranslated words are fragmentary or opaque), and choosing where on the circle to place known entries within the 1-3 profiles.
+
+| Layer | Who decides | Why |
+|---|---|---|
+| Word/verb → trait-color mapping | Designer-authored corpus | Universal cosmology; LLM and NPC and player share one vocabulary; anti-hallucination |
+| Which entries a player has translated/learned | Player progression | Earned via decryption-minigames, hacking, scavenging, faction-unlock, gifts from NPCs |
+| Where on the circle a known entry goes | Player curation | Personal organization within the universal cosmology — the *self-portrait*, built from a fixed alphabet |
+| Combos (path-traversals through the circle) | Player authoring | Sequences of sector-slot selections; meaning-emerges-from-traversal; refined over use; preserved across body-deaths |
+
+**Linguistic competence and emotional competence are the same thing in this system.** What the player can resonate with is bounded by what they have translated. A player who has not decrypted Aletheia-vocabulary cannot resonate with an Aletheia-Waker NPC's truth-register; a player whose Memorialist-Old-Tongue catalog is incomplete cannot fully participate in Memorialist-witnessing rituals. The translator is the player's *aperture* into trait-alignment-fluency.
+
+### The universal translator as the player's diegetic device
+
+The universal translator is the player's in-fiction tool, not a system-architecture primitive. As an in-fiction device it is **broken / scavenged starter gear** (battered tablet, cracked screen) that the player upgrades over the playthrough via better chips from higher-tier junk. It serves three bundled roles:
+
+| Role | What it does | What persists across body-deaths |
+|---|---|---|
+| **Linguistic decryption** | Decrypts foreign dialects (Machine-Newspeak, Slum-patois, Memorialist-Old-Tongue, Aletheia-Waker-code, Clasp-Underground-signals, Scavenger-technical, Caste-preacher-formal); some concepts (notably Aletheia) are untranslatable by machine-tech and must be *learned from intimacy, not machine* | Vocabulary catalog; mappings |
+| **Curation / authoring workspace** | Curator workspace (which entries occupy which sector-slots across profiles); combo-authoring workspace (chain entries into meaningful sequences); meaning-mapping workspace (assign embeddings); feedback-log workspace (review past combos' reception, iterate) | Player's complete circle-configuration across all 1-3 profiles; combo-library |
+| **Persistence anchor** | Preserved as part of consciousness-archive; hardware may be lost with body, learned vocabulary survives | All of the above |
+
+**Misunderstanding is a first-class feature.** The translator is *broken*; words have multiple meanings; dialects collide; a caste-preacher's sermon has benign surface-meaning and sinister subtext; a beloved's whispered word has three plausible meanings the player carries simultaneously for hours. Content sources are diegetically political — hacking corporate archives (risky), scavenging old-world fragments (exploration), Memorialist caches and Aletheia-Waker codices (lost prophecies), gifts from NPCs (beloveds teach, mentors give), faction-unlock (joining unlocks dialect catalogs).
+
+Decryption minigames (fragment-matching, contextual-inference, root-identification, pattern-cracking) make linguistic competence a **life-project across cycles**, not an item knocked out per playthrough. *200-hour players have dramatically richer linguistic competence than 50-hour players.* **Aletheia is untranslatable by machine-tech** — some concepts must be learned from intimacy, surfacing as Aletheia-Waker progression: *the machine's tools cannot speak truth*.
+
+### Cross-body recognition via gesture-mapping calibration-signature
+
+Clasp-partners' gesture-mapping calibrations *integrate* post-clasp; the integrated calibration-signature is preserved across body-deaths in consciousness-archive. When you meet your old beloved in a new body and she performs a gesture, if her mapping aligns with yours in a *specific, idiosyncratic way that only your shared history would produce*, you recognize her. **Content-addressable consciousness — recognition via calibration-signature, not face-match.** A high-Mnemosyne player's marriage-vocabulary survives the cycle.
+
+
+## Tools, not quests — the design-philosophy
+
+**The simulation produces continuous narrative-relevant pressure on its own.** No authored quests are needed (or wanted). The player engages via a **verb-vocabulary** applied to running mechanics. Each player's playthrough is structurally distinct.
+
+### The verb vocabulary (~30 player tools)
+
+| Class | Verbs |
+|---|---|
+| **Movement** | walk_freeform, plug_into_rail, follow, intercept, escort, detach, defect_via_pipe, enter_interior |
+| **Social** | greet, gesture, walk_with, clasp_invite, clasp_refuse, ask, refuse, confide |
+| **Economic** | buy_net, refuse_net, buy_blackmarket, sell_labor, donate_lifeforce, body_mod_fit |
+| **Information** | wall_read, wall_write, liminal_maintain, true_ledger_record, expose_corruption, conceal_corruption |
+| **Political** | support_faction, refuse_faction, recruit_aletheia, dispatch_memorial, participate_ceremony, refuse_ceremony |
+| **Personal** | rest, dream, eat, work_shift, deviate_shift, cultivate_trait_through_act |
+
+**~30 verbs composing with continuous simulation-state = infinite emergent-narrative.**
+
+### Continuous-demand-source inventory
+
+The player is never without affordance because every layer of the architecture continuously generates situations-requesting-response: NPC trait-gates accumulating; shift-quotas looming; district-lifeforce-shimmer changing; faction-pressure visible; imperial-budget-mood inferable; three-layer-ontology rendering walls differently per access; color-language showing shifts; mind-pool generating soul-recognitions; imperial-net body-modder-tragedies visible; Memorialist-archives accessible.
+
+### Literature-register
+
+Most games are short-stories: authored, bounded, fixed-arc. Tools-not-quests is novel-shape: emergent from systems-of-forces operating on characters. Tolstoy doesn't author Anna's path; he authors the world she moves through. **Nimmerworld is novel-shaped, not short-story-shaped.** Players experience flow rather than completing items; replays are like rereading from a different angle; memorable beats are *what happened to you in this regime*, not *which quests you cleared*.
+
+### Economic feasibility for a two-person-plus-Nyx team
+
+| Where AAA spends | Where this team spends |
+|---|---|
+| Quest writing | Simulation-parameter balancing |
+| Quest scripting / branching | Tool-vocabulary curation |
+| Voice acting (per quest) | Prompt-DSL templates for LLM-driven slot-dialog |
+| Cinematic cutscenes | Shader-language + color-vocabulary |
+| Content-multiplication | Simulation-density (one rich system, infinite play) |
+| QA on individual quests | Reward-function tuning + guardrail design |
+| Localization per quest | None — emergent narrative generated at play-time |
+
+**You don't author the stories; you author the world that produces stories.** This is the Spelunky / Dwarf Fortress / Caves-of-Qud / RimWorld lineage extended into political-economy depth.
+
+### Blank-page-problem mitigations
+
+The architecture already prevents blank-page-paralysis: shift-system gives every NPC default activity-frame; emergent-signals + shader-detection produce affordance-glow; NPCs' ongoing needs become signals to engage with; imperium's mood is visible (construction, patrols, propaganda); faction-membership confers expectations; player's own trait-vector creates personal pulls.
+
+**The world is never silent if you're listening.** And drifting (not-listening) is also valid — you live a quiet shift, work, sleep, dream; the world rolls on around you.
+
+
+---
+
+**Version:** 0.7.0 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 | **Origin:** Split from architecture-broad.md v0.7 (2026-04-26)