feat(doc): re-write readme/top-level docs and add specs section to html docs (#2677)

* docs(specs): add Specs section with overview

Introduce a top-level `Specs` section in the mkdocs navigation and a new
`docs/specs/index.md` page that explains what EELS is, the coordination
problem it solves, why Python was chosen, the Correct/Complete/Accessible
principles, and the fork-as-a-copy (WET) model.

This is the anchor page for further specs-side documentation (writing
specs, adding a new EIP, spec releases, protocol history); those pages
land in follow-up commits.

* docs(specs): move protocol history table from README to Specs section

The full mainnet hardfork table, the "clarifications without a protocol
release" table, and the Paris/Shanghai activation note now live on a
dedicated `docs/specs/protocol_history.md` page linked from the Specs
overview and the mkdocs navigation. `README.md` keeps a one-line pointer
to the new page.

Fork-manifest links switch from repo-relative paths (`/src/ethereum/...`)
to absolute GitHub URLs on `forks/amsterdam` so they resolve correctly
from the rendered docs site.

* docs(specs): move EIP_AUTHORS_MANUAL.md to docs/specs/adding_a_new_eip.md

Pure rename so `git log --follow` (and `mkdocs-git-authors-plugin` by
extension) continues to trace the file's history back to the original
author, Guruprasad Kamath. Content modernization for the post-Weld
world lands in the follow-up commit.

* docs(specs): modernize adding_a_new_eip for the unified repo

Post-Weld rewrite of the EIP author's manual. The cross-repo references
to `execution-spec-tests` are replaced with pointers to in-tree tests
under `./tests/`; the step-by-step workflow points at the in-tree
`ethereum_spec_tools` utilities. The YouTube opcode tutorial link is
preserved.

The rename from `EIP_AUTHORS_MANUAL.md` to
`docs/specs/adding_a_new_eip.md` was done as a pure `git mv` in the
previous commit so `git log --follow` (and therefore the
`mkdocs-git-authors-plugin`) continues to attribute the earlier content
to its original author.

Co-authored-by: Guruprasad Kamath <guru241987@gmail.com>

* docs(specs): add writing_specs page from CONTRIBUTING technicals

Extracts the style, comments, docstrings, constants, and cross-fork
sections from `CONTRIBUTING.md` into a dedicated
`docs/specs/writing_specs.md` page, alongside documentation for the
`ethereum_spec_tools` CLI utilities (New Fork Tool, Sync Tool, Patch
Tool, Lint Tool) and the `--evm-trace` debugging flag.

The EIP-attributed-comment pitfall is preserved as a collapsible detail
block so it remains readable without dominating the page.

`CONTRIBUTING.md` is untouched in this commit; the slimming down to
who/how/what happens in a follow-up. The `adding_a_new_eip` page gets
its `Writing Specs` link back in this commit now that the target exists.

* docs(contributing): slim CONTRIBUTING.md to who/how/what

`CONTRIBUTING.md` now focuses on who the project welcomes contributions
from, how to raise issues/PRs, and the three guiding principles
(Correct, Complete, Accessible). The remaining sections point at the
authoritative docs:

- Environment setup, `uv`/`just`/shell completions, Python version,
  and the full recipe list go to `docs/getting_started/installation.md`.
- Naming/comments/docstrings/constants/cross-fork discipline, and the
  `ethereum_spec_tools` CLI utilities go to `docs/specs/writing_specs.md`.
- The `--evm-trace` debugging tip lives in `docs/specs/writing_specs.md`.
- The `MYPY_CACHE_DIR` worktree tip is already covered in the
  installation docs.

`copy_repo_docs_to_mkdocs.py` learns two new link rewrites so the
repo-relative `docs/...` paths in `CONTRIBUTING.md` work both when
viewed on GitHub and when the file is copied to
`docs/getting_started/contributing.md` for the rendered site.

* docs(specs): split RELEASING into contributor and maintainer pages

The old `RELEASING.md` mixed two audiences: contributors (who want to
understand the version-number scheme when reading `pyproject.toml` or
proposing a release) and maintainers (who cut the tag, publish to PyPI,
and file the GitHub release).

Split along that seam:

- `docs/specs/spec_releases.md` covers the versioning scheme (format,
  examples, and the current-to-next lookup table), sitting alongside
  the other specs-side documentation.
- `docs/dev/releasing.md` is the maintainer runbook (updating the
  version in source, tagging, GitHub release, PyPI publish).

Each page links to the other so a reader landing on either one can find
the half they need.

* docs(readme): rewrite README around the docs site and a Quick Start

Post-Weld `README.md` becomes the GitHub-landing hook: a short
description, pointers to the rendered documentation site, the
`docc`-rendered pyspec, the protocol history page, a single-tab Quick
Start cribbed from `docs/getting_started/installation.md`, and the
license.

The README now treats `docs/getting_started/installation.md` as the
source of truth for environment setup: the Python-version line reflects
the 3.11 to 3.14 range (recommending 3.12) rather than the stale
"Python 3.11+"; the "Building Specification Documentation" and
"Browsing Updated Documentation" sections collapse into a single
`mkdocs serve` / `just docs-spec` note; and the "work-in-progress"
placeholder heading is gone.

* docs(specs): rename top-level section header to "Specifications"

Use the full word "Specifications" in the navigation sidebar and the
section index H1. The folder name under `docs/specs/` and the URL path
are unchanged.

* docs(specs): reframe coordination section around client diversity

The opening section now leads with "Client Diversity requires
Coordination" and frames client diversity as a positive property
(resilience, no privileged implementation, permissionless participation)
rather than opening on the coordination *problem*. Coordination follows
as the natural consequence of that diversity: a multi-client network
needs a precise shared description of behaviour, and EELS is it.

Links the ethereum.org client-diversity page for readers who want the
full argument. The Python-versus-prose point is kept but slimmed of
incidental color ("implementation differences in early EIPs are part of
the lore") that didn't add to the reframed narrative.

* docs(specs): unwrap hard-wrapped paragraphs in docs/specs/

Consecutive prose lines and list-item continuations are collapsed onto a
single line per paragraph / list item. Fenced code blocks, tables, HTML
blocks, headings, admonition markers, blockquotes, and link reference
definitions are preserved verbatim.

Matches the single-line-per-paragraph style already applied to the
opening paragraph of `docs/specs/index.md`, and makes the files easier
to diff on prose edits.

* docs(contributing): unwrap hard-wrapped paragraphs in CONTRIBUTING.md

Matches the single-line-per-paragraph style now used across
`docs/specs/*.md`, for cleaner future prose diffs. The blockquote
content under the `[!IMPORTANT]` alert is also collapsed to a single
line after the marker.

* docs(contributing): point Getting Set Up at the README Quick Start

`CONTRIBUTING.md` no longer embeds its own abbreviated install commands;
it points at the [Quick Start](README.md#quick-start) for the short
version and at the Installation guide for full setup. Avoids a third
copy of the install commands drifting out of sync.

`copy_repo_docs_to_mkdocs.py` rewrites `README.md#quick-start` to
`installation.md#quick-start` when copying `CONTRIBUTING.md` into the
mkdocs site, since the rendered site has no `README.md`.

* docs(readme): unwrap paragraphs and use `just` recipes for docs builds

Paragraphs are collapsed to a single line each, matching the style now
used across `docs/specs/*.md` and `CONTRIBUTING.md` for cleaner future
prose diffs.

`mkdocs serve` is replaced with `just docs-serve-fast` so the README
drives users through the repo's task runner rather than a raw `uv run`
invocation; the `just docs-spec` call gets its own code block for
symmetry. Both fences use the `console` language now that they are
pure shell commands.

* chore(docs): improve readme

* chore(docs): 3.12 as default; 3.13 doesn't have coincurve wheels

* chore(docs): improve contributing

* chore(docs): update production client list in readme

---------

Co-authored-by: Guruprasad Kamath <guru241987@gmail.com>

Author: danceratopz

CONTRIBUTING.md

@@ -1,312 +1,46 @@
 # Contribution Guidelines
 
-Help is always welcome and there are plenty of options to contribute to the Ethereum Execution Layer Specifications (EELS).
+Help is always welcome. The Ethereum Execution Layer Specifications (EELS) are a community effort and we appreciate support in the following areas:
 
-In particular, we appreciate support in the following areas:
-
-- Reporting issues
-- Fixing and responding to [issues](https://github.com/ethereum/execution-specs/issues), especially those tagged as [E-easy](https://github.com/ethereum/execution-specs/labels/E-easy) which are meant as introductory issues for external contributors.
+- Reporting issues.
+- Fixing and responding to [issues](https://github.com/ethereum/execution-specs/issues), especially those tagged [E-easy](https://github.com/ethereum/execution-specs/labels/E-easy), which are intended as introductory issues for external contributors.
 - Improving the documentation.
 
 > [!IMPORTANT]
-> Generally, we do not assign issues to external contributors. If you want to work on an issue, you are very welcome to go ahead and make a pull request. We would, however, be happy to answer questions you may have before you start implementing.
-
-For details about EELS usage and building, please refer to the [README](https://github.com/ethereum/execution-specs/blob/master/README.md#usage)
-
-## Contribution Guidelines
-
-This specification aims to be:
-
-1. **Correct** - Describe the _intended_ behavior of the Ethereum blockchain, and any deviation from that is a bug.
-2. **Complete** - Capture the entirety of _consensus critical_ parts of Ethereum.
-3. **Accessible** - Prioritize readability, clarity, and plain language over performance and brevity.
-
-### Style
-
-#### Spelling and Naming
-
-- Attempt to use descriptive English words (or _very common_ abbreviations) in documentation and identifiers.
-- Avoid using EIP numbers in identifiers, and prefer descriptive text instead (eg. `FeeMarketTransaction` instead of `Eip1559Transaction`).
-- If necessary, there is a custom dictionary `whitelist.txt`.
-- Avoid uninformative prefixes in identifiers (like `get_` or `compute_`). They don't add useful meaning and take up valuable real estate.
-
-#### Comments
-
-- Don't repeat what is obvious from the code.
-- <details>
-    <summary><em>(expand)</em> Consider how future changes will interleave with yours, especially when creating semantic blocks.</summary>
-
-    <br>Consider:
-    <table valign="top">
-
-    <tr valign="top">
-    <th>Fork T</th>
-    <th>Fork T+1</th>
-    </tr>
-
-    <tr valign="top">
-
-    <td>
-
-    <!--
-        Note that the trailing whitespace is necessary to move the copy button
-        in the github UI over so it doesn't obscure the text.
-    -->
-
-    ```python
-    # EIP-1234: The dingus is the rate of fleep      
-    dingus = a + b
-    dingus += c ^ d
-    dingus /= fleep(e)
-    ```
-
-    </td>
-
-    <td>
-
-    ```python
-    # EIP-1234: The dingus is the rate of fleep      
-    dingus = a + b
-
-    # EIP-4567: Frobulate the dingus
-    dingus = frobulate(dingus)
-
-    dingus += c ^ d        # <-
-    dingus /= fleep(e)     # <-
-    ```
-
-    </td>
-
-    </tr>
-
-    </table>
-
-    The marked lines (`<-`) are now incorrectly attributed to EIP-4567 in Fork+1. Instead, omit the EIP identifier in the comments, and describe the changes introduced by the EIP in the function's docstrings. The rendered diffs will make it pretty obvious what's changed.
-  </details>
-
-#### Docstrings
-
-- Write in complete sentences, providing necessary background and context for the associated code.
-- Function and method docstrings must use the imperative mood in the summary line.
-    - **Good:** Build the house using the provided lumber.
-    - **Bad:** Builds the house using the provided lumber.
-- Always start with a single-line summary. When more detail is needed, use a multi-line docstring with a blank line after the summary line.
-    - **One-line summary:**
-
-      ```python
-      """Return the pathname of the KOS root directory."""
-      ```
-
-    - **Multi-line:**
-
-      ```python
-      """
-      Add a bloom entry to the bloom filter.
-
-      The number of hash functions used is 3. They are calculated by
-      taking the least significant 11 bits from the first 3 16-bit
-      words of the `keccak_256()` hash of `bloom_entry`.
-      """
-      ```
-
-- Format using markdown.
-- Links to relevant standards and EIPs may be specified using reference-style links.
-
-  ```python
-  """
-  Minimum gas cost per byte of calldata as per [EIP-7976].
-
-  [EIP-7976]: https://eips.ethereum.org/EIPS/eip-7976
-  """
-  ```
-
-- Avoid beginning docstrings with an article ("the"/"a") or a pronoun ("it", "they", etc.).
-- Don't include the function's signature.
-
-##### Constants
-
-- Do not include constant values in docstrings, neither as literals nor as expressions. It's too easy to change a constant's value and forget to update its docstring.
-- Construct the constant's value from other constants or meaningful expressions in order to provide meaningful context.
-    - **Great:** `TARGET_BLOB_GAS_PER_BLOCK = GAS_PER_BLOB * BLOB_SCHEDULE_TARGET`
-        - Composed from named constants; the reader immediately understands what the value represents.
-    - **Acceptable:** `TX_MAX_GAS = Uint(2 ** 24)`
-        - More readable than a raw number, but still a literal expression that doesn't convey _why_ this value was chosen.
-    - **Bad:** `TX_MAX_GAS = Uint(16_777_216)`
-        - A magic number with no context.
-
-### Changes across various Forks
-
-Many contributions require changes across multiple forks, organized under `src/ethereum/forks/*`. When making such changes, please ensure that differences between the forks are minimal and consist only of necessary differences. This will help with getting cleaner [diff outputs](https://ethereum.github.io/execution-specs/diffs/index.html).
-
-When creating pull requests affecting multiple forks, we recommended submitting your PR in two steps:
-
-1. Apply the changes on a single fork, open a _draft_ pull request, and get feedback; then
-2. Apply the changes across the other forks, push them, and mark the pull request as ready for review.
-
-This saves you having to apply code review feedback repeatedly for each fork.
-
-### Development
-
-Running the tests necessary to merge into the repository requires:
-
-- [`uv`](https://docs.astral.sh/uv/) package manager,
-- [`just`](https://just.systems/) command runner (install via your package manager, [`uv tool install just-bin`](https://pypi.org/project/just-bin/), or [pre-built binaries](https://just.systems/man/en/pre-built-binaries.html)),
-- Python 3.11.x,
-- [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later.
-- `geth` installed and present in `$PATH`.
-
-`execution-specs` depends on a submodule that contains common tests that are run across all clients, so we need to clone the repo with the --recursive flag. Example:
-
-```bash
-git clone --recursive https://github.com/ethereum/execution-specs.git
-```
-
-Or, if you've already cloned the repository, you can fetch the submodules with:
-
-```bash
-git submodule update --init --recursive
-```
-
-The static checks can be run with:
-
-```bash
-just static
-```
-
-Individual checks and auto-fix are also available as recipes:
-
-```bash
-just fix           # Auto-fix formatting and lint issues.
-just lint          # Lint with ruff.
-just format-check  # Check formatting with ruff.
-just typecheck     # Run type checking with mypy.
-just spellcheck    # Check spelling with codespell.
-```
-
-Run `just` to see all available recipes. Recipes that accept arguments can be passed extra flags, for example:
-
-```bash
-just typecheck --warn-unreachable
-```
-
-> [!TIP]
-> If you use multiple git worktrees, set `MYPY_CACHE_DIR` to share a single
-> mypy cache across all of them and avoid cold-start delays:
->
-> ```bash
-> export MYPY_CACHE_DIR=~/path/to/execution-specs/.mypy_cache
-> ```
-
-### Shell Auto-Completion
-
-`just` provides tab-completion for recipe names and arguments. To enable it for your shell:
-
-**Bash** — add to `~/.bashrc`:
-
-```bash
-eval "$(just --completions bash)"
-```
-
-**Zsh** — add to `~/.zshrc`:
-
-```bash
-eval "$(just --completions zsh)"
-```
-
-**Fish** — run once (fish auto-loads completions from this directory):
-
-```bash
-just --completions fish > ~/.config/fish/completions/just.fish
-```
-
-After restarting your shell (or sourcing the config), `just <Tab>` will complete recipe names.
-
-A trace of the EVM execution for any test case can be obtained by providing the `--evm-trace` argument to pytest.
-Note: Make sure to run the EVM trace on a small number of tests at a time. The log might otherwise get very big.
-Below is an example.
-
-```bash
-uv run pytest \
-    'tests/json_loader/test_state_tests.py::test_state_tests_frontier[stAttackTest - ContractCreationSpam - 0]' \
-    --evm_trace
-```
-
-## CLI Utilities `ethereum_spec_tools`
-
-The EELS repository has various CLI utilities that can help in the development process.
-
-### New Fork Tool
-
-This tool can be used to create the base code for a new fork by using the existing code from a given fork.
-
-The command takes 4 arguments, 2 of which are optional
-
-- from_fork: The fork name from which the code is to be duplicated. Eg. - "Tangerine Whistle"
-- to_fork: The fork name of the new fork Eg - "Spurious Dragon"
-- from_test (Optional): Name of the from fork within the test fixtures in case it is different from fork name. Eg. - "EIP150"
-- to_test (Optional): Name of the to fork within the test fixtures in case it is different from fork name Eg - "EIP158"
-
-As an example, if one wants to create baseline code for the `Spurious Dragon` fork from the `Tangerine Whistle` one
-
-```bash
-uv run ethereum-spec-new-fork --from_fork="Tangerine Whistle" --to_fork="Spurious Dragon" --from_test=EIP150 --to_test=EIP158
-```
-
-The following will have to however, be updated manually
-
-1. The fork number and `MAINNET_FORK_BLOCK` in `__init__.py`. If you are proposing a new EIP, please set `MAINNET_FORK_BLOCK` to `None`.
-2. Any absolute package imports from other forks eg. in `trie.py`
-3. Package names under `setup.cfg`
-4. Add the new fork to the `monkey_patch()` function in `src/ethereum_optimized/__init__.py`
-5. Adjust the underline in `fork/__init__.py`
+> Generally, we do not assign issues to external contributors. If you want to work on an issue, you are welcome to go ahead and make a pull request. We are happy to answer questions before you start implementing.
 
-### Sync Tool
+## Contributions we don't accept
 
-The sync tool allows one to use an RPC provider to fetch and validate blocks against EELS.
-The state can also be stored in a local DB after validation. Since syncing directly with the specs can be
-very slow, one can also leverage the optimized module. This contains alternative implementations of routines
-in EELS that have been optimized for speed rather than clarity/readability.
+Pull requests should have reasonable substance and context. In particular, we do not accept:
 
-The tool can be called using the `ethereum-spec-sync` command which takes the following arguments
+- Contributions that only fix spelling or grammatical errors in documentation, code, or elsewhere.
+- Drive-by or vibe-coded contributions without proper engagement or context.
 
-- rpc-url: Endpoint providing the Ethereum RPC API. Defaults to `http://localhost:8545/`
-- unoptimized: Don't use the optimized state/ethash (this can be extremely slow)
-- persist: Store the state in a db in this file
-- geth: Use geth specific RPC endpoints while fetching blocks
-- reset: Delete the db and start from scratch
-- gas-per-commit: Commit to db each time this much gas is consumed. Defaults to 1_000_000_000
-- initial-state: Start from the state in this db, rather than genesis
-- stop-at: After syncing this block, exit successfully
+## Code of Conduct
 
-- The following options are not supported WITH `--unoptimized` -> `--persist`, `--initial-state`, `--reset`
-- The following options are not supported WITHOUT `--persist` -> `--initial_state`, `--reset`
+All contributors are expected to be excellent to each other; other behavior is not tolerated. To report a concern, contact one of the [STEEL team members](https://steel.ethereum.foundation/team/).
 
-### Patch Tool
+## Principles
 
-This tool can be used to apply the unstaged changes in `SOURCE_FORK` to each of the `TARGET_FORKS`. If some
-of the change didn't apply, '.rej' files listing the unapplied changes will be left in the `TARGET_FORK`.
+The specification aims to be:
 
-The tool takes the following command line arguments
+1. **Correct.** Describe the *intended* behavior of the Ethereum blockchain. Any deviation from that is a bug.
+2. **Complete.** Capture the entirety of *consensus-critical* parts of Ethereum.
+3. **Accessible.** Prioritize readability, clarity, and plain language over performance and brevity.
 
-- The fork name where the changes have been made. Eg:- `frontier` (only a single fork name)
-- The fork names where the changes have to be applied. Eg:- `homestead` (multiple values can be provided separated by space)
-- optimized: Patch the optimized code instead
-- tests: Patch the tests instead
+## Getting set up
 
-As an example, if one wants to apply changes made in `Frontier` fork to `Homestead` and `Tangerine Whistle`
+Environment setup (cloning the repository, installing `uv` and `just`, Python requirements) is documented in the [Installation guide](docs/getting_started/installation.md).
 
-```bash
-uv run python src/ethereum_spec_tools/patch_tool.py frontier homestead tangerine_whistle
-```
+Before opening a PR, run the checks relevant to your change; see [Verifying Changes](docs/getting_started/verifying_changes.md).
 
-### Lint Tool
+## Changes that affect multiple forks
 
-This tool checks for style and formatting issues specific to EELS and emits diagnostics
-when issues are found
+When creating pull requests that touch several forks under `src/ethereum/forks/`, we recommend a two-step workflow:
 
-The tool currently performs the following checks
+1. Apply the changes on a single fork, open a *draft* PR, and get feedback.
+2. Apply the changes across the other forks, push them, and mark the PR as ready for review.
 
-- The order of the identifiers between each hardfork is consistent.
-- Import statements follow the relevant import rules in modules.
+This saves you from applying code review feedback repeatedly for each fork.
 
-The command to run the tool is `just lint-spec` (or `uv run ethereum-spec-lint`).
+See [Writing Specs](docs/specs/writing_specs.md) for the technical style rules (naming, comments, docstrings, constants, cross-fork discipline) and for the `ethereum_spec_tools` CLI utilities that help with these workflows.