@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

package/README.md

@@ -1,265 +1,220 @@
-# GoTry
-
-> **身体和灵魂，更多旅行，更少旅游。**
-> *Body and soul — more travel, less tourism.*
-
-**GoTry 是「从出发到下一次出发」的 AI 旅行 Agent**：你用一句话说想去哪、为什么想出发；它先问清楚你的工作时间和已订资源，再用**数学求解器**给你一份经过验证的行程方案。
-
-**GoTry is an AI travel agent for departure-to-next-departure.** Tell it where you want to go and why. It asks what's missing, then hands you a **formally verified itinerary** — not vibes.
-
-| | |
-|---|---|
-| **Version** | `v0.0.1-rc.7`(npm: `@danceiny/gotry@rc`;rc.8 已构建待发布;[release notes](docs/release-notes.md)) |
-| **Status** | M4 记忆域推进中(2026-08-28):记忆写读闭环 + 效用 sidecar + 「下一次出发」0::1 召回;13 工具;全栈回归全绿(套件清单见 `scripts/run-all-tests.sh` 分节) |
-| **Repo** | [github.com/Danceiny/gotry](https://github.com/Danceiny/gotry) (private) |
-| **Runtime** | DeepSeek Harness 0.1.1-rc.2 (vendored `ts/dsh-runtime/`, [upstream](https://github.com/deepseek-ai/DeepSeek-Harness)) · Z3 (npm `z3-solver`) · LoopX (pipx, `~/.local/pipx/venvs/loopx/bin/loopx`) · Agent-Reach v1.5.0 (`.venv/bin/agent-reach`) |
-| **License** | **MIT** (2026-08-23 落定,见 [LICENSE](LICENSE)) |
-
-
----
-
-## ✨ 它做什么 — What it does
-
-GoTry 把「想去哪」变成「能不能、怎么去」：
-
-| 阶段 | AI/Engine | 输什么 |
-|---|---|---|
-| **动机访谈** | LLM | 必问项：工作窗口 / 已订资源 / 出发城市 |
-| **事实抽取** | LLM | 工作窗口生效 + 休假语义识别 |
-| **可行性判定** | **Z3** | 哪些候选目的地**可行**、哪些**不可行**、为什么、**如何最小化改动让它变可行** |
-| **门到门全成本** | 求解器 | 真实飞行时长（含时差）+ 醒来起夜惩罚 + 接驳代价 + 到达精力 % |
-| **证据链** | 渲染层 | 每个数字标 `[骨架:openflights]`、`[实时API:hbcli]`、`[静态包:估算]` |
-
-**不像普通 AI 聊天**——LLM 只做理解和解释，**判定与算术是数学求解器**算的。
-
-> **Unlike a regular AI chat**, the LLM only translates and explains. **Decisions and arithmetic are computed by a Z3 solver**, not guessed.
-
----
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-## 🚀 快速开始 — Quick start
-
-### 一行启动(npm,推荐)
+# GoTry
 
-```bash
-npx @danceiny/gotry@rc web          # 首跑会提示在当前目录建 .env(LLM_API_KEY=<DeepSeek key>)
+> **Body and soul — more travel, less tourism.**
+> *身体和灵魂，更多旅行，更少旅游。*
+
+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)
+[![npm](https://img.shields.io/npm/v/@danceiny/gotry)](https://www.npmjs.com/package/@danceiny/gotry)
+[![License: MIT](https://img.shields.io/badge/License-MIT-informational)](LICENSE)
+[![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 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
+
+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** — 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
+
+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;
 ```
 
-装完即得 :3080 对话界面。已装 dsh 的用户同理——上面的命令会自动以 cordis patch
-挂载 gotry 插件,无需任何额外配置(零成本启动)。
+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:
 
-### 源码安装(开发者)
+<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>
 
-```bash
-git clone https://github.com/Danceiny/gotry
-cd gotry
-```
+> 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).
 
-#### A. 装 vendored dsh runtime(一次性,约 1 分钟)
+Capability groups:
 
-```bash
-cd ts/dsh-runtime
-pnpm install    # 拉 @deepseek-ai/dsh 0.1.1-rc.2 + 依赖(实测 51 秒)
-cd ../..
-```
+- **Evidence-first retrieval and routing** — realtime sources and your own browser session remain read-only, with source tags, channel-health advice, and fail-closed fact boundaries. See [`docs/tools.md`](docs/tools.md), [`docs/data-sources.md`](docs/data-sources.md), and the [session data RFC](docs/rfc/user-session-data-rfc.md).
+- **Artifacts and local review** — itinerary Markdown/HTML artifacts can be listed and read as source text; native preview and opt-in Lavish feedback remain separate host capabilities. See [artifact and Lavish contracts](docs/design/lavish-local.md#9-registration-into-the-product-tool-surface).
+- **External events** — the W2A envelope is bounded and inert by default; listeners and sensor activation remain a separate seam. See [external-event design](docs/design/external-event-seam.md).
 
-> 为什么这一步:dsh runtime 是 vendored 的(`ts/dsh-runtime/`)——
-> 避免 npm 一键分发时把整个 dsh 也打包进去。
-> 之后可以重复使用,无需重装。
+## Demo
 
-#### B. 环境前置 — Prerequisites
+https://github.com/user-attachments/assets/6628c254-eba1-4017-a883-c70d22616939
 
-- **Node 22+**(`nvm install 22` 或更高)
-- 一个 LLM API key(默认走 DeepSeek,也支持 OpenAI 兼容协议)
+*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)):*
 
-#### C. 配 — Configure
-
-```bash
-cp .env.example .env
-# 填 LLM_API_KEY(deepseek: sk-...; 也兼容 OpenAI/Anthropic 兼容协议)
 ```
+> Two or three days staring at Erhai Lake, leaving from Shanghai, budget 3000, annual leave — no work.
 
-#### D. 跑 — Run(仓内入口,开发者)
-
-gotry 把 **DeepSeek Harness (dsh) 运行时**作为唯一推荐面——任何自然语言输入在那里面都能跟 GoTry 正常对话(自动调用引擎、追问缺失字段、给出证据链)。
-
-启动方式有三种,对应三种使用场景:
-
-| 入口 | 命令 | 什么时候用 | 给你什么 |
-|---|---|---|---|
-| **① dsh Web 对话框**(推荐) | `./gotry web` | 第一天上手;持续多轮规划;想看推理过程可视化 | `http://127.0.0.1:3080` 浏览器界面;带 GoTry 人格的对话框 |
-| **② headless 一次性问答** | `./gotry "一句完整任务..."` | 写脚本、CI 自动化、定向 LLM 调试 | stdout 输出 markdown 回答 |
-| **③ help** | `./gotry help` | 不知道用法 | 三行帮助 |
-
-```bash
-# 推荐:打开对话框,正常打「我想去大理三天」,看引擎回答
-./gotry web
-#   → http://127.0.0.1:3080,在输入框里像跟 DeepSeek 对话一样打字
+GoTry: constraints captured —
+  • window: 2 days   • departure: Shanghai   • budget: ¥3000 all-in
+  • motivation: recovery [escape_rest: 0.7]   • no bookings yet
 
-# 调试/自动化:直接一问一答,无浏览器
-./gotry "我想从深圳休整两天,预算 3000"
-#   → stdout 拿到引擎判定 + 证据链 + 候选 gate
+Engine verdict:
+  **Erhai, Dali: not feasible now** — a 2-day window can't hold "at least 5 days of Erhai recovery".
+    Relax: extend to 5 days, ~¥4950. ★ saved to your "next departure" wish pool.
+  **Qiandao Lake: feasible** (G7315 06:35, ¥996, arrival energy 84%, effective rest 4.4h)
+  **Taihu Lake: feasible** (G101 09:00, ¥716, effective rest 4.6h)
+  Suggestion: Qiandao Lake (imagery match 80%).
 
-# 不知道用法
-./gotry help
+[skeleton:openflights] ✓ SZX↔PVG verified [realtime:hbcli] Shanghai airports live
+[static-pack:estimate] G7315/G7316 priced on Jul–Aug off-season rates
 ```
 
-> ⚠️ **dsh 运行时端口冲突**:如果你之前已经手动 `node ...dsh web` 跑过,而后再 `./gotry web`,会因 `:3080` 占用启动失败。要么先 `kill <PID>`,要么直接用已经在跑的那个。
->
-> **dsh 启动耗时**:第一次 cold start 6–15 秒(cordis 组合 + plugin 加载 + LLM 准备);之后热启动 < 2 秒。
->
-> **headless 报错兜底**:意外退出(exit ≠ 0 / signal)会 fsync 一条记录到 `gotry-state/incidents.jsonl`,作为事故证据而不是沉默(D-NEW 进程护栏)。
-
-<br>
-
-*One-liner mental model: `npx @danceiny/gotry@rc web` + `.env` 一行 key — done。dsh 对话框是唯一产品面(旧 shell 前端已删除)。*
-
-> 一行安装的关键点: `./gotry web`(终端粘贴即用),或 `./gotry "任务"`(一句问答)。**任何自然语言都能用**(这是 dsh runtime 投资的最大价值)。详见 [known limitations](#-known-limitations)。
-
-
----
+> 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.
 
-## 🎬 一段对话 — Demo
+## Benchmark
 
-输入 → 引擎判定 → 输出（真实截图，monospace 保留原味）：
+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/)).
 
