Skip to content

Restructure the site around the shipped provers - #25

Merged
somnergy merged 12 commits into
mainfrom
som/docs-restructure
Oct 26, 2026
Merged

somnergy merged 12 commits into
mainfrom
som/docs-restructure

Conversation

@somnergy

Copy link
Copy Markdown
Member

Summary

Rebuilds the documentation site around what Zilkworm ships. The marketing landing page and the collaboration page are gone; the docs are served at / and the Overview is the home page.

Structure: Overview, Provers (Choosing a prover, Airbender, Hypercube, ZisK, Ethproofs posting), Inside the guest (Execution pipeline, Witness formats, Precompiles and syscalls, Proof guarantees), Testing (Execution spec tests, RISC-V tests under QEMU, ERE validation), Reference (CLI reference, Releases and assets, Building from source, Benchmarks and CI). 17 pages.

Every fact traces to a path in zilkworm main (311749c99) or a release tag. Performance numbers appear only on Releases and assets. The Hypercube page states the current prove, verify and setup behaviour plainly. The rollups essay is removed from the site.

Chrome: section index pages render as terminal frames, sidebar sections start collapsed, footer keeps the brand lockup and the four social icons, navbar has Blog and GitHub. Client redirects cover every old /documentation/... URL and /collaboration.

Supersedes the CLI snippet fixes in #20, whose landing-page, GPU docker example and cd qemu_runner corrections are folded in here.

Checks

typecheck, check:tsconfig, build (onBrokenLinks: throw), generate-llms.py --check, scripts unit tests, all green at every commit.

🤖 Generated with Claude Code

somnergy and others added 12 commits October 26, 2026 18:42
…redirects

Docs now serve from / with an explicit sidebar in four categories, each
with a generated index page (/provers, /inside-the-guest, /testing,
/reference). New pages are stubs for the content pass.

What moved where:
- docs/index.md: Welcome page -> Overview at /, with a status strip,
  product cards and reader cards (src/components/Overview/). The strip
  reads src/data/status.json.
- getting-started/how-it-works, fundamentals/background
  -> inside-the-guest/execution-pipeline
- getting-started/quickstart-hypercube, running-the-prover
  -> provers/hypercube-prover
- getting-started/airbender-prover -> provers/airbender-prover
- getting-started/ethproofs-prover -> provers/ethproofs-posting
- getting-started/zisk-prover -> provers/zisk-prover
- getting-started/cli-reference -> reference/cli-reference
- fundamentals/witness-formats -> inside-the-guest/witness-formats
- fundamentals/write-your-own-rollups-using-zilkworm -> removed, redirects to /
- testing/ethereum-execution-tests-eests -> testing/execution-spec-tests
- testing/riscv-testing-eests-on-rv32im-via-qemu -> testing/riscv-tests-under-qemu
- development/{releases,building-and-testing,benchmarks-and-ci}
  -> reference/{releases-and-assets,building-from-source,benchmarks-and-ci}
- New: provers/choosing-a-prover, inside-the-guest/precompiles-and-syscalls,
  inside-the-guest/proof-guarantees, testing/ere-validation
- Removed: the React landing (src/pages/index.tsx, index.module.css),
  /collaboration, HomeCards, and the landing-only CSS.

Chrome:
- @docusaurus/plugin-client-redirects 3.10.2 maps all 17 old
  /documentation/... URLs and /collaboration to the new pages.
- Navbar: Documentation and Collaboration items removed; Releases and
  Blog are plain links; GitHub icon, search and colour toggle stay.
- Footer links GitHub, Releases, Ethproofs, the blog and Erigon; the
  slogan line is gone.
- 404 cards point at Overview, Choosing a prover, Execution pipeline,
  CLI reference and GitHub.
- Tagline and meta description drop the old superlatives.
- generate-llms.py uses https://zilkworm.erigon.tech as the base and
  orders pages like the sidebar; llms.txt and llms-full.txt regenerated.
- README: Node 24, green #1F9D3E, new layout, release status note.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ting

Pages: provers/choosing-a-prover.md, provers/airbender-prover.md,
provers/hypercube-prover.md, provers/zisk-prover.md,
provers/ethproofs-posting.md.

Corrected in verification:
- Choosing a prover: the ZisK row reads MFBD and EJSN. The ZisK host
  wraps --is-test fixtures as EJSN (e5eeec967 prover_zisk/src/
  stdin_builders.rs) and the shared runner has the EJSN case.
- Choosing a prover: the Hypercube Ethproofs cell says "No live
  cluster". Nothing in the repo shows Ethproofs accepts its proofs.
- Airbender: the image holds three recursion verifier programs, each a
  .bin and .text pair (prover/docker/fsv.sha256), not six programs.
