docs: lead with personalized learning loop

JUDGES.md

@@ -5,9 +5,26 @@
 **License:** Apache-2.0  
 **Codex session ID:** `019f7184-325b-7ec0-879a-856b59de5e17`
 
-VibeBloat turns mistakes found in coding-agent history into deterministic,
+VibeBloat is a private, personalized learning loop for coding agents. It onboards
+to each developer's tools and history, retrieves old incidents semantically even
+when the next mistake is reworded, and keeps proposing stronger protections as
+new history arrives. Human-approved lessons compile into deterministic,
 cross-agent guards that run before dangerous commands execute.
 
+## What makes it different
+
+1. **Onboarding is custom to you.** VibeBloat detects agent runners and history
+   sources, asks explicit privacy and recall questions, measures the available
+   evidence, and installs only approved integrations and guards.
+2. **Recall is semantic.** Optional local MiniLM embeddings retrieve incidents by
+   meaning rather than exact tokens. A destructive-shape prefilter keeps benign
+   same-tool commands quiet and avoids unnecessary model startup.
+3. **It learns over time.** Returning-user incremental scans and an optional
+   native daily scheduler propose new or strengthened guards as history grows.
+4. **Learning cannot silently become enforcement.** Semantic hits remain
+   advisory. Every promotion to a hard block requires human approval, and the
+   runtime hot path remains deterministic.
+
 ## Two-minute evaluation
 
 Prerequisites: Git and [Bun](https://bun.sh) `>=1.3.0`.
@@ -38,6 +55,55 @@ The output then shows:
 - Safe variants `docker compose down` and `git stash` allowed with exit code `0`.
 - Same guard returned as a structured Codex `PreToolUse` denial.
 
+This proves the final enforcement result. The personalized learning system that
+produces those guards can be evaluated below.
+
+## Evaluate personalized onboarding
+
+```sh
+bun src/cli.ts init --pretty
+```
+
+The onboarding detects supported agents and history sources, explains what it
+would read, asks for consent, lets the user choose lexical or local semantic
+recall, reviews mined incidents, and installs only explicitly approved guards.
+The user can decline before any personal history is ingested.
+
+Automated onboarding proof:
+
+```sh
+bun test tests/e2e/onboarding-12min.test.ts tests/onboarding-returning.test.ts
+```
+
+## Evaluate semantic and ongoing learning
+
+Fast deterministic coverage:
+
+```sh
+bun test tests/recall-local.test.ts tests/onboarding/returning-service.test.ts tests/onboarding-daily-scheduler.test.ts
+```
+
+Optional live MiniLM coverage requires Node.js `>=20` and downloads the model on
+first run:
+
+macOS or Linux:
+
+```sh
+VIBEBLOAT_REQUIRE_REALMODEL=1 bun test tests/recall-local-realmodel.test.ts
+```
+
+Windows PowerShell:
+
+```powershell
+$env:VIBEBLOAT_REQUIRE_REALMODEL = '1'
+bun test tests/recall-local-realmodel.test.ts
+```
+
+The real-model test requires benign same-family Git commands to remain below the
+warning threshold while a genuine reworded destructive incident remains above
+it. If the model cannot load, the required gate fails instead of reporting a
+false green result.
+
 ## Reproduce the submitted proof
 
 ```sh

README.md

@@ -1,11 +1,27 @@
 # VibeBloat
 
-**Your coding agent keeps making the same mistake. VibeBloat learns it once and never lets it through again.**
+**Your coding environment learns from your agent mistakes and gets harder to break over time.**
+
+VibeBloat is not a static command blocklist. It privately onboards to your agent
+setup and history, uses semantic recall to recognize old failure patterns even
+when they are reworded, and turns the lessons you approve into deterministic
+guards shared across your tools. Incremental scans keep proposing new and
+stronger protections as you work; a human still approves every hard block.
 
 ## OpenAI Build Week judges: start here
 
-This deterministic two-minute path uses invented sample history. It reads none of
-your data, needs no API key, and makes no model call.
+The fast demo shows the enforcement end of VibeBloat's larger learning loop:
+
+1. **Personal onboarding:** detect your agents and history sources, then let you
+   choose privacy, recall, review, and enforcement preferences.
+2. **Semantic memory:** retrieve relevant past incidents by meaning, not only by
+   exact command tokens.
+3. **Learning over time:** incremental scans and daily strengthening propose new
+   lessons as your history grows.
+4. **Safe enforcement:** only human-approved guards become deterministic blocks.
+
+This deterministic two-minute path uses invented sample history. It reads none
+of your data, needs no API key, and makes no model call:
 
 ```sh
 git clone https://github.com/veltri-23/vibebloat.git
@@ -22,7 +38,11 @@ Codex denial.
 
 Give an agent enough rope and it will eventually run `git stash -u` over untracked files, `docker compose down -v` on the dev database, or `git reset --hard` over an hour of uncommitted work. You fix it, you move on, and three days later a different agent does the same thing. The lesson lives in your head, not in the tools.
 
-VibeBloat reads your agent history, finds the commands that actually burned you, and compiles each one into a deterministic guard that blocks it before it runs again. One heavy scan up front. After that the guards enforce for free, on every agent, forever. No tokens, no prompt budget, nothing the model can talk itself out of.
+VibeBloat reads your agent history, finds the failures that actually burned you,
+and compiles each approved lesson into a deterministic guard. The first scan
+builds your personal baseline; bounded returning scans process new evidence and
+propose updates. Between scans, guards enforce for free across agents: no tokens,
+no prompt budget, and nothing a model can talk itself out of.
 
 <p align="center">
   <img src="assets/block.png" alt="A recovered Claude Code session tries git stash -u and gets blocked with exit code 2, citing the exact incident that produced the guard" width="760">