#16248·foundry

meta(docs): clean up developer documentation

Author: figtracerCreated Aug 19, 2026Updated Aug 30, 2026
LabelsA-docsT-metaA-internals

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 https://github.com/foundry-rs/foundry/issues/13880#issuecomment-4161052129, 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 #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.