docs: separate mdBook sources and output

.gitignore

@@ -4,5 +4,8 @@
 # macOS
 .DS_Store
 
+# Generated by mdBook
+/docs/book/
+
 # Generated by `oranda generate ci`
-public/
+public/

AGENTS.md

@@ -14,8 +14,9 @@ Edit documentation sources under `docs/src/` and navigation in `docs/src/SUMMARY
 - `cargo test` runs unit, integration, and documentation tests.
 - `cargo fmt --all -- --check` checks formatting; `cargo fmt --all` applies it.
 - `cargo clippy --all-targets --all-features -- -D warnings` runs strict linting.
+- `mdbook build docs` is the canonical documentation build; `mdbook test docs` tests its Rust examples.
 
-Known legacy formatting, doctest, and Clippy failures are tracked in `TODO.md`. Do not introduce new failures; roadmap issues will establish clean required baselines.
+All established formatting, compilation, test, and lint checks must pass before review.
 
 ## Coding Style & Testing
 

CONTRIBUTING.md

@@ -35,6 +35,7 @@ Pull requests are squash-merged only. Do not use merge commits or rebase merges.
 ### Prerequisites
 - [Rust](https://www.rust-lang.org/tools/install) (Edition 2024 or later)
 - [Cargo](https://doc.rust-lang.org/cargo/)
+- [mdBook 0.5.2](https://rust-lang.github.io/mdBook/guide/installation.html): `cargo install mdbook --locked --version 0.5.2`
 
 ### Workflow
 1. **Clone your fork**:
@@ -51,8 +52,13 @@ Pull requests are squash-merged only. Do not use merge commits or rebase merges.
    ```bash
    cargo test
    ```
+4. **Build and Test Documentation**:
+   ```bash
+   mdbook build docs
+   mdbook test docs
+   ```
 
-Before review, also run `cargo fmt --all -- --check` and `cargo clippy --all-targets --all-features -- -D warnings`. Known legacy failures are recorded in `TODO.md`; do not add new failures while cleanup issues are open.
+`mdbook build docs` is the canonical documentation build command. Before review, run all applicable commands above plus `cargo fmt --all -- --check` and `cargo clippy --all-targets --all-features -- -D warnings`; all established checks must pass.
 
 ## Architectural Overview
 

TODO.md

@@ -4,14 +4,15 @@ This document is the issue source for PooLang's clean-break transition from the
 
 ## Current Audit
 
-Snapshot: 2026-07-28.
+Snapshot: 2026-07-29.
 
 ### What works
 
 - `cargo fmt --all -- --check` passes and is enforced for pull requests.
 - `cargo check --all-targets` passes.
 - `cargo test` passes and is enforced for pull requests, including all 48 integration specifications and the library doctest.
 - `cargo clippy --all-targets --all-features -- -D warnings` passes and is enforced for pull requests.
+- `mdbook build docs` reproducibly generates ignored documentation output from `docs/src/`.
 - The crate exposes checked file/source execution APIs and typed I/O, parse, and runtime error categories.
 - Lexer, parser, interpreter, type-inference, examples, mdBook documentation, and cargo-dist release assets exist.
 
@@ -30,7 +31,6 @@ Snapshot: 2026-07-28.
 - Function examples omit required parameter types or use return/type spelling that differs from the parser.
 - `trait` is tokenized but not supported as a complete tested language feature.
 - Examples contain multiple syntax generations and unverified standard-library methods.
-- `docs/book/` contains 42 tracked generated files and can drift from `docs/src/`.
 - README development/release claims do not fully match current checks and workflows.
 
 ### Missing platform capabilities
@@ -74,7 +74,7 @@ Snapshot: 2026-07-28.
 - [x] Resolve strict Clippy findings in the interpreter without lint suppressions or behavior changes.
 - [x] Resolve the remaining strict Clippy findings in the lexer, parser, type inference, and symbol table.
 - [x] Require `cargo clippy --all-targets --all-features -- -D warnings` in pull-request CI.
-- [ ] Separate generated mdBook output from sources and define one reproducible documentation build command.
+- [x] Separate generated mdBook output from sources and define one reproducible documentation build command.
 - [ ] Reconcile README commands, branch names, CI claims, supported features, and examples with executable behavior.
 - [ ] Add focused lexer/parser error tests for malformed strings, comments, UTF-8 input, and unexpected EOF.
 - [ ] Audit release workflow actions, permissions, secrets, installers, and generated cargo-dist configuration.