docs: update project documentation to reflect fine-tuned model integration and remove standalone model dependencies

README.md

@@ -9,66 +9,64 @@ app_port: 7860
 
 # Step-Zero
 
-Step-Zero is a local-first hackathon demo for a "Cognitive Pacemaker": it shows only one next action at a time, lets the user mark it done or too hard, and trips a circuit breaker when friction stays too high.
+Step-Zero is a local-first hackathon demo for a "Cognitive Pacemaker": it shows only one next action at a time, lets the user mark it done or too hard, and trips a circuit breaker when friction stays too high. 
 
-## Quick Start
+It leverages a custom dual-model architecture:
+1. **Nemotron-Mini-4B-Instruct (Fine-Tuned)**: SFT fine-tuned specifically on daily goal breakdown datasets to produce extremely strict 8-word physical atomic actions without "assistant" conversational filler.
+2. **MiniCPM-3-4B**: Acts as a robust fallback and history-aware router for rejected step breakdown and stylistic rewriting (Encouraging vs Calm tones).
+
+## Hugging Face Assets
+The resulting fine-tuned model and synthetic dataset from this project have been published to Hugging Face:
+- **Model:** [tc043/step-zero-nemotron](https://huggingface.co/tc043/step-zero-nemotron)
+- **Dataset:** [tc043/step-zero-dataset](https://huggingface.co/datasets/tc043/step-zero-dataset)
+
+## Quick Start (Mock Mode)
 
 ```bash
 python3 -m venv .venv
 . .venv/bin/activate
 python -m pip install -r requirements.txt
-python generate_dataset.py
 uvicorn app:app --host 0.0.0.0 --port 7860
 ```
 
 Open `http://localhost:7860`.
 
-The app starts in mock mode so the custom UI and WebSocket loop work before model files are present.
+The app starts in mock mode by default if the GGUF models are not found, so the custom UI and WebSocket loops work out-of-the-box.
 Choose Direct, Calm, or Encouraging before pressing Enter to start a session.
 
-## Demo Checklist
-
-1. Enter a goal, for example `I need to write my tax report`.
-2. Confirm the app shows one instruction only.
-3. Click `TOO HARD` once to show the smaller prerequisite step.
-4. Click `TOO HARD` again to trigger the circuit breaker.
-5. Use `Export Trace` or open `http://localhost:7860/trace` to capture the agent trace JSON.
+## Full Local Model Mode (Production)
 
-## Local Model Mode
+To run the full LLM backend, place the required quantized GGUF files under `models/`:
+* `step-zero-nemotron-finetuned.gguf`
+* `minicpm-3-4b.gguf`
 
-Put quantized GGUF files under `models/`, then run:
+Then run:
 
 ```bash
-python -m pip install -r requirements-models.txt
 STEP_ZERO_MOCK=0 \
-NEMOTRON_MODEL_PATH=./models/nemotron-mini-4b.gguf \
+NEMOTRON_MODEL_PATH=./models/step-zero-nemotron-finetuned.gguf \
 MINICPM_MODEL_PATH=./models/minicpm-3-4b.gguf \
 uvicorn app:app --host 0.0.0.0 --port 7860
 ```
 
-The Gradio compatibility panel is available at `http://localhost:7860/gradio`; the custom Codex-generated Fog of War UI remains the root page.
+## Modal Fine-Tuning Pipeline
 
-## Modal Fine-Tune
-
-Generate the dataset first:
+If you want to reproduce the Nemotron fine-tuning run:
 
+1. Generate the synthetic dataset:
 ```bash
 python generate_dataset.py
 ```
-
-Then install Modal, authenticate, and launch the scaffold:
-
+2. Authenticate and launch the Modal training job:
 ```bash
-python -m pip install modal
 modal setup
 modal run modal_train.py
 ```
 
-`modal_train.py` is currently a scaffold for the hackathon story. The remaining production step is to wire `verbs.jsonl` into Modal storage, uncomment the `SFTTrainer` block, run the LoRA job, and export/publish the GGUF or adapter artifact.
-
-## Known Limitations & Model Trade-offs
+`modal_train.py` handles the Unsloth LoRA SFT training on `verbs.jsonl` and merges the weights into a single GGUF artifact on Modal volumes.
 
-During semantic stress testing of the live backend, we discovered the classic "Alignment Tax" associated with small, 4B-parameter local models:
-* **The Problem:** Highly instruction-tuned base models (like Nemotron-Mini and MiniCPM) are deeply trained to act like "helpful conversational assistants." When prompted with complex goals like *"write a python script"*, they often break out of the Cognitive Pacemaker persona and output helpful paragraphs instead of strict 8-word physical atomic actions.
-* **Current Mitigation:** We employ aggressive few-shot prompting, manual Jinja template overrides, and Python-side text post-processing to brutally truncate their output.
-* **The Ultimate Fix (Roadmap):** Instead of changing to a larger, slower 8B+ model, we plan to fully execute the `modal_train.py` Unsloth fine-tuning pipeline. By training a LoRA adapter specifically on `verbs.jsonl`, we will permanently "lobotomize" the chatbot persona, forcing the model to strictly output imperative verbs natively.
+## System Architecture Fixes
+During development, we successfully mitigated several core "Small LLM Alignment Taxes":
+* **The "Paragraph" Tax:** MiniCPM stylistic rewrites are strictly constrained to exactly one sentence under 12 words via robust system prompting.
+* **The "Cognitive Planning" Bug:** Fallback breakdowns explicitly ban cognitive verbs (think, plan, remember) to force strictly physical next steps.
+* **The Syntactic Rut & Repetition Loops:** Implemented a short-memory sliding window (`history[-3:]`) and an explicit string-matching repetition guard that bounces identical consecutive outputs to the history-aware fallback router.

requirements-models.txt

@@ -1 +0,0 @@
-llama-cpp-python==0.3.5

requirements.txt

@@ -2,4 +2,7 @@ fastapi==0.115.6
 gradio==5.9.1
 uvicorn[standard]==0.32.1
 websockets==14.1
-requests
+requests
+python-dotenv
+llama-cpp-python
+modal