docs/architecture.md

@@ -217,6 +217,13 @@ Key UKO capabilities:
 - **Graph persistence** — `UKOGraphPersistence` serialises/restores state via
   JSON-file or in-memory backends across application restarts
 
+**Skeleton context propagation:** `ContextAssembler.assemble()` invokes
+`SkeletonCompressor` during Phase 3 assembly and includes the resulting
+compressed fragments in `ContextPayload.skeleton_fragments`, propagating
+parent-plan skeleton context to child plans. `skeleton_ratio` defaults to
+`0.15`; `parent_fragments=None` preserves backward compatibility when no
+parent context exists. (Closes #3563.)
+
 ---
 
 ## Invariant Reconciliation
@@ -323,6 +330,41 @@ Never construct services directly in application code.
 
 ---
 
+## UAT Showcase Documentation Generation
+
+The UAT tester (`scripts/` and related agent definitions) now serves a dual
+purpose: finding bugs through comprehensive testing **and** generating
+high-quality showcase documentation from successful end-to-end test runs.
+
+**How it works:**
+
+1. When a UAT test run completes successfully end-to-end, the tester captures
+   the workflow (prompts, responses, artefacts produced).
+2. A duplicate-detection step checks `docs/showcase/examples.json` to avoid
+   re-generating examples that already exist.
+3. New examples are written to `docs/showcase/<category>/` where `<category>`
+   is one of `cli-tools`, `api-clients`, `data-processing`, or `testing-tools`.
+4. An automatic PR is created to deliver the new showcase docs to `master`
+   without manual intervention.
+
+**Directory structure:**
+
+```
+docs/showcase/
+├── index.md              # Overview and category index
+├── examples.json         # Tracking index for duplicate detection
+├── example-template.md   # Template for new examples
+├── cli-tools/            # CLI tool showcase examples
+├── api-clients/          # API client showcase examples
+├── data-processing/      # Data processing showcase examples
+└── testing-tools/        # Testing tool showcase examples
+```
+
+All showcase examples are automatically verified (generated from passing
+test runs), self-contained, reproducible, and educational.
+
+---
+
 ## Key Design Decisions
 
 | Decision | ADR | Summary |

mkdocs.yml

@@ -32,6 +32,12 @@ nav:
     - System Watchdog: development/system-watchdog.md
   - Implementation Timeline: timeline.md
   - FAQ: faq.md
+  - Showcase:
+    - Overview: showcase/index.md
+    - CLI Tools: showcase/cli-tools/
+    - API Clients: showcase/api-clients/
+    - Data Processing: showcase/data-processing/
+    - Testing Tools: showcase/testing-tools/
   - Reference: reference/
   - Architecture Decision Records (ADRs):
     - Overview: adr/index.md