- Airbender: main pushes retag the image only when its inputs change
  (airbender-image.yml path filter).
- ZisK: the guest also takes EJSN via --is-test. The
  tx_invalid_first_in_block failure is fixed on main by #141.
- Ethproofs posting: no production endpoint is documented. The staging
  URL is cited with its two source files; <endpoint> stays.
- Prover pages: "What ships" and "What the host checks" become
  "Shipped artifacts" and "Host checks", per the heading style rule.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ntees

Pages: inside-the-guest/execution-pipeline.md,
inside-the-guest/witness-formats.md,
inside-the-guest/precompiles-and-syscalls.md,
inside-the-guest/proof-guarantees.md.

Checked in verification, no corrections needed:
- The 112-, 43- and 32-byte public-value layouts against both guest
  main.cpp files.
- The input dispatch per guest in state_transition.cpp, including the
  "needs the HashState guest" error for raw SSZ on DirectState builds.
- FBND v14 and the 56-byte, six-section bundle header (flat_bundle.hpp).
- The Airbender CSR list; Blake2s 0x7C7 has helpers but no callers.
- SP1 ecall call sites in the evmone pin 85f66c8e.
- The alpha.7 key changes against the CHANGELOG (#137, #141).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Pages: testing/execution-spec-tests.md,
testing/riscv-tests-under-qemu.md, testing/ere-validation.md.

Corrected in verification:
- Execution spec tests: drop "on every change". The zkVM EEST
  workflows are path-filtered, and Airbender skips release/*.
- ERE validation: headings "What a run checks" and "The ERE Benchmark
  workflow" become "Checks per fixture" and "ERE benchmark workflow".
- QEMU: heading "What cross-architecture runs catch" becomes "Bugs that
  cross-architecture runs catch".

Checked, no change: the tests@v21.0.1 pin and sha256, the 25 Airbender
known failures, the header-only native list, the broken make tests
targets, the QEMU workflow triggers, and the ere-bin staging paths.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Pages: reference/cli-reference.md, reference/releases-and-assets.md,
reference/building-from-source.md, reference/benchmarks-and-ci.md.
Regenerates static/llms.txt and static/llms-full.txt for all 17 pages.

Checked in verification, no corrections needed:
- The alpha.7 asset names and sizes against gh release view, and the
  release titles and dates against gh release list.
- Both hosts' flag defaults: --cycles 5,000,000,000 and the
  1,073,741,822 clamp, RUST_LOG warn and info, --post-every unused.
- The Hypercube prove, setup and verify stubs (service.rs, main.rs).
- state_transition exit codes and its .json/.bin directory scan.
- CMake 3.28 and GCC 15 against CMakeLists.txt and the CI image.
- The workflow triggers in the CI table.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Eject DocCardList and DocCard from @docusaurus/theme-classic (DocCard
sub-folders dropped). DocCardList draws one frame with a
"$ zilkworm docs <dir>/" title bar, where <dir> is the last segment of
the deepest sidebar category's href, and a blinking cursor line. DocCard
draws each doc as a "> title" row with its description below; nested
categories render as "<title>/". Both use the new shared
src/components/TerminalList.

The 404 page's link cards now use the same frame and rows, and its
buttons are square. custom.css drops the 404 card rules, zeroes the
sidebar box, details, navbar GitHub icon and 404 button radii, and
removes the pagination lift and shadow.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Eject DocCategoryGeneratedIndexPage from @docusaurus/theme-classic. It
keeps PageMetadata, DocVersionBanner, DocBreadcrumbs, DocVersionBadge and
DocPaginator, drops the header above the list, and renders one
TerminalFrame: the category title as a real <h1> on the top border, then
"$ zilkworm docs <dir>/" and the category description as a "# ..."
comment line inside.

Rows take a summary of at most seven words from a new
customProps.summary on every doc item in sidebars.ts; DocCard falls back
to the description only when it is missing. Summary columns line up via
subgrid and drop under the title when the frame is narrower than 36rem.
The 404 rows get summaries of the same length, and the four category
descriptions are cut to at most ten words in sidebars.ts and
_category_.json.

Remove the blinking cursor line from every frame, with its CSS and
keyframes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Voice pass over every page and the overview and 404 components.
Hedges dropped, lists turned into paragraphs where they read better.
Sidebar summaries and category descriptions reworded and kept in sync.
llms.txt and llms-full.txt regenerated and checked.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 26, 2026 20:38

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@somnergy
somnergy merged commit a7a1efc into main Oct 26, 2026
1 check passed
@somnergy
somnergy deleted the som/docs-restructure branch October 26, 2026 20:40
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.

2 participants