meta(docs): clean up developer documentation

[figtracer]

context

the workspace changed quite a bit since #13880 was opened. wallets moved to foundry-core, solar and tui were added, and there are more crates under evm/. manually documenting every crate and its dependencies in one file will probably become outdated again pretty quickly.

as @zerosnacks mentioned in #13880 (comment), i think it is higher leverage to remove this page and improve the generated crate docs and the book incrementally.

there are a few other things to clean up at the same time:

• docs/dev/README.md is linked as the developer guidelines, but it still says that it is incomplete and possibly outdated;
• the index does not include existing pages like lintrules.md, output-channels.md, and showmap.md;
• it is not very clear what should live in docs/dev, Rustdoc, the book, CONTRIBUTING.md, or AGENTS.md;
• some instructions are duplicated between these places and can drift;
• crate-level Rustdoc exists for the whole workspace, but some crate landing pages still have very little context.

i think the split should roughly be:

• user-facing guides, config and CLI documentation belong in the book;
• crate/module internals and APIs belong in the source as Rustdoc and are published at https://foundry-rs.github.io/foundry/;
• cross-crate contributor workflows and invariants can stay in docs/dev or CONTRIBUTING.md;
• agent-specific instructions should stay in AGENTS.md, but link to the canonical docs instead of duplicating them;
• release-facing changes should use .changelog and the generated changelog/release notes.

work

• remove docs/dev/architecture.md and its entry from the developer docs index;
• clean up docs/dev/README.md and make it an accurate index of the contributor documentation we actually maintain;
• audit the existing docs/dev/*.md files and decide which ones should stay, be updated, move somewhere else, or be removed;
• link the developer docs to the book, generated Rustdoc, CONTRIBUTING.md, and the changelog instructions;
• reduce duplicated guidance between docs/dev, CONTRIBUTING.md, and AGENTS.md;
• improve crate-level Rustdoc overviews incrementally where they are missing useful context;
• open focused issues in foundry-rs/book for concrete user-facing gaps instead of tracking a general book rewrite here;
• close docs: architecture.md is outdated and missing coverage for most crates #13880 as superseded by this issue.

i don't think we should remove all of docs/dev. pages like cheatcodes.md, output-channels.md, and showmap.md are still actively maintained. the goal is mostly to remove the stale parts and make the ownership of the remaining docs clearer.

[haythemsellami]

From my experience working on Monad Foundry, I largely had to infer the intended architecture from previous Tempo and OP implementations, both in Foundry and while working on the corresponding Alloy and REVM extensions. Initially it was not clear where each responsibility should live (or it could be just me new to this whole stack 🤷🏽‍♂️ ).

The hardest part was building the the correct mental model across the Foundry<>Alloy<>Revm boundary. For example, it took time to understand the responsibilities of FoundryEvmNetwork, FoundryEvmFactory, the active NetworkConfigs, the Alloy EVM factory, and REVM’s context and journal types. One distinction that was particularly easy to miss is that having support for an EVM compiled into the binary is different from that network being selected at runtime. A clear guidance on these ownership boundaries would definitely have saved time and iterations.

Another source of blockers was the state lifecycle management: a custom EVM may have consensus relevant state outside of the ordinary account db, as in Monad things like the reserve-balance tracking. That state had to remain coherent across nested EVM execution, snapshots and revertToState, state-mutating cheatcodes, fork creation, vm.transact, anvil rollback...etc. There was several correctness issues only discovered during PR reviews and when auditing those operations individually. I guess a custom EVM integration guidelines should ask to inventory every piece of auxiliary state, define its lifetime, and explain how it is initialized, copied, committed, reverted...etc. Or if it is possible to have such checks automated through a reusable fixture or some conformance harness, that would be ideal.

At the end of the PR review we have few comments and blockers around the CI and cargo feature propagation, so having a standard CI template for custom execution environments would make this much easier.

The PR process itself was constructive and the reviews were very useful, but the integration eventually covered hundreds of files and thousands changed lines. At that scale, it was challenging both to review the whole system and to retain the reasoning behind every earlier change. LLMs definitely helps and in my case I would say it improved a lot the pace of work and helped me initially understand the codebase and navigate it and apply changes. Maybe that can be leveraged more by having a dedicated AGENTS.md file with how-to extend Foundry support for other VMs and overall more docs. Given that integration could remain disabled behind it's feature, the guideline can recommend a stacked-PR structure and maintainer can provide earlier feedback and faster feedback-loop.