Diagram generation: ref-arch-driven procedure + spec validator + KB enrichment

The diagram path now follows a documented standard procedure (lookup
the closest Oracle Architecture Center reference → confirm components
→ author absolute_layout → spec validator → render → visually verify)
and ships persistent guardrails so layout regressions can't recur.

Persistent procedure changes (apply to all users, all sessions):
- tools/diagram_spec_validator.py — geometry checks (CONTAINER_TOO_THIN,
  CONTAINER_PADDING_VIOLATION, LABEL_OVERFLOW_PARENT) run BEFORE either
  renderer (drawio + PPTX). Catches the subnet-collapse / label-overflow
  bugs that the post-render drawio validator missed.
- tools/oci_diagram_gen.py + tools/oci_pptx_diagram_gen.py — call the
  spec validator before emitting any output. Adds mysql / mysql_heatwave
  type aliases.
- tools/archcenter_pattern_lookup.py — scores against cached page
  descriptions (not just the 1-line summary), supports --queries for
  multi-fragment composition, and applies synonym expansion via
  kb/architecture-center/synonyms.yaml so "LB HA cross AD" matches
  "load balancer high availability availability domain".
- kb/architecture-center/synonyms.yaml — canonical synonym table
  (load balancer, autonomous database, data guard, …) used by the
  lookup scorer.

KB enrichment:
- tools/archcenter_description_fetcher.py + 121 cached _description.md
  under kb/diagram/assets/archcenter-refs/<slug>/. Removes the runtime
  dependency on docs.oracle.com when authoring specs and feeds the
  pattern-lookup scorer.
- 110+ cached .drawio / .svg / .png references for offline reuse,
  plus the OCI Toolkit v24.2 import (kb/diagram/assets/oci-toolkit-drawio).

Documentation:
- docs/skill/output-formats.md — new "Standard diagram-generation
  procedure (MANDATORY)" + geometry rules + the new validator entry.
- SKILL.md option 2 — references the mandatory procedure.
- README.md — describes the spec validator, archcenter_pattern_lookup
  and description fetcher, and updates the KB-health table.

Tooling that backs the procedure (cumulative across recent sessions):
tools/archcenter_case_runner.py, archcenter_batch_driver.py,
archcenter_zip_downloader.py, drawio_visual_validator.py,
drawio_fidelity_eval.py, harvest_drawio_icon.py, import_oci_library.py,
oci_pptx_diagram_gen.py, oci_pptx_render.py, refresh_pptx_icon_index.py.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/skill/output-formats.md

@@ -25,7 +25,7 @@ Default output is a **slide deck (.pptx)**. The architect can specify:
 
 | Format | Output |
 |--------|--------|
-| `deck` (default) | 10-12 slide presentation |
+| `deck` (default) | 10-12 slide presentation, with native OCI PowerPoint diagram when applicable |
 | `deck + drawio` | + editable architecture diagram |
 | `deck + doc` | + technical document (15-25 pages) |
 | `deck + xlsx` | + cost spreadsheet with formulas |
@@ -43,7 +43,7 @@ Slide count adapts to engagement tier (6-8 small, 10-12 standard, 12-16 complex)
 2. **Value Story** — business driver, hypothesis, desired outcomes
 3. **Service Tiering** — workload-to-tier mapping (Platinum/Gold/Silver/Bronze) with SLA, RTO/RPO
 4. **Architecture Principles** — selected ECAL principles (Design/Deployment/Service) that govern the architecture
-5. **Architecture Diagram** — fills 85% of slide
+5. **Architecture Diagram** — fills 85% of slide; prefer native OCI PowerPoint shapes inside the deck when the architecture is structured enough
 6. **Architecture Decisions** — 4-6 key decisions with rationale
 7. **HA/DR** — topology + RTO/RPO per tier
 8. **Security & Compliance** — controls grid, compliance badges
@@ -56,11 +56,86 @@ Slide count adapts to engagement tier (6-8 small, 10-12 standard, 12-16 complex)
 15. **Well-Architected Scorecard** — 5-pillar traffic-light indicators
 16. **Next Steps** — concrete SMART actions with dates
 
