docs(*): send the README's reference sections to the documentation site

[LivXue]

Summary

Five sections leave both READMEs: self-hosting, the command reference, the
documentation index, the repo layout and the architecture. Each is already a
page on the documentation site, and a second copy in the README is the one
that drifts. Quick Start now ends by naming the site, so a reader who has just
installed Raven is told where the rest lives. English drops 258 lines and
Chinese 228, and the two stay in step: every section removed and the pointer
added exist in both.

The repo-layout table went with them, and it was never only prose. It is the
canonical set of commit scopes: a test held it equal to the packages on disk
while commitlint computes its enum from that same tree, so the table is what
keeps the list a reader is sent to and the list the tooling enforces from
splitting. Removing the section broke both of that test's assertions, and the
test reads the documentation page now, which carries the same table and the
same key directories block. It is renamed with the move, because it no longer
reads a README. AGENTS.md, raven/README.md and two comments in
commitlint.config.cjs name the page as well. The enum commitlint computes is
unchanged at 71 scopes, because it was always read from the tree rather than
from the table.

Two things are deliberately left alone. The dated records under docs/plans and
docs/specs still describe the old location: they record the tree as of their
date. And the English README keeps a Showcase section the Chinese one does not
have, which is how they already were.

Type

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

Verification

The coupling was demonstrated rather than assumed: removing the sections first
was run against the existing test, which failed with "README.md lost its 'Repo
layout' section" and "Key directories lost its agents/ line". After repointing,
dropping one table row from the documentation page fails it again with "package
on disk without a table row: ['acp']", so the guard still bites from its new
source.

• uv run pytest tests/test_scope_canon.py tests/test_docs_site.py tests/test_docker_runtime.py tests/test_living_docs.py tests/test_external_consumer_surface.py -> 22 passed
• uv run pytest over the eleven other tests that read a README -> 859 passed
• make lint-python, make lint-imports, make lint-deps, make lint-types
  -> exit 0, against an environment synced the way CI installs
• make check-commits, make check-source-language, make check-large-files,
  and pre-commit run --from-ref origin/main --to-ref HEAD -> exit 0
• make docs-build -> built
• node -e on commitlint.config.cjs -> 71 scopes, the same set as before
• the only internal anchors left in either README are #readme-top, whose
  target is still there, and no remaining link points into a removed section

Risk

User-visible: the README no longer answers self-hosting, the commands, the
layout or the architecture; it points at the site instead. Anyone who had
bookmarked a README anchor for one of those sections loses it. The scope list
AGENTS.md sends a contributor to is now a page rather than a README section.

Rollback: revert the commit. Nothing outside the repository depends on the
removed sections, and the site pages they moved to were already published.

Related Issues

N/A

[gloryfromca]

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

I reviewed the complete github/main...HEAD diff and the surrounding documentation-site pages, repository rules, CONTEXT-MAP.md/runtime terminology, affected scope-canon contract and commitlint callers, relevant history, deleted-anchor compatibility, and architecture boundaries. The canonical table and key-directory checks still follow the moved English page; I found no in-repository links to the deleted README anchors, no weakened test used to manufacture a green result, and no runtime or dependency change.

Verification: uv run --frozen --python 3.12 --all-extras pytest tests/test_scope_canon.py tests/test_docs_site.py tests/test_docker_runtime.py tests/test_living_docs.py -q (18 passed); the exact underlying commands for docs-build, check-source-language, and check-large-files passed; git diff --check github/main...HEAD passed. (make itself is unavailable in this environment, so I invoked those Makefile recipes directly.)

[ZuyiZhou]

Approving. The part that could actually break something is the scope canon moving out of the README, so that is what I checked.

The enum is unchanged and structurally could not have changed: base and head both compute 71 scopes and the sorted sets are identical. That is guaranteed rather than lucky, because ravenPackages() reads the tree relative to the config's own directory and never reads the table -- I confirmed it the blunt way, by running the base config from outside the repo and watching it fail on a missing raven/ rather than on a missing table.

The guard still bites from its new source. Dropping one row from the documentation page fails with package on disk without a table row: ['acp'], so the coupling survived the move intact.

One scoping change worth naming, since the test got looser and the description does not mention it: the old helper cut the Repo layout section out of the README before matching rows, and the new one matches against the whole page. That is harmless today -- repo-layout.md carries exactly one table, 40 rows -- and if a second table ever appeared, the row set would exceed the packages on disk and the test would fail loudly rather than quietly accept a wrong row. So it fails safe. It is just a wider net than the one it replaced.

The real residue is the other language. The canonical scope table now exists twice, and only the English page is guarded. The two currently agree -- I diffed the row keys and they are identical, 40 apiece -- but the parity guard in test_docs_site.py compares page existence and heading anchors, not table contents, so the Chinese table can drift from the tree with nothing red. Cheap to close later by running the same row extraction over both pages.

The rest checks out:

• The pointer updates are consistent across AGENTS.md, raven/README.md and the two commitlint comments.
• No dangling anchors. The only internal anchors left in either README are #readme-top, whose target is present in both files, and the one other hit in the tree points at data/longrun/README.md, a different file.
• Every surviving mention of the old README sections is confined to docs/plans/ and docs/specs/, which CONTEXT.md defines as records of the tree as of their date. Correctly left alone and correctly disclosed.
• 13 targeted tests pass. A broader sweep threw 88 import errors, all ModuleNotFoundError: raven_ppt, which reproduce identically on the base commit -- a plugin missing from my throwaway environment, nothing to do with this change.

The rename is the right call and matches section 5.1's aspect-suffix form: the file no longer reads a README, so keeping readme in its name would have been the misleading option.

[0xKT]

Not a blocker -- and this landed while I was reviewing, so it is now a note about main rather
than about a merge. The move conserves everything I could place except one pointer, and that
pointer was the only reader-facing way to reach a file that is still maintained.

What I verified, on the merged tree. Both READMEs lose the same ten headings, so the two stay
in step with each other -- that is the failure mode this repo has hit before, and it did not happen
here. docs-site/docs/self-hosting.md carries all five Self-Hosting subsections, and
docs-site/docs/repo-layout.md carries the scope table the re-pointed readers now name. Of the
distinctive facts in the deleted text, each is present somewhere under docs-site/docs:

docker/.env.local   RAVEN_IMAGE=raven:local   make docker-down   raven web --foreground
raven gateway       build_runtime             rpc-schema/openrpc.json   raven-data

The exception: docker/README.md. Measured on 7ab685f, the merged tip:

mentions in README.md          0      (the pointer this PR removed)
mentions in README.zh-CN.md    0
pages under docs-site/docs     0      (it never had one)
the file itself                still there, 4.9 KB

It holds eight sections a reader cannot get elsewhere -- "What comes up", "Signing in",
"Configuring a provider", "Settings", "Data", "Running a CLI command", "Notes and limits" -- and I
checked those subjects against the docs site by name: zero pages each. Before this change, both
READMEs sent the reader there for "container layout, the login flow, provider configuration and
operational notes". After it, the only things in the repository that link to that file are
docs/plans/2026-09-18-docs-site.md and docs/specs/2026-09-18-docs-site-design.md -- two planning
documents, which is not a route a reader takes.

So the file is not deleted, it is unreachable. That is the cheapest kind of loss to ship and the
hardest to notice later, because nothing is red and the content is still in the tree.

The smallest fix is one line: a link from docs-site/docs/self-hosting.md to docker/README.md,
in the section that already covers Compose. If the intent was that the docs site should absorb
those eight sections instead, that is a bigger change and worth its own PR -- either way the
decision wants making on purpose rather than by omission.

For the record, what else I checked and found sound: the four re-pointed readers all name a file
that exists and says what they claim -- AGENTS.md section 3.1, both comments in
commitlint.config.cjs, raven/README.md, and the renamed test; tests/test_scope_canon.py keeps
the same invariant it had as test_readme_scope_canon.py (the table equals the tree, now read from
the docs page) and passes, 2 passed; and
GATES OK head=fa828c35 tip=b4b0604f base=b4b0604f ruff/lint-imports/commit/large/lang rc=0.

One small thing while I am here: commitlint.config.cjs's second comment now reads "see that page's
preamble", and its antecedent is twenty lines above in a different comment block. It resolved when
the words were "README.md's repo-layout preamble"; naming the page again would cost four words.

[0xKT]

Not a blocker -- a second, smaller one, separate from the docker/README.md pointer above and
worth its own line because a follow-up could fix both together.

Both READMEs now reach 480 lines of moved reference material through exactly one route: an external
URL.

README.md:209        **[Read the documentation](https://evermind-ai.github.io/Raven/)**
README.zh-CN.md:148  the same, pointing at /zh/

$ grep -rn "docs-site/docs" README.md README.zh-CN.md
(nothing)

The content is in the tree at docs-site/docs/*.md, and no README line names that path. The plan
that designed this move asked for a second link for exactly this reason
(docs/plans/2026-09-18-docs-site.md, the sentence about keeping the content reachable when the
site is down); it did not ship.

Two things I want to state precisely rather than let the point run further than it should. First,
this is not a regression: the base READMEs had no such link either. What this change does is create
the condition the second link was designed for, by removing the inline copy. Second, the repository
is not actually silent about docs-site/ -- AGENTS.md:56, AGENTS.md:175, raven/README.md:3
and commitlint.config.cjs:18 all name it, two of them added by this very PR, and all four are
plain files a reader still has with the site down. So an in-tree route does exist for the scope
table: README -> AGENTS.md -> docs-site/docs/repo-layout.md. It is two hops and it covers only
that one page, not self-hosting, the WebUI or the command reference.

And the design spec itself does not require a fallback link -- its Risk section names the exposure
and answers it with revertability ("the content carries no risk of loss; it is in git history").
The fallback-link wording is the plan's, and docs/README.md marks docs/plans/ an archive. So
this is a gap against designed intent, not against an enforced rule, which is why it is a note.

The cheap version is one line per README, next to the link that is already there, naming
docs-site/docs/ as where the same pages live in the tree.