Restructure documentation to GitBook three-layer architecture by Troublor · Pull Request #23 · megaeth-labs/documentation

Troublor · 2026-04-01T02:20:57Z

Summary

Restructures the entire documentation site from flat Pandoc-generated HTML into a three-layer GitBook architecture: User Guide (user/), Developer Docs (dev/), and Specification (maintained in mega-evm, linked via absolute URLs).
Removes all legacy build artifacts (Pandoc templates, HTML output, manifest files) and migrates content into GitBook-flavored Markdown with proper frontmatter, custom blocks, and GitBook space variables.
Adds comprehensive new developer documentation: gas estimation, debugging with mega-evme, RPC method reference pages (eth_subscribe, eth_callAfter, eth_getLogsWithCursor, realtime_sendRawTransaction, error codes), realtime API guide, volatile data access, resource limits, system contracts, contracts & tokens registry, tooling & infrastructure partners, Build with AI, and developer FAQ.
Adds user guide pages: get started, connect wallet, bridge, faucet, featured apps, and user FAQ.
Adds top-level narrative pages: architecture overview and mini-blocks explainer.
Adds layer-specific AGENTS.md writing rules for each directory and doc-audit skills (correctness, freshness, readability).
Fixes broken internal links, a GitBook rendering bug (duplicate endtab), a typo (debug_replyBlock → debug_replayBlock), and corrects eth_getLogsWithCursor availability status.

…tegration)

…or, remove impl detail

… and proper structure

…S.md

…i-block terminology - Reorganize user guide: replace mainnet.md/testnet.md with topic pages (get-started, connect, bridge, contracts) using mainnet/testnet tabs - Add missing legacy content: L1 contracts, Multicall3, chain params - Rename 'mini block' to 'mini-block' across all docs (70 occurrences) - Add mini-block and EVM block definitions to spec glossary - Add uptime.megaeth.com network status to user pages - Move README.md to top-level in SUMMARY.md - Fix all cross-links to deleted pages

…xplorer links

…larify testnet-only faucet

…add token listing guide

…ctions (same addresses on mainnet and testnet)

…ions

…rview - Rename dev/getting-started.md to dev/overview.md, reframe as overview - Remove duplicate 'Connect to MegaETH' section from overview - Add dev/gas-estimation.md: eth_estimateGas usage, toolchain config, common errors - Add dev/debugging.md: debug RPC methods, mega-evme replay/simulation, tracers - Slim overview.md gas estimation and debugging sections to link to new pages - Update gas-model.md tips to cross-link to gas estimation page - Update all cross-references (SUMMARY, README, bridge, contracts, spec)

…missing Rewrite 20 descriptions that duplicated the page's opening paragraph with distinct SEO summaries. Add missing descriptions to 6 spec pages (overview, glossary, hardfork-spec, dual-gas-model, gas-detention, upgrades/overview).

Move the Access to Volatile Data section from evm-differences.md into a new dev/volatile-data.md page. Add best practices: defer reads, split heavy transactions, use DELEGATECALL for oracle, separate gas-sensitive logic. Include good/bad Solidity patterns in tabs. Keep a summary + link in evm-differences.md. Update cross-references in debugging.md and gas-estimation.md.

Under the current absolute cap, read order is irrelevant. Replace 'read late' advice with 'keep under 20M' guidance. Move the read-late pattern into a Rex4 (unstable) expandable where it actually applies.

…vailability

claude · 2026-04-01T02:27:34Z

Review: GitBook restructure

This is a major restructure (62 commits, 79 files) migrating the docs from Pandoc/Cloudflare Pages to a GitBook three-layer architecture. The structure, navigation, and most content look good. A few issues need attention before merge.

Blocking:

Factual error in landing page: "sub-millisecond block times" (mini-blocks are ~10ms = sub-second)
Gas limit contradiction: resource-limits.md says 10,000,000,000 per-transaction; gas-estimation.md and dev/faq.md both say the on-chain transaction gas limit is 1,000,000,000. One of these is wrong.

Non-blocking:

.claude/doc-audit.md references docs/integration/AGENTS.md (line 3) and claims resource-limits.md says 2B (line 30), both stale — the audit was written against an earlier version of the files.

cloudflare-workers-and-pages · 2026-04-01T02:29:34Z

Deploying megaeth-documentation with Cloudflare Pages

Latest commit:	`ef916c6`
Status:	🚫 Build failed.

