Install Rust style doctrine

1 files changed, 22 insertions, 6 deletions

diff --git a/docs/bootstrap-fresh.md b/docs/bootstrap-fresh.md
index 89bf757..b0dd3f8 100644
--- a/docs/bootstrap-fresh.md
+++ b/docs/bootstrap-fresh.md
@@ -6,6 +6,7 @@ Use this surface when the target repo is blank or when you are setting up Rust l
 
 Install the `rust-starter` lint posture cleanly:
 
+- target `AGENTS.md` links to the canonical Rust style doctrine
 - root `Cargo.toml` owns lint levels
 - every crate inherits workspace lint policy
 - `rust-toolchain.toml` is pinned exactly
@@ -25,11 +26,14 @@ Before copying the template, decide:
 - 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
+- how to merge the Rust style doctrine link into any existing target `AGENTS.md` guidance
 
 ## Files To Start From
 
 Use these as the concrete baseline:
 
+- [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md)
+- [template/fresh/AGENTS.md](/home/main/programming/projects/rust_starter/template/fresh/AGENTS.md)
 - [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)
@@ -41,7 +45,18 @@ Do not copy them mechanically. Replace the placeholder members, names, license,
 
 ## Sequence
 
-### 1. Write the root manifest first
+### 1. Seed `AGENTS.md` first
+
+Create or adapt the target repo's `AGENTS.md` so it links to
+[docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md).
+Use [template/fresh/AGENTS.md](/home/main/programming/projects/rust_starter/template/fresh/AGENTS.md)
+as the starting point for a blank repo. If the target already has instructions,
+merge the link without erasing local rules.
+
+The point is inheritance: future agents entering the repo must encounter the
+Rust style doctrine without knowing this bootstrap skill exists.
+
+### 2. Write the root manifest
 
 Start from the template root manifest and adapt:
 
@@ -56,11 +71,11 @@ The fresh template exports an ordered `canonicalize_commands` pipeline. Keep it
 
 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
+### 3. Pin the toolchain
 
 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
+### 4. Make every crate inherit lint policy
 
 Each member crate must contain:
 
@@ -71,13 +86,13 @@ workspace = true
 
 Do not rely on memory or convention here; add it explicitly.
 
-### 4. Add `clippy.toml` only if it carries real configuration
+### 5. 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
+### 6. 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.
 
@@ -95,7 +110,7 @@ If the target repo already prefers another orchestration surface, keep that surf
 
 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
+### 7. Keep the deep gate opt-in
 
 The template only installs the fast gate. Add the deeper posture when the repo is mature enough:
 
@@ -116,6 +131,7 @@ The template only installs the fast gate. Add the deeper posture when the repo i
 ## Acceptance Checklist
 
 - root `Cargo.toml` contains `[workspace.lints.rust]`, `[workspace.lints.rustdoc]`, and `[workspace.lints.clippy]`
+- target `AGENTS.md` links to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md)
 - root `Cargo.toml` owns warning-fatality policy, e.g. `warnings = "deny"` under `[workspace.lints.rust]`, rather than hiding it in runner flags
 - 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]`