update spec links to docs.megaeth.com/spec and add mega-evme doc links (#24)

Troublor · web-flow · commit 398d483fdaa4 · 2026-04-01T18:16:31.000+08:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -106,8 +106,9 @@ When a PR creation is requested, the agent should:
 - **One sentence, one line.**
   When writing Markdown files, put each sentence on a separate line.
   This improves diff readability and makes reviews easier.
-- **Cross-link to the EVM spec with absolute GitBook URLs.**
+- **Cross-link to the EVM spec with absolute URLs.**
   The EVM spec is maintained in the mega-evm repo and synced into a separate GitBook space — it does not exist as a file in this repo.
-  Use absolute URLs: `[Dual Gas Model](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model)`.
+  Use absolute URLs with the base `https://docs.megaeth.com/spec/`: `[Dual Gas Model](https://docs.megaeth.com/spec/megaevm/dual-gas-model)`.
+  EVM pages use the `megaevm/` prefix (not `evm/`), system contracts use `system-contracts/`.
 - **Keep commit messages simple.**
   No co-author information or "generated with" footers.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -102,13 +102,20 @@ Use relative paths from the current file: `[Connect](../user/connect.md)` or `[E
 ### To the EVM Specification
 
 The EVM spec is maintained in the [mega-evm repo](https://github.com/megaeth-labs/mega-evm) and synced into a separate GitBook space.
-Use absolute URLs:
-`[Dual Gas Model](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model)`.
+Use absolute URLs with the base `https://docs.megaeth.com/spec/`:
+`[Dual Gas Model](https://docs.megaeth.com/spec/megaevm/dual-gas-model)`.
+EVM pages use the `megaevm/` prefix (not `evm/`), system contracts use `system-contracts/`.
+
+### To the mega-evme Documentation
+
+The mega-evme tool docs are hosted at `https://docs.megaeth.com/mega-evme`.
+Use absolute URLs: `[mega-evme](https://docs.megaeth.com/mega-evme)`.
 
 ### Direction rule
 
 - **User docs → Developer docs**: "For technical details, see [Developer Docs](dev/overview.md)."
-- **Developer docs → EVM Spec**: "For the formal specification, see [Dual Gas Model](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model)."
+- **Developer docs → EVM Spec**: "For the formal specification, see [Dual Gas Model](https://docs.megaeth.com/spec/megaevm/dual-gas-model)."
+- **Developer docs → mega-evme**: "For the full command reference, see [mega-evme](https://docs.megaeth.com/mega-evme)."
 - **EVM Spec → nothing**: The spec is self-contained. It never links to user or developer docs.
 
 ## Content Reuse
diff --git a/docs/README.md b/docs/README.md
@@ -38,7 +38,7 @@ MegaETH is a high-performance Ethereum L2 with ~10ms block times and real-time t
         <tr>
             <td><strong>Specification</strong></td>
             <td>Formal protocol spec — EVM behavior, gas model, system contracts, and upgrade history.</td>
-            <td><a href="https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/">Specification</a></td>
+            <td><a href="https://docs.megaeth.com/spec/">Specification</a></td>
         </tr>
     </tbody>
 </table>
diff --git a/docs/dev/AGENTS.md b/docs/dev/AGENTS.md
@@ -36,7 +36,7 @@ For every concept that has a formal spec in `mega-evm/docs/`:
 1. **Summarize** the practical implications (1-3 paragraphs)
 2. **Include** a key values table if applicable
 3. **Add** code examples showing how to work with it
-4. **Link** to the spec: "For the formal specification, see [Dual Gas Model](https://docs.megaeth.com/evm-spec/evm/dual-gas-model)."
+4. **Link** to the spec: "For the formal specification, see [Dual Gas Model](https://docs.megaeth.com/spec/megaevm/dual-gas-model)."
 
 Example pattern:
 
@@ -55,7 +55,7 @@ Use `eth_estimateGas` on a MegaETH RPC endpoint for accurate gas estimates.
 Do not attempt to compute gas costs manually.
 {% endhint %}
 
-For the complete storage gas schedule, see the [formal specification](https://docs.megaeth.com/evm-spec/evm/dual-gas-model).
+For the complete storage gas schedule, see the [formal specification](https://docs.megaeth.com/spec/megaevm/dual-gas-model).
 ```
 
 ## Code Sample Rules
diff --git a/docs/dev/execution/gas-model.md b/docs/dev/execution/gas-model.md
@@ -130,5 +130,5 @@ See [Resource Limits](resource-limits.md) for the full limits table, enforcement
 
 - [Resource Limits](resource-limits.md) — per-transaction and per-block resource ceilings
 - [EVM Differences](overview.md) — full list of behavioral differences from Ethereum
-- [Dual Gas Model (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model) — formal specification of compute gas and storage gas
-- [Resource Accounting (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-accounting) — how counters are tracked per opcode
+- [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas
+- [Resource Accounting (spec)](https://docs.megaeth.com/spec/megaevm/resource-accounting) — how counters are tracked per opcode
diff --git a/docs/dev/execution/overview.md b/docs/dev/execution/overview.md
@@ -43,19 +43,19 @@ Reading volatile data — `block.timestamp`, `block.number`, oracle storage, or
 This ensures transactions with external dependencies yield quickly and don't block parallel execution.
 
 For the full list of triggers, best practices for structuring contracts around this cap, and Solidity examples, see [Volatile Data Access](volatile-data.md).
-For the formal specification, see [Gas Detention](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/gas-detention).
+For the formal specification, see [Gas Detention](https://docs.megaeth.com/spec/megaevm/gas-detention).
 
 ## Increased Contract Size Limit
 
 MegaETH supports contracts up to **512 KB** in size, increased from 24 KB in Ethereum.
-For the formal specification, see [Contract Limits](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/contract-limits).
+For the formal specification, see [Contract Limits](https://docs.megaeth.com/spec/megaevm/contract-limits).
 
 ## `SELFDESTRUCT` with EIP-6780 Semantics
 
 The `SELFDESTRUCT` opcode follows [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780) semantics.
 It only destroys a contract when called within the same transaction that created the contract.
 In all other cases, `SELFDESTRUCT` behaves as a simple Ether transfer without destroying the contract or clearing its storage.
-For the formal specification, see [SELFDESTRUCT](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/selfdestruct).
+For the formal specification, see [SELFDESTRUCT](https://docs.megaeth.com/spec/megaevm/selfdestruct).
 
 ## No Storage Gas Refund for SSTORE Resets
 
@@ -78,7 +78,7 @@ The parent call frame retains 2% instead of ~1.6%, so subcalls receive slightly
 Review any patterns that rely on precise gas forwarding calculations.
 {% endhint %}
 
-For the formal specification, see [Gas Forwarding](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/gas-forwarding).
+For the formal specification, see [Gas Forwarding](https://docs.megaeth.com/spec/megaevm/gas-forwarding).
 
 ## Precompile Gas Overrides
 
@@ -90,11 +90,11 @@ Two precompiles have adjusted gas costs:
 | KZG Point Evaluation | `0x0A`  | 100,000 gas (2× the standard Prague cost of 50,000)                                                               |
 | ModExp               | `0x05`  | [EIP-7883](https://eips.ethereum.org/EIPS/eip-7883) gas schedule (raises the cost floor for large-exponent calls) |
 
-For the formal specification, see [Precompiles](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/precompiles).
+For the formal specification, see [Precompiles](https://docs.megaeth.com/spec/megaevm/precompiles).
 
 ## Related Pages
 
 - [Gas Model](gas-model.md) — full dual gas model and resource limits
 - [System Contracts](system-contracts.md) — native oracle interface and high-precision timestamp
 - [Volatile Data Access](volatile-data.md) — compute gas cap on volatile data reads
-- [EVM Specification](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/overview) — formal normative specification
+- [EVM Specification](https://docs.megaeth.com/spec/megaevm/overview) — formal normative specification
diff --git a/docs/dev/execution/resource-limits.md b/docs/dev/execution/resource-limits.md
@@ -34,7 +34,7 @@ Note: "Unlimited" means no dedicated per-block limit exists for that resource, b
 
 For Data Size, KV Updates, and State Growth, block-level usage is the sum of usage across all transactions in the block.
 
-For formal definitions of resource limits and accounting, see [Resource Limits (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-limits) and [Resource Accounting (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-accounting).
+For formal definitions of resource limits and accounting, see [Resource Limits (spec)](https://docs.megaeth.com/spec/megaevm/resource-limits) and [Resource Accounting (spec)](https://docs.megaeth.com/spec/megaevm/resource-accounting).
 
 ## Enforcement
 
@@ -50,7 +50,7 @@ The block builder stops adding transactions once the block's cumulative gas or D
 
 ### During execution
 
-**Compute Gas**, **Data Size**, **KV Updates**, and **State Growth** are enforced while the transaction runs (see [formal spec](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-limits)).
+**Compute Gas**, **Data Size**, **KV Updates**, and **State Growth** are enforced while the transaction runs (see [formal spec](https://docs.megaeth.com/spec/megaevm/resource-limits)).
 
 **Per-transaction**: when a transaction exceeds any of these four limits:
 
@@ -76,5 +76,5 @@ Since Compute Gas is a component of total gas, and each transaction's total gas
 - [Gas Model](gas-model.md) — compute gas, storage gas, and the bucket multiplier
 - [Gas Estimation](../send-tx/gas-estimation.md) — estimate gas correctly and avoid common errors
 - [EVM Differences](overview.md) — full list of behavioral differences from Ethereum
-- [Resource Limits (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-limits) — formal specification of limit enforcement
-- [Resource Accounting (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-accounting) — how counters are tracked per opcode
+- [Resource Limits (spec)](https://docs.megaeth.com/spec/megaevm/resource-limits) — formal specification of limit enforcement
+- [Resource Accounting (spec)](https://docs.megaeth.com/spec/megaevm/resource-accounting) — how counters are tracked per opcode
diff --git a/docs/dev/execution/system-contracts.md b/docs/dev/execution/system-contracts.md
@@ -137,6 +137,6 @@ Addresses and interfaces are subject to change before release.
 ## Related Pages
 
 - [Volatile Data Access](volatile-data.md) — compute gas cap, best practices for reading volatile data
-- [System Contracts (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/system-contracts/overview) — formal specification of the system contract registry
-- [Oracle (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/system-contracts/oracle) — underlying oracle contract that powers the High-Precision Timestamp and other services
-- [KeylessDeploy (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/system-contracts/keyless-deploy) — keyless deployment sandbox and validation rules
+- [System Contracts (spec)](https://docs.megaeth.com/spec/system-contracts/overview) — formal specification of the system contract registry
+- [Oracle (spec)](https://docs.megaeth.com/spec/system-contracts/oracle) — underlying oracle contract that powers the High-Precision Timestamp and other services
+- [KeylessDeploy (spec)](https://docs.megaeth.com/spec/system-contracts/keyless-deploy) — keyless deployment sandbox and validation rules
diff --git a/docs/dev/execution/volatile-data.md b/docs/dev/execution/volatile-data.md
@@ -24,7 +24,7 @@ Under the current absolute model, the same transaction would have only 5M remain
 
 This change removes the penalty for accessing volatile data late in a transaction's execution.
 Under relative detention, reading volatile data **as late as possible** becomes a valid optimization — see [Best Practices](#best-practices).
-For the formal definition, see [Gas Detention](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/gas-detention).
+For the formal definition, see [Gas Detention](https://docs.megaeth.com/spec/megaevm/gas-detention).
 
 </details>
 
@@ -109,7 +109,7 @@ function processWithTimestamp(uint256[] calldata items) external {
 ```
 
 Under the current absolute cap, read order makes no difference — the 20M ceiling applies to total compute gas regardless.
-For the formal definition, see [Gas Detention](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/gas-detention).
+For the formal definition, see [Gas Detention](https://docs.megaeth.com/spec/megaevm/gas-detention).
 
 </details>
 
@@ -118,4 +118,4 @@ For the formal definition, see [Gas Detention](https://app.gitbook.com/o/iBzILuN
 - [EVM Differences](overview.md) — full list of MegaEVM behavioral differences
 - [Gas Estimation](../send-tx/gas-estimation.md) — estimate gas correctly on MegaETH
 - [Debugging Transactions](../send-tx/debugging.md) — trace gas consumption with mega-evme
-- [Gas Detention (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/gas-detention) — formal specification of the gas detention mechanism
+- [Gas Detention (spec)](https://docs.megaeth.com/spec/megaevm/gas-detention) — formal specification of the gas detention mechanism
diff --git a/docs/dev/faq.md b/docs/dev/faq.md
@@ -42,7 +42,7 @@ Write error handling for rollbacks of preconfirmed blocks.
 ### What is the contract size limit?
 
 512 KB, rather than Ethereum's 24 KB.
-See the [Contract Limits specification](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/contract-limits) for details.
+See the [Contract Limits specification](https://docs.megaeth.com/spec/megaevm/contract-limits) for details.
 
 ## Transaction Lifecycle & Txpool
 
diff --git a/docs/dev/overview.md b/docs/dev/overview.md
@@ -12,7 +12,7 @@ For network parameters (chain ID, RPC URLs, block explorers), see [Connect to Me
 ## EVM Compatibility
 
 MegaETH's execution environment is called **MegaEVM**.
-It is fully compatible with Ethereum smart contracts but introduces a few differences compared to Ethereum's EVM, especially around the [dual gas model](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model).
+It is fully compatible with Ethereum smart contracts but introduces a few differences compared to Ethereum's EVM, especially around the [dual gas model](https://docs.megaeth.com/spec/megaevm/dual-gas-model).
 See [EVM Differences](execution/overview.md) for a complete list.
 
 The MegaEVM implementation is open source and can be found on [GitHub](https://github.com/megaeth-labs/mega-evm).
@@ -25,7 +25,7 @@ See [Gas Estimation](send-tx/gas-estimation.md) for code examples, toolchain con
 
 ## Debugging Transactions
 
-MegaETH supports `debug_traceTransaction` and other debug RPC methods (via managed RPC providers), and provides `mega-evme` for local transaction replay and simulation.
+MegaETH supports `debug_traceTransaction` and other debug RPC methods (via managed RPC providers), and provides [`mega-evme`](https://docs.megaeth.com/mega-evme) for local transaction replay and simulation.
 See [Debugging Transactions](send-tx/debugging.md) for usage examples and common debugging scenarios.
 
 ## Using the Canonical Bridge
diff --git a/docs/dev/send-tx/debugging.md b/docs/dev/send-tx/debugging.md
@@ -38,7 +38,7 @@ For method parameters, tracer configuration options, and response formats, see t
 
 ## Using mega-evme
 
-`mega-evme` is a local CLI tool that uses the open-source [MegaEVM](https://github.com/megaeth-labs/mega-evm) implementation.
+[`mega-evme`](https://docs.megaeth.com/mega-evme) is a local CLI tool that uses the open-source [MegaEVM](https://github.com/megaeth-labs/mega-evm) implementation.
 It can perfectly simulate any transaction's behavior on MegaETH, including storage gas, compute gas caps, and resource limits.
 
 Use `mega-evme` when you want full local control over tracing, or when you don't have access to a managed RPC endpoint with debug methods.
@@ -208,5 +208,6 @@ See [Volatile Data Access](../execution/volatile-data.md) for the full list of t
 - [EVM Differences](../execution/overview.md) — volatile data caps, SSTORE refund changes, 98/100 forwarding
 - [Gas Model](../execution/gas-model.md) — how compute gas and storage gas work
 - [RPC Reference](../read/overview.md) — method availability and restrictions
-- [Dual Gas Model (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model) — formal specification of compute gas and storage gas
-- [Gas Detention (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/gas-detention) — compute gas cap triggered by volatile data access
+- [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas
+- [Gas Detention (spec)](https://docs.megaeth.com/spec/megaevm/gas-detention) — compute gas cap triggered by volatile data access
+- [mega-evme](https://docs.megaeth.com/mega-evme) — full command reference, configuration, and cookbook
diff --git a/docs/dev/send-tx/gas-estimation.md b/docs/dev/send-tx/gas-estimation.md
@@ -146,5 +146,5 @@ If you need to debug which dimension caused a failure, see [Debugging Transactio
 - [EVM Differences](../execution/overview.md) — volatile data caps, SSTORE refund changes, 98/100 forwarding
 - [RPC Reference](../read/overview.md) — method availability and restrictions
 - [Developer FAQ](../faq.md) — `eth_estimateGas` gas cap, block gas limit
-- [Dual Gas Model (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/dual-gas-model) — formal specification of compute gas and storage gas
-- [Resource Limits (spec)](https://app.gitbook.com/o/iBzILuNyLtuxU3vUEuPe/s/apRp1sxFYuGhHAo7Y2Pz/evm/resource-limits) — per-transaction and per-block limit enforcement
+- [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas
+- [Resource Limits (spec)](https://docs.megaeth.com/spec/megaevm/resource-limits) — per-transaction and per-block limit enforcement
