Repository navigation
docs: sync bilingual README overview - #486
Conversation
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
gloryfromca
left a comment
There was a problem hiding this comment.
Blocking: the overview contradicts the documented Evolver architecture.
I found one blocking documentation error, marked inline.
Coverage: I reviewed the full bilingual diff and surrounding README sections; checked AGENTS.md and CONTEXT-MAP.md; traced shipped-agent discovery and onboarding behavior; checked the Evolver boundary and import contract; examined recent README history and the PR record; considered link/heading compatibility; and confirmed that no tests were weakened.
Verification: the two targeted pytest selections each passed (1 passed); check_large_files.py, check_source_language.py, and git diff --check passed; the worktree is clean; and all GitHub CI checks are green. The first local --no-sync attempt found no prepared pytest environment, so I synchronized the required Python 3.12/all-extras environment and reran successfully.
ZuyiZhou
left a comment
There was a problem hiding this comment.
Approving: docs only, two files, all 18 checks green, and the bilingual halves stay in step.
Checked the zh text against the new en text line by line -- the Host Agent framing, the EverOS sentence, the built-in agent line, the Raven Evolver paragraph and the new blockquote all carry the same claims in both files, and the same two paragraphs are dropped on both sides. The benchmark image, its link, the surrounding sections and the repo-layout table are untouched, so tests/test_readme_scope_canon.py keeps its anchor and nothing keys on the changed H1.
Two notes, neither blocking, both for a follow-up if you agree:
-
The new blockquote "All four agents are built in and ready for orchestration out of the box" sits in tension with the install section this PR leaves alone, which still says "Setup asks about each product and registers the ones you take up" (
README.md:62-66,README.zh-CN.md:62). That paragraph matches the code: agents carry a per-agentenabledflag and setup prompts for each one. The removed line "Enable the agents you need during onboarding" was the accurate half. Theagents/README.mdlink survives atREADME.md:66, so nothing is orphaned, but the two statements now read differently on the same page. -
"state-of-the-art (SOTA) performance in their respective domains" is a strong public claim across four domains, and the README shows one benchmark, for orchestration. Worth either scoping the claim to what the chart supports or pointing at per-agent numbers.
Style nit: the en README had no curly apostrophes and no em dashes before this change (8 straight 's, 0 of either); it now gains EverMind's with a curly apostrophe and one em dash. The zh -- is idiomatic there and fine. No gate rejects it, since *.md self-governs, but the en file is otherwise ASCII-punctuation throughout.
… states (#503) ## Summary The overview says the four built-in agents are "Powered by the **Raven Evolver** engine". The architecture section of the same file says `evolver/` is a separate tool that consumes Raven as a library and that the runtime does not import Evolver, and `pyproject.toml` enforces that with an import-linter contract literally named "the runtime does not import the evolver". A reader gets two incompatible answers to whether Evolver is a runtime engine or an external development tool, and the contract settles which one is true. This was gloryfromca's blocking review finding on #486. The thread was resolved when that PR merged, but the text was never changed, so the contradiction is live on `main` today in both language mirrors. Both mirrors now put Evolver where it actually runs: refining the shared harness from outside, against benchmarks, developing the agents rather than running inside them. That is the reading the review offered for the case where the intended claim was that Evolver was used to develop the agents. The overview also takes the canonical spelling of harness self-evolution from the architecture section, as the review asked. Scope note: only the Evolver relationship changes. The SOTA sentence in the same paragraph is untouched - it was not part of the finding, and what it should say is a product call rather than a consistency fix. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Prose only: two lines, one per language mirror, no code and no new files. - `git diff --stat` -> `README.md | 2 +-`, `README.zh-CN.md | 2 +-` - The two gates that apply here are satisfied by construction rather than by a command: `check-source-language` exempts `*.md` by suffix (AGENTS.md 1.3), and `check-large-files` sees no added or resized file. - Read back against the two places the claim has to agree with: the Evolver row of the agent table, and the harness self-evolution bullet in the architecture section. Both mirrors now match both. - [ ] Relevant tests pass locally - [ ] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk Documentation wording only. No runtime behaviour, no interface, no build. Rollback is a plain revert. The claim removed was the one the import-linter contract forbids being true, so nothing downstream depends on it. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A. Lands the finding from #486 that was resolved without a change. Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary Synchronize the Chinese README with the updated English overview. The change aligns the Raven introduction and built-in agent section, including the Host Agent positioning, Raven Evolver description, built-in agent wording, and orchestration readiness statement. The existing benchmark charts, links, captions, and the remaining bilingual sections are preserved. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed Commands run: - `uv run --no-sync pytest tests/test_readme_scope_canon.py tests/test_cli_onboard_commands.py -k readme_quickstart -q` (1 passed) - `uv run --no-sync pytest tests/test_docker_runtime.py -k container_exposes_no_engine_selector -q` (1 passed) - `UV_NO_SYNC=1 make check-large-files check-source-language PYTHON_VERSION=.venv/bin/python COMMIT_RANGE=HEAD` (passed) - `git diff --check` (passed) ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes This is a documentation-only change. Reverting the commit restores the previous README wording. ## Related Issues N/A Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
… states (#503) ## Summary The overview says the four built-in agents are "Powered by the **Raven Evolver** engine". The architecture section of the same file says `evolver/` is a separate tool that consumes Raven as a library and that the runtime does not import Evolver, and `pyproject.toml` enforces that with an import-linter contract literally named "the runtime does not import the evolver". A reader gets two incompatible answers to whether Evolver is a runtime engine or an external development tool, and the contract settles which one is true. This was gloryfromca's blocking review finding on #486. The thread was resolved when that PR merged, but the text was never changed, so the contradiction is live on `main` today in both language mirrors. Both mirrors now put Evolver where it actually runs: refining the shared harness from outside, against benchmarks, developing the agents rather than running inside them. That is the reading the review offered for the case where the intended claim was that Evolver was used to develop the agents. The overview also takes the canonical spelling of harness self-evolution from the architecture section, as the review asked. Scope note: only the Evolver relationship changes. The SOTA sentence in the same paragraph is untouched - it was not part of the finding, and what it should say is a product call rather than a consistency fix. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Prose only: two lines, one per language mirror, no code and no new files. - `git diff --stat` -> `README.md | 2 +-`, `README.zh-CN.md | 2 +-` - The two gates that apply here are satisfied by construction rather than by a command: `check-source-language` exempts `*.md` by suffix (AGENTS.md 1.3), and `check-large-files` sees no added or resized file. - Read back against the two places the claim has to agree with: the Evolver row of the agent table, and the harness self-evolution bullet in the architecture section. Both mirrors now match both. - [ ] Relevant tests pass locally - [ ] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk Documentation wording only. No runtime behaviour, no interface, no build. Rollback is a plain revert. The claim removed was the one the import-linter contract forbids being true, so nothing downstream depends on it. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A. Lands the finding from #486 that was resolved without a change. Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
Summary
Synchronize the Chinese README with the updated English overview. The change aligns the Raven introduction and built-in agent section, including the Host Agent positioning, Raven Evolver description, built-in agent wording, and orchestration readiness statement.
The existing benchmark charts, links, captions, and the remaining bilingual sections are preserved.
Type
Verification
Commands run:
uv run --no-sync pytest tests/test_readme_scope_canon.py tests/test_cli_onboard_commands.py -k readme_quickstart -q(1 passed)uv run --no-sync pytest tests/test_docker_runtime.py -k container_exposes_no_engine_selector -q(1 passed)UV_NO_SYNC=1 make check-large-files check-source-language PYTHON_VERSION=.venv/bin/python COMMIT_RANGE=HEAD(passed)git diff --check(passed)Risk
This is a documentation-only change. Reverting the commit restores the previous README wording.
Related Issues
N/A