View logs

claude · 2026-04-01T02:35:11Z

This is a large, well-structured restructure. The architecture is clean and the new content is comprehensive. Three outstanding issues from previous review rounds still need to be addressed before merging:

docs/README.md — "sub-millisecond" is factually wrong (thread already open). Mini-blocks are ~10 ms, which is sub-second, not sub-millisecond. Fix: replace with "sub-second".
Gas limit inconsistency: 10B vs 1B (thread already open on resource-limits.md). resource-limits.md states the per-transaction gas limit is 10,000,000,000 (10B), but dev/faq.md and dev/send-tx/gas-estimation.md both state it is 1,000,000,000 (1B). One of these is wrong — verify against the sequencer config and make all three files consistent.
.claude/doc-audit.md references a non-existent layer (thread already open). Line 3 cites docs/integration/AGENTS.md, which does not exist in this PR. Line 30 also states resource-limits.md says "2,000,000,000 (2B)" but the actual file says 10B. Update the audit doc to match reality before merging.

claude · 2026-04-01T02:36:37Z

+  * [Debugging Transactions](dev/send-tx/debugging.md)
+* [Read from MegaETH](dev/read/overview.md)
+  * [Realtime API](dev/read/realtime-api.md)
+  * RPC Reference


Navigation broken: RPC Reference is a plain-text entry with no page link. GitBook requires every navigation item to have a target file. Either create a docs/dev/read/rpc/overview.md landing page and link it here, or collapse the section so each method appears directly under "Read from MegaETH".

Suggested change

* RPC Reference

* [RPC Reference](dev/read/rpc/overview.md)

claude · 2026-04-01T02:37:45Z

Review

3 previously flagged issues remain unresolved — addressing those is a blocker.

Open threads (not addressed in latest push)

docs/README.md — sub-millisecond block times is still present. Mini-blocks are ~10 ms (sub-second, not sub-millisecond).
docs/dev/execution/resource-limits.md — per-transaction Gas limit is 10,000,000,000 in resource-limits.md but dev/faq.md line 54 says 1,000,000,000. Still inconsistent.
.claude/doc-audit.md — references docs/integration/AGENTS.md (non-existent layer) and quotes resource-limits.md as saying 2 B gas when the file says 10 B.

New issue

