docs: add bilingual research notes

.agents/skills/land-pr/SKILL.md

@@ -5,16 +5,18 @@ description: >
   Makes the PR self-contained: rewrites the PR description from the PR's own
   contents, appends a changelog [Unreleased] entry when warranted, regenerates the
   English dev notes from the Chinese source when touched, and keeps the bilingual
-  README in sync. Then — only after explicit maintainer confirmation — merges the
-  PR. Does NOT tag or publish. Triggers on
+  README in sync. It also checks bilingual research notes and reminds the maintainer
+  when their English version needs refreshing. Then — only after explicit maintainer
+  confirmation — merges the PR. Does NOT tag or publish. Triggers on
   "合并 PR / land PR / 合并这个 PR / merge this PR".
 ---
 
 # Land a PR
 
 Merge a feature/bugfix PR into `main`, making the PR **self-contained** first:
-its code, changelog entry, dev notes (zh + en), and README (zh + en) all in sync
-within the PR. This skill never tags or publishes — that is the `release` skill's job.
+its code, changelog entry, dev notes (zh + en), research-note translation status,
+and README (zh + en) all accounted for within the PR. This skill never tags or
+publishes — that is the `release` skill's job.
 
 ## Prerequisites
 
@@ -31,38 +33,46 @@ file, e.g. `docs/changelogs/0.1.x.md` / `docs/dev_notes/{zh-CN,en}/0.1.x.md`.
 - `git status --porcelain` — empty (clean tree).
 - current branch is **not** `main` (`git branch --show-current`).
 
-### 2. Ensure a PR exists
+### 2. Check English research notes before PR creation
+If the branch modified any `docs/research/zh-CN/<name>.md`, check the
+corresponding `docs/research/en/<name>.md`. Explicitly remind the maintainer
+that the English version must also be translated or refreshed, and report
+whether it is in sync. Do this even when the English file was already updated.
+If it is missing or stale, surface that clearly before opening or landing the
+PR; do not silently treat the Chinese-only change as complete.
+
+### 3. Ensure a PR exists
 ```bash
 gh pr view --json number,url 2>/dev/null || gh pr create --fill
 ```
 Note the PR number for later steps.
 
-### 3. Append a changelog entry (when warranted)
+### 4. Append a changelog entry (when warranted)
 Inspect `git diff main...HEAD`. If the changes are worth recording for users, add
 an entry under `## [Unreleased]` in `<series>` (changelogs) in the right group
 (Added / Changed / Fixed / Removed). Purely internal/tooling changes may need
 **no** entry — decide, and surface the decision at the gate.
 
-### 4. Sync English dev notes (if the Chinese source changed)
+### 5. Sync English dev notes (if the Chinese source changed)
 If this PR modified `docs/dev_notes/zh-CN/<series>.md`, regenerate the whole
 `docs/dev_notes/en/<series>.md` by translating the Chinese source. The English
 file is generated — do not hand-edit beyond this regeneration.
 
-### 5. Keep the bilingual README in sync
+### 6. Keep the bilingual README in sync
 If this PR changed only one of `README.md` / `README.zh-CN.md`, mirror the change
 into the other (translate/align) so the pair stays consistent. Both READMEs are
 hand-written sources — propose the synced change and let the maintainer adjust the
 wording at the gate; do not blindly overwrite. If both were already changed, skip.
 
-### 6. Commit and push the sync changes
-Commit any changes from steps 3–5 to the feature branch and push:
+### 7. Commit and push the sync changes
+Commit any changes from steps 4–6 to the feature branch and push:
 ```bash
 git commit -am "docs: sync changelog/dev-notes/README for this PR"
 git push
 ```
-(Skip if steps 3–5 produced no changes.)
+(Skip if steps 4–6 produced no changes.)
 
