1 files changed, 128 insertions, 0 deletions
diff --git a/docs/bootstrap-fresh.md b/docs/bootstrap-fresh.md
new file mode 100644
index 0000000..f77b819
--- /dev/null
+++ b/docs/bootstrap-fresh.md
@@ -0,0 +1,128 @@
+# Fresh Bootstrap
+
+Use this surface when the target repo is blank or when you are setting up Rust linting from scratch.
+
+## Goal
+
+Install the `rust-starter` lint posture cleanly:
+
+- root `Cargo.toml` owns lint levels
+- every crate inherits workspace lint policy
+- `rust-toolchain.toml` is pinned exactly
+- `clippy.toml` stays tiny and only carries structured config
+- the runner stays thin and reads canonicalization and verification command vectors plus the source-file cap from workspace metadata instead of restating policy
+
+## Inputs To Set Deliberately
+
+Before copying the template, decide:
+
+- actual workspace members
+- package naming
+- license policy
+- exact pinned stable toolchain
+- actual MSRV / `rust-version`
+- whether tests should allow `expect`, `unwrap`, or `panic`
+- whether the repo is library-heavy enough to keep rustdoc linting in the fast gate or only the deep gate
+- whether unsafe Rust is forbidden or tightly-governed
+- whether the default `2500`-line source-file cap should stay as-is or be tightened for this repo
+
+## Files To Start From
+
+Use these as the concrete baseline:
+
+- [template/fresh/Cargo.toml](/home/main/programming/projects/rust_starter/template/fresh/Cargo.toml)
+- [template/fresh/rust-toolchain.toml](/home/main/programming/projects/rust_starter/template/fresh/rust-toolchain.toml)
+- [template/fresh/clippy.toml](/home/main/programming/projects/rust_starter/template/fresh/clippy.toml)
+- [template/fresh/check.py](/home/main/programming/projects/rust_starter/template/fresh/check.py)
+- [template/fresh/crates/app/Cargo.toml](/home/main/programming/projects/rust_starter/template/fresh/crates/app/Cargo.toml)
+- [template/fresh/crates/app/src/main.rs](/home/main/programming/projects/rust_starter/template/fresh/crates/app/src/main.rs)
+
+Do not copy them mechanically. Replace the placeholder members, names, license, and version/toolchain values.
+
+## Sequence
+
+### 1. Write the root manifest first
+
+Start from the template root manifest and adapt:
+
+- workspace member list
+- package metadata
+- pinned `rust-version`
+- repo-wide Clippy carve-outs
+
+Keep the command vectors in `[workspace.metadata.rust-starter]` even if you later wrap them with a different local runner.
+
+The fresh template exports an ordered `canonicalize_commands` pipeline. Keep it repo-owned in the root manifest and make the default `check` path run it automatically before the verification gate so humans and agents do not need to remember a separate pre-pass.
+
+Also keep the source-file cap in `[workspace.metadata.rust-starter.source_files]`. The starter default is a hard `2500`-line limit across `*.rs` files. Tighten it if the repo already has sharper discipline.
+
+### 2. Pin the toolchain second
+
+Write `rust-toolchain.toml` early, before deciding whether a lint is noisy or broken. Lint output is part of the toolchain contract.
+
+### 3. Make every crate inherit lint policy
+
+Each member crate must contain:
+
+```toml
+[lints]
+workspace = true
+```
+
+Do not rely on memory or convention here; add it explicitly.
+
+### 4. Add `clippy.toml` only if it carries real configuration
+
+The default template only relaxes `expect`, `unwrap`, and `panic` inside tests. If the target repo does not want that, delete the file instead of leaving inert config behind.
+
+Do not move global allow/deny policy into `clippy.toml`.
+
+### 5. Add a thin runner
+
+The template `check.py` is intentionally small. It reads canonicalization and verification commands plus the source-file policy from workspace metadata, enforces the file cap, and then runs the Rust commands.
+
+Default runner shape:
+
+- `check`: enforce the file cap, run canonicalization, then verify formatting, lint, and tests
+- `verify`: enforce the file cap without mutating files; this is the non-writing CI-friendly path
+- `deep`: `check` plus docs
+- `fix` / `canon`: canonicalization only
+
+If the target repo already prefers another orchestration surface, keep that surface only if it remains policy-thin:
+
+- okay: `xtask`, `just`, shell wrapper, CI job that calls the canonical commands
+- not okay: restating dozens of `-A` and `-D` flags in scripts
+
+If the repo has checked-in generated Rust that should not count against the cap, express that with explicit `exclude` patterns under `[workspace.metadata.rust-starter.source_files]` instead of weakening the global limit.
+
+### 6. Keep the deep gate opt-in
+
+The template only installs the fast gate. Add the deeper posture when the repo is mature enough:
+
+- `cargo hack clippy --workspace --all-targets --feature-powerset`
+- `cargo hack test --workspace --feature-powerset`
+- `cargo doc --workspace --all-features --no-deps`
+- `cargo deny check`
+- optionally `cargo nextest` and `cargo semver-checks`
+
+## Do Not Do These
+
+- do not use `--no-deps` as the workspace-wide Clippy default
+- do not enable `clippy::restriction` wholesale
+- do not enable `clippy::nursery` wholesale
+- do not duplicate lint policy in scripts, CI, and editor config
+- do not leave placeholder toolchain or MSRV values unreviewed
+
+## Acceptance Checklist
+
+- root `Cargo.toml` contains `[workspace.lints.rust]`, `[workspace.lints.rustdoc]`, and `[workspace.lints.clippy]`
+- root `Cargo.toml` contains canonical command vectors in `[workspace.metadata.rust-starter]`
+- root `Cargo.toml` contains an ordered `canonicalize_commands` pipeline in `[workspace.metadata.rust-starter]`
+- root `Cargo.toml` contains `[workspace.metadata.rust-starter.source_files]` with an intentional `max_lines` value
+- each member crate opts into `[lints] workspace = true`
+- `rust-toolchain.toml` pins an exact stable patch and includes `clippy` plus `rustfmt`
+- `clippy.toml` is either tiny and justified or absent
+- the default `check` path canonicalizes before verification, and a non-mutating `verify` path exists for CI or drift detection
+- no runner or CI file duplicates the Clippy allowlist
+
+Read [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md) only when you need rationale or policy nuance.