diff --git a/docs/netsuke-design.md b/docs/netsuke-design.md
index d2738947..ac902e4b 100644
--- a/docs/netsuke-design.md
+++ b/docs/netsuke-design.md
@@ -2109,6 +2109,12 @@ reporter output, timing summaries, and the semantic prefix surface are guarded
 by `insta` snapshots so spacing, prefix alignment, and wrapping regressions
 fail with reviewable diffs instead of drifting silently.
 
+The Advanced Usage chapter in `docs/users-guide.md` is validated by behavioural
+tests in `tests/features/advanced_usage.feature`. Netsuke treats those
+scenarios as executable documentation for the `clean`, `graph`, and `manifest`
+subcommands, configuration layering, and JSON diagnostics so the guide stays
+synchronized with runtime behaviour rather than drifting behind it.
+
 For screen readers: The following flowchart shows how the build script audits
 localization keys against English and Spanish Fluent bundles.
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
index a49bfcb4..e9e43874 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -318,8 +318,8 @@ library, and CLI ergonomics.
 - [x] 3.13.1. Add smoke tests for novice flows.
   - [x] Test first run success, missing manifest, and help output.
   - [x] Confirm UX matches documented journey.
-- [ ] 3.13.2. Extend user documentation with advanced usage chapter.
-  - [ ] Cover `clean`, `graph`, `manifest`, configuration layering, and JSON
+- [x] 3.13.2. Extend user documentation with advanced usage chapter.
+  - [x] Cover `clean`, `graph`, `manifest`, configuration layering, and JSON
     diagnostics.
 - [ ] 3.13.3. Provide CI-focused guidance.
   - [ ] Include examples of consuming JSON diagnostics.