-### 7. Rewrite the PR description from scratch
+### 8. Rewrite the PR description from scratch
 Build the description **only** from the PR's actual contents — commits, changed
 files, `gh pr diff`. **Do not read or extend the old description** (it may be
 stale). Update via the GitHub API (`gh pr edit` can fail on deprecated Projects
@@ -71,13 +81,14 @@ Classic):
 gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f body="..." --silent
 ```
 
-### 8. ⛔ Confirmation gate (mandatory)
+### 9. ⛔ Confirmation gate (mandatory)
 Present to the maintainer: the rewritten **PR description**, the **changelog
 entry** added (or "none, because …"), and any **dev notes / README sync** done
-(or a README drift warning). **Wait for explicit confirmation** (e.g. "确认 / go").
-Do not merge until approved.
+(or a README drift warning), plus the **English research-note sync status** when
+applicable. **Wait for explicit confirmation** (e.g. "确认 / go"). Do not merge
+until approved.
 
-### 9. Merge
+### 10. Merge
 ```bash
 gh pr merge --merge
 ```

AGENTS.md

@@ -37,6 +37,19 @@ The **only** exception is documentation explicitly designated as Chinese:
 Everything outside that list — including code under `src/`, this file, and all
 other docs — is English.
 
+### Bilingual research notes
+
+Research notes are bilingual:
+
+- `docs/research/zh-CN/` contains the hand-written Chinese sources of truth.
+- `docs/research/en/` contains English versions generated from the Chinese
+  sources; regenerate the whole corresponding file instead of hand-editing it.
+
+When a change to a Chinese research source is headed into a pull request, the
+agent MUST remind the user that the corresponding English version also needs to
+be translated or refreshed. Before opening or landing the PR, report whether
+the English version is in sync, even when it has already been updated.
+
 ## Commits & PRs
 
 All agents working in this repo MUST follow

docs/changelogs/0.7.x.md

@@ -0,0 +1,23 @@
+# Changelog — 0.7.x
+
+All notable changes in the **0.7.x** release series are documented here.
+
+## [Unreleased]
+
+### Added
+- English translations for all research notes, organized alongside their
+  hand-written Chinese sources of truth. Development notes now link to the
+  matching research language, and the pull-request workflow reports whether
+  English research translations are in sync when Chinese sources change.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.7.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

docs/dev_notes/en/0.5.x.md

@@ -10,15 +10,15 @@ When the tool starts up without printing its version, I sometimes cannot tell wh
 
 ### Built-in tools in common code agents
 
-For a survey of the built-in tools of mainstream code agents, see [Built-in Tools in Common Code Agents](../../research/agent_tools.md) (Chinese).
+For a survey of the built-in tools of mainstream code agents, see [Built-in Tools in Common Code Agents](../../research/en/agent_tools.md).
 
 ### Designing the built-in tools
 
 As the survey shows, beyond the core file/command tools that something like pi offers, the other agents have grown a large number of tools around subagent orchestration, task management, scheduling, user interaction, and so on. For our nano code agent, though, let's start expanding from the most basic category of all: file operations.
 
 #### The read tool
 
-We also surveyed the [read tool](../../research/read_tool.md) (Chinese): apart from codex, every code agent has a dedicated read tool. pi and opencode are model-agnostic, and you can see it in their read tools — their limits are line counts and file sizes, with no token limit. The other, model-specific code agents all have token limits; presumably because they only support their own vendor's models, where tokens are easier to count?
+We also surveyed the [read tool](../../research/en/read_tool.md): apart from codex, every code agent has a dedicated read tool. pi and opencode are model-agnostic, and you can see it in their read tools — their limits are line counts and file sizes, with no token limit. The other, model-specific code agents all have token limits; presumably because they only support their own vendor's models, where tokens are easier to count?
 
 Functionally, read and bash both seem able to satisfy the need to read a file. Even accounting for files that may exceed a size limit, bash can still read them fine. Take codex: in actual testing, whatever the size of the file, it always starts with a `sed -n '1,260p' foo.md`, and then, if it finds there is more, it may follow up with `wc -l foo.md && sed -n '1,260p' foo.md` — reading chunk by chunk, which looks a lot like the `limit` of a dedicated read tool. But I'm not sure whether, for any given model, reading files is better done with a dedicated tool or with `bash`.
 

docs/dev_notes/en/0.6.x.md

@@ -35,7 +35,7 @@ print("Hello, World!")
 Running it outputs: `Hello, World!`
 ````
 
-Based on the revised conclusion of the [write tool research](../../research/write_tool.md), the write tool should implement:
+Based on the revised conclusion of the [write tool research](../../research/en/write_tool.md), the write tool should implement:
 
 - Structured `{path, content}` input: the content lands on disk as data, never passing through shell expansion, heredoc delimiters, or quote escaping — eliminating the whole class of failures where a heredoc silently corrupts a file;
 - Create the file when it does not exist, overwrite it whole when it does, and state which of the two happened in the result;

docs/dev_notes/zh-CN/0.5.x.md

@@ -8,15 +8,15 @@
 工具启动时，如果不打印版本号，有时候自己分辨不出来是哪个版本。先开发一下这个功能。
 
 ### 常见 code agent 内置工具
-主流 Code Agent 的内置工具调研见 [《常见 Code Agent 内置工具》](../../research/agent_tools.md)。
+主流 Code Agent 的内置工具调研见 [《常见 Code Agent 内置工具》](../../research/zh-CN/agent_tools.md)。
 
 ### 内置工具设计
 
 可以看出，除了 pi 那样的核心文件/命令工具外，其他 agent 还围绕子代理编排、任务管理、定时调度、用户交互等场景扩展了大量工具。不过对我们的 nano code agent 来说，先从文件操作这一类最基础的工具开始扩展。
 
 #### read 工具
 
-我们对 [read工具](../../research/read_tool.md) 也做了调研，除了 codex 外，其他 code agent 都有专门的 read 工具。pi 和 opencode 是模型无关的，可以看出他们的 read 工具，limit 除了行数，还有文件大小，并没有 token 限制。而其他专用的 code agent，都有 token 限制，大概是只支持自家模型，token 更方便计算？
+我们对 [read工具](../../research/zh-CN/read_tool.md) 也做了调研，除了 codex 外，其他 code agent 都有专门的 read 工具。pi 和 opencode 是模型无关的，可以看出他们的 read 工具，limit 除了行数，还有文件大小，并没有 token 限制。而其他专用的 code agent，都有 token 限制，大概是只支持自家模型，token 更方便计算？
 
 功能上讲，似乎 read 和 bash 都能实现读文件需求。即使考虑文件大小可能超出限制，bash 也能正常读取。例如 codex，实际测试中发现 codex 读文件的操作，不管读什么大小文件，他都会先来个 `sed -n '1,260p' foo.md`，之后如果发现还有内容，可能会 `wc -l foo.md && sed -n '1,260p' foo.md`,相当于一块一块读，和专用 read 工具的 limit 似乎差不多。但不太确定各个模型，在读文件的时候，是用专用工具好，还是用 `bash` 更好。
 

docs/dev_notes/zh-CN/0.6.x.md

@@ -33,7 +33,7 @@ print("Hello, World!")
 Running it outputs: `Hello, World!`
 ````
 
-基于 [write 工具调研](../../research/write_tool.md)修正后的结论，write 工具要实现的功能：
+基于 [write 工具调研](../../research/zh-CN/write_tool.md)修正后的结论，write 工具要实现的功能：
 
 - 结构化 `{path, content}` 入参：内容作为数据直接落盘，不经过 shell 展开、heredoc delimiter 和引号转义，消除 heredoc 静默写坏文件这一整类失败；
 - 文件不存在则创建，存在则整文件覆盖，并在结果中说明是哪一种；

docs/research/README.md

@@ -5,14 +5,25 @@ building the equivalent here. Unlike changelogs and dev notes, these are not
 tied to a release series — each file stands on its own, and the decisions they
 feed into are recorded in [`../dev_notes/`](../dev_notes/).
 
-These notes are **written and maintained in Chinese**; each file says so at the
-top.
+Research notes are bilingual, split by language:
 
-- [`agent_tools.md`](agent_tools.md) — the built-in tools of Pi, Claude Code,
-  Codex, OpenCode and Grok Build.
-- [`edit_tool.md`](edit_tool.md) — how five agent projects express a localized
-  edit, and what contract a first Edit tool here should commit to.
-- [`read_tool.md`](read_tool.md) — how five agent projects read files, and what
-  a dedicated read tool buys over plain bash.
-- [`write_tool.md`](write_tool.md) — how five agent projects write whole files,
-  and why a structured write beats a heredoc.
+- [`zh-CN/`](zh-CN/) — **hand-written Chinese source** (source of truth)
+- [`en/`](en/) — **English, generated from the Chinese source** (do not edit by
+  hand)
+
+When a pull request adds or updates a Chinese source, its corresponding English
+version also needs to be translated or refreshed. The agent preparing or
+landing the pull request must remind the user and report whether the two
+versions are in sync.
+
+- Built-in tools of Pi, Claude Code, Codex, OpenCode, and Grok Build:
+  [English](en/agent_tools.md) | [Chinese](zh-CN/agent_tools.md)
+- How five agent projects express a localized edit, and what contract a first
+  Edit tool here should commit to:
+  [English](en/edit_tool.md) | [Chinese](zh-CN/edit_tool.md)
+- How five agent projects read files, and what a dedicated read tool buys over
+  plain Bash:
+  [English](en/read_tool.md) | [Chinese](zh-CN/read_tool.md)
+- How five agent projects write whole files, and why a structured write beats a
+  heredoc:
+  [English](en/write_tool.md) | [Chinese](zh-CN/write_tool.md)