AGENTS.md lines 110–111 — the "Cross-link to the EVM spec with relative paths" bullet contradicts the rest of the same file (spec doesn't live in this repo), docs/AGENTS.md, and every page in this PR (all use absolute GitBook URLs). Inline suggestion posted.

claude · 2026-04-01T02:38:48Z

Reviewed the current state of the PR. All 7 previously opened threads remain unresolved:

docs/README.md — still says "sub-millisecond block times" (should be ~10ms)
docs/dev/execution/resource-limits.md vs gas-estimation.md / dev/faq.md — Gas limit is 10B in resource-limits but 1B in the other two files; contradition unresolved
.claude/doc-audit.md — still references non-existent docs/integration/AGENTS.md and claims resource-limits.md says 2B (it says 10B)
docs/SUMMARY.md — "RPC Reference" is still a plain-text entry with no link target
docs/dev/send-tx/contracts.md — heading hierarchy still jumps H1→H3, skipping H2
docs/dev/faq.md — blockHash FAQ heading says 0xfff[...]fff but the answer describes a null value
docs/dev/faq.md — token address question still points to the community wiki instead of contracts.md

Please address the open threads before merging.

…ng instructions

…s, FAQ answers, spec link guidance

claude · 2026-04-01T03:00:59Z

Review update — 2026-04-01

Resolved 7 of 8 previous threads — all addressed. One remains open:

docs/SUMMARY.md — RPC Reference still has no target file. GitBook requires every navigation entry to be a linked page. The plain-text RPC Reference grouping label will break navigation. Either add a docs/dev/read/rpc/overview.md landing page and link it, or promote the method pages one level up under "Read from MegaETH".

No new issues found — the restructure is solid.

…omments

claude · 2026-04-01T03:05:31Z

Reviewed the latest changes. All previous threads are resolved except one:

Still open: docs/SUMMARY.md — RPC Reference is still a plain-text entry with no linked page (thread PRRT_kwDOODfgX854HZ9b). GitBook will not render this as a navigation item. Either create a docs/dev/read/rpc/overview.md landing page and link it, or remove the grouping level and list the individual RPC methods directly under "Read from MegaETH".

No new issues found. Content is internally consistent (gas limits, heading levels, spec cross-links all clean).

Troublor added 30 commits March 26, 2026 18:54

restructure docs from Pandoc to GitBook format

e17ec7f

restructure docs into three-layer GitBook architecture (user, dev, in…

254cc45

…tegration)

migrate all legacy content into three-layer GitBook structure

78dbe71

enrich developer docs with dapp-builder content from EVM spec

7e27a5c

add EVM specification layer mirrored from mega-evm/docs

3619c07

refocus spec overview to target node builders and auditors

bec87ae

broaden spec scope from EVM-only to full verifiable behavior

0af9bf9

broaden spec language from MegaEVM-specific to full verifiable behavi…

07eef31

…or, remove impl detail

rewrite dual gas model spec with normative language, constants table,…

d682154

… and proper structure

add Motivation section to dual gas model spec

2860114

codify spec page structure and writing rules from dual gas model review

2719bd2

move motivation to top after abstract, update page structure in AGENT…

96b1593

…S.md

move constants after specification section

e16bf99

soften compute gas wording in dual gas model spec

f48d26a

add note that constants appear after specification

1e6f536

clarify user is ultimate source of truth for spec updates

55b42d5

expand spec verification guidance to include mega-reth and other repos

7aea61c

refine spec structure and move oracle services into developer docs

4db58b5

fix block gas limit in FAQ, expand token list with descriptions and e…

8635d17

…xplorer links

inline OP Stack predeploys and preinstalls on contracts page

45cb0cf

update bridge and faucet docs: point users to Rabbithole bridge UI, c…

c7d9a08

…larify testnet-only faucet

rename Bridge/Faucet nav titles to clarify mainnet vs testnet

84224f0

move contracts page to dev docs, restructure with per-category tabs, …

f0f64a3

…add token listing guide

move token listing guide to end of page, remove tabs from OP Stack se…

588ded6

…ctions (same addresses on mainnet and testnet)

add GitBook space variables and replace hardcoded values with express…

de497f7

…ions

fix volatile data best practices: read-late advice only applies to Rex4

ad84212

Under the current absolute cap, read order is irrelevant. Replace 'read late' advice with 'keep under 20M' guidance. Move the read-late pattern into a Rex4 (unstable) expandable where it actually applies.

Troublor and others added 6 commits March 31, 2026 22:04

fix spec link in landing page

820fd68

try relative path without .md for spec link

db6cf02

GITBOOK-3: No subject

c17736b

replace all spec relative links with absolute GitBook URLs

1296dc0

update

fa41254

fix broken links, typo, duplicate endtab, and eth_getLogsWithCursor a…

ed6c304

…vailability

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread docs/README.md

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread docs/dev/execution/resource-limits.md Outdated

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread .claude/doc-audit.md Outdated

replace Pandoc build CI with lychee link checker

0fd1ca2

Troublor added 3 commits April 1, 2026 10:31

add review guidelines for PR reviews

73a08a3

point PR review prompt back to REVIEW.md

d0b23d0

add local lychee link check instructions to README

5b6412e

fix lychee config and remaining broken fragment links

9768678

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread docs/dev/send-tx/contracts.md Outdated

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread docs/dev/faq.md Outdated

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread docs/dev/faq.md Outdated

claude Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Troublor added 2 commits April 1, 2026 10:42

add markdownlint to CI, fix lint violations, update README with linti…

aae4df6

…ng instructions

address PR review: fix block time claim, gas limit wording, stale ref…

958fef2

…s, FAQ answers, spec link guidance

add prettier formatter, mise for tool management, address PR review c…

ef916c6

…omments

Troublor merged commit 7e0f519 into main Apr 1, 2026
4 of 5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure documentation to GitBook three-layer architecture#23

Restructure documentation to GitBook three-layer architecture#23
Troublor merged 70 commits into
mainfrom
william/doc/restructure-to-gitbook

Troublor commented Apr 1, 2026

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 1, 2026 •

edited

Loading

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Troublor commented Apr 1, 2026

Summary

Uh oh!

claude Bot commented Apr 1, 2026

Review: GitBook restructure

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying megaeth-documentation with Cloudflare Pages

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Apr 1, 2026

Review

Open threads (not addressed in latest push)

New issue

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

claude Bot commented Apr 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cloudflare-workers-and-pages Bot commented Apr 1, 2026 •

edited

Loading