@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/README.md

@@ -5,7 +5,7 @@
 > **Body and soul — more travel, less tourism.**
 > *身体和灵魂,更多旅行,更少旅游。*
 
-GoTry is an AI travel agent for **"departure to next departure."** You tell it where you want to go and why; it interviews you about your working hours and existing bookings, then hands you a **formally verified itinerary** — computed by a Z3 solver, not guessed by a model.
+GoTry is an AI travel agent for **"departure to next departure."** You say where you want to go and why; it asks what needs asking, then lets code — not the model — make the call: can you go, how, and at what true cost. Every number comes with a source; nothing is hallucinated.
 
 [![GitHub Stars](https://img.shields.io/github/stars/Danceiny/gotry?style=social)](https://github.com/Danceiny/gotry/stargazers)
 [![CI](https://github.com/Danceiny/gotry/actions/workflows/ci.yml/badge.svg)](https://github.com/Danceiny/gotry/actions/workflows/ci.yml)
@@ -14,86 +14,70 @@ GoTry is an AI travel agent for **"departure to next departure."** You tell it w
 [![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.15-blue)](https://www.npmjs.com/package/@danceiny/gotry)
 [![Docs](https://img.shields.io/badge/docs-architecture.md-blue)](docs/architecture.md)
 
-**[What GoTry Does](#what-gotry-does)** · **[How It Works](#how-it-works)** · **[Tools](#tools)** · **[Demo](#demo)** · **[Benchmark](#how-mainstream-ai-answers-the-same-trip)** · **[Quick Start](#quick-start)** · **[Consent and Privacy](#consent-and-privacy)** · **[Trustworthy by Construction](#trustworthy-by-construction)** · **[Project Status](#project-status)** · **[Roadmap](#roadmap)** · **[For AI Agents](#for-ai-agents)** · **[Documentation](#documentation)** · **[License](#license)** · **[Star History](#star-history)**
-
-> **Tip for newcomers:** one command is enough to feel the difference — `npx @danceiny/gotry web`, open `http://127.0.0.1:3080`, and say *"I want three relaxing days in Dali."* The agent interviews you first; then the solver, not the model, decides what is feasible. Full walkthrough: [`docs/user-guide.md`](docs/user-guide.md).
+**[What it does](#what-gotry-does)** · **[How it works](#how-it-works)** · **[Demo](#demo)** · **[Benchmark](#benchmark)** · **[Quick start](#quick-start)** · **[Privacy & trust](#privacy-and-trust)** · **[Status & roadmap](#project-status-and-roadmap)** · **[Contributing](#contributing)** · **[Docs](#documentation)**
 
 ## What GoTry Does
 
-GoTry turns "I want to go somewhere" into "can I — and how, at what true cost?" When the answer is "not this weekend," the destination is caught in a wish pool with its conditions instead of being dropped.
+Turns "I want to go somewhere" into "can I go, how, and at what true cost?" If this weekend won't work, GoTry doesn't drop the idea — the destination is parked in a wish pool with the exact conditions that would reopen it.
 
-- **For travelers** — a conversational planner that asks the questions that actually matter (working window, booked resources, departure city, budget), then returns a verdict per destination: feasible or not, why, and the **smallest change that makes it feasible**.
-- **For agent builders** — a working example of an agent where the LLM only listens, translates, and explains. Decisions and arithmetic live in a Z3 solver; every deliverable number carries a provenance tag; write operations are gated by design.
-- **Evidence built in** — an estimate never poses as realtime. Tags are attached by the render layer, never by the model, and switch honestly on degradation. Bookable claims that cannot trace to an exact-date tool result are blocked before delivery.
+- **For travelers** — it asks the right questions first (which days you can leave, departing from where, on what budget), then gives every destination a straight answer: yes, no, or why — plus the smallest change that turns a no into a yes.
+- **For agent builders** — the LLM only listens, translates, and explains; numbers are computed and verdicts made by code. Every delivered number carries a source tag; writes are gated by design.
 
 ## How It Works
 
-One planning pass is a pipeline. The model owns the two language-heavy ends; the solver owns everything numeric:
+The model owns the language ends; deterministic code owns the numbers:
+
+```mermaid
+flowchart LR
+  U(["Traveler: 'I want three relaxing days in Dali'"]) --> A
+  subgraph LANG["LLM owns — language"]
+    A["Motivation interview<br/>working window · bookings · departure city"] --> B["Fact extraction<br/>working-hours &amp; leave semantics"]
+  end
+  subgraph NUM["Deterministic TypeScript kernel — ordinary choice path"]
+    C["Candidate enumeration<br/>solveChoiceSegment"] --> D["Evaluate each choice<br/>evaluateChoice · true-cost checks"] --> V["Choice verdict<br/>feasible / infeasible · recommendation"]
+  end
+  subgraph Z3PATH["Separate script/control-plane entry"]
+    Z["solveUnified<br/>script/control-plane flight-chain · Z3"]
+  end
+  subgraph GATE["Gates &amp; memory"]
+    E["Evidence chain<br/>every number carries a source tag"] --> F{"Fact gate"}
+    F -->|"all claims trace to exact-date tools"| G["Verified itinerary delivered"]
+    F -->|"unverifiable"| H["Blocked — never posed as verified"]
+    I[("Wish pool<br/>saved with recall conditions")]
+  end
+  B --> C
+  V --> E
+  B -.->|"separate script/control-plane entry"| Z
+  Z --> E
+  V -.->|"infeasible today"| I
+  I -.->|"conditions met — enumerate again"| C
+  classDef llm fill:#1f6feb22,stroke:#1f6feb,color:#1f6feb;
+  classDef solver fill:#2ea04322,stroke:#2ea043,color:#2ea043;
+  classDef gate fill:#d2992222,stroke:#d29922,color:#9e6a03;
+  class A,B llm;
+  class C,D solver;
+  class E,F,G,H,I gate;
+```
 
-| Stage | Who | Output |
-|---|---|---|
-| Motivation interview | LLM | Mandatory questions: working window / booked resources / departure city |
-| Fact extraction | LLM | Working-hours semantics, leave semantics |
-| Feasibility verdict | **Z3 solver** | Which destinations are feasible / infeasible, why, and the smallest change that makes them feasible |
-| Door-to-door true cost | Solver | Real flight duration (incl. time zones) + early-wake penalty + transfer cost + arrival energy |
-| Evidence chain | Render layer | Every number carries a source tag |
-| Delivery gate | Fact gate | Bookable claims must trace to exact-date tool results, or the artifact is blocked |
-| Memory | Domain layer | Infeasible today → wish pool, with explicit recall conditions |
+Architecture — the sync path from chat through the kernel to the fact gate, plus the state/async control plane and the read-only data layer:
 
-Vocabulary you will meet in a GoTry answer:
+<a href="docs/assets/gotry-system-architecture.en.html">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/gotry-system-architecture.en.dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/gotry-system-architecture.en.light.png" />
+    <img alt="GoTry system architecture — sync path from chat through TypeScript candidate enumeration, evaluation, and choice to the fact gate, with the explicit flight-chain Z3 path shown separately, plus the state/async control plane and the read-only data layer" src="docs/assets/gotry-system-architecture.en.light.png" />
+  </picture>
+</a>
 
-- **Evidence tag** — `[skeleton:openflights]` route existence verified against the public route database; `[realtime:...]` pulled live from an API seconds ago; `[static-pack:estimate]` a researched estimate — not realtime, verify before booking. On degradation the tag switches honestly.
-- **Door-to-door true cost** — the ticket price plus what the trip actually takes from you: real duration across time zones, the early-wake penalty, transfers, and the energy you land with.
-- **Wish pool** — "next departure" storage. An infeasible dream is saved with explicit conditions (e.g. "5+ days, off-season") and recalled when they can be met.
-- **Fact gate** — pre-delivery check on itinerary artifacts: every bookable claim (flight no. / time / airport / price / policy) must trace to an exact-date tool result; unverifiable means blocked — never presented as a verified plan.
+> Interactive version: [`docs/assets/gotry-system-architecture.en.html`](docs/assets/gotry-system-architecture.en.html) (archify, showcase-validated). Layers: L2 dsh plugin · L3 `ts/src/unified.ts` kernel · L4 effect interpreter + realtime bridges · L5 loopx governance. ADRs: [`docs/architecture.md`](docs/architecture.md).
 
-Architecture, five layers:
+23 registered tools in groups: realtime retrieval (Fliggy official channel + your own Chrome session, read-only) · catalog · decision engine · memory · artifacts · fact gate · external search · `gotry_doctor` self-check. No hidden dispatch — a channel registry returns an ordered suggestion list; the model or user chooses. Per-tool contracts: [`docs/tools.md`](docs/tools.md).
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│ L1  chat-as-interface; gates are in-message choice cards       │
-│ L2  orchestration  dsh runtime + GoTry plugin (ReAct); 21 tools│
-│ L3  domain  unified itinerary model + Z3 feasibility engine    │
-│ L4  data  static packs + hotelbyte-cli bridge + OpenFlights    │
-│ L5  governance  LoopX (objective / gates / evidence / quota)   │
-└──────────────────────────────────────────────────────────────┘
-```
+## Demo
 
-| Layer | Module | Role |
-|---|---|---|
-| L2 | `ts/src/index.ts` (dsh plugin) | 21 tools, time-anchor & memory-brief variables; execute isolation + consent gate + per-turn tool budget + process guards |
-| L3 | `ts/src/unified.ts` · `py/gotry_feasibility/` | single solving entry (candidate enumeration + flight-chain Z3) |
-| L4 | `ts/capabilities/effect.ts` · `hbcli.ts` · `skeleton-check.ts` | effect interpreter (backoff retry / circuit breaker / mock interpreter) + realtime inventory bridge + OpenFlights skeleton (three-valued semantics) |
-| L5 | loopx governance | objective / gates / evidence / quota |
-
-> Full ADRs / evolution / debt ledger: [`docs/architecture.md`](docs/architecture.md) (Chinese — English versions planned for v0.1.0).
-
-## Tools
-
-22 tools in six groups:
-
-| Group | Tool | What it does |
-|---|---|---|
-| **Realtime retrieval (OTA/official, read-only)** | `gotry_flyai_search` | Live flight/train/hotel quotes via the Fliggy official channel (masked hotel prices upstream; real prices on the jumpUrl page; exhausted anonymous trial quota degrades as `needs-setup` with key guidance, never silent retries) |
-| | `gotry_session_search` | Ctrip flights **and hotels** + 12306 trains on the **user's own Chrome session** (consent-gated, physically read-only; hotels = `kind:"hotel"` + optional `cityId`, real logged-in prices; trains = `kind:"train"`, public query face — codes/times/seat availability, no prices in the list API) |
-| | `gotry_session_login` | Login bootstrap: auto-detects existing login first; otherwise opens the login entry in the user's Chrome (**zero terminal**) |
-| | `gotry_weather_check` | Open-Meteo forecast ≤16 d + historical climate baseline |
-| | `gotry_flight_verify` | OpenSky ADS-B live flight observation (three-valued) |
-| | `gotry_skeleton_check` | OpenFlights 168-hub-pair connectivity (three-valued) |
-| **Inventory & catalog** | `gotry_hotel_search` | hotel-byte realtime bridge, degrades to static pack (tagged) |
-| | `gotry_anything_search` | mixed city/hotel/POI catalog (hotel-be Anything) |
-| **Decision engine** | `gotry_feasibility_check` | Door-to-door true-cost feasibility (Z3), per-candidate verdicts |
-| **Memory & reachability** | `gotry_motivation_save` | Persist motivation profile (evidence mandatory, anti-fabrication) |
-| | `gotry_wish_pool_add` / `gotry_wish_pool_list` | "next departure" wish pool + 0..1 conditional recall |
-| | `gotry_companion_save` · `gotry_trip_log` | companion profile / travel timeline |
-| **Artifacts** | `gotry_artifacts_list` / `gotry_artifacts_read` | Discover & view generated artifacts (async deliverables + working-dir markdown) as a line-numbered file view (read-only) |
-| **Factuality gate** | `gotry_fact_gate` | Pre-delivery gate for itinerary artifacts — see [fact gate](#how-it-works) above |
-| **General external** | `gotry_web_search` · `gotry_video_subtitle` · `gotry_github_search` · `gotry_agent_reach` | web / subtitles / GitHub / all-channel external info (via Agent-Reach) |
-| **Self-check** | `gotry_doctor` | Read-only health check of optional dependencies (extension / Agent-Reach .venv / hbcli / FlyAI key **+ recent trial-quota exhaustion time** / dsh-calendar mount state / sidebar / dsh-map-tools & dsh-tool-ask-user presence) with exact repair guidance; installs only ever happen via the user running `npx gotry doctor --fix`. LLM keys are the dsh host's business — deliberately out of scope. Report lands in `gotry-state/doctor-report.md` (sidebar-workbench previewable) |
-
-> **Channel routing**: retrieval tools stay flat (no hidden dispatch); the persona routing card and the `routing` suggestions attached to failed search results are **generated from one channel registry** (official API > user session > web fallback, filtered by per-session channel health). When a channel exhausts its quota the result says so and names the next channel — retry-blindness is a contract violation, not a prompt hope.
+https://github.com/user-attachments/assets/6628c254-eba1-4017-a883-c70d22616939
 
-## Demo
+*Illustrative animation-harness capture of a condensed transcript — not a real `gotry web` product UI E2E (sources: [SVG](docs/assets/demo.en.svg) · [webm](docs/assets/demo.en.webm)):*
 
 ```
 > Two or three days staring at Erhai Lake, leaving from Shanghai, budget 3000, annual leave — no work.
@@ -113,11 +97,11 @@ Engine verdict:
 [static-pack:estimate] G7315/G7316 priced on Jul–Aug off-season rates
 ```
 
-> Tag guide: `[skeleton:openflights]` means "this route can be flown" was verified against the public route database; `[realtime:...]` marks data pulled live seconds ago; `[static-pack:estimate]` flags an off-season estimate — **verify before booking**. Tags are attached by the render layer, never by the model.
+> Tags: `[skeleton:openflights]` route verified against the public route DB · `[realtime:...]` pulled live seconds ago · `[static-pack:estimate]` estimate — **verify before booking**. Attached by the render layer, never the model.
 
-## How Mainstream AI Answers the Same Trip
+## Benchmark
 
-GoTry's product persona is calibrated against evidence, not taste: the same real three-week multi-country workation prompt — with planted traps (no year given, a vague "some seaside town called Wan-xx", an ambiguity the user already resolved) — is fed verbatim to mainstream assistants, their answers archived word-for-word, and scored against a ground-truth rubric. Transcripts, rubric, and the contract feedback: [`docs/persona-bench/`](docs/evaluation/persona-bench/).
+The same real multi-country workation prompt — with planted traps (no year given, a vague "Wan-xx", an already-resolved ambiguity) — goes verbatim to mainstream assistants; answers are archived word-for-word and scored against a ground-truth rubric ([`docs/evaluation/persona-bench/`](docs/evaluation/persona-bench/)).
 
 | Dimension | Generic chat assistant (Kimi, 13 real turns) | OTA agent (Fliggy open platform, single turn) | GoTry contract |
 |---|---|---|---|
@@ -128,171 +112,95 @@ GoTry's product persona is calibrated against evidence, not taste: the same real
 | Structure completeness | △ decent comparison table only at turn 13 | ✓✓ full skeleton in one turn — completeness is table stakes | verified completeness (fact gate) |
 | Persona in one line | erudite but stateless chatter — the user ends up doing four jobs | a flawless-brochure OTA clerk — every section ends in a price table | trusted travel engineer: interview first, the solver decides, infeasible says infeasible |
 
-**Single best finding: two unrelated products derived their weekdays from the 2025 calendar.** Calendar grounding has to be a product mechanism (anchor card, assert once, never recompute) — not model luck. Cautionary deep-dive: [`docs/research/kimi-postmortem.md`](docs/research/kimi-postmortem.md).
+> **Evidence boundary:** a qualitative comparison, not a scorecard. The Kimi/Fliggy columns summarize archived transcripts (13 turns vs one); the GoTry column summarizes repository behavior contracts. No ranking or uplift is asserted.
 
-## Quick Start
+Single best finding: two unrelated products derived their weekdays from the 2025 calendar — calendar grounding must be a mechanism, not model luck ([postmortem](docs/research/kimi-postmortem.md)).
 
-### npm (recommended)
-
-```bash
-npx @danceiny/gotry web
-# → open http://127.0.0.1:3080 and chat: "I want three relaxing days in Dali"
-# LLM key & model: handled by the dsh host UI; nothing for gotry to ask on the CLI
-```
-
-| Entry | Command | When |
-|---|---|---|
-| Web chat (recommended) | `npx @danceiny/gotry web` | multi-turn planning with visualized reasoning → `:3080` |
-| Headless one-shot | `npx @danceiny/gotry "Two recovery days from Shenzhen, budget 3000"` | scripts / CI / targeted debugging → stdout |
-| Dependency doctor | `npx @danceiny/gotry doctor` (`--fix` to repair) | optional channels misbehaving: checks extension / Agent-Reach / hbcli / FlyAI key / sidebar / dsh-calendar mount / dsh-map-tools & dsh-tool-ask-user presence, prints exact repair guidance, writes `gotry-state/doctor-report.md` (previewable in the sidebar workbench) |
-
-Requires Node ≥ 22.15. LLM credentials are managed by your dsh host UI — gotry itself never asks for or echoes them. OpenAI-compatible endpoints (MiniMax / relays / self-hosted gateways) are handled by the dsh model configuration. First cold start takes 6–15 s; if port `:3080` is taken, free it first; unexpected exits leave evidence in `gotry-state/incidents.jsonl` (nothing silent).
-
-> **Cost accounting** — `ts/data/llm-price-table.json` (schema `gotry_llm_price_table_v2`) is the single source of truth for nightly run cost. Adding a model or switching relays = a PR against this file (peak-conservative upper bounds only); unknown models **fail closed** — no guessed prices. Drift monitor: `npx tsx ts/scripts/price-drift-watch.ts` (offline baseline diff; `--fetch` for live official pages). It never auto-applies changes.
-
-> **Quality metrics (repo-side)** — `npx tsx ts/scripts/build-metrics-report.ts [--state-root <root>] [--out report.md] [--days 7]` aggregates the persisted sidecars (fact-gate verdict distribution & blocked rate, channel down/cooldown, incidents, bridge latency vs the 500 ms re-audit budget, ledger / doctor-report presence) into one read-only markdown report. No new dependencies, zero LLM; the state root is never written (only `--out` produces a file, outside the state root).
-
-> **Channel probe tick (out-of-band health)** — `npx tsx ts/scripts/channel-probe.ts --state-root <root>` runs one read-only probe round over headless-probeable channels (hbcli whoami / open-meteo / opensky; session surfaces are skipped, FlyAI is not probed by default to preserve the shared anonymous quota) and appends `down` / `'ok'` recovery events to `channel-health.jsonl` — routing advice and doctor pick them up with zero changes. Driven by cron/loopx; no resident process. Wish recall consumes the same facts: a wish whose `conditions.channels` names a currently-down channel is vetoed for that recall. Remote (world2agent) callback stays gated on D-31.
-
-### Developer source install
+## Quick Start
 
 ```bash
-git clone https://github.com/Danceiny/gotry && cd gotry
-npm ci && npm --prefix ts ci                      # pinned root/TS closure
-node scripts/build-dist.mjs                       # build the JS runtime
-./gotry web                                       # in-repo entry, same UX
+npx @danceiny/gotry web        # → http://127.0.0.1:3080
+npx @danceiny/gotry doctor     # optional-channel health check (--fix to repair)
+npx @danceiny/gotry "Two recovery days from Shenzhen, budget 3000"   # headless one-shot
 ```
 
-The source entry and the npm package resolve the same 216-package DeepSeek Harness `0.1.2-alpha.3` closure (exact direct dependencies; publish preverify rejects omissions, mixed versions, and ranges). Source normal runs keep their state under `ts/dsh-runtime/gotry-state/`; benchmark opt-in and npm-package runs use the invocation directory for isolation.
-
-## Consent and Privacy
+Node ≥ 22.15. LLM keys live in the dsh host UI (OpenAI-compatible endpoints included) — gotry never asks for or echoes them. Any npm-compatible registry works; pin an exact version if a mirror's `latest` lags. Inside this repo use the source entry `./gotry web` (bare-name npx fails there). Eligible launches may offer a one-time capability check; CI / non-TTY never prompts, never installs. Onboarding details + operator scripts: [`docs/tools.md`](docs/tools.md). Source install: `npm ci && npm --prefix ts ci && node scripts/build-dist.mjs` — the same pinned DSH `0.1.5-rc.1` closure as the npm package. Full-stack verify: `./scripts/run-all-tests.sh`.
 
-The account-session channel reads realtime hotel/flight data from **your own logged-in Chrome**, under four hard rules:
+## Privacy and Trust
 
-1. **Login happens on the external website.** GoTry never offers, fills, or collects any password / SMS code / cookie value. It only answers one boolean question — "does a login-ticket cookie exist" (reads cookie **names** only, zero values touched). Existing logins are auto-detected with zero popups.
-2. **Consent card, once per session.** The first account-session use pops a runtime approval card; approval holds for the session, a refusal revokes it (no repeat prompting). Master switch `sessionAccess: ask|allow|off` at any time.
-3. **Physically read-only.** A ReadGuard aborts all write requests at the network layer — ordering/payment is unreachable in transport. The agent never touches credentials or captchas; on a captcha it stops and hands control back to you.
-4. **Never hijacks your browser.** Retrieval/login always open their own dedicated tab; the login page is brought to front and stays with you; routine test runs never open browser windows.
+The account-session channel reads realtime data from **your own logged-in Chrome**, under four hard rules:
 
-One-time prerequisite: the [GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) Chrome extension — handled by the dsh host UI when an account-session tool first needs it (`gotry_session_search` surfaces the install URL as a clickable link in the verdict). The extension itself is one-click on the Chrome Web Store, auto-updates, and the gotry side never asks the user to load unpacked or to run a setup wizard. Zero Chrome system dialogs afterwards — the extension passively forwards the site's own search responses (read-only by construction; cookies are read by NAME only, values never leave the browser). A background health-watch auto-replays your query once the extension is connected. Until installed, tools return `needs-extension` with the store URL and spend nothing.
+1. **Login happens on the external website** — no passwords, SMS codes, or cookie values; cookie *names* only.
+2. **Consent card, once per session** — refusal revokes it; master switch `sessionAccess: ask|allow|off`.
+3. **Physically read-only** — a ReadGuard aborts writes at the network layer; a captcha stops the agent.
+4. **Never hijacks your browser** — dedicated tabs only; tests never open windows.
 
-## Trustworthy by Construction
+One-time prerequisite: the [GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) extension (one-click, auto-updates) — until installed, tools return `needs-extension` with the store link and spend nothing.
 
-1. **The model translates; the solver decides.** The LLM never produces feasibility verdicts or arithmetic — those are computed by Z3 against the extracted facts.
-2. **Every number carries a source tag** — attached by the render layer, never the model. Tags switch honestly on degradation; an estimate never poses as realtime.
-3. **No write path exists.** Booking/payment-class tools must pass WriteGate before any implementation ships; the future booking seam is already pinned by the `booking_saga_fsm.v1` edge table.
-4. **Login never touches credentials.** Login happens on the external website; GoTry reads cookie names only; consent is asked once per session and revocable.
-5. **Retrieval is physically read-only.** A ReadGuard aborts write requests at the network layer; a captcha stops the agent and hands control back to you.
-6. **Unverifiable means blocked.** The fact gate refuses to deliver any itinerary whose bookable claims cannot trace to exact-date tool results — it is never presented as a verified plan.
-7. **Prices fail closed.** Unknown models get no guessed price; the price table changes only by PR; the drift monitor reports, never auto-applies.
-8. **Your data is yours.** Product state lives under `gotry-state/`; automated tests and smoke runs use isolated state roots and never write the founder's real product data.
+Trust is structural, not promised:
 
-## Project Status
+1. **The model translates; code decides** — no LLM feasibility verdicts or arithmetic.
+2. **Every number carries a source tag** — attached by the render layer, switched honestly on degradation.
+3. **No write path exists** — booking/payment tools must pass WriteGate before they ship.
+4. **Unverifiable means blocked** — the fact gate never lets an untraceable claim ship as "verified"; anchors are fingerprinted.
+5. **Prices fail closed** — unknown model, no guessed price; the price table changes only by PR.
+6. **Your data is yours** — state under `gotry-state/`; tests run on isolated roots.
 
-Current release: **v0.0.1-rc.18** (npm `latest` and `rc` both point here; registry pull-verified 2026-09-03: clean install / bin / dist entry all pass). Evaluation is at Phase 0 foundation — deterministic contracts, validators, and a cadence policy; no external benchmark scores, no spend, no uplift claims.
+## Project Status and Roadmap
 
-**Working today** (full-stack regression green; every item has deterministic tests):
+**v0.0.1-rc.24** on npm (`latest`). Pre-1.0: the core loop works end to end; evaluation is still at deterministic contracts and validators, with no external scores or uplift claims.
 
-- **Z3 solving engine** — feasibility verdicts + door-to-door whole-cost; the historical concurrency race is fixed and regression-gated
-- **Realtime retrieval** — flights/trains/hotels (Fliggy official channel), destination/hotel catalogs, weather, live flight observation, route connectivity; realtime prices can overwrite solver prices (`GOTRY_REALTIME_PRICING=1`); exhausted FlyAI anonymous trial quota is classified `needs-setup` with key guidance (no blind retries)
-- **Dependency doctor** — `npx gotry doctor` (CLI) / `gotry_doctor` (in-chat tool): read-only health check of optional dependencies (extension / Agent-Reach / hbcli / FlyAI key / sidebar / dsh-calendar mount / dsh-map-tools & dsh-tool-ask-user presence) with exact repair guidance; map tools ship as a bundled MIT payload rather than an incompatible external npm peer; `--fix` installs; LLM keys stay with the dsh host
-- **Account-session search** — Ctrip flights **and hotels** + 12306 trains on your Chrome (hotels 2026-09-03: real logged-in prices via passive sniffing; trains 2026-09-03: public left-ticket query; interface surfaces calibrate with the first live session); observed runs scored every landed hit 13/13 with zero write attempts, while non-hits stay explicit `miss` records — no live-availability claim beyond that
-- **Extension install on demand** — `[GoTry Session Bridge](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd)` is offered as a clickable link in the dsh UI when an account-session tool first needs it (one-click install + auto-update); the gotry side never runs a setup wizard
-- **Memory & reachability** — motivation profile / wish pool / companions / travel timeline; English solve output via `GOTRY_LOCALE=en`
-- **Routed turn budgets** — every turn is classified (quick / sync / deep-planning) by a deterministic, zero-LLM router; time is the only budget and the deadline exit follows the task: quick and sync turns converge to an answer, deep-planning turns hand off to a persisted background ticket (`gotry_turn_handoff.v1`, ETA ≈1h) instead of dying mid-stream; the ticket is collected in the background by `scripts/turn-handoff-collect.ts` (idempotent, recursion-guarded child planner) and surfaces in-chat via the read-only `gotry_turn_handoff_list` tool; exercised end-to-end through a packaged consumer install in CI
+**Working today** — interview → deterministic feasibility verdict → itinerary with door-to-door true cost · realtime retrieval (Fliggy + your own Chrome session, read-only) with typed, invocation-bound facts · memory (motivation, wish pool, companions, timeline) on a tenant-scoped ledger · self-check doctor with scoped, approved repair.
 
-**Open limitations** (honest list):
+**Not yet** — nothing is bookable today; booking ships only behind the WriteGate user-confirmation design · live-availability evidence is still partial · the real-user cohort study has not reached its exit bar · English covers the solver output layer only.
 
-- **M3 Exit not closed** — engineering & distribution are ready, but real seed-user evidence (50–200 person cohort) has not been accumulated; automated tests prove contracts and formulas, not business pass
-- **Hotel session adapters** — Ctrip-hotel / Meituan logged-in surfaces await real login-state backfill; flights are done
-- **Interface language** — English covers the deterministic solve-output layer; the dsh host UI and dialogue surface belong to the host / calibration samples
-- **External benchmark generalization** — every frozen external run to date remains diagnostic-only (no score, no uplift claim). After the Round 10 `glm-5.3-flash` visibility diagnosis on main `c843fae` (57 empty `{}` calls), Round 11 keeps execution validation exact against frozen descriptors while exposing a flat model-facing `tools/call/errors` wire with descriptor-derived tool names and generic object arguments; the round-by-round engineering ledger lives in [`docs/evaluation/benchmark-environment-bridge.md`](docs/evaluation/benchmark-environment-bridge.md)
-- **Booking** — nothing bookable ships today; M5 opens only through WriteGate and the booking-saga FSM
-
-<details>
-<summary>Deeper engineering state (ledger contracts / evidence contracts / milestone stance)</summary>
-
-The authoritative state lives in the docs, not this README: transactional state ledger (ADR-15) + dual-form freeze (ADR-16: one ledger semantics for local+web); the M3 real-cohort evidence contract stands (fixtures don't count toward Exit; 50–200 real samples open the gate); the M4 paired-cohort value evidence contract (synthetic data is never Exit evidence); the async work-order terminal contract (`gotry_async_terminal.v1`: 4/4 → succeeded / ledger settled / exit 0). Details: [`docs/roadmap.md`](docs/roadmap.md) / [`docs/architecture.md`](docs/architecture.md) §1 and issues #19–#22.
-
-</details>
-
-## Roadmap
-
-| # | Milestone | Scope | Status |
-|---|---|---|---|
-| M0 | Deterministic pipeline | dual engine implementations + real data packs + reconciliation | ✅ |
-| M1 | Agent form established | LLM in the loop; chat as interface; gates as choice cards | ✅ 2026-08-22 |
-| M2 | Realtime data | hotelbyte bridge + flight sources; evidence chain switches to realtime tags | ✅ 2026-08-22 |
-| M3 | MVP | minimal web face + 50–200 seed users (Erhai / Phuket scenarios) | **← current — evidence open** |
-| M4 | Memory & "next departure" | six-layer memory C-end domain; paired-cohort value evidence | founder-authorized parallel |
-| M5 | Transaction loop | WriteGate in production; booking / payment / refunds | entry-gated |
-| M6 | B2B embedding | principal/sponsor plugin with zero kernel changes | entry-gated |
-
-The single authoritative timeline — entry/exit conditions, deliverables, and gates per milestone — is [`docs/roadmap.md`](docs/roadmap.md).
-
-## Verify
-
-```bash
-./scripts/run-all-tests.sh                     # full-stack suite (pure TS, no Python needed)
-cd ts
-npx tsx scripts/evaluation-contract-tests.ts   # evaluation Phase 0 contracts (offline)
-npx tsx scripts/evaluation-cadence-tests.ts    # deterministic cadence policy/planner
+```mermaid
+timeline
+  title From departure to next departure
+  M0 ✅ : Deterministic pipeline — dual engines reconciled
+  M1 ✅ : Agent form — chat as interface
+  M2 ✅ : Realtime data — evidence tags go live
+  M3 ◀ current : MVP — web face + 50–200 seed users, evidence open
+  M4 : Memory &amp; next departure — wish pool · cohort evidence
+  M5 : Transaction loop — WriteGate-gated booking
+  M6 : B2B embedding — zero-kernel-diff sponsor plugin
 ```
 
-The suite covers golden engines, dialogue replay, cross-process async work-orders, plugin smoke, realtime bridges, process guards, i18n, memory domain, the Z3 concurrency gate, the fact gate, and a packaged-consumer turn-deadline E2E, among others; the authoritative section list is whatever `scripts/run-all-tests.sh` enumerates. The live session benchmark (`npx tsx scripts/sf-live-benchmark.ts --golden=static`) is opt-in, requires your connected Chrome session, and never runs in CI.
+Milestone gates: [`docs/roadmap.md`](docs/roadmap.md) · engineering state: [`docs/architecture.md`](docs/architecture.md) · per-version decisions: [`docs/release-notes.md`](docs/release-notes.md) + [CHANGELOG.md](CHANGELOG.md).
 
 ## Contributing
 
-Branch off latest `main` (`feat/ · fix/ · docs/ · chore/`), full suite green locally, open a Pull Request — `main` never takes direct pushes. CI (Node 22/24, typecheck + all suites) plus maintainer review, then squash-merge. **Red tests never merge.** Full guide: [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports / feature suggestions: use the issue templates (search existing issues first).
-
-## For AI Agents
-
-If you are an agent working in this repository, [`AGENTS.md`](AGENTS.md) is the binding contract — read it first. In brief:
+Branch off latest `main` (`feat/ · fix/ · docs/ · chore/`), keep typecheck + full regression green, open a PR. **Red tests never merge.** Guide: [CONTRIBUTING.md](CONTRIBUTING.md).
 
-- **Sweep async work orders on entry**: `ts/gotry-state/async/*.json` without a matching `.deliverable.md` → `cd ts && npx tsx scripts/async-collect.ts <id>`.
-- **Layer discipline**: arithmetic only in the evaluate layer of `model.ts` / `unified.py`; solving only in `unified.ts` / `unified.py`; `engine.*` / `journey.*` are deprecated compatibility layers — new code must not call them. Any side change requires the full-stack regression.
-- **Never write shared state**: `ts/dsh-runtime/gotry-state/` is the founder's real product data; validate write paths with an isolated `stateRoot` only.
-- **State-sync discipline**: any commit changing the system's shape/state/debt must sync the six state faces of `architecture.md` §11 in the same commit; stage only named files — never `git add -A`.
-
-Program-level context: [`docs/gotry-master-outline.md`](docs/gotry-master-outline.md). Technical authority: [`docs/architecture.md`](docs/architecture.md).
+AI agents: [`AGENTS.md`](AGENTS.md) is the binding contract — sweep async work orders on entry · arithmetic only in the evaluate layer, solving only in `unified.*` · never write shared state (`ts/dsh-runtime/gotry-state/`) · sync the six state faces of `architecture.md` §11 in the same commit · stage named files only, no `git add -A`.
 
 ## Documentation
 
+Documents ship as bilingual pairs (`x.md` English + `x.zh-CN.md` 中文); divergence within a pair is treated as a bug (machine-generated `CHANGELOG.md` and the tool-managed `superpowers/` namespace exempt).
+
 | Document | Purpose |
 |---|---|
-| [`docs/README.md`](docs/README.md) | Docs conventions & full index (taxonomy, naming, lifecycle) |
-| [`docs/architecture.md`](docs/architecture.md) | System, ADRs, evolution, debt ledger (Chinese, authoritative) |
-| [`docs/gotry-master-outline.md`](docs/gotry-master-outline.md) | Program master outline & reuse matrix |
-| [`docs/gotry-product-design.md`](docs/gotry-product-design.md) | Product design: main loop, transparency, whole-cost model |
+| [`docs/architecture.md`](docs/architecture.md) | System, ADRs, evolution, debt (authoritative) |
 | [`docs/roadmap.md`](docs/roadmap.md) | M0–M6 timeline & current position |
 | [`docs/user-guide.md`](docs/user-guide.md) | End-user guide |
+| [`docs/tools.md`](docs/tools.md) | Tool reference: contracts, routing, onboarding |
 | [`docs/data-sources.md`](docs/data-sources.md) | Data sources & evidence-chain policy |
-| [`docs/ops/extension-privacy.md`](docs/ops/extension-privacy.md) | Session Bridge extension privacy |
-| [`docs/evaluation/benchmark-environment-bridge.md`](docs/evaluation/benchmark-environment-bridge.md) | External benchmark bridge — engineering ledger |
-| [`docs/evaluation/evaluation-foundation.md`](docs/evaluation/evaluation-foundation.md) | Evaluation Phase 0 foundation |
-| [`docs/design/booking-saga-fsm.md`](docs/design/booking-saga-fsm.md) | Booking saga FSM (the M5 seam vocabulary) |
-| [`docs/research/kimi-postmortem.md`](docs/research/kimi-postmortem.md) | A real AI-travel-planning failure postmortem (cautionary tale) |
-| [`docs/evaluation/persona-bench/`](docs/evaluation/persona-bench/) | Agent-persona benchmark — same real-trip prompt answered by mainstream AIs: transcripts, scoring rubric, and the persona it shapes |
 | [`docs/release-notes.md`](docs/release-notes.md) | Release decisions per version (the "why") |
-| [`CHANGELOG.md`](CHANGELOG.md) | Machine-derived changelog (Keep a Changelog + Conventional Commits) |
-| [`docs/tokens.md`](docs/tokens.md) | npm 2FA / release mechanics |
+| [`CHANGELOG.md`](CHANGELOG.md) | Machine-derived changelog |
+| [`docs/README.md`](docs/README.md) | Docs conventions & full index |
 
 ## License
 
 **MIT** — same as upstream dsh. See [LICENSE](LICENSE).
 
-## Star History
+**Built with**: DeepSeek Harness 0.1.5-rc.1 (root-pinned) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 · OpenFlights · TypeScript
+
+**Version baseline: `v0.0.1-rc.24` (npm `latest`).** Verification gates: `scripts/run-all-tests.sh`; release flow: `scripts/publish-npm.sh`.
 
 <a href="https://www.star-history.com/?repos=danceiny%2Fgotry&type=date&legend=top-left">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=danceiny/gotry&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=danceiny/gotry&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=danceiny/gotry&type=date&theme=light&legend=top-left" />
    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=danceiny/gotry&type=date&legend=top-left" />
  </picture>
 </a>
-
----
-
-**Built with**: DeepSeek Harness 0.1.2-alpha.3 (root-pinned) · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 · OpenFlights · TypeScript
-
-**Version baseline: `v0.0.1-rc.18` (npm `latest`).** The authoritative verification gates for the current checkout are enumerated by `scripts/run-all-tests.sh`; release flow: `scripts/publish-npm.sh`.