docs: plain-language home and README copy

README.md

@@ -17,12 +17,10 @@
   <a href="./LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-3ccf91?style=flat-square"></a>
 </p>
 
-**A3S Code** is an async Rust runtime for building governed coding agents. The
-library default is a **thin coding harness** (`local-code`): agent loop,
-workspace tools, policy, events, and bundled lexical retrieval. Advanced
-evaluation, server, and headless search stay opt-in. Side effects, evidence,
-and recovery sit behind explicit contracts — from Rust, Node.js, Python, Go, or
-`a3s code`.
+**A3S Code** is an async Rust runtime for coding agents. By default it ships a
+small harness (`local-code`): the agent loop, workspace tools, policy, events,
+and lexical search. Heavier pieces (evaluation, server, headless search) stay
+opt-in. Use it from Rust, Node.js, Python, Go, or `a3s code`.
 
 <p align="center">
   <a href="#start-in-60-seconds">Start</a> ·
@@ -36,24 +34,22 @@ and recovery sit behind explicit contracts — from Rust, Node.js, Python, Go, o
 
 ## What's new in 8.5
 
-Workspace search planes stay separate; session-store reopen recovers under flock:
-
-- **`grep` candidate pruning (CODE-G1).** Default `local-code` builds an
-  in-tree trigram filter under `.a3s-code/grep-trigram` so literal needles open
-  fewer files before the exact regex scan. Non-literals and index failures fail
-  open. Exact matches remain owned by Code — this path never opens durable zvec
-  FTS (`mode: "bm25"` stays the ranked plane).
-- **Session-store WAL flock (8.5.1).** Concurrent writers re-read the durable
-  max sequence under a cross-process flock; corrupt WALs can be quarantined so
-  hosts continue from durable snapshots.
+- **Faster `grep` (CODE-G1).** For literal searches, `local-code` builds a small
+  trigram cache under `.a3s-code/grep-trigram` so fewer files need a full regex
+  pass. If the cache misses or the pattern is not literal, it just falls back.
+  Exact match still comes from Code's own `grep` — this never opens the durable
+  zvec FTS index (`bm25` stays for ranked search).
+- **Safer session reopen (8.5.1).** Writers take a cross-process flock, re-read
+  the durable sequence, and can quarantine a bad WAL instead of minting
+  colliding IDs.
 
 Docs: [a3s-lab.github.io/Code](https://a3s-lab.github.io/Code/) (`v8.5.1`).
 
 ### Earlier lines
 
-- **8.4** — thin `local-code` defaults, unified `task` fan-out, Active-only
-  durable memory, `update_plan`, SDK capabilities v2.
-- **8.3** — negotiable session-store durability, typed tool-result trust,
+- **8.4** — smaller `local-code` defaults, one `task` path for fan-out,
+  Active-only durable memory, `update_plan`, SDK capabilities v2.
+- **8.3** — session-store durability options, typed tool-result trust,
   workspace source snapshots, fallible FFI init, host checkpoint hooks.
 - **8.0+** — run-owned spacetime, generation-exact capabilities, portable
   checkpoints, convergent workflows. Full history:

README.zh-CN.md

@@ -17,10 +17,10 @@
   <a href="./LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-3ccf91?style=flat-square"></a>
 </p>
 
-**A3S Code** 是用于构建受治理编码 Agent 的异步 Rust 运行时。库的默认配置是
-**变薄的编码 Harness**（`local-code`）：Agent 循环、工作区工具、策略、事件与
-捆绑词法检索。Advanced 评估、server 与无头搜索保持显式启用。副作用、证据与
-恢复都放在显式契约之后 — 可通过 Rust、Node.js、Python、Go，或 `a3s code` 使用。
+**A3S Code** 是做编码 Agent 的异步 Rust 运行时。默认是一套够用的小 harness
+（`local-code`）：Agent 循环、工作区工具、策略、事件，以及词法搜索。评估、
+server、无头搜索这些更重的能力需要显式打开。可用 Rust、Node.js、Python、Go，
+或直接跑 `a3s code`。
 
 <p align="center">
   <a href="#60-秒内起步">起步</a> ·
@@ -34,22 +34,20 @@
 
 ## 8.5 有什么新内容
 
-工作区搜索平面保持分离；会话存储重开在 flock 下恢复：
-
-- **`grep` 候选裁剪（CODE-G1）。** 默认 `local-code` 在
-  `.a3s-code/grep-trigram` 下构建进程内 trigram 过滤器，使字面量模式在精确
-  正则扫描前打开更少文件。非字面量与索引失败会失败开放。精确匹配仍由 Code
-  拥有 — 该路径不会打开持久 zvec FTS（排序检索仍用 `mode: "bm25"`）。
-- **会话存储 WAL flock（8.5.1）。** 并发写者在跨进程 flock 下重读持久最大
-  序号；可隔离损坏的 WAL，使宿主从持久快照继续。
+- **更快的 `grep`（CODE-G1）。** 字面量搜索时，`local-code` 会在
+  `.a3s-code/grep-trigram` 下建一个小的 trigram 缓存，先缩小文件范围再做精确
+  正则。缓存不可用或不是字面量时直接回退。精确匹配仍走 Code 自己的 `grep`，
+  不会碰持久 zvec FTS（排序检索继续用 `bm25`）。
+- **会话重开更稳（8.5.1）。** 写者先拿跨进程 flock，再读持久序号；坏掉的 WAL
+  可以隔离，避免并发写出冲突 ID。
 
 文档：[a3s-lab.github.io/Code](https://a3s-lab.github.io/Code/)（`v8.5.1`）。
 
 ### 更早的版本线
 
-- **8.4** — 变薄的 `local-code` 默认、统一 `task` 扇出、仅 Active 的 Durable
+- **8.4** — 更小的 `local-code` 默认、统一用 `task` 做扇出、仅 Active 的 Durable
   Memory、`update_plan`、SDK capabilities v2。
-- **8.3** — 可协商会话存储耐久、类型化工具结果信任、工作区源快照、可失败 FFI
+- **8.3** — 会话存储耐久选项、类型化工具结果信任、工作区源快照、可失败 FFI
   init、宿主 checkpoint 钩子。
 - **8.0+** — Run 拥有的时空组合、generation-exact 能力、可移植检查点、收敛工作流。
   完整历史见 [CHANGELOG.md](CHANGELOG.md)。Go 模块路径：
@@ -69,9 +67,8 @@ cd /path/to/your/project
 a3s code
 ```
 
-终端产品流推理、工具活动、审批、任务
-进展和差异。使用 `a3s code resume` 恢复持续工作或
-`a3s code resume <session-id>`。
+终端里会流式显示推理、工具、审批、任务进度和 diff。恢复会话用
+`a3s code resume` 或 `a3s code resume <session-id>`。
 
 ### 嵌入运行时
 

website/docs/v8.5.1/en/guide/index.mdx

@@ -7,23 +7,20 @@ import { Tab, Tabs } from '@rspress/core/theme';
 
 # A3S Code
 
-A3S Code is the Rust runtime behind the `a3s code` terminal application. You can
-also embed it in an IDE, runner, service, or desktop application. It handles the
-agent loop, context, tool calls, permission checks, child tasks, asynchronous
-Workspace retrieval, durable evidence, and session recovery.
+A3S Code is the Rust runtime behind `a3s code`. Embed it in an IDE, runner,
+service, or desktop app when you need the same loop outside the terminal: tools,
+permissions, child tasks, workspace search, and session save/resume.
 
-Version 8.5.1 keeps the thin `local-code` harness and separates workspace search
-planes: exact `grep` (with optional in-tree trigram candidate pruning) never
-opens durable zvec FTS, while `bm25` remains the ranked lexical path. Session
-stores recover corrupt WALs under a cross-process flock so concurrent writers
-cannot mint colliding sequences.
+In 8.5.1, literal `grep` can use a small trigram cache so it opens fewer files
+first; ranked search still goes through `bm25` / zvec. Session stores take a
+flock on reopen so a bad WAL does not mint colliding sequence numbers.
 
 ## Design rules
 
 | Rule                        | Meaning                                                                                                |
 | --------------------------- | ------------------------------------------------------------------------------------------------------ |
 | Thin default                | Core `default` = `local-code`. Advanced evaluation, server, and headless search are explicit features. |
-| Grep ≠ zvec                 | Exact `grep` is match authority; trigram pruning is fail-open only. Ranked retrieval uses `bm25`.      |
+| Grep ≠ zvec                 | Exact `grep` owns matches; trigram pruning only narrows candidates and fails open. Use `bm25` to rank. |
 | One delegation path         | Multi-item fan-out uses `task` / `session.tasks`. Do not restore `parallel_task`.                      |
 | Active-only memory          | Durable serving is `active_recall`. Candidate shadow mode is refused.                                  |
 | Evidence before Gate claims | Incomplete or retention-gapped evidence cannot satisfy Gate evaluation.                                |
@@ -65,14 +62,13 @@ same events, so every UI does not need its own agent loop.
 
 ## What is new in v8.5.1
 
-- Default `local-code` **trigram pruning for `grep`** (`CODE-G1`): literal
-  needles build a fail-open candidate cache under `.a3s-code/grep-trigram`
-  without opening durable zvec FTS. Exact regex matching stays in Code.
-- **Session-store WAL flock recovery**: concurrent writers re-read the durable
-  max sequence under a cross-process flock; hosts can quarantine a corrupt WAL
-  and continue from durable snapshots.
-- Carries forward the 8.4 thin harness (Active-only memory, unified `task`,
-  `update_plan`, SDK capabilities v2) and the 8.3 durability/trust kernel.
+- **Faster literal `grep` (`CODE-G1`).** Builds a fail-open trigram cache under
+  `.a3s-code/grep-trigram`. Exact regex still runs in Code; durable zvec FTS is
+  not opened on this path.
+- **Session-store WAL flock.** Concurrent writers re-read the durable max
+  sequence under flock; a corrupt WAL can be quarantined so the host keeps
+  going from snapshots.
+- Still includes the 8.4 smaller harness and the 8.3 durability/trust work.
 
 ## Earlier v8.4.0 additions
 

website/docs/v8.5.1/zh/guide/index.mdx

@@ -7,20 +7,19 @@ import { Tab, Tabs } from '@rspress/core/theme';
 
 # A3S Code
 
-A3S Code 是 `a3s code` 终端应用背后的 Rust Runtime，也可以单独接入 IDE、
-Runner 或服务端。它负责 Agent Loop、上下文、工具调用、权限检查、子任务、
-异步 Workspace 检索、持久证据，以及任务的保存和恢复。
+A3S Code 是 `a3s code` 背后的 Rust Runtime。也可以嵌进 IDE、Runner、服务端或
+桌面应用，复用同一套 Agent 循环：工具、权限、子任务、工作区搜索，以及会话的
+保存和恢复。
 
-8.5.1 保持变薄的 `local-code` Harness，并分离工作区搜索平面：精确 `grep`
-（可选进程内 trigram 候选裁剪）不会打开持久 zvec FTS，而 `bm25` 仍是排序词法
-路径。会话存储在跨进程 flock 下恢复损坏的 WAL，避免并发写者铸造冲突序号。
+8.5.1 里，字面量 `grep` 可以先用小的 trigram 缓存缩小文件范围；排序检索仍走
+`bm25` / zvec。会话存储重开时会拿 flock，坏 WAL 不会再写出冲突序号。
 
 ## 设计规则
 
 | 规则             | 含义                                                                       |
 | ---------------- | -------------------------------------------------------------------------- |
 | 默认变薄         | Core `default` = `local-code`。Advanced 评估、server、无头搜索需显式开启。 |
-| Grep ≠ zvec      | 精确 `grep` 是匹配权威；trigram 裁剪仅失败开放。排序检索使用 `bm25`。      |
+| Grep ≠ zvec      | 精确 `grep` 负责匹配；trigram 只缩小候选，失败就回退。排序检索用 `bm25`。  |
 | 单一委派路径     | 多条目扇出使用 `task` / `session.tasks`。不要恢复 `parallel_task`。        |
 | 仅 Active 记忆   | Durable 服务路径为 `active_recall`。拒绝 Candidate shadow。                |
 | Gate 先要证据    | 证据不完整或存在 retention 缺口时，Gate 不可宣称已完成评估。               |
@@ -61,13 +60,11 @@ Runner 或服务端。它负责 Agent Loop、上下文、工具调用、权限
 
 ## v8.5.1 新增内容
 
-- 默认 `local-code` 的 **`grep` trigram 裁剪**（`CODE-G1`）：字面量模式在
-  `.a3s-code/grep-trigram` 下构建失败开放的候选缓存，且不会打开持久 zvec FTS。
-  精确正则匹配仍由 Code 拥有。
-- **会话存储 WAL flock 恢复**：并发写者在跨进程 flock 下重读持久最大序号；宿主
-  可隔离损坏的 WAL，并从持久快照继续。
-- 延续 8.4 变薄 Harness（仅 Active 记忆、统一 `task`、`update_plan`、SDK
-  capabilities v2）以及 8.3 耐久/信任内核。
+- **更快的字面量 `grep`（`CODE-G1`）。** 在 `.a3s-code/grep-trigram` 下建失败可
+  回退的 trigram 缓存。精确正则仍在 Code 里跑，这条路径不打开持久 zvec FTS。
+- **会话存储 WAL flock。** 并发写者在 flock 下重读持久最大序号；坏 WAL 可以隔离，
+  宿主从快照继续。
+- 仍包含 8.4 的小 harness 默认，以及 8.3 的耐久 / 信任改动。
 
 ## 早期 v8.4.0 新增内容