# 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.