Align docs around LLM-driven scenario generation

README.md

@@ -63,9 +63,9 @@ The post highlights the app, the hackathon track, the Codex-assisted build proce
 
 ## What It Does
 
-The user enters a fork in the road, chooses one path to simulate, adds one real constraint, and selects a persona voice. LifeChoice then runs an eight-node future where every decision changes the state of the world and creates durable consequences.
+The user enters a fork in the road, chooses one path to simulate, adds one real constraint, and selects a persona voice. LifeChoice then uses a 7B language model to help generate adaptive future scenarios inside an eight-node simulation where every decision changes the state of the world and creates durable consequences.
 
-Unlike a normal chatbot, the model does not own the simulation. The deterministic engine owns arithmetic, state transitions, facts, obligations, closed options, cascade moments, safety boundaries, and the final report. The language model is used only for optional bounded node enrichment.
+Unlike a normal chatbot, the LLM is not asked to improvise the whole product from scratch on every turn. It is the narrative scenario engine for the adaptive experience, while deterministic code provides the structure around it: arithmetic, state transitions, facts, obligations, closed options, cascade moments, safety boundaries, and the final report.
 
 ## Why It Is Not Just A Chatbot
 
@@ -80,7 +80,7 @@ A chatbot responds turn by turn with prose. LifeChoice runs a stateful simulatio
 - A bounded context packet prevents token growth across the simulation.
 - The final report is computed from actual behavior, not a conversational impression.
 
-The model enriches bounded decision nodes. It does not control scoring, state transitions, safety limits, or simulation completion.
+The LLM generates and adapts the scenario text inside bounded decision nodes. Deterministic code handles scoring, state transitions, safety limits, and simulation completion so the model's creativity stays grounded in a consistent causal system.
 
 ## Product Design
 
@@ -90,7 +90,7 @@ LifeChoice is designed around fast entry, bounded generation, and visible conseq
 |---|---|
 | Fast onboarding | Dilemma, path selection, one calibration answer, and persona selection |
 | Immediate play | The opening node is deterministic and available without model latency |
-| Efficient generation | One future node is enriched at a time and prefetched in the background |
+| Efficient generation | One future node is generated at a time and prefetched in the background |
 | Bounded context | Last 3 choices, 8 facts, 5 obligations, and 5 closed options only |
 | Stable characters | Characters remain static session data, not regenerated every turn |
 | Consistent world state | Threshold facts and narrative validation enforce visible pressure |
@@ -103,7 +103,7 @@ LifeChoice is designed around fast entry, bounded generation, and visible conseq
 
 1. Gradio captures a dilemma, chosen path, calibration fact, and persona.
 2. The engine returns an immediate deterministic opening scene.
-3. A background worker optionally enriches future nodes with the 7B model.
+3. A background worker generates future scenario nodes with the 7B model.
 4. The deterministic state engine applies deltas and updates the causal ledger.
 5. Narrative validation rejects generated scenes that contradict critical metrics.
 6. The environment derives its visual state from all five metrics.
@@ -116,9 +116,9 @@ Only one model is configured.
 
 | Model | Parameters | Purpose |
 |---|---:|---|
-| [`Qwen/Qwen2.5-7B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) | 7.616B | Optional bounded decision-node enrichment |
+| [`Qwen/Qwen2.5-7B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) | 7.616B | Bounded adaptive scenario generation |
 
-Hugging Face repository metadata reports `7,615,616,512` parameters. No secondary model is configured, and no model at or above 32B is used. If hosted inference is unavailable, the simulation uses deterministic authored nodes and remains fully playable.
+Hugging Face repository metadata reports `7,615,616,512` parameters. No secondary model is configured, and no model at or above 32B is used. The submitted experience is LLM-centered: the model is what makes later scenarios adaptive to the user's dilemma and prior choices. Deterministic authored nodes remain as a reliability fallback for demos and outages, but they are not the core creative experience.
 
 Run the compliance test:
 
@@ -135,7 +135,7 @@ Safety controls include:
 - Deterministic metric arithmetic and clamping to `0..100`
 - Bounded model context
 - Strict model-output schema validation
-- Deterministic fallback for outages or invalid output
+- Deterministic fallback for outages or invalid model output
 - No autonomous real-world action
 - No recommendation of a "correct" path
 - Explicit uncertainty and disclaimer text in the UI
@@ -149,7 +149,7 @@ Codex helped turn the initial hackathon concept into a production-shaped system:
 - Converted the idea into a modular simulation architecture with deterministic state ownership.
 - Implemented the Gradio application, custom interface, scenario rendering, persona panel, sprite state, metrics, and report view.
 - Designed the causal ledger model: facts, obligations, closed options, recent choices, and delayed cascade moments.
-- Added bounded LLM integration through Hugging Face `InferenceClient` while preserving deterministic fallback behavior.
+- Integrated Hugging Face `InferenceClient` so the 7B model can generate bounded adaptive scenarios while deterministic code validates and scores the simulation.
 - Built validation logic so generated scenes cannot ignore critical stress, money, or family thresholds.
 - Created compliance artifacts for model-size limits, safety posture, architecture, screenshots, demo flow, and submission evidence.
 - Verified live Space access, runtime state, repository files, world-state transitions, and character-state transitions.
@@ -190,7 +190,7 @@ pip install -r requirements.txt
 python app.py
 ```
 
-`HF_TOKEN` is optional. Without it, deterministic fallback content is used.
+`HF_TOKEN` should be configured for the submitted experience. The fallback path exists only to avoid a blank demo during outages; it is not the intended model-driven product mode.
 
 ## Tests