Symptom on the GCP→OCI PostgreSQL deck: the OCI PostgreSQL icon bbox
rendered as empty space — labels and surrounding ADs all visible,
but no icon where the postgres stencil should be.
Root cause: ``_lookup_icon_ref`` returned the first hit from
``stencils.database_icons`` without checking it was cloneable.
The bucket happens to ship one degraded entry — ``database`` is
``tag=sp`` with ``bbox=None`` (a label-strip leaf, not the real
icon group) — so ``_clone_translated_block`` emitted a zero-size
shape. The 19 viable refs for the same key in
``shape_library.entries`` were ignored because the early-return in
``database_icons`` won.
Fix: extract a shared ``_is_viable_ref`` predicate (slide_path +
child_index/node_path + non-empty bbox + supported tag) and apply
it before returning from BOTH stencil buckets (``database_icons``,
``sample_icon_refs``). On miss, fall through to
``shape_library_entries`` where ``_select_preferred_ref`` already
filtered the same way.
Affects every alias that routes to a degraded stencil entry —
``postgresql`` / ``postgres`` / ``oci_postgresql`` were the obvious
fallout because they all alias to ``database``. The Architecture
Center reconstructions on shape-library-only slugs were unaffected.
Verified by re-rendering examples/output-gcp-virginia-oci-postgres-
adbs-clone/*.pptx — the OCI PostgreSQL bbox now shows the icon
(teal stencil + "Database" intrinsic caption) consistently with
the ADB-S and Refreshable Clone bboxes next to it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Diego pointed at examples/output-ashburn-redis-oke and asked: does
Oracle ship a Redis icon for drawio? Answer: NO. Confirmed against
both libraries:
- kb/diagram/oci-icons.json (OCI Toolkit v24.2) → 0 hits
- kb/diagram/oci-pptx-icons-index.json (OCI_Icons.pptx) → 0 hits
Same for OCI Cache, Valkey, OCI PostgreSQL — all are GA after the
toolkit shipped.
Oracle's own reference architecture
``modernize-app-dev-oci-postgresql-redis-opensearch`` works around
this by embedding inline SVG vector data into ``shape=stencil(...)``
cells — there is no reusable named stencil. The closest reusable
match is the generic ``database`` icon (8 cells in oci-icons.json,
the canonical "Database" stencil).
Persistent fixes:
- TYPE_TO_ICON (PPTX) and ICON_TYPE_ALIASES (drawio) both gain
aliases for ``redis`` / ``oci_cache`` / ``oci_cache_with_redis`` /
``cache`` / ``valkey`` / ``postgresql`` / ``postgres`` /
``oci_postgresql`` → ``database``. Plus ``opensearch`` →
``database_opensearch`` (which exists) on the PPTX side.
- SKILL.md option 2 step 3 documents the convention: when an OCI
service doesn't have a toolkit icon, use the generic stencil and
pair with an explicit ``label:`` carrying the real service name
(e.g. ``label: "OCI Cache (Redis)"``). When Oracle ships a v25+
toolkit with these icons, update oci-icons.json + the alias tables
and the next render picks up the real icon automatically.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Diego flagged two patterns from the Codex session:
1. Aliases for natural-language slugs were missing — Codex authored
``type: refreshable_clone`` and ``type: oci_goldengate`` and the
resolver returned None for both. Beyond fixing those two, expand
the table proactively: 50+ slugs an SA / agent might naturally
reach for (atp, alb, nlb, apigw, lambda, kms, secret, kafka,
alarm, email, identity, iam, iac, terraform, oac, oic, language /
speech / vision, rpc / lpg / cpe, health_check, tags, etc.) all
mapped to canonical icon entries that exist in
kb/diagram/oci-pptx-icons-index.json.
2. Codex was editing tools/oci_deck_gen.py and the deck-spec while
fulfilling a menu-driven option-2 request — going off the
procedure to "fix" perceived bugs in the renderer. New rule in
SKILL.md § What You Do NOT Do: when the user is in menu mode
(options 1–14), the agent USES the existing tools, never modifies
them. Tool gaps (missing aliases, broken paths) get surfaced as
end-of-reply follow-ups for a separate developer-mode session.
Two narrow exceptions kept: kb/field-findings/tracker.yaml via
option 11, and writing customer spec/output YAML under examples/.
Codex copy auto-synced via the pre-commit hook.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Spec authors hand the renderer a polyline like
``points: [[210,280],[400,280],[700,130]]``. The previous code emitted
one ``prst="line"`` shape per segment, so the elbow was two separate
straight lines that PowerPoint cannot recognise as a connected path.
The OCI template (kb/diagram/assets/OCI_Icons.pptx) uses native
PowerPoint bent connectors instead — 98 ``straightConnector1`` plus
22 ``bentConnector2/3/5`` plus 15 ``line`` across 48 slides. Match
that convention:
• 2 points → straightConnector1 (one segment, unchanged)
• 3 points → bentConnector2 (one elbow)
• 4 points → bentConnector3 (S-shape, two elbows)
• 5+ points → bentConnector5 (four elbows)
The rasterizer (oci_pptx_render.py) now also understands bentConnectorN
so the local PNG preview matches what real PowerPoint draws — without
this it rendered every connector as one straight diagonal regardless of
the prst.
Persistent: applies to every absolute_layout connector for every spec,
not a per-case patch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
OCI_Icons.pptx ships both a full icon group (tag=grpSp, ~0.7" tall)
and a tiny "label strip" (tag=sp, ~0.2" tall) under the same slug for
many services. The previous resolver picked whichever came first in
the index, which for 'mysql' returned the text strip — so the PPTX
diagram showed a label-only shape instead of the dolphin/HeatWave
icon, while drawio rendered the proper stencil.
Two fixes, both persistent (apply to every icon family, not just MySQL):
- TYPE_TO_ICON for mysql/heatwave now lists 'mysql_heatwave' (the
grpSp) before 'mysql' (the strip).
- _select_preferred_ref now filters viable refs to those that are
either grpSp/pic OR have a bbox ≥0.4"x0.4" — text strips fall out
before the scoring function runs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
