Polish README and document Codex-assisted build

README.md

@@ -19,61 +19,83 @@ tags:
   - best-agent
   - best-demo
   - openai
+  - track:wood
+  - sponsor:openai
+  - achievement:offbrand
+  - achievement:sharing
+  - achievement:fieldnotes
 ---
 
 # LifeChoice Simulator
 
-LifeChoice Simulator turns a difficult real-life dilemma into a short, consequential future you can play through. It is designed for reflection, not prediction or advice.
+LifeChoice Simulator turns a difficult real-life dilemma into a short, consequential future that a user can play through. It is built for reflection, not prediction or advice: the app shows how tradeoffs can compound across money, fulfillment, social validation, stress, and family pressure.
 
 ![Architecture](docs/architecture.svg)
 
 ## Live Demo
 
-- Hugging Face Space target: `build-small-hackathon/LifeChoice-Simulator` (organization authorization pending)
+- Live Space: [build-small-hackathon/LifeChoice-Simulator](https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator)
+- Agent build trace: [lifechoice-simulator-trace](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace)
 - Public demo video: [watch the 22-second walkthrough](https://github.com/Ajey95/LifeChoice-Simulator-Hackathon/raw/main/docs/lifechoice-demo.mp4)
-- Agent build trace: [LifeChoice Simulator trace dataset](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace)
-- Social post: publishing pending
+- Social post draft: [docs/social-post.md](docs/social-post.md)
+- Demo script: [docs/demo-script.md](docs/demo-script.md)
 
-The repository includes a longer [demo script](docs/demo-script.md) and [social post draft](docs/social-post.md) ready for public publishing.
+## What It Does
 
-## Why It Is Not Just a Chatbot
+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.
+
+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.
+
+## Why It Is Not Just A Chatbot
 
 A chatbot responds turn by turn with prose. LifeChoice runs a stateful simulation engine:
 
 - Every choice changes five deterministic metrics.
 - Choices create durable facts, obligations, and closed options.
-- Later scenes must respect those causal records and metric thresholds.
+- Later scenes must respect causal records and metric thresholds.
 - Earlier choices return through three cascade moments.
 - The visual environment changes among `thriving`, `stable`, and `struggling`.
+- The player sprite changes among `neutral`, `stressed`, and `confident`.
 - A bounded context packet prevents token growth across the simulation.
 - The final report is computed from actual behavior, not a conversational impression.
 
-The language model enriches bounded decision nodes. It does not own arithmetic, state transitions, safety limits, or simulation completion.
+The model enriches bounded decision nodes. It does not control scoring, state transitions, safety limits, or simulation completion.
 
 ## Product Design
 
-LifeChoice is designed around fast entry, bounded generation, and consequences that remain visible:
+LifeChoice is designed around fast entry, bounded generation, and visible consequences.
 
 | Capability | Design |
 |---|---|
-| Fast onboarding | Dilemma, path, one concrete calibration answer, and one persona selection |
+| 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 |
 | Bounded context | Last 3 choices, 8 facts, 5 obligations, and 5 closed options only |
-| Stable characters | Characters remain static session data |
+| Stable characters | Characters remain static session data, not regenerated every turn |
 | Consistent world state | Threshold facts and narrative validation enforce visible pressure |
-| Meaningful choices | Every choice mutates causal facts, obligations, closed options, and metrics |
-| Persona continuity | Reactions appear at opening, nodes 1/3/5/7, and critical thresholds |
+| Meaningful choices | Every choice mutates facts, obligations, closed options, and metrics |
+| Persona continuity | Reactions appear at opening, selected later nodes, and critical thresholds |
 | Delayed consequences | Small echo at node 2, major consequence at node 5, final payoff at node 7 |
-| Reactive visuals | Environment image and metric panel update after every decision |
+| Reactive visuals | Environment image, metric panel, and sprite expression update after decisions |
+
+## Architecture
+
+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.
+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.
+7. Persona reactions and cascade events reuse the causal ledger.
+8. The final report summarizes observed behavior inside the simulation.
 
 ## Model Compliance
 
-Only one model is configured:
+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 node enrichment |
+| [`Qwen/Qwen2.5-7B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) | 7.616B | Optional bounded decision-node enrichment |
 
 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.
 
@@ -83,16 +105,6 @@ Run the compliance test:
 pytest tests/test_model_compliance.py
 ```
 
-## Architecture
-
-1. Gradio captures a dilemma, chosen path, one 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.
-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.
-7. Cascades and the final report use the causal ledger.
-
 ## Safety
 
 LifeChoice is a reflective simulation, not medical, legal, financial, mental-health, or career advice. Its futures are fictional hypotheses rather than predictions. Users should not enter secrets or sensitive personal data. High-stakes decisions should be discussed with qualified people who understand the real situation.
@@ -104,9 +116,40 @@ Safety controls include:
 - Strict model-output schema validation
 - Deterministic fallback for outages or invalid output
 - No autonomous real-world action
-- No recommendation of a “correct” path
+- No recommendation of a "correct" path
 - Explicit uncertainty and disclaimer text in the UI
 
+## Built With Codex
+
+This submission was developed with Codex as an implementation partner, not just as a code autocomplete tool. Codex was used across product design, architecture, implementation, verification, documentation, and deployment preparation.
+
+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.
+- 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.
+- Published a public agent build trace for transparency and the `Sharing is Caring` badge.
+
+The workflow stayed human-directed: the project owner selected the product direction, reviewed behavior in the running Space, chose badge claims, and guided final submission positioning. Codex handled implementation details, consistency checks, and documentation polish so the build could move from prototype to submission-ready artifact quickly.
+
+Codex-attributed commits use:
+
+```text
+Author: Codex <codex@openai.com>
+```
+
+## Bonus Badges
+
+- **Off-Brand**: custom game-style Gradio frontend instead of default Gradio presentation.
+- **Field Notes**: README, architecture diagram, demo script, compliance checklist, screenshots, and submission notes.
+- **Sharing is Caring**: public [agent build trace dataset](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace) with 26 event rows.
+
+This submission does not claim Tiny Titan, OpenBMB, NVIDIA, Modal credits, Off the Grid, Well-Tuned, or Llama Champion.
+
 ## Tech Stack
 
 - Python 3.10+
@@ -128,17 +171,6 @@ python app.py
 
 `HF_TOKEN` is optional. Without it, deterministic fallback content is used.
 
-### Deploy The Organization Space
-
-Authenticate specifically as `Ajeya95`, with write permission in `build-small-hackathon`, then run:
-
-```bash
-hf auth login
-python scripts/deploy_space.py
-```
-
-The deployment script checks both the username and organization role before creating or updating the public Space.
-
 ## Tests
 
 ```bash
@@ -147,27 +179,18 @@ pytest -q
 
 The suite covers model-size compliance, bounded context, branch divergence, world-state clamping, state-to-narrative consistency, cascades, persona cadence, and metric-driven environment changes.
 
-## Hackathon Categories
-
-- Thousand Token Wood
-- Best Agent
-- Best Demo
-- OpenAI Prize
-
-## Bonus Badges
-
-- Off-Brand: custom game-style Gradio frontend instead of default Gradio presentation
-- Field Notes: project README, architecture notes, demo script, compliance checklist, and screenshots
-- Sharing is Caring: public [agent build trace dataset](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace)
+## Deployment
 
-This submission does not claim Tiny Titan, OpenBMB, NVIDIA, Modal credits, Off the Grid, Well-Tuned, or Llama Champion.
+Authenticate as an account with write permission in `build-small-hackathon`, then upload the Space files to:
 
-## Built With Codex
+```text
+build-small-hackathon/LifeChoice-Simulator
+```
 
-Codex built the simulation architecture, Gradio interface, tests, documentation, and deployment workflow. Codex-attributed commits use:
+The current public Space is available at:
 
 ```text
-Author: Codex <codex@openai.com>
+https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator
 ```
 
 ## Screenshots
@@ -186,6 +209,6 @@ Author: Codex <codex@openai.com>
 
 ## Submission Status
 
-Code, tests, Space metadata, model compliance, safety documentation, architecture, and publishing assets are included. Public URL fields are updated only after the authenticated GitHub repository, Hugging Face organization Space, video, and social post exist.
+Code, Space metadata, model compliance, safety documentation, architecture, screenshots, demo script, public trace dataset, and badge evidence are included.
 
-See the dated [compliance checklist](docs/compliance-checklist.md) for requirement-by-requirement evidence and external blockers.
+See the dated [compliance checklist](docs/compliance-checklist.md) for requirement-by-requirement evidence.