Install Rust style doctrine

1 files changed, 21 insertions, 8 deletions

diff --git a/docs/bootstrap-retrofit.md b/docs/bootstrap-retrofit.md
index a2910ce..5c337e6 100644
--- a/docs/bootstrap-retrofit.md
+++ b/docs/bootstrap-retrofit.md
@@ -6,6 +6,7 @@ Use this surface when the target repo already has Rust linting, but you want to
 
 Migrate the repo toward the `rust-starter` posture while staying diff-aware:
 
+- install the canonical Rust style doctrine link in target `AGENTS.md`
 - preserve stricter existing rules
 - preserve justified local carve-outs
 - delete duplicated policy only after it has been re-homed into the manifest
@@ -17,6 +18,7 @@ Migrate the repo toward the `rust-starter` posture while staying diff-aware:
 Before editing, inspect all of the places the repo may already encode lint policy:
 
 - root and member `Cargo.toml`
+- `AGENTS.md` and any nested agent instruction files
 - `check.py`, `xtask`, shell wrappers, `justfile`, or other runners
 - CI workflow files
 - any existing auto-fix or canonicalization commands
@@ -36,6 +38,7 @@ Use these as the baseline, not as paste targets:
 
 - [template/fresh](/home/main/programming/projects/rust_starter/template/fresh)
 - [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md)
+- [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md)
 
 The fresh template tells you the shape to converge toward. The proposal doc tells you why.
 
@@ -80,45 +83,54 @@ Keep `clippy.toml` only for structured knobs such as test allowances.
 
 Apply tightenings in this order:
 
-### 1. Pin or refresh the toolchain
+### 1. Install style inheritance
+
+Add or preserve a target `AGENTS.md` link to
+[docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md).
+Do not overwrite local agent instructions; merge the doctrine link into them.
+
+This is intentionally infectious. Future agents should read the Rust style
+doctrine by entering the target repo, not only by invoking this bootstrap skill.
+
+### 2. Pin or refresh the toolchain
 
 Add `rust-toolchain.toml` if missing. If present but floating, pin it.
 
-### 2. Install workspace lint tables
+### 3. Install workspace lint tables
 
 Move repo-wide policy into root `[workspace.lints.*]`.
 
-### 3. Make member crates inherit explicitly
+### 4. Make member crates inherit explicitly
 
 Add `[lints] workspace = true` to every member crate.
 
-### 4. Re-home script flags into the manifest
+### 5. Re-home script flags into the manifest
 
 Take inline `cargo clippy -- -A/-D ...` tails from scripts and CI, and migrate them into the root manifest in grouped, commented form.
 
 That includes `-D warnings`: if warnings are meant to be fatal, encode that as
 `warnings = "deny"` under `[workspace.lints.rust]` instead of leaving it as a command-line tail.
 
-### 5. Tighten local suppression discipline
+### 6. Tighten local suppression discipline
 
 Prefer:
 
 - `#[expect(..., reason = "...")]` for temporary or evidence-backed suppressions
 - `#[allow(..., reason = "...")]` only for stable local policy
 
-### 6. Simplify the runner
+### 7. Simplify the runner
 
 Once the manifest is authoritative, collapse the runner to orchestration-only plus generic manifest-backed checks such as the source-file cap.
 
 If the repo already has an auto-fix pass, re-home it into root `workspace.metadata.rust-starter.canonicalize_commands` and make the default local `check` path invoke it before the verification gate instead of relying on engineers or agents to remember a separate pre-pass.
 
-### 7. Install the source-file cap
+### 8. Install the source-file cap
 
 Add `[workspace.metadata.rust-starter.source_files]` to the root manifest and set `max_lines` deliberately.
 
 Default to `2500` if the repo has no existing stance. If the repo already enforces a stricter cap, keep the stricter value. If the repo has checked-in generated Rust that would make the rule meaningless, exclude those paths explicitly instead of disabling the whole mechanism.
 
-### 8. Add deep-gate posture if the repo is ready
+### 9. Add deep-gate posture if the repo is ready
 
 Add `cargo hack`, docs, and dependency-hygiene checks only when the repo can support them without turning the whole effort into churn theater.
 
@@ -148,6 +160,7 @@ If the repo wants CI to detect canonicalization drift rather than rewriting file
 ## Acceptance Checklist
 
 - repo-wide policy lives in root `[workspace.lints.*]`
+- target `AGENTS.md` links to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md)
 - every member crate inherits that policy explicitly
 - scripts and CI no longer restate Clippy allowlists
 - manifest-owned canonicalization exists where the repo wants auto-fixes, instead of living in shell aliases or tribal memory