-```
-> 我想去洱海边发呆两三天，上海出发，预算 3000，年假别让我办公。
-
-GoTry: 收到。先把约束记下来——
-  • 窗口: 2 天(2026 年窗口)
-  • 出发: 上海
-  • 预算: ¥3000 全含
-  • 动机: 休整 / [escape_rest: 0.7]
-  • 不要求工作窗口(年假)
-  • 还没订任何东西
-
-引擎判定:
-
-  **大理·洱海: 现在不行** —— 冲突约束: duration。
-    你的 2 天窗口装不下「至少 5 天的洱海休整」(你之前的画像也有此约)。
-    放宽方案: 把行程延长到 5 天,约 ¥4950。
-  ★已放入「下一次出发」清单: 需 5 天起,3-5 / 9-11 月最佳。
-
-  **千岛湖: 可行** (G7315 06:35 出发,bus 接驳,
-   ¥996,起床 06:35,到达精力 84%,门到门 5h20m,
-   有效休整 4.4h)
-  **太湖: 可行** (G101 09:00 出发,
-   ¥716,起床 07:12,到达精力 84%,
-   有效休整 4.6h)
-
-  建议: 千岛湖(意象匹配 80%)。
-  备选: 太湖(¥716,匹配 60%)。
-
-**待你决定**:
-  1. 千岛湖还是太湖?(前者更贴意象,后者更省)
-  2. 出发班次选 G7315(06:35)还是更晚的?
-
-[骨架:openflights] ✓ SZX↔PVG 已校验 [实时API:hbcli] 上海机场在跑
-[静态包:估算] G7315/G7316 价格按 7-8 月淡季估算
-```
+| Dimension | Generic chat assistant (Kimi, 13 real turns) | OTA agent (Fliggy open platform, single turn) | GoTry contract |
+|---|---|---|---|
+| Calendar grounding | ✗ 2025 calendar; three user corrections, three apology-refits | ✗ derived weekdays land on the 2025 calendar — contradicting its own answer on the same page | (2)(8)(9) + time-anchor card |
+| Constraint interview | ✗ zero questions; both load-bearing constraints surfaced by the user at turn 6 | △ asks sales qualifiers (budget / star level / sea view); zero must-asks | (1)(10) |
+| Feasibility & time accounting | ✗ density illusion, caught by the user | ✗ HK errands + same-day flight with no time budget; an "8h" flight contradicting its own arrival time | (4) + door-to-door true cost |
+| Fact provenance | △ destination research holds up | ✗ sells a defunct airline (retired 2020); every price unsourced | (3)(7)(13)(20) |
+| 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 |
 
