From c205d315b73b6ea2569d53d01083e10edee01cea Mon Sep 17 00:00:00 2001
From: Torres <torres@mackwnox.ca>
Date: Tue, 10 Nov 2026 23:18:21 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20Phase=203=20status?=
 =?UTF-8?q?,=20agent-pass=20+=20copy-hygiene=20develop=20notes,=20new=20ro?=
 =?UTF-8?q?utes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index fcbc9f4..842d420 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 A private, Tinder-style web app for browsing the motorcycle market: swipe real listings (like / nope / maybe), see everything on one editable list, and let the deck learn your taste. Built for Glenn; runs on the Rotarran, published to the tailnet only.
 
-**Status:** Phase 2 (production build) — FastAPI backend + no-build PWA shipped on `dev` (2026-11-10): migrations, API with cursor-paginated deck, swipe persistence, real list/matches screens, image mirror, PWA shell. Deployment (podman stack) is Phase 4 — not started.
+**Status:** Phase 3 (personalization) built on `dev` (2026-11-11): sections of 25 (wildcards + second looks + new), taste engine with match points, tank gauges, dossier "Why this rank", real Trends tab, agent pass (mock / live / fallback). Phase 2 remains shipped as-is; deployment (podman stack) is Phase 4 — not started.
 
 ## How it works
 
@@ -52,17 +52,38 @@ python3 -m app.importer --state-dir ~/.hermes/scripts/motorcycle-hunt.d --db dat
 # serve the app (127.0.0.1:9453 by default)
 .venv/bin/python -m app.serve --db data/bike-tinder.sqlite3 --port 9453
 
-# self-check: 8 P1 spine checks + 6 P2 API checks (on a temp DB copy)
+# self-check: P1 + P2 + P3 (25 checks, temp DB copies only)
 .venv/bin/python -m app.selfcheck
 
+# P3: agent pass — mock is deterministic + offline (tests, offline forge);
+# --live needs OPENROUTER_API_KEY (+ optional BT_AGENT_MODEL); --dry-run
+# validates the payload and writes nothing; --print-summary prints exactly
+# the strike summary a live pass would be sent.
+.venv/bin/python -m app.agentpass --db /tmp/bt-copy.sqlite3 --mock
+.venv/bin/python -m app.agentpass --db /tmp/bt-copy.sqlite3 --print-summary --dry-run
+
+# P3: run a scratch server against a COPY (NEVER point a dev server at
+# data/bike-tinder.sqlite3 while the live service owns it — use port 9454).
+cp data/bike-tinder.sqlite3 /tmp/bt-copy.sqlite3
+.venv/bin/python -m app.serve --db /tmp/bt-copy.sqlite3 --img-dir data/img --port 9454
+curl -s http://127.0.0.1:9454/api/section            # first read composes a section
+curl -s -X POST http://127.0.0.1:9454/api/section/forge \
+  -H 'Content-Type: application/json' -d '{"size": 8}'   # mock pass + compose
+
 # proof CLI: ranked deck + counts (read-only)
 python3 -m app.deck --db data/bike-tinder.sqlite3 --top 15
 ```
 
-Key routes: `/` (PWA), `/api/health`, `/api/stats`, `/api/deck?limit=&cursor=`,
-`POST /api/swipe` / `DELETE /api/swipe/{id}`, `/api/list?decision=&sort=&q=&limit=&offset=`,
+Key routes: `/` (PWA), `/api/health`, `/api/stats`, `/api/deck?limit=&cursor=` (read-only
+legacy fallback), `POST /api/swipe` / `DELETE /api/swipe/{id}`, `/api/list?decision=&sort=&q=&limit=&offset=`,
 `/api/listing/{id}`, `POST /api/import`, `POST /api/badge/seen`, `/img/{id}`
-(cached file → 302 source CDN → 404 placeholder). Full contract: `docs/UI-SPEC.md` + the task brief.
+(cached file → 302 source CDN → 404 placeholder).
+P3 (Phase 3): `GET /api/section`, `POST /api/section/forge` `{size}`,
+`GET /api/trends`, `POST /api/agent/run` `{source: mock|live}`,
+`POST /api/prefs` `{key: forge_mode, value: ondemand|strict}`. Listing
+payloads carry `points`, `tank {value, band}`, `slot`, `round_next`,
+`points_breakdown`. Full contract: `docs/UI-SPEC.md` §10 + `docs/RANKING.md`
+Stage 2 + the task brief.
 
 `data/` and `.venv/` are gitignored — the DB, image mirror and venv are local state.