[LivXue]

Summary

Stands up a bilingual MkDocs site under docs-site/, published to GitHub Pages
by a workflow that builds on every pull request and deploys only from main.
Fourteen topics ship in English and Chinese: the quick start, self-hosting,
Docker, the WebUI, the sandbox manual, the runtime architecture, the command
reference, the repository layout, the developer workflow, the proactivity design
and reference pair, the self-evolution map and the tracing API.

This pull request is additive. Both READMEs keep their prose and gain one link
to the site in the header row; trimming them is deliberately a second pull
request, so the site can be confirmed live before anything depends on it.

Key decisions:

• docs-site/, not docs/. docs/README.md defines docs/ as design
  notes and dated records, and docs/plans/ is an archive explicitly not held
  to today's layout. A user manual has the opposite lifecycle.
• Full bilingual parity, via the mkdocs-static-i18n suffix structure
  (page.md beside page.zh.md). Parity decays immediately without a guard, so
  a test fails when a page has no twin.
• Anchors are pinned on the Chinese side. A CJK heading slugifies to
  nothing, so Markdown numbers it _1, _2, and inserting one heading
  renumbers every anchor below it, silently breaking links readers already hold.
  Each Chinese heading therefore states the anchor its English twin gets for
  free: 133 heading anchors, identical across the two languages, none
  positional.
• A left rail, not a top bar. The header carries the brand, the search box
  and the navigation tree down the left; the table of contents on the right is
  one continuous polyline clipped to the headings currently on screen.
• No template overrides. Material customises through theme.custom_dir with
  Jinja partials, those partials are .html, and scripts/check_large_files.py
  holds .html in BLOCKED_ASSET_EXTENSIONS. The skin is therefore one
  stylesheet remapping Material's own custom properties, plus one script for the
  table-of-contents rail. The brand mark is a data: URI for the same reason.
• An owner-signed docs-site/ exemption zone in AGENTS.md section 1.3. The
  i18n config carries the Chinese navigation labels, and mkdocs.yml is not
  *.md, so the blanket suffix exemption does not reach it. A contract test
  holds the AGENTS.md list and EXEMPT_PREFIXES equal, so both moved together.
• The site never links out to a file it does not host. Documents that stay
  in the repository are named as plain paths rather than linked, and a guard
  fails a page that links to an external webpage or a repository-relative path.

Two defects found and closed here rather than after publication. The Chinese
site rendered an English sidebar: navigation labels live in mkdocs.yml, not in
any page, so comparing the two languages' Markdown finds nothing and only the
rendered output shows it. And a control could be present, sized, animated and
answer querySelector while being unclickable, because a popup Material sized
for a top bar landed outside the viewport once the header became a rail.

Type

• Fix
• Feature
• Docs
• CI / tooling
• Refactor
• Other

Verification

All commands run at the pushed head, rebased onto origin/main.

make check-large-files                                         exit 0
make check-source-language                                     exit 0
make docs-build                                                exit 0, 0 errors
  docs-site/site/index.html and docs-site/site/zh/index.html   both present
  mkdocs_static_i18n: Translated 17 navigation elements to zh
uv run pytest tests/test_docs_site.py tests/test_source_language_check.py \
  tests/test_readme_scope_canon.py tests/test_docker_runtime.py \
  tests/test_living_docs.py                                    44 passed
uv run pytest tests/integration/test_docs_site_controls_e2e.py 13 passed
pre-commit run --files <changed files>                         all hooks pass
git diff --check                                               clean

Anchor parity was measured on the built HTML rather than assumed: 14 page pairs,
133 heading anchors compared at h2 through h6, every one identical between the
two languages and none positional.

The controls are hit-tested rather than queried. document.elementFromPoint at
the exact point a reader clicks must return the control itself, which is the
only check that catches an off-viewport popup; the language switcher, the search
panel, the repository link and the table-of-contents rail each pass it.

The brand lockup is measured, not eyeballed. A failing test was written first
and reported the wordmark sitting 4.00px below the mark's centre line; it is
0.00px after the fix, and a 4x screenshot puts the residual optical offset at
0.25px.

Every guard this branch adds was confirmed to fail first. The brand-class guard
was mutated from both sides in turn: renaming .em-eyebrow in the stylesheet
turned it red, renaming class="em-standfirst" in index.md turned it red, and
it is green again with both restored. The anchor guard was shown to catch both
failure modes, a missing anchor and a wrong one.

• Relevant tests pass locally
• Relevant lint / type checks pass locally
• User-facing docs or screenshots are updated when needed

Risk

No behaviour change to any shipped code path. Nothing imports docs-site/, the
new Makefile targets are additive, and the only change outside docs-site/ and
its tests is one link added to each README's header row.

Rollback is deleting the branch: the site does not exist until Pages is enabled
with Source: GitHub Actions, and every other change is inert without it.

Disclosed residue, checked and deliberately not changed:

• The README header now links to https://evermind-ai.github.io/Raven/, which
  404s until Pages is enabled. It is the same URL the Documentation section
  already carries.
• The deploy job is skipped on pull requests by design, so a green check here
  does not prove deployment works. The first real evidence is the deploy job's
  own conclusion on the main run after merge.
• GitHub Pages is not enabled on this repository. Measured: GET /repos/.../pages
  returns 404. Under Deploy from a branch the uploaded artifact is silently
  ignored while the workflow still reports success, so the source must be set to
  GitHub Actions.
• tests/integration/ is excluded by norecursedirs, so the browser suite is a
  local guard and never runs in CI.
• The self-hosting page's Makefile target, docker path and port claims are
  unguarded. They were equally unguarded in the README they came from, and the
  owner ruled against adding a guard for them.
• The self-evolution SOP and the benchmark contract stay in the repository and
  are named as plain paths from the pages that reference them. The SOP is a
  translation of an upstream project's internal document and carries redaction
  placeholders, which is a publication decision rather than a formatting one.
• docs/plans/ still shows the pre-restyle mkdocs.yml. CONTEXT.md defines that
  directory as an archive of the tree as it stood, with an explicit rule against
  updating an old plan to match a later change.
• The Chinese pages drop the brand's italic serif accent word. Cormorant Garamond
  carries no CJK glyphs, so it would fall back to another face without any sign.
• The code font is Material's default Roboto Mono. The brand names four
  typefaces and no monospace, so none was invented for it.

Related Issues

N/A

[gloryfromca]

Blocking: remove or replace the stylesheet's untracked local-only source reference.

I found one blocking repository-rule violation, marked inline.

I reviewed the full github/main...7f9aa66a3b97 diff, including the commit added while this review was in progress; the relevant site/config callers and generated link behavior; commit history and action tag availability; AGENTS.md, CLAUDE.md, and CONTEXT routing; backward compatibility; test changes for weakening; and the documented two-stage Pages deployment architecture.

Verification at the latest head: the strict bilingual MkDocs build succeeded and generated both locales with seven translated navigation elements; 40 relevant pytest cases passed; the source-language and large-file gates passed against github/main...HEAD; and git diff --check passed. GNU make is unavailable in this environment, so I ran the exact uv commands behind the Makefile targets. The PR's docs build GitHub check is also green. I found no other blockers.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

The only delta from the previously reviewed head replaces the inaccessible source citation with tracked, accurate references, so the prior blocker is resolved; I replied on and resolved that thread. I reviewed the new commit in the context of the full diff, repository rules and context documents, surrounding site/build configuration, history, backward compatibility, unchanged test strength, and the two-stage deployment architecture. No new issue emerged.

Verification at 33d8d6198534: strict bilingual MkDocs build passed with both locale trees and seven translated navigation elements; 40 focused pytest cases passed; source-language and large-file checks passed against github/main...HEAD; the replacement spec path is tracked; and git diff --check passed.

[gloryfromca]

Blocking: make the docs-site unit test importable in the standard unit environment.

I found one new blocker in the expanded revision, marked inline.

I reviewed the full github/main...5887e91b0a64 diff and the four post-review commits, including repository rules and context documents, the generated site and build/deploy callers, relevant history, backward compatibility, test strength and discovery, and the rail/browser architecture. The previously resolved stylesheet thread remains resolved.

Verification: the strict bilingual MkDocs build passed and translated 17 navigation elements; the source-language and large-file gates plus git diff --check passed; and 44 focused tests passed after the docs group had been installed. That last environment masks the blocker: an isolated reproduction matching the unit job (--all-extras --dev --no-group docs) aborts collection of tests/test_docs_site.py with ModuleNotFoundError: markdown. The browser suite collected 13 tests locally but all 13 skipped because this runner has no Chrome binary; the PR records a separate 13-pass run.

This is a round-five blocker on all three required grounds: this revision adds the import, the ordinary unit shard reaches it, and the shard cannot run past collection without a code or dependency correction. I found no other new blocker.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

The dependency fix at 4a2c0f75e7c8 is correct: markdown is now a direct dev dependency, so the docs-site guard imports and runs in the ordinary unit environment without relying on a prior docs build. The exact isolated reproduction passes 5 tests; the 44-test focused set, strict bilingual MkDocs build, source-language gate, large-file gate, and git diff --check all pass. I replied to and resolved the settled unit-environment finding.

This round covered the revision delta and lock metadata, the standard CI unit caller, dependency/backward-compatibility impact, and whether test coverage was weakened; it was not. The prior full-diff review covered the repository rules and context files, docs/deploy callers and history, compatibility, and architectural constraints. I found no new plain error or blocker.

[ZuyiZhou]

Approving. Reviewed independently rather than taking the description at its word.

Verified locally at the pushed head:

• make docs-build (--strict) builds clean; both site/index.html and site/zh/index.html are produced.
• Anchor parity measured on the built HTML, not the Markdown: 14 page pairs, 133 h2-h6 anchors, every one identical across the two languages, and none of the positional _1 / _2 form the pinning exists to prevent.
• The Chinese sidebar renders Chinese and the document carries lang="zh", so the navigation-label defect is actually closed.
• 31 unit tests pass (test_docs_site.py, test_source_language_check.py), and make check-large-files / make check-source-language both exit 0.
• Every raven <command> in the command reference exists in the real CLI, and the subcommands were checked against --help too: gateway status|reload|stop, agents new, plugin auth, mcp bridge, ops connection, and tracing compact (an action argument, correctly documented as one).
• Section 7 is clean: no new file over 100 KiB, no .html or .svg committed, the brand mark is a 35-character data: URI.
• The AGENTS.md zone and EXEMPT_PREFIXES moved together and the contract test holds them equal. Action versions match the other 18 workflows.

Three non-blocking notes, none worth another round:

1. The docs-site/ exemption prefix is wider than the AGENTS.md entry describes. The stated need is the navigation labels in mkdocs.yml; the prefix also quietly exempts stylesheets/ and javascripts/. docs-site/mkdocs.yml would match the text exactly.
2. Two guards in tests/test_docs_site.py disagree in their remediation advice: the relative-link test tells you to make the target an absolute github.com URL, and the external-link test then rejects exactly that. Both pass today because no page has a link of either kind, so it is only the message that misleads.
3. CHROME = "/usr/bin/google-chrome" means the browser suite silently skips on macOS rather than running. Combined with norecursedirs excluding tests/integration/, the rail's coupling to Material's internal class names has no guard that runs anywhere by default.

One thing to know at merge time, already disclosed: the workflow-level cancel-in-progress: true outranks the deploy job's own cancel-in-progress: false, so two merges landing close together can cancel a deploy in flight. The following push redeploys, so it self-corrects.

Pages still needs Source: GitHub Actions before the README link resolves.