-> **Brief English summary**: input → engine verdicts (feasibility + whole-cost) → recommendation + wish-pool entry for infeasible candidates. Every numeric carries an evidence tag.
+> **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.
 
----
+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)).
 
-## 🏛️ 架构 — Architecture
+## Quick Start
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│ L1  对话即界面  chat-as-UI; gates 是消息内选择题                 │
-│ L2  编排  dsh 运行时 + GoTry 插件(ReAct);13 个工具            │
-│ L3  领域  统一行程模型 + Z3 可行性引擎(枚举/Z3 双形态)        │
-│ L4  数据  静态数据包 + hotelbyte-cli 实时桥 + OpenFlights 骨架 │
-│ L5  治理  LoopX(objective / gates / evidence / quota)         │
-└──────────────────────────────────────────────────────────────┘
+```bash
+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
 ```
 
-| 层 | 模块 | 角色 |
-|---|---|---|
-| L2 | `ts/src/index.ts` (dsh 插件) | 注册 13 个工具,挂 `{{current_date}}`/`{{time_anchor_card}}`/`{{motivation_brief}}` 变量,工具 execute 异常隔离 + 平铺观察 envelope + uncaughtException 护栏 |
-| L3 | `ts/src/unified.ts` · `py/gotry_feasibility/unified.py` | 唯一求解入口(候选枚举 + 航班链 Z3) |
-| L4 | `ts/capabilities/hbcli.ts` | hotelbyte-cli 进程封装 + 降级到 `data/hotels_2026.json` |
-| L4 | `ts/scripts/skeleton-check.ts` | OpenFlights 168 对枢纽,三值语义(阳性/枢纽对否定≠证伪/枢纽外=无结论) |
+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.2.0-rc.2` closure as the npm package. Full-stack verify: `./scripts/run-all-tests.sh`.
 
-> 📖 完整 ADR / 演进阶段 / 债务清单见 [`docs/architecture.md`](docs/architecture.md)。
+## Privacy and Trust
 
+The personal desktop account-session channel reads realtime data from **your own logged-in Chrome**, under four hard rules:
 
----
+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.
 
-## ⚠️ Known limitations · 已知限制
+One-time prerequisite: the [Stai Travel Bridge extension](https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd) (one-click, auto-updates) — until installed, tools return `needs-extension` with the store link and spend nothing. The separate HotelByte employee-portal flow can send search data to an authorized backend bridge and can handle one-time supplier-login credentials in memory; see the [extension privacy policy](docs/ops/extension-privacy.md).
 
-- ✅ **License MIT** (D-1 落地 2026-08-23)
-- **zh-CN 体验** — 当前面向中国出境首发(你的账号语言习惯)。英文界面/wider 国际化未做,等 M4 校准输入落定。
-- **机票实时数据** — 静态包(`data/flights_2026.json`)作为降级。实时票价接入留到 v0.1.x。
-- **Z3 WASM race** — 连续跑多个测试套件时偶发 `memory access out of bounds`(已规避回滚)。M3 早期处理。
-- **薄壳已废弃** — `./gotry shell` 不再推荐;dsh web 是唯一面。本版 README 仍保留旧命令行做迁移证据。
+Trust is structural, not promised:
 
+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 active supplier booking/payment write path exists** — the mechanism exists but is not activated; such 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.
 
----
+## Project Status and Roadmap
+Current boundary: deterministic planning and evidence-bound read capabilities are available; booking and real-user acceptance remain outside the shipped claim. See the [architecture](docs/architecture.md) and [roadmap](docs/roadmap.md).
 
-## 📚 文档 — Docs
+**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. External W2A events are contract-only and inert; no real sensor bridge or consumer is active yet.
 
-| 文档 | 适合谁 |
-|---|---|
-| [本 README](README.md) | **所有人**:是什么 · 怎么用 · 限制 |
-| [`docs/architecture.md`](docs/architecture.md) | 工程师:分层 · ADR · 演进 · 债务 |
-| [`docs/roadmap.md`](docs/roadmap.md) | 项目管理:M0–M6 与当前位置 |
-| [`docs/user-guide.md`](docs/user-guide.md) | 终端用户:详细使用文档 |
-| [`docs/gotry-product-design.md`](docs/gotry-product-design.md) | 产品:主循环 · 透明机制 · 全成本模型 |
-| [`docs/gotry-master-outline.md`](docs/gotry-master-outline.md) | 决策者:工作分解 · 复用矩阵 |
-| [`docs/kimi-postmortem.md`](docs/kimi-postmortem.md) | 所有人:真实 AI 旅行规划失败复盘(反面教材) |
-| [`docs/release-notes.md`](docs/release-notes.md) | 历史:每个 tag 的发布闸勾稽 |
+**Working today**
 
+- Interview, deterministic feasibility verdicts, and itineraries with door-to-door true cost.
+- Read-only realtime retrieval with typed, invocation-bound facts and explicit provenance.
+- Tenant-scoped memory for motivation, wishes, companions, timeline, and durable work.
+- Non-overwriting itinerary HTML generation from registered session facts, plus a scoped self-check and approved repair path.
 
----
+**Not yet**
 
-## 🧪 跑测试 — Verify
+- No supplier booking or payment path is active; any future write remains behind WriteGate and trusted user confirmation.
+- Live-availability evidence is partial, and the real-user cohort has not reached its exit bar.
+- English coverage remains limited to the solver output layer.
 
-```bash
-./scripts/run-all-tests.sh
+```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
 ```
 
-全栈一次性绿(纯 TS,无 Python 依赖):engine/journey/unified 金标准 · 对话重放 ·
-异步工单跨进程 · 插件 smoke · hbcli · 进程护栏(含工具异常隔离) · 天气 · 航班 ·
-Anything · probePoi · agent-reach(web/deep/wrapper)· 双路径稳定性 ·
-时间感评测(锚点卡/槽位过期校验/评分器/mock 回放;真模型巡检 `time-eval-tests.ts --real`)·
-记忆域(动机合并守门/效用 sidecar/只读指标投影)。
+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
 
-## 🤝 参与开发 — Contributing
+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).
 
-仓库内 branch 模型:`main` 是唯一分支(没有 dev/staging)。所有迭代在 main 直接推(每次提交需全栈绿)。
+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/`) · update only the affected documentation authority defined by `architecture.md` §11 · stage named files only, no `git add -A`.
 
-```bash
-./scripts/run-all-tests.sh   # 提交前必跑
-
-# 单独跑某个套件
-cd ts && npx tsx scripts/replay.ts          # 对话重放(mock,不需要 key)
-cd ts && npx tsx scripts/hbcli-tests.ts     # 能力封装
-cd ts && npx tsx scripts/incident-tests.ts  # 进程护栏
-```
-
-ADR 与技术债见 [`docs/architecture.md` §8 / §10](docs/architecture.md)。Agent 协作契约见 [`AGENTS.md`](AGENTS.md)。
-
----
-
-## 📜 License
-
-**MIT**（2026-08-23 落定）。与上游 dsh（MIT）/ loopx 一致——宽松、可商用、可闭源分叉。
+## Documentation
 
-文本见 [LICENSE](LICENSE)。
+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).
 
----
-
-## 🌐 中英版 — Locales
-
-- **English section summaries** are inline above (italic blockquotes).
-- 本 README 主语言是中文,面向中国出境首发种子用户群。
-- 完整英文版 README 计划在 v0.1.0 同步([issue 路线](#-known-limitations))。
-
----
-
-**Built with**: DeepSeek Harness 0.1.1-rc.2 · Cordis · Z3 (WASM) · loopx (pipx) · hotelbyte-cli · Agent-Reach v1.5.0 (`.venv/`) · OpenFlights · TypeScript · Bun
-
-**Last verified against `main`(rc.8 已构建待发布,2026-08-28)** — 全栈回归全绿(发布流程见 `scripts/publish-npm.sh`,内部决策见 [docs/decisions-needed.md](docs/decisions-needed.md)、[docs/tokens.md](docs/tokens.md))。
+| Document | Purpose |
+|---|---|
+| [`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/release-notes.md`](docs/release-notes.md) | Release decisions per version (the "why") |
+| [`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).
+
+**Built with**: DeepSeek Harness 0.2.0-rc.2 (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&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>