207 lines
7.7 KiB
JavaScript
Raw Permalink Normal View History

feat(docs): add a bilingual documentation site and its deploy pipeline (#507) ## 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 - [x] 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. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] 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 --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 15:06:24 +08:00
/*
* The table-of-contents rail: one continuous polyline through every entry, and
* the stretch of it the reader is currently inside.
*
* The line is a single path walked in document order, not one line per nesting
* level: each entry contributes a vertical run at its own depth, and the 12px
* between two entries is where the line changes column, which draws as a
* diagonal when their depths differ and as plain vertical when they do not.
* Colouring a contiguous stretch of that one path is what makes a parent and
* the children under it read as a single bracket.
*
* The path only moves when the column is laid out again, so it is rebuilt on
* resize and load; scrolling moves the clip rectangle alone.
*/
(() => {
const SVG_NS = "http://www.w3.org/2000/svg";
const CLIP_ID = "raven-toc-progress-clip";
/* Each level sits 10px right of the one above; the first is inset by 1 so a
1px stroke lands whole inside the 12px viewBox. */
const columnFor = (depth) => 1 + depth * 10;
/* Half of the run an entry boundary turns through. Entries butt against each
other, so reserving this at both ends of every run leaves exactly one 12px
gap per boundary for the line to cross columns in. */
const JOIN = 6;
const listSelector = ".md-sidebar--secondary .md-nav--secondary > .md-nav__list";
const entriesOf = (list) => {
const found = [];
const walk = (ul, depth) => {
for (const item of ul.querySelectorAll(":scope > .md-nav__item")) {
const link = item.querySelector(":scope > .md-nav__link");
if (link) found.push({ link, depth });
const nested = item.querySelector(":scope > .md-nav > .md-nav__list");
if (nested) walk(nested, depth + 1);
}
};
walk(list, 0);
return found;
};
const railFor = (list) => {
let rail = list.querySelector(":scope > .raven-toc-progress");
if (rail) return rail;
rail = document.createElementNS(SVG_NS, "svg");
rail.classList.add("raven-toc-progress");
rail.setAttribute("aria-hidden", "true");
const clip = document.createElementNS(SVG_NS, "clipPath");
clip.id = CLIP_ID;
clip.append(document.createElementNS(SVG_NS, "rect"));
const base = document.createElementNS(SVG_NS, "path");
base.classList.add("raven-toc-progress__base");
const lead = document.createElementNS(SVG_NS, "path");
lead.classList.add("raven-toc-progress__active");
lead.setAttribute("clip-path", `url(#${CLIP_ID})`);
rail.append(clip, base, lead);
list.prepend(rail);
return rail;
};
/* Where an entry's own vertical run starts and ends. The outermost ends are
flush: nothing joins onto the first entry from above or the last from
below, so neither reserves a gap there. */
const runOf = (spans, index) => {
const span = spans[index];
return {
start: index === 0 ? span.top : span.top + JOIN,
end: index === spans.length - 1 ? span.bottom : span.bottom - JOIN,
};
};
const state = { list: null, entries: [], spans: [], height: 0 };
const layout = () => {
const list = document.querySelector(listSelector);
if (!list) return false;
const entries = entriesOf(list);
if (!entries.length) return false;
const origin = list.getBoundingClientRect().top;
const spans = entries.map(({ link, depth }) => {
const box = link.getBoundingClientRect();
return { top: box.top - origin, bottom: box.bottom - origin, depth };
});
const commands = [];
spans.forEach((span, index) => {
const run = runOf(spans, index);
const column = columnFor(span.depth);
if (index === 0) commands.push(`M${column} ${run.start}`);
commands.push(`L${column} ${run.end}`);
const next = spans[index + 1];
if (next) {
commands.push(`L${columnFor(next.depth)} ${runOf(spans, index + 1).start}`);
}
});
const height = spans[spans.length - 1].bottom;
const rail = railFor(list);
rail.setAttribute("viewBox", `0 0 12 ${height}`);
rail.setAttribute("width", "12");
rail.setAttribute("height", String(height));
const d = commands.join(" ");
rail.querySelector(".raven-toc-progress__base").setAttribute("d", d);
rail.querySelector(".raven-toc-progress__active").setAttribute("d", d);
Object.assign(state, { list, entries, spans, height });
return true;
};
/* An entry is current while its heading is anywhere in the viewport, which
is why several can be current at once and why the lit stretch grows and
fix(docs): light the contents rail between headings and use raven.evermind.ai's favicon (#734) ## Summary Two fixes to the documentation site. **The contents rail went dark between headings.** The right-hand table of contents lit an entry only while its heading was inside the viewport. Partway through a section longer than the screen every heading sits above or below it, so nothing was lit, the gold stretch collapsed to zero height, and the column stopped following the reader. On the built site before this change, 18 of 28 English pages had such stretches: 114 of 1264 scroll positions sampled every 120px. `sync()` in `docs-site/docs/javascripts/toc-progress.js` now falls back to the nearest heading above when none is in view and lights that entry alone. The lit stretch and the column follow read the same list, so both pick it up with no further change. Above the first heading nothing is lit, since no section has begun there. The design spec states the rule, and the rail's section comment in `evermind.css`, which still credited Material with marking the section, now names what does. **The tab icon differed from raven.evermind.ai.** The site drew its own simplified EverMind mark, a single heavy lemniscate without the rings. raven.evermind.ai links one 192px PNG of the full mark for its light, dark and apple-touch icons alike. `theme.favicon` in `docs-site/mkdocs.yml` now inlines that PNG byte for byte as a data URI, since AGENTS.md section 7 keeps image files out of `docs-site/`. For whoever refreshes it: that site's CDN answers any `Accept` naming `image/avif` with a lossy AVIF re-encode (5178 bytes), and only a plain `Accept: */*` returns the original PNG (5184 bytes). The comment above the value says so. Checked and deliberately left alone: - The mark at the top of the navigation rail (`--em-mark` in `evermind.css`) is a separate drawing and still the simplified one. This change is the tab icon only. - raven.evermind.ai also sets an apple-touch icon. Material emits no such link, and adding one needs a template override, which is an `.html` file that section 7 blocks. - The favicon's identity is verified by the measurements below rather than pinned by a test: a pinned hash would only detect change, and comparing against the live site would put the network in the suite. - `tests/integration/` is outside every CI job (`norecursedirs`), so the e2e results below are local runs. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `uv run --frozen --extra browser --group docs pytest tests/integration/test_docs_site_controls_e2e.py tests/integration/test_docs_site_search_e2e.py -n 0 -q`: 63 passed. - `uv run --frozen --extra browser --group docs pytest tests/test_docs_site.py -q`: 16 passed. - The new `test_table_of_contents_keeps_the_section_above_lit_between_headings` computes, from the Sandbox page's own layout, every stretch between two headings (or after the last) with none on screen, and checks the middle of each. Against the unfixed script it fails (`at 1354px: assert [] == [2]`), and with the fix it passes. - A sweep of every built page in headless Chrome at 1440x900, one sample every 120px, checking the rule at each position: 0 violations over 1264 English, 1145 Chinese and 21 Overview positions after the change, and wherever an entry is lit, the first one sits inside the contents column. The unfixed script gives 114 violations over the same English positions. - Favicon: each of the 63 built HTML files carries exactly one icon link, and its decoded bytes match the PNG raven.evermind.ai links (sha256 `4a5051e1781fac64...`). Drawn in Chrome at 16, 32 and 192px, the docs icon and that PNG differ in 0 pixels. - `mkdocs build --strict`, `scripts/check_source_language.py origin/main...HEAD`, `scripts/check_large_files.py origin/main...HEAD`, `scripts/check_commit_messages.py origin/main..HEAD`, commitlint, `pre-commit run --from-ref origin/main --to-ref HEAD`, ruff and `git diff --check`: all pass. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [ ] User-facing docs or screenshots are updated when needed The last box is left blank because nothing needed it: no documentation page describes the rail or the icon, and the design spec is updated in this change. ## Risk - Between headings, the entry of the section above now stays lit and the contents column keeps it in view. While any heading is on screen the behaviour is unchanged. - The tab icon changes to the full mark. Each page's head now carries about 6.9 KB of base64 for it, against about 0.6 KB for the previous SVG. - The new code relies on no browser API newer than `Array.prototype.includes` (2016). - The two halves touch disjoint files, so either can be reverted on its own. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes The inlined PNG was read chunk by chunk: standard chunks plus three ImageMagick timestamps, and nothing after IEND. Inlining it adds no third-party request, which hotlinking the CDN copy would have. ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-09-23 22:09:48 +08:00
shrinks rather than jumping between entries. Partway through a section
longer than the screen no heading is in view, yet the reader is still
inside the section the nearest heading above opened, so that entry is
current on its own until the next heading comes on screen. */
feat(docs): add a bilingual documentation site and its deploy pipeline (#507) ## 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 - [x] 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. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] 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 --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 15:06:24 +08:00
const sync = () => {
if (!state.list && !layout()) return;
fix(docs): light the contents rail between headings and use raven.evermind.ai's favicon (#734) ## Summary Two fixes to the documentation site. **The contents rail went dark between headings.** The right-hand table of contents lit an entry only while its heading was inside the viewport. Partway through a section longer than the screen every heading sits above or below it, so nothing was lit, the gold stretch collapsed to zero height, and the column stopped following the reader. On the built site before this change, 18 of 28 English pages had such stretches: 114 of 1264 scroll positions sampled every 120px. `sync()` in `docs-site/docs/javascripts/toc-progress.js` now falls back to the nearest heading above when none is in view and lights that entry alone. The lit stretch and the column follow read the same list, so both pick it up with no further change. Above the first heading nothing is lit, since no section has begun there. The design spec states the rule, and the rail's section comment in `evermind.css`, which still credited Material with marking the section, now names what does. **The tab icon differed from raven.evermind.ai.** The site drew its own simplified EverMind mark, a single heavy lemniscate without the rings. raven.evermind.ai links one 192px PNG of the full mark for its light, dark and apple-touch icons alike. `theme.favicon` in `docs-site/mkdocs.yml` now inlines that PNG byte for byte as a data URI, since AGENTS.md section 7 keeps image files out of `docs-site/`. For whoever refreshes it: that site's CDN answers any `Accept` naming `image/avif` with a lossy AVIF re-encode (5178 bytes), and only a plain `Accept: */*` returns the original PNG (5184 bytes). The comment above the value says so. Checked and deliberately left alone: - The mark at the top of the navigation rail (`--em-mark` in `evermind.css`) is a separate drawing and still the simplified one. This change is the tab icon only. - raven.evermind.ai also sets an apple-touch icon. Material emits no such link, and adding one needs a template override, which is an `.html` file that section 7 blocks. - The favicon's identity is verified by the measurements below rather than pinned by a test: a pinned hash would only detect change, and comparing against the live site would put the network in the suite. - `tests/integration/` is outside every CI job (`norecursedirs`), so the e2e results below are local runs. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `uv run --frozen --extra browser --group docs pytest tests/integration/test_docs_site_controls_e2e.py tests/integration/test_docs_site_search_e2e.py -n 0 -q`: 63 passed. - `uv run --frozen --extra browser --group docs pytest tests/test_docs_site.py -q`: 16 passed. - The new `test_table_of_contents_keeps_the_section_above_lit_between_headings` computes, from the Sandbox page's own layout, every stretch between two headings (or after the last) with none on screen, and checks the middle of each. Against the unfixed script it fails (`at 1354px: assert [] == [2]`), and with the fix it passes. - A sweep of every built page in headless Chrome at 1440x900, one sample every 120px, checking the rule at each position: 0 violations over 1264 English, 1145 Chinese and 21 Overview positions after the change, and wherever an entry is lit, the first one sits inside the contents column. The unfixed script gives 114 violations over the same English positions. - Favicon: each of the 63 built HTML files carries exactly one icon link, and its decoded bytes match the PNG raven.evermind.ai links (sha256 `4a5051e1781fac64...`). Drawn in Chrome at 16, 32 and 192px, the docs icon and that PNG differ in 0 pixels. - `mkdocs build --strict`, `scripts/check_source_language.py origin/main...HEAD`, `scripts/check_large_files.py origin/main...HEAD`, `scripts/check_commit_messages.py origin/main..HEAD`, commitlint, `pre-commit run --from-ref origin/main --to-ref HEAD`, ruff and `git diff --check`: all pass. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [ ] User-facing docs or screenshots are updated when needed The last box is left blank because nothing needed it: no documentation page describes the rail or the icon, and the design spec is updated in this change. ## Risk - Between headings, the entry of the section above now stays lit and the contents column keeps it in view. While any heading is on screen the behaviour is unchanged. - The tab icon changes to the full mark. Each page's head now carries about 6.9 KB of base64 for it, against about 0.6 KB for the previous SVG. - The new code relies on no browser API newer than `Array.prototype.includes` (2016). - The two halves touch disjoint files, so either can be reverted on its own. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes The inlined PNG was read chunk by chunk: standard chunks plus three ImageMagick timestamps, and nothing after IEND. Inlining it adds no third-party request, which hotlinking the CDN copy would have. ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-09-23 22:09:48 +08:00
const boxes = state.entries.map(({ link }) => {
feat(docs): add a bilingual documentation site and its deploy pipeline (#507) ## 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 - [x] 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. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] 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 --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 15:06:24 +08:00
const id = (link.getAttribute("href") || "").slice(1);
const heading = id ? document.getElementById(id) : null;
fix(docs): light the contents rail between headings and use raven.evermind.ai's favicon (#734) ## Summary Two fixes to the documentation site. **The contents rail went dark between headings.** The right-hand table of contents lit an entry only while its heading was inside the viewport. Partway through a section longer than the screen every heading sits above or below it, so nothing was lit, the gold stretch collapsed to zero height, and the column stopped following the reader. On the built site before this change, 18 of 28 English pages had such stretches: 114 of 1264 scroll positions sampled every 120px. `sync()` in `docs-site/docs/javascripts/toc-progress.js` now falls back to the nearest heading above when none is in view and lights that entry alone. The lit stretch and the column follow read the same list, so both pick it up with no further change. Above the first heading nothing is lit, since no section has begun there. The design spec states the rule, and the rail's section comment in `evermind.css`, which still credited Material with marking the section, now names what does. **The tab icon differed from raven.evermind.ai.** The site drew its own simplified EverMind mark, a single heavy lemniscate without the rings. raven.evermind.ai links one 192px PNG of the full mark for its light, dark and apple-touch icons alike. `theme.favicon` in `docs-site/mkdocs.yml` now inlines that PNG byte for byte as a data URI, since AGENTS.md section 7 keeps image files out of `docs-site/`. For whoever refreshes it: that site's CDN answers any `Accept` naming `image/avif` with a lossy AVIF re-encode (5178 bytes), and only a plain `Accept: */*` returns the original PNG (5184 bytes). The comment above the value says so. Checked and deliberately left alone: - The mark at the top of the navigation rail (`--em-mark` in `evermind.css`) is a separate drawing and still the simplified one. This change is the tab icon only. - raven.evermind.ai also sets an apple-touch icon. Material emits no such link, and adding one needs a template override, which is an `.html` file that section 7 blocks. - The favicon's identity is verified by the measurements below rather than pinned by a test: a pinned hash would only detect change, and comparing against the live site would put the network in the suite. - `tests/integration/` is outside every CI job (`norecursedirs`), so the e2e results below are local runs. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `uv run --frozen --extra browser --group docs pytest tests/integration/test_docs_site_controls_e2e.py tests/integration/test_docs_site_search_e2e.py -n 0 -q`: 63 passed. - `uv run --frozen --extra browser --group docs pytest tests/test_docs_site.py -q`: 16 passed. - The new `test_table_of_contents_keeps_the_section_above_lit_between_headings` computes, from the Sandbox page's own layout, every stretch between two headings (or after the last) with none on screen, and checks the middle of each. Against the unfixed script it fails (`at 1354px: assert [] == [2]`), and with the fix it passes. - A sweep of every built page in headless Chrome at 1440x900, one sample every 120px, checking the rule at each position: 0 violations over 1264 English, 1145 Chinese and 21 Overview positions after the change, and wherever an entry is lit, the first one sits inside the contents column. The unfixed script gives 114 violations over the same English positions. - Favicon: each of the 63 built HTML files carries exactly one icon link, and its decoded bytes match the PNG raven.evermind.ai links (sha256 `4a5051e1781fac64...`). Drawn in Chrome at 16, 32 and 192px, the docs icon and that PNG differ in 0 pixels. - `mkdocs build --strict`, `scripts/check_source_language.py origin/main...HEAD`, `scripts/check_large_files.py origin/main...HEAD`, `scripts/check_commit_messages.py origin/main..HEAD`, commitlint, `pre-commit run --from-ref origin/main --to-ref HEAD`, ruff and `git diff --check`: all pass. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [ ] User-facing docs or screenshots are updated when needed The last box is left blank because nothing needed it: no documentation page describes the rail or the icon, and the design spec is updated in this change. ## Risk - Between headings, the entry of the section above now stays lit and the contents column keeps it in view. While any heading is on screen the behaviour is unchanged. - The tab icon changes to the full mark. Each page's head now carries about 6.9 KB of base64 for it, against about 0.6 KB for the previous SVG. - The new code relies on no browser API newer than `Array.prototype.includes` (2016). - The two halves touch disjoint files, so either can be reverted on its own. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes The inlined PNG was read chunk by chunk: standard chunks plus three ImageMagick timestamps, and nothing after IEND. Inlining it adds no third-party request, which hotlinking the CDN copy would have. ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-09-23 22:09:48 +08:00
return heading && heading.getBoundingClientRect();
});
const active = [];
boxes.forEach((box, index) => {
if (box && box.bottom > 0 && box.top < window.innerHeight) active.push(index);
});
if (!active.length) {
const above = boxes.reduce(
(last, box, index) => (box && box.top < 0 ? index : last),
-1,
);
if (above !== -1) active.push(above);
}
state.entries.forEach(({ link }, index) => {
link.classList.toggle("md-nav__link--raven-active", active.includes(index));
feat(docs): add a bilingual documentation site and its deploy pipeline (#507) ## 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 - [x] 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. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] 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 --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 15:06:24 +08:00
});
const rect = state.list.querySelector(`.raven-toc-progress clipPath rect`);
if (!rect) return;
const top = active.length ? runOf(state.spans, active[0]).start : 0;
const bottom = active.length ? runOf(state.spans, active[active.length - 1]).end : 0;
const height = Math.max(0, bottom - top);
rect.setAttribute("x", "0");
rect.setAttribute("width", "12");
rect.setAttribute("y", String(top));
rect.setAttribute("height", String(height));
/* The transition runs on the styled value, so both are kept in step. */
rect.style.y = `${top}px`;
rect.style.height = `${height}px`;
fix(docs): give each language its own search index and settle the site shell (#516) ## Summary The documentation site built one search index for both languages, so a reader on the English pages was offered Chinese ones: results they cannot read, behind links that leave the language they chose. A build hook now splits the merged index in two and points the Chinese pages at their own copy, which the theme also resolves every result link against. Where that split runs is the whole fix. The merge lands in a plugin's own `on_post_build`, so the split has to be the last thing that event does. Running it on `on_shutdown` looks equivalent and is not: `mkdocs serve` never shuts down, so the preview went on serving the merged index however often it rebuilt. The new guard makes the same assertion against `mkdocs build` and against `mkdocs serve`, because passing one says nothing about the other. The rest settles the shell against the reference layout: - the rail's foot is its own box the navigation cannot show through, and the tab icon is the EverMind mark; - the footer keeps to the content column instead of covering the fixed columns once the reader reaches the page foot; - the contents column reaches the screen foot with its scrollbar hidden behind a fade, and follows the reader by centring the first lit entry; - search opens as a centred dialog over the page. The form itself travels into that dialog, so what stays in the rail is drawn from the field's own metrics and its shape does not change on a click. Neither state animates: the theme transitions the two shapes into each other, and leaving search played that out in the corner of the page after the reader had moved on. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `uv run pytest tests/integration/test_docs_site_search_e2e.py` -> 2 passed. Without this change the preview case fails: the Chinese index is HTTP 404 and the English index carries 146 Chinese pages. - `uv run pytest tests/integration/test_docs_site_controls_e2e.py` -> 25 passed - `uv run pytest tests/test_docs_site.py tests/test_source_language_check.py` -> 31 passed - `make check-commits`, `make check-source-language`, `make check-large-files` -> exit 0; `ruff check` on the added files -> no findings - `make docs-build` -> the root index holds 149 entries and no Chinese page; the Chinese index holds 146, none of them addressed from the site root Driven in a real browser at 1560x820 in both languages: a word that appears in both trees returns 10 results and 0 from the other language, and the corner of the page is pixel-identical to its never-opened state at every frame after leaving search. Every page of the built site was checked at the page foot (28 pages, 0 faults) for a footer covering a column, for a column whose last entry cannot be reached, and for the rail's foot icons being clickable. No page content changed, so nothing else needed updating with it. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk User-visible: search no longer returns pages from the other language, and the search control, the footer and the two fixed columns change shape. The field left in the rail while the dialog is open is a drawn replica, and every rule behind it sits above the theme's desktop breakpoint, so narrow viewports keep the theme's own full-screen search untouched. Rollback: revert the commit. The hook is one file, and dropping it from the `hooks:` list in `docs-site/mkdocs.yml` restores the previous merged index on its own. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 21:22:24 +08:00
follow(active);
};
/*
* The column scrolls on its own, so on a long outline the lit entry walks
* off its bottom edge and the reader loses their place. The reference layout
* centres the first lit entry and clamps at both ends -- the first, not the
* lit stretch, so the anchor does not drift as the stretch grows and shrinks.
*/
const follow = (active) => {
if (!active.length) return;
const scroller = state.list.closest(".md-sidebar__scrollwrap");
if (!scroller) return;
const link = state.entries[active[0]].link;
const box = link.getBoundingClientRect();
const frame = scroller.getBoundingClientRect();
const centre = scroller.scrollTop + (box.top - frame.top) + box.height / 2;
const limit = scroller.scrollHeight - scroller.clientHeight;
const target = Math.max(0, Math.min(limit, centre - scroller.clientHeight / 2));
/* A hair of tolerance: writing scrollTop every frame fights a reader who
is dragging the column, and a sub-pixel correction is never visible. */
if (Math.abs(target - scroller.scrollTop) > 1) scroller.scrollTop = target;
feat(docs): add a bilingual documentation site and its deploy pipeline (#507) ## 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 - [x] 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. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] 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 --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 15:06:24 +08:00
};
const relayout = () => {
layout();
sync();
};
const start = () => {
relayout();
window.addEventListener("scroll", sync, { passive: true });
window.addEventListener("resize", relayout);
if (document.fonts && document.fonts.ready) document.fonts.ready.then(relayout);
};
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", start, { once: true });
} else {
start();
}
})();