docs: complete verification and retrospective

Check off all 7 plan verification items with results.
Write retrospective covering what went well (phased approach,
source verification, CHALLENGE decisions), surprises (sketch
false positives, extra Sukr instances, existing Tera link),
process observations (CORE granularity, cross-phase deps,
tech debt tracking), and intentional deferrals (G2, G5,
security.md mixed quadrants).

docs/plans/documentation-overhaul.md

@@ -92,13 +92,13 @@ None. All CHALLENGE questions resolved.
 
 ## Verification
 
-- [ ] `cargo test` passes (no source code changes, but hygiene check)
-- [ ] Docs site builds: `cd docs && sukr` (assumes `sukr` in PATH via `cargo install --path .`)
-- [ ] `grep -ri "Sukr" docs/ README.md` returns zero results (only lowercase "sukr")
-- [ ] Built docs site: homepage no longer claims `cargo install sukr`
-- [ ] Built docs site: getting-started tutorial has working templates and completion step
-- [ ] Built docs site: deployment page exists and renders
-- [ ] Built docs site: no broken internal links
+- [x] `cargo test` passes — 69/69 (no source code changes, hygiene check)
+- [x] Docs site builds: `cargo run -- -c docs/site.toml` succeeds, all pages rendered
+- [x] No uppercase `Sukr` in docs or README (all lowercase `sukr`)
+- [x] No `cargo install sukr` in docs content
+- [x] Getting-started tutorial has working templates (base.html, page.html, default.html) and completion step ("View your site")
+- [x] Deployment page exists and renders at `docs/public/deployment.html`
+- [x] No broken internal cross-reference links (all navigation links resolve; "broken" hits are example/illustrative paths in prose)
 
 ## Technical Debt
 
@@ -108,7 +108,39 @@ None. All CHALLENGE questions resolved.
 
 ## Retrospective
 
-_To be filled after execution._
+### What went well
+
+**Phased approach payoff.** The 4-phase structure (surface → structural → gaps → README) prevented scope creep by giving each commit a clear boundary. Phases 1 and 2 could be verified independently before touching cross-references or creating new pages. Total execution was 7 commits across 4 phases — manageable, reviewable.
+
+**Source verification during planning.** CHALLENGE phase verified claims against source code before committing to plan scope. Finding S7 (template override path `page/special.html` vs. source's `content/special.html`) and the frontmatter defaults (verified against `content.rs`) prevented shipping incorrect documentation. The CHALLENGE also correctly identified 3 false positives (S2, S3, S8) that would have been wasted effort.
+
+**CHALLENGE phase earned its keep.** Beyond false positive elimination, CHALLENGE produced two durable architectural decisions: (1) theming content goes into `syntax-highlighting.md` rather than a standalone `theming.md` page (avoids sync drift with `themes/README.md`), and (2) deployment guide uses platform links rather than embedded platform-specific config snippets (avoids maintenance burden). Both decisions were validated by nrd and shaped better outcomes than the initial PROPOSE.
+
+**Sections consolidation.** The option (b) approach — slim `sections.md` to reference-only, move explanation into `content-organization.md` — preserved both navigation entries while eliminating content duplication. Clean quadrant discipline: explanation stays in one place, reference in another.
+
+### What surprised us
+
+**Sketch accuracy:** 3 of 9 surface findings were false positives (correct repo URL, not wrong). The initial audit assumed `nrdxp/sukr` was wrong because the repo is `nrdxp/nrd.sh`, but `nrdxp/sukr` is the correct canonical URL for cloning. Lesson: always verify before planning, not just before executing.
+
+**Extra Sukr instances:** Plan flagged `architecture.md` L8 for uppercase "Sukr," but execution found 3 additional instances (L71, L82, L124). Minor divergence — same fix applied consistently. Reinforces the value of `grep` over line-targeted assumptions.
+
+**Tera link existed:** Sketch's §11 finding said `templates.md` had "no link to upstream Tera docs." During execution, the link was already present — just at a stale URL (`tera.netlify.app`). Step adapted: update URL + add authoring syntax pointer, rather than add a new link from scratch. Sketches capture impressions; execution verifies them.
+
+### Process observations
+
+**CORE 2-commit granularity was right-sized.** Each phase fit cleanly into 1–2 commits. Phase 1's split (tutorial fix vs. mechanical fixes) kept diffs reviewable. Phase 2's split (structural rework vs. enrichments) separated destructive changes (rewriting, consolidating) from additive ones (new columns, new sections). The maximum of 2–3 commits per CORE kept scope bounded.
+
+**Cross-phase dependencies are minor but real.** Phase 3 (deployment.md) touched Phase 2's output (`_index.md`'s Learn More section). Phase 4 (weight fix) resolved Phase 3's tech debt. These weren't blockers — just small edits to existing files — but they show that purely independent phases are a useful fiction for planning, not execution reality.
+
+**Tech debt tracking worked.** The nav weight collision surfaced during Phase 3 execution, was recorded in the plan's Technical Debt table, and resolved in Phase 4 step 4. The table mechanic (Item / Severity / Why / Follow-up / Resolved) provided clean traceability from discovery to resolution.
+
+### Intentional deferrals
+
+| Item                                | Rationale                                                                                                                                                        |
+| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| G2: Troubleshooting/error reference | sukr errors are self-descriptive. Unclear errors are a code fix, not a docs page. No user signal that current messages cause confusion.                          |
+| G5: Dedicated CLI reference page    | One flag (`-c`). CLI section added to `configuration.md` instead. Will revisit when CLI surface grows.                                                           |
+| `security.md` mixed quadrants       | Flagged in sketch (trust model = reference, CSP headers = how-to). Left as-is — page is short, splitting would create two thin pages. Pragmatic exception to §7. |
 
 ## References