-Use `tools/oci_deck_gen.py` for generation. Colors: teal `#2D5967`, copper `#AA643B`, purple `#804998`. Font: Segoe UI. Design standards: `config/output-formats.yaml`.
+Use `tools/oci_deck_gen.py` for generation. Decks should prefer native OCI PowerPoint diagrams over pasted images when the architecture can be rendered from structured input. Colors: teal `#2D5967`, copper `#AA643B`, purple `#804998`. Font: Segoe UI. Design standards: `config/output-formats.yaml`.
 
 ## Architecture diagram
 
-Use `tools/oci_diagram_gen.py` with OCI official styles from `kb/diagram/oci-toolkit-styles.yaml`. Containers, service blocks, connections, and typography rules are defined there.
+Use `tools/oci_diagram_gen.py` with OCI official styles from `kb/diagram/oci-toolkit-styles.yaml` when the user wants an editable technical diagram (`.drawio`). For customer-facing or presentation-ready output, prefer the native PowerPoint path via `tools/oci_deck_gen.py` and the PPTX icon library/index under `kb/diagram/`.
+
+### Standard diagram-generation procedure (MANDATORY)
+
+Follow these steps for every diagram, in order. Skipping a step is the single most common source of layout regressions.
+
+1. **Reference architecture lookup.** Run `python tools/archcenter_pattern_lookup.py "<topology keywords>"` against `kb/architecture-center/catalog.yaml` (123 entries). Pick the highest-scoring entry whose topology matches what the user asked for. The lookup surfaces cached `.drawio` / `.svg` under `kb/diagram/assets/archcenter-refs/<slug>/` — open it to copy proven container nesting, padding, and AD/subnet placement instead of inventing geometry.
+2. **Pre-generation review (per SKILL.md § What You Do NOT Do).** Confirm the component list with the user. Never add services the user did not mention except via the explicit auto-include whitelist.
+3. **Author the spec.** Use `absolute_layout` for ref-arch reproductions or any topology where geometry matters. Honor the geometry rules below (the spec validator enforces them).
+4. **Spec validation runs automatically.** Both `tools/oci_diagram_gen.py` (drawio) and `tools/oci_pptx_diagram_gen.py` (PPTX, called via `oci_deck_gen.py`) call `tools/diagram_spec_validator.py` before emitting any output. A `fail` status raises and aborts generation — fix the geometry, re-run.
+5. **Render.** Generate the `.drawio` and/or `.pptx`. The drawio path additionally runs `drawio_visual_validator.py` post-render to catch anything the spec validator missed (font sizes, off-canvas, duplicate ids).
+6. **Visually verify.** Rasterize the PPTX with `python tools/oci_pptx_render.py --pptx X.pptx --output X.png --width 1600` and inspect the PNG before reporting success.
+
+### Geometry rules for `absolute_layout`
+
+These rules are enforced by `tools/diagram_spec_validator.py` and exist because each one corresponds to a regression that previously shipped to the user:
+
+- **Container padding ≥ 12px.** Every nested container must keep ≥12px between its bottom edge and its parent's bottom edge. Otherwise the borders visually merge (`CONTAINER_PADDING_VIOLATION`).
+- **Subnet height ≥ label band + 12px.** A container labeled at 11pt needs h ≥ ~30px to avoid the label collapsing onto the bottom edge. Public-subnet bands holding an icon need to clear icon height + label band + breathing room (`CONTAINER_TOO_THIN`).
+- **Labels stay inside their parent, ≥ 6px from the bottom edge.** Free-floating labels under a service icon must not cross or sit within 6px of the enclosing subnet's bottom edge (`LABEL_OVERFLOW_PARENT`).
+- **AD columns nest INSIDE the VCN, never beside it.** Otherwise AD borders align with VCN borders and visually merge.
+- **Subnets may span AD columns** (regional public subnet, cross-AD DB subnet) — that is the canonical Oracle pattern for HA topologies; do not split a regional subnet per AD.
+
+### Diagram modes
+
+The diagram generator accepts two spec shapes:
+
+1. **Workload-driven (default)** — `tenancy → region(s) → vcn(s) → subnet(s) → service(s)` plus on-premises and external actors. The generator auto-lays out containers and service blocks. Use this for most customer proposals where you describe the workload abstractly.
+2. **`absolute_layout` (fidelity mode)** — explicit `(x, y, w, h)` for every container, service, label, and connection. Use this when the user wants to reproduce an Oracle Architecture Center reference diagram with maximum visual fidelity, or when a layout already exists (e.g. extracted from an official `.drawio`).
+
+```yaml
+absolute_layout:
+  canvas: {width: 720, height: 420}
+  containers:
+    - {id: region, type: region, label: "OCI Region", x: 0, y: 0, w: 720, h: 420}
+    - {id: vcn, type: vcn, label: "VCN 10.10.0.0/16", x: 28, y: 52, w: 670, h: 348}
+  services:
+    - {id: drg,  label: "", type: drg,  x: 8, y: 200, w: 55, h: 66}
+    - {id: adb,  label: "", type: adb_d, x: 230, y: 240, w: 60, h: 80}
+  labels:
+    - {id: lbl_drg, text: "DRG", x: 8, y: 268, w: 55, h: 14, fontSize: 700}
+  connections:
+    - {id: c1, from: drg, to: adb, type: standard, points: [[63, 233], [260, 240]]}
+```
+
+`fontSize` is shared with the PPTX `absolute_layout` schema — it's hundredths of a point (720 → 7.2pt). The drawio renderer auto-converts.
+
+The Architecture Center reconstruction pipeline lives at `tools/archcenter_case_runner.py` (single case) and `tools/archcenter_batch_driver.py` (batch). Reference: `kb/diagram/reference-layouts/archcenter-batch-runner.yaml`.
+
+### Pre-delivery validation (automatic)
+
+Both generators run sanity checks before the file ships, so a broken artifact never reaches the user:
+
+- **`tools/diagram_spec_validator.py`** — runs automatically *before* either renderer (drawio or PPTX). Validates the parsed `absolute_layout` for `CONTAINER_TOO_THIN`, `CONTAINER_PADDING_VIOLATION`, and `LABEL_OVERFLOW_PARENT`. A fail aborts generation. Set `OCI_DIAGRAM_VALIDATOR_SOFT=1` to demote errors to warnings.
+- **`tools/drawio_visual_validator.py`** — runs automatically inside `OCIDiagramGenerator.save()`. Hard-fails on `fontSize ≥ 50pt` (catches the PPTX-cents-of-pt → drawio-pt unit confusion that produced 700pt labels), duplicate cell ids, off-canvas geometry, and dangling edge endpoints. Reports OK/warnings/errors to stderr. Pass `--strict` on the CLI to make errors fail the build.
+- **`OCIDeckGenerator.save()` post-check** — verifies `[Content_Types].xml` declares a `<Default>` for every embedded media extension (PowerPoint refuses to open a deck and prompts to "repair" it when this is missing — the SVG-backed icons in `OCI_Icons.pptx` are the canonical case), and that no slide rels point to absent media or duplicate cNvPr ids.
+- **`tools/drawio_fidelity_eval.py`** — pixel-diff the rebuilt drawio against a canonical Architecture Center PNG. Runs automatically when the spec carries `source.diagram_asset` (or via `--reference-png` on the CLI). Default rendering path is the SVG companion via `cairosvg` (works in any environment); the rebuilt-drawio path through the actual `draw.io` binary is opt-in via the `DRAWIO_EXE` env var (the binary is not bundled with the skill — install on demand).
+
+CLI usage:
+
+```bash
+# Standard run (validators on by default)
+python tools/oci_diagram_gen.py --spec my-spec.yaml --output out.drawio
+
+# Fail the build if validator finds errors
+python tools/oci_diagram_gen.py --spec my-spec.yaml --output out.drawio --strict
+
+# Fidelity comparison vs canonical PNG
+python tools/oci_diagram_gen.py --spec my-spec.yaml --output out.drawio \
+   --reference-png kb/diagram/reference-layouts/.../canonical.png
+
+# Strict draw.io binary path (opt-in)
+DRAWIO_EXE=/usr/bin/drawio python tools/oci_diagram_gen.py --spec ... --reference-png ...
+```
+
+Skip validators only when intentionally generating a fixture or test: `--no-validate`.
 
 ## Service categorization