Skip to content

docs: sync bilingual README overview - #486

Merged
LivXue merged 1 commit into
mainfrom
docs/readme_manual_updates
Sep 18, 2026
Merged

LivXue merged 1 commit into
mainfrom
docs/readme_manual_updates

Conversation

@LivXue

@LivXue LivXue commented Sep 18, 2026

Copy link
Copy Markdown
Member

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
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

  • Relevant tests pass locally
  • Relevant lint / type checks pass locally
  • 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

  • Security impact considered
  • Backward compatibility considered
  • 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>

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread README.md Resolved

@ZuyiZhou ZuyiZhou left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. 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-agent enabled flag and setup prompts for each one. The removed line "Enable the agents you need during onboarding" was the accurate half. The agents/README.md link survives at README.md:66, so nothing is orphaned, but the two statements now read differently on the same page.

  2. "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.

@LivXue
LivXue merged commit 0859633 into main Sep 18, 2026
21 checks passed
@LivXue
LivXue deleted the docs/readme_manual_updates branch September 18, 2026 03:01
0xKT pushed a commit that referenced this pull request Sep 19, 2026
… 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>
LivXue added a commit that referenced this pull request Oct 12, 2026
## 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>
LivXue pushed a commit that referenced this pull request Oct 12, 2026
… 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants