docs(skills): add contents lists to long references, restore rotation ordering

Anthropic's guidance: reference files over 100 lines should open with a
table of contents, because Claude often previews a file with head and would
otherwise never see the full scope. All 119 long reference files lacked one.

scripts/add_reference_toc.py generates the list from each file's own H2
headings and inserts it below the title and When-to-read callout. It skips
fenced code (# is a comment there), skips files that already have Contents,
and is idempotent, so it can run again after new references are written.

Also restores one durable idea lost when cli-audit-credential was removed in
7208d9b. That deletion was justified (machine-level scope, LLM reading real
keys), and the file-permission and git-history checks were absorbed into
cli-audit-code C9, but the create -> deploy -> verify -> revoke ordering was
not. It is the part that prevents a rotation outage and does not depend on
any provider console, so it now lives in the cli-forge-infra entropy
checklist next to the rotation item that referenced a procedure.

Author: Destynova2

cli-audit-code/reference.md

@@ -1,5 +1,13 @@
 # Clean Code Reference — Full Principles Catalog
 
+## Contents
+
+- Sources
+- Principles Not in the wojteklu Gist
+- Rust-Specific Clean Code Idioms
+
+---
+
 ## Sources
 
 This reference synthesizes principles from multiple authorities, not just Robert C. Martin.

cli-audit-code/references/categories.md

@@ -4,6 +4,23 @@
 
 ---
 
+## Contents
+
+- C1: NAMING & READABILITY (8%)
+- C2: FUNCTIONS & COGNITIVE COMPLEXITY (12%)
+- C3: MODULE DESIGN — DEEP VS SHALLOW (10%)
+- C4: DRY & CHANGE AMPLIFICATION (8%)
+- C5: ERROR HANDLING & ROBUSTNESS (10%)
+- C6: TYPE SAFETY & LANGUAGE IDIOMS (8%)
+- C7: COMMENTS & PUBLIC API DOCS (5%)
+- C8: TEST QUALITY (12%)
+- C9: SECURITY & INPUT VALIDATION (10%)
+- C10: IMMUTABILITY & STATE MANAGEMENT (7%)
+- C11: COGNITIVE LOAD & CONTROL FLOW (5%)
+- C12: DEPENDENCIES & ARCHITECTURE (5%)
+
+---
+
 ## C1: NAMING & READABILITY (8%)
 
 **Source:** Robert C. Martin (Clean Code), Google Style Guides, Microsoft Rust Guidelines (M-CONCISE-NAMES)

cli-audit-code/references/scoring.md

@@ -4,6 +4,19 @@
 
 ---
 
+## Contents
+
+- CQI Formula
+- Scoring Guide
+- Category Weights
+- CQI Thresholds
+- Derived Metrics
+- Anti-Patterns (Named, from Fowler/Mantyla + extended taxonomy)
+- Comparative Benchmarks
+- Sources
+
+---
+
 ## CQI Formula
 
 ```

cli-audit-data/references/order-reservation-review.md

@@ -1,5 +1,24 @@
 # Worked example — réservation de la dernière unité d'un produit
 
+## Contents
+
+- 1. Verdict
+- 2. Décision de base de données
+- 3. Sources de vérité
+- 4. Invariants
+- 5. Conservation
+- 6. Machine à états
+- 7. Interleaving dangereux
+- 8. Frontière transactionnelle
+- 9. SQLx
+- 10. Migration
+- 11. Tests
+- 12. Homéostasie
+- 13. Pré-mortem
+- 14. Points non prouvés
+
+---
+
 Cet exemple montre le niveau de raisonnement attendu. Il ne remplace pas l'analyse du projet réel.
 
 ## 1. Verdict

cli-audit-data/references/review-templates.md

@@ -1,5 +1,19 @@
 # Data safety review templates / Canevas de travail
 
+## Contents
+
+- A. Décision de conception
+- B. Matrice d'invariants
+- C. Interleaving
+- D. Machine à états
+- E. Compatibilité de migration
+- F. Pré-mortem
+- G. Revue de code
+- H. Homéostasie
+- I. Rapport final
+
+---
+
 ## A. Décision de conception
 
 ```markdown

cli-audit-doc/reference.md

@@ -1,5 +1,17 @@
 # Documentation Audit Reference — Standards & Language Conventions
 
+## Contents
+
+- Sources
+- Universal Rules (All Languages)
+- Language-Specific Conventions
+- Documentation Completeness Index (DCI)
+- Coverage Tiers
+- Confidence Protocol
+- Anti-Patterns Checklist
+
+---
+
 ## Sources
 
 ### Standards

cli-audit-doc/references/categories.md

@@ -4,6 +4,23 @@
 
 ---
 
+## Contents
+
+- C1: DIATAXIS COVERAGE (10%)
+- C2: COMPLETENESS (12%)
+- C3: FRESHNESS & ACCURACY (10%)
+- C4: READABILITY & PROSE QUALITY (10%)
+- C5: STRUCTURE & FINDABILITY (8%)
+- C6: STANDARD SECTIONS (8%)
+- C7: CODE EXAMPLES (10%)
+- C8: ACCESSIBILITY & INCLUSIVITY (6%)
+- C9: INLINE COMMENTS QUALITY (8%)
+- C10: CROSS-REFERENCES & LINKING (5%)
+- C11: TESTING & CI (8%)
+- C12: MAINTENANCE PROCESS (5%)
+
+---
+
 ## C1: DIATAXIS COVERAGE (10%)
 
 **Source:** Daniele Procida (Diataxis framework)

cli-audit-doc/references/scoring.md

@@ -4,6 +4,18 @@
 
 ---
 
+## Contents
+
+- DQI Formula
+- Scoring Guide
+- Category Weights
+- DQI Thresholds
+- Derived Metrics
+- Anti-Patterns
+- Sources
+
+---
+
 ## DQI Formula
 
 ```

cli-audit-drift/references/contracts-template.md

@@ -4,6 +4,16 @@
 
 ---
 
+## Contents
+
+- File header
+- Contract block template
+- Common invariant templates
+- Contract sizing guide
+- Example: complete contract
+
+---
+
 ## File header
 
 ```markdown

cli-audit-drift/references/drift-detection-rules.md

@@ -4,6 +4,15 @@
 
 ---
 
+## Contents
+
+- Detection workflow per function
+- Classification decision tree
+- Severity scoring
+- Common drift patterns by domain
+
+---
+
 ## Detection workflow per function
 
 For each contracted function, execute these checks in order: