create-yss-spec 2.1.5 → 2.1.7

package/template/.agents/skills/drawio/references/docs/migration-readiness.md

@@ -1,73 +0,0 @@
-# Migration Readiness
-
-This note explains what is already backend-agnostic in the draw.io skill, what still depends on the current live provider, and how to approach a future official-provider migration without rewriting the whole skill.
-
-## 1. What depends on offline bundle vs live backend?
-
-### Offline bundle responsibilities
-
-These should remain stable regardless of which live provider exists:
-
-- YAML spec as the canonical editable representation
-- CLI validation and regeneration
-- `.drawio` + `.spec.yaml` + `.arch.json` sidecar workflow
-- Mermaid and CSV normalization into YAML spec
-- Academic, formula, theme, and edge-quality rules
-- Replication color extraction and theme fallback rules
-
-### Live backend responsibilities
-
-These are optional enhancements only:
-
-- Open a diagram in a browser or inline viewer
-- Read current browser state back before further edits
-- Apply incremental cell patches in a live editor
-- Export from the live session
-- Search an official shape index when exact stencils matter
-
-## 2. Capability gaps across providers
-
-| Provider | Good at | Missing |
-|----------|---------|---------|
-| Current next-ai live MCP | Real edit sessions, read-back, patching, export | Shape search, inline chat preview |
-| Official Tool Server | Browser handoff from XML/CSV/Mermaid | Read-back, patching, export, inline preview, shape search |
-| Official App Server | Inline preview and official shape search | Read-back, patching, export |
-
-## 3. What does that mean today?
-
-- Official references should be integrated now.
-- Official Tool/App Server can be treated as **supplementary providers**, not as edit-session replacements.
-- The current live provider must remain available for true live incremental editing until another provider offers equivalent `read_diagram_xml`, `patch_diagram_cells`, and `export_diagram_file` capabilities.
-
-## 4. If we migrate later, what changes first?
-
-Start at the provider-mapping layer, not the workflow layer.
-
-1. Update the live-backend capability mapping in [mcp-tools.md](mcp-tools.md).
-2. Update any install/setup surface that advertises optional live providers.
-3. Keep `create`, `edit`, and `replicate` workflows unchanged unless the capability matrix changes.
-
-## 5. What should not change during a future migration?
-
-- YAML spec schema
-- Sidecar trio (`.drawio`, `.spec.yaml`, `.arch.json`)
-- CLI flags and local export behavior
-- Academic / formula / replication validation rules
-- Offline-first default routing
-
-## 6. What would justify replacing the current live edit provider?
-
-Only a provider with equivalent support for all of the following:
-
-- `replace_diagram_xml`
-- `read_diagram_xml`
-- `patch_diagram_cells`
-- `export_diagram_file`
-
-`search_shape_catalog` and `render_inline_preview` are useful additions, but they do not by themselves replace a live edit backend.
-
-## Related
-
-- [Live Backend Reference](mcp-tools.md)
-- [Official XML Reference Mirror](../official/xml-reference.md)
-- [Official Style Reference Mirror](../official/style-reference.md)

package/template/.agents/skills/drawio/references/docs/stencil-library-guide.md

@@ -1,97 +0,0 @@
-# Stencil Library Guide
-
-Use semantic shapes by default. Switch to provider or device stencils only when the diagram needs vendor-specific meaning or standardized equipment symbols.
-
-## Search Before Writing
-
-For vendor stencils, use the bundled offline catalog before putting an icon in YAML. It requires no MCP server or network connection:
-
-```bash
-node scripts/cli.js search pod --prefix kubernetes
-node scripts/cli.js search "s3, lambda, nat gateway"
-node scripts/cli.js search virtual-machine --prefix mscae --limit 5
-```
-
-Results show the real draw.io name and, when available, the correct YAML syntax such as `k8s.pod`. `--prefix` filters a library, `--limit` controls the number of rows, and `--json` produces machine-readable output. Covered unknown names are rejected during conversion with suggestions. Correct the YAML or run the suggested search; use `--allow-unknown-shapes` only when preserving a known legacy raw stencil is more important than validation.
-
-### Bundled coverage
-
-| Library | Search and validation coverage |
-| --- | --- |
-| `aws4` | 599 flat stencils plus 132 product-icon parameters |
-| `gcp2` | 110 upstream stencils |
-| `azure` | 87 upstream stencils |
-| `mscae` | 148 Azure supplemental stencils |
-| `kubernetes` | 39 `icon2` parameters, including `k8s.pod` |
-| `cisco` / `cisco19` | 291 flat Cisco stencils plus 149 `cisco19.rect` parameters |
-| `networks` | 58 network stencils |
-
-Other `mxgraph.*` libraries remain pass-through and are not rejected by this catalog.
-
-## Decide Whether Exact Stencil Search Is Needed
-
-### Skip shape search when the diagram is mostly basic geometry
-
-- flowcharts
-- UML diagrams
-- ER diagrams
-- org charts
-- mind maps
-- timelines
-- wireframes
-- academic figures that only need boxes, diamonds, cylinders, circles, and arrows
-
-### Use shape search when exact stencil identity matters
-
-- AWS / Azure / GCP architectures
-- Cisco or rack-network topologies
-- Kubernetes or vendor-heavy platform diagrams
-- P&ID / electrical / circuit diagrams
-- BPMN variants where exact task or event symbols matter
-
-If the requested library is outside the bundled coverage, fall back to:
-
-1. known icon mappings in the design system
-2. bundled `lobe.*` or `ai.*` icons for OpenAI, Claude, and Gemini
-3. `brand.*` icons for supported non-AI product logos such as Redis
-4. `lucide.*` icons for generic semantic roles such as AI, cache, document,
-   server, workflow, and security
-5. semantic shapes when exact icon resolution cannot be guaranteed
-
-Do not invent a raw name just because the requested library is not covered.
-
-## Core Rules
-
-1. Use semantic shapes when the audience cares more about function than branding.
-2. Use stencils when vendor or device identity materially improves clarity.
-3. Do not guess raw stencil names that are not documented or returned by search.
-4. If mixed with semantic shapes, keep icon usage limited to nodes whose branded identity matters.
-5. In academic figures, prefer monochrome-compatible icons or add a legend.
-
-## Provider Prefixes
-
-Common icon prefixes supported by the design system:
-
-- `aws.*`
-- `azure.*`
-- `gcp.*`
-- `k8s.*`
-- `kubernetes.*`
-- `lobe.*` / `ai.*` for the bundled OpenAI, Claude, and Gemini logos
-- `brand.*` for supported non-cloud product identity icons
-- `lucide.*` for the curated embedded semantic SVG icon set
-
-Unsupported image-icon names fail shape validation. Add new names by bundling
-their SVG data and license notice; do not add runtime CDN fallbacks.
-
-## Recommended Usage
-
-- Cloud reference architecture: provider icons for gateways, queues, storage, compute
-- Network topology: routers, switches, firewalls, APs when exact device semantics matter
-- Academic or conceptual system figure: semantic shapes first, provider icons only for external deployment targets
-
-## Related
-
-- [Live Backend Reference](mcp-tools.md)
-- [Official XML Reference Mirror](../official/xml-reference.md)
-- [Design System Icons](design-system/icons.md)

package/template/.agents/skills/drawio/references/docs/style-extraction.md

@@ -1,261 +0,0 @@
-# Style Extraction — agent reference
-
-Loaded on demand by `SKILL.md` when the user asks to learn a style ("learn my style from `<path>` as `<name>`") or when the agent needs to render a sample after extraction.
-
-## Sample diagram (for approval render)
-
-After extracting a candidate preset, render this seven-node sample using the candidate's palette/shapes/fonts/edges. Each role appears exactly once; six edges, one dashed, exercise `edges.arrow`, `edges.style`, and `edges.dashedFor`.
-
-**Layout (TB):**
-
-- Row 1 (y=40): `gateway` centered at x=340
-- Row 2 (y=180): `security` (x=80), `service` (x=340), `queue` (x=600)
-- Row 3 (y=340): `database` (x=80), `external` (x=340), `error` (x=600)
-
-**Template — substitute `{{...}}` placeholders from the candidate preset.**
-
-The vertex style for role `R` is built as:
-`<shapes[R]>;whiteSpace=wrap;html=1;fillColor=<palette[roles[R]].fillColor>;strokeColor=<palette[roles[R]].strokeColor>;fontFamily=<font.fontFamily>;fontSize=<font.fontSize>`
-
-- If `extras.sketch=true`, append `;sketch=1` to every vertex style AND every edge style.
-- If `extras.globalStrokeWidth !== 1` (i.e., any value other than the drawio default of 1, including `0.5`), append `;strokeWidth=<n>` to every vertex style AND every edge style.
-
-The edge style is built as:
-`<edges.style>;<edges.arrow>`
-
-- Per-edge routing keys (`exitX/entryX/...`) are added as literals below.
-- Edge 15 exercises `edges.dashedFor`:
-  - If `edges.dashedFor` is **non-empty**, use its first entry as the edge's `value` (label) AND append `;dashed=1` to the edge style.
-  - If `edges.dashedFor` is empty (`[]`), use the label `cross-call` and do NOT append `;dashed=1` — the preset has no dashed convention, so the sample must not fake one.
-
-**Placeholder expansion (applied when filling the XML):**
-
-- `{{VSTYLE:<role>}}` expands to the vertex-style formula above with `R = <role>`. Write the result as a literal string; do not URL-encode.
-- `{{ESTYLE}}` expands to the edge-style formula above.
-- `{{EDGE15_LABEL}}` and `{{EDGE15_DASH}}` follow the Edge-15 rule above.
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<mxfile host="drawio" version="26.0.0">
-  <diagram name="Preset Sample">
-    <mxGraphModel>
-      <root>
-        <mxCell id="0" />
-        <mxCell id="1" parent="0" />
-
-        <!-- Row 1: gateway -->
-        <mxCell id="2" value="Gateway" style="{{VSTYLE:gateway}}" vertex="1" parent="1">
-          <mxGeometry x="340" y="40" width="160" height="60" as="geometry" />
-        </mxCell>
-
-        <!-- Row 2: security | service | queue -->
-        <mxCell id="3" value="Auth" style="{{VSTYLE:security}}" vertex="1" parent="1">
-          <mxGeometry x="80" y="180" width="160" height="60" as="geometry" />
-        </mxCell>
-        <mxCell id="4" value="Service" style="{{VSTYLE:service}}" vertex="1" parent="1">
-          <mxGeometry x="340" y="180" width="160" height="60" as="geometry" />
-        </mxCell>
-        <mxCell id="5" value="Queue" style="{{VSTYLE:queue}}" vertex="1" parent="1">
-          <mxGeometry x="600" y="180" width="160" height="60" as="geometry" />
-        </mxCell>
-
-        <!-- Row 3: database | external | error -->
-        <mxCell id="6" value="Database" style="{{VSTYLE:database}}" vertex="1" parent="1">
-          <mxGeometry x="80" y="340" width="160" height="70" as="geometry" />
-        </mxCell>
-        <mxCell id="7" value="External API" style="{{VSTYLE:external}}" vertex="1" parent="1">
-          <mxGeometry x="340" y="340" width="160" height="60" as="geometry" />
-        </mxCell>
-        <mxCell id="8" value="Error Sink" style="{{VSTYLE:error}}" vertex="1" parent="1">
-          <mxGeometry x="600" y="340" width="160" height="60" as="geometry" />
-        </mxCell>
-
-        <!-- Edges -->
-        <mxCell id="10" value="" style="{{ESTYLE}};exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="2" target="3">
-          <mxGeometry relative="1" as="geometry" />
-        </mxCell>
-        <mxCell id="11" value="" style="{{ESTYLE}};exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="2" target="4">
-          <mxGeometry relative="1" as="geometry" />
-        </mxCell>
-        <mxCell id="12" value="" style="{{ESTYLE}};exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="2" target="5">
-          <mxGeometry relative="1" as="geometry" />
-        </mxCell>
-        <mxCell id="13" value="" style="{{ESTYLE}};exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="4" target="7">
-          <mxGeometry relative="1" as="geometry" />
-        </mxCell>
-        <mxCell id="14" value="" style="{{ESTYLE}};exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0" edge="1" parent="1" source="4" target="6">
-          <mxGeometry relative="1" as="geometry" />
-        </mxCell>
-        <mxCell id="15" value="{{EDGE15_LABEL}}" style="{{ESTYLE}}{{EDGE15_DASH}};exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0" edge="1" parent="1" source="4" target="8">
-          <mxGeometry relative="1" as="geometry" />
-        </mxCell>
-
-      </root>
-    </mxGraphModel>
-  </diagram>
-</mxfile>
-```
-
-### Rendering the sample
-
-1. Write the filled XML to `/tmp/drawio-preset-<name>.drawio`.
-2. Run the same `draw.io -x -f png -e -s 2 -o <preset-name>-sample.png <tmp>.drawio` command the main workflow uses.
-3. Save the PNG as `./preset-<name>-sample.png` (the user's working directory).
-4. Show the user: preset summary table + PNG path + provenance/confidence line.
-
-### Approval loop
-
-- "save" / "looks good" → write candidate to `~/.drawio-skill/styles/<name>.json`; delete tempfile and sample PNG.
-- "change <field> to <value>" → edit the in-memory candidate; re-render; re-ask.
-- "cancel" → delete tempfile and sample PNG; no save.
-
-### If sample render fails (draw.io CLI missing / export error)
-
-Still show the summary table and the provenance line. Note: *"Could not render sample PNG (CLI unavailable). Save anyway on your OK."* Do not block.
-
-## XML extraction path
-
-Input: a `.drawio` file path. Output: candidate preset JSON. Deterministic, no LLM inference.
-
-### Steps
-
-1. **Parse the file.** Read the XML, collect every `<mxCell>` with a `style=` attribute, split into vertices (`vertex="1"`) and edges (`edge="1"`).
-2. **Tokenize each `style=` string** on `;`. Each element is either `key=value` or a bare keyword (e.g., `rhombus`, `ellipse`, `rounded=1`).
-3. **Extract palette.** For every vertex, take the `(fillColor, strokeColor)` pair (skip vertices with neither). Count frequency. Keep the top ≤7 pairs.
-4. **Extract shape vocabulary + role mapping.** For each vertex determine a shape class by precedence:
-   `cylinder3 > ellipse > rhombus > swimlane > rounded=1 > rounded=0`.
-   Then infer the semantic role from the vertex's shape class and its `value` (label) attribute. **Evaluate the rules below in order; first match wins.**
-   - `cylinder3` → `database`
-   - `rhombus` → `decision`
-   - `swimlane` → `container`
-   - `dashed=1` present + **grey-family fill** (hex where the R, G, and B channels all fall within ±16 of each other, i.e., near-achromatic) → `external`
-   - label matches `/queue|bus|kafka|rabbit/i` → `queue`
-   - label matches `/gateway|api|lb|load/i` → `gateway`
-   - label matches `/auth|login|jwt|oauth/i` → `security`
-   - label matches `/error|fail|alert/i` → `error`
-   - everything else → `service`
-
-   For each **role that has a canonical palette slot** — `service`, `database`, `queue`, `gateway`, `error`, `external`, `security` — the most frequent `(role, color-pair)` mapping wins. The pair goes into the role's canonical palette slot:
-   `service→primary, database→success, queue→warning, gateway→accent, error→danger, external→neutral, security→secondary`.
-   Set `roles[role]` to that slot name.
-
-   **Decision and container shapes do not get a `roles[...]` entry** — they are recorded only in `shapes.decision` and `shapes.container`. Any color pairs observed on decision/container vertices still participate in the palette (they can fill leftover slots) but are not tied to a semantic role.
-
-   Leftover color pairs (not claimed by any role-slot mapping) fill remaining empty palette slots in descending-frequency order.
-
-   Record the shape class string used per role in `shapes[role]`. The six named shape keys are `service`, `database`, `queue`, `decision`, `external`, `container` — `gateway`, `error`, and `security` roles inherit `shapes.service` and do not get their own `shapes[...]` entry. Example: `shapes.database = "shape=cylinder3"`.
-
-5. **Extract fonts.** Compute modal `fontFamily` and `fontSize` across vertices; emit them as `font.fontFamily` and `font.fontSize`. Also track `fontStyle` per vertex as a **working variable** (not an output field — the schema has no top-level `font.fontStyle`). If a distinguishable subset of vertices uses a larger `fontSize` combined with `fontStyle=1` (bold), treat that subset as titles: set `font.titleFontSize` to their modal size and `font.titleBold: true`. Otherwise omit both title fields.
-
-6. **Extract edge defaults.** Take the modal edge style string, but strip these per-edge coordinate keys before counting: `entryX`, `entryY`, `exitX`, `exitY`, `entryDx`, `entryDy`, `exitDx`, `exitDy`. Record arrow style from `endArrow`/`endFill` separately in `edges.arrow`.
-   If any edges have `dashed=1`, collect their `value` (label) attributes. If ≥2 share a common token (e.g., all are labeled "async" or "optional"), add that token to `edges.dashedFor`.
-
-7. **Extract extras.** `sketch=1` seen on any vertex or edge → `extras.sketch = true`. Modal `strokeWidth` across vertices → `extras.globalStrokeWidth` (default `1`).
-
-8. **Set provenance.**
-
-   ```json
-   {
-     "source": { "type": "xml", "path": "<input absolute path>", "extracted_at": "YYYY-MM-DD" },
-     "confidence": "high"
-   }
-   ```
-
-### XML edge cases
-
-| Situation | Behavior |
-|---|---|
-| Source has <3 distinct color pairs | Leave unfilled slots as `null`. Downgrade `confidence` to `"medium"`. Summary warns the user. |
-| Source has >7 color pairs | Keep the top 7 by frequency. Summary warns that some colors were dropped. |
-| Non-standard `shape=` keywords (e.g., `shape=mxgraph.aws4.*`) | These do not match the Step 4 precedence ladder, so the vertex falls through to `rounded=0` for shape-class purposes. Iconography is lost; color, label, and edge style are still captured. Role inference still runs via the label-regex rules. Summary notes: *"Non-standard shape library detected — iconography not preserved in preset (color and label captured)."* |
-| Non-English labels | The English-keyword regexes in step 4 will mostly miss; most vertices collapse to `service`. Palette/shapes/font/edges still captured correctly (they don't depend on label text). `confidence` stays `"high"`. Summary notes: *"Role labels not in English — `service`/`database`/`decision`/`container`/`external` inferred from shape class; other roles not mapped."* |
-| File has no `<mxCell vertex="1">` at all | Stop. Refuse to save. Message: *"Nothing to learn from — source file has no shapes."* |
-
-## Image extraction path
-
-Input: path to a PNG/JPG (or any vision-readable image format). Output: candidate preset JSON. Inference-based; `confidence: "medium"` at best.
-
-**Prerequisite:** the agent's vision capability must be available (same mechanism the main workflow's self-check uses). If vision is not available, stop and tell the user:
-*"Image-based learning needs a vision-enabled model (Claude Sonnet or Opus). Re-run on such a model, or provide the `.drawio` source file instead."*
-
-### Steps
-
-1. **Read the image.** Use the agent's vision input — the same path the main workflow's step 5 uses to read exported PNGs during self-check.
-
-2. **Extract palette by visual inspection.** Identify distinct fill-color regions on shape bodies.
-
-   For each distinct fill:
-   - `fillColor` — quantize each RGB channel to the nearest multiple of 16. If the resulting HSL lightness is below 0.75, raise it to 0.85 (keep hue and saturation; set L=0.85; HSL→RGB round-trip). Emit as `#RRGGBB`. Drawio-standard pastels occupy L≈0.85–0.96; below 0.75 reads as "too dark for a fill color" and this step lifts it back into that range.
-   - `strokeColor` — read the matching border. If unreadable, derive from fill by darkening ~25% (match HSL, drop L by 0.25).
-
-   Map each `(fillColor, strokeColor)` pair to a named slot using this decision order:
-
-   1. **Grey check first.** If the fill has R, G, and B channels all within ±16 of each other (same definition as the XML path's grey-family rule), OR HSL saturation < 0.20, classify as `neutral`. This check wins regardless of hue angle.
-   2. **Hue band otherwise.** Use these explicit HSL hue ranges:
-      - 180°–260° → `primary` (blue)
-      - 80°–170° → `success` (green)
-      - 45°–65° → `warning` (yellow)
-      - 20°–44° → `accent` (orange)
-      - 0°–19° or 320°–360° → `danger` (red/pink)
-      - 260°–320° → `secondary` (purple)
-   3. **No band matched** (gap regions at 65°–80° or 170°–180°) → spill to the nearest band by angular distance.
-
-   **Collision rule.** If ≥2 distinct fills land in the same slot, sort them by total pixel area covered in the image (descending). The largest keeps the canonical slot. Remaining fills spill to the **nearest empty slot** measured by hue-band angular distance — first to adjacent bands on either side, then farther out. If every slot is already filled, drop the extras and warn in the summary.
-
-3. **Extract shape vocabulary.** Classify every visible shape by silhouette:
-   - rounded rectangle → `rounded=1`
-   - sharp rectangle → `rounded=0`
-   - circle / oval → `ellipse`
-   - diamond → `rhombus`
-   - cylinder (rectangle with curved top/bottom) → `shape=cylinder3`
-   - titled container (header bar + nested children inside) → `swimlane;startSize=30`
-   - dashed-bordered rectangle → `rounded=1;dashed=1`
-
-   Role assignment uses the **same label-text + shape rules as the XML path step 4**. Visible labels are read via vision.
-
-4. **Extract fonts.** Best-effort. Distinguishable categories:
-   - clearly serif → `fontFamily: "Georgia"`
-   - clearly monospaced → `fontFamily: "Courier New"`
-   - otherwise → `fontFamily: "Helvetica"`
-
-   Size by relative appearance:
-   - small → `fontSize: 11`
-   - medium → `fontSize: 12`
-   - large → `fontSize: 14`
-
-   If titles/container headers are distinctly larger or bolder → set `titleFontSize` accordingly and `titleBold: true`.
-
-5. **Extract edge defaults.**
-   - Right-angle orthogonal arrows → `edges.style = "edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1"`.
-   - Curved arrows → append `;curved=1` to `edges.style`.
-   - Filled triangle arrowheads → `edges.arrow = "endArrow=classic;endFill=1"`.
-   - Open V-shaped arrowheads → `edges.arrow = "endArrow=open;endFill=0"`.
-   - Any dashed arrows near labels like "optional", "async", "fallback", "secondary" → add those label tokens to `edges.dashedFor`.
-
-6. **Extract extras.**
-   - Visibly hand-drawn / rough / sketch look (wavy strokes, uneven fills) → `extras.sketch = true`.
-   - Heavy strokes (clearly >1.5× normal) → `extras.globalStrokeWidth = 2`.
-   - Otherwise default: `extras = { "sketch": false, "globalStrokeWidth": 1 }`.
-
-7. **Set provenance and confidence.**
-
-   ```json
-   {
-     "source": { "type": "image", "path": "<input absolute path>", "extracted_at": "YYYY-MM-DD" },
-     "confidence": "medium"
-   }
-   ```
-
-   Adjustments:
-   - <3 distinct shapes identifiable → `confidence: "low"`.
-   - Image path stays at `"medium"` by default. The only path to `"high"` is a strictly-verifiable signal: the source image was exported from drawio itself (recognizable drawio default chrome, grid, or a visible drawio watermark), **and** all seven palette slots are filled, **and** all seven roles are labeled. This preserves the semantic gap between inference-based (image) and parse-based (XML) provenance.
-
-### Image edge cases
-
-| Situation | Behavior |
-|---|---|
-| Vision unavailable | Stop as described above — do not fall back to guessing. |
-| Image has <3 identifiable shapes | Continue; mark `confidence: "low"`; summary explicitly warns the user that the preset is a loose approximation. |
-| Image has no visible labels | Role assignment collapses to shape-class only: cylinders → `database`, diamonds → `decision`, swimlanes → `container`, dashed-bordered rectangles with grey fill → `external`, everything else → `service`. Palette/font/edges still captured. Summary notes: *"No labels readable — semantic roles beyond shape-class not inferred."* |
-| Two palette slots would land in the same hue family | Keep the more frequent one in its canonical slot; spill the other to the adjacent empty slot (rule in step 2). |
-| Image has more than 7 distinct fills | Keep the 7 most area-covering fills per the Step 2 collision rule. Summary warns that some colors were dropped. |

package/template/.agents/skills/drawio/references/docs/style-presets.md

@@ -1,126 +0,0 @@
-# Style Presets
-
-This file is a **local supplement**, not the full draw.io style dictionary.
-
-Use these presets when you need a small set of copy-paste style strings for quick patches or hand-authored XML. For the full upstream catalog of shape types, style properties, color semantics, and HTML label rules, read:
-
-- [Official Style Reference Mirror](../official/style-reference.md)
-- [Official XML Reference Mirror](../official/xml-reference.md)
-
-For normal skill usage, prefer the design system over raw style strings:
-
-- [Design System Overview](design-system/README.md)
-- [Themes](design-system/themes.md)
-- [Shapes](design-system/shapes.md)
-- [Connectors](design-system/connectors.md)
-
-## Local Usage Rules
-
-- Keep a limited palette (3-4 colors) unless the source diagram explicitly needs more.
-- Use `html=1` for rich text and MathJax labels.
-- Prefer orthogonal connectors for technical architecture diagrams.
-- When patching existing XML, only use these presets as short helpers; do not treat them as the authoritative style vocabulary.
-
-## Presets: Nodes
-
-### Service / Component
-
-```
-rounded=1;html=1;whiteSpace=wrap;align=left;verticalAlign=middle;
-fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;fontColor=#000000;
-spacingLeft=10;spacingRight=10;spacingTop=6;spacingBottom=6
-```
-
-### Data / Result
-
-```
-rounded=1;html=1;whiteSpace=wrap;align=left;verticalAlign=middle;
-fillColor=#d5e8d4;strokeColor=#82b366;fontSize=14;fontColor=#000000;
-spacingLeft=10;spacingRight=10;spacingTop=6;spacingBottom=6
-```
-
-### Note / Constraint
-
-```
-rounded=1;html=1;whiteSpace=wrap;align=left;verticalAlign=middle;
-fillColor=#fff2cc;strokeColor=#d6b656;fontSize=13;fontColor=#000000;
-spacingLeft=10;spacingRight=10;spacingTop=6;spacingBottom=6
-```
-
-### Formula
-
-```
-rounded=1;html=1;whiteSpace=wrap;align=left;verticalAlign=middle;
-fillColor=#ffffff;strokeColor=#6c8ebf;fontSize=16;fontColor=#000000;
-spacingLeft=12;spacingRight=12;spacingTop=8;spacingBottom=8
-```
-
-## Presets: Containers
-
-### Zone / Boundary
-
-```
-rounded=0;html=1;whiteSpace=wrap;align=left;verticalAlign=top;
-fillColor=#f5f5f5;strokeColor=#999999;fontSize=12;fontColor=#333333;
-spacingLeft=12;spacingRight=12;spacingTop=10;spacingBottom=10
-```
-
-### Dashed Boundary
-
-```
-rounded=0;html=1;whiteSpace=wrap;align=left;verticalAlign=top;
-fillColor=#f5f5f5;strokeColor=#999999;dashed=1;dashPattern=4 4;
-fontSize=12;fontColor=#333333;spacingLeft=12;spacingRight=12;spacingTop=10;spacingBottom=10
-```
-
-## Presets: Edges
-
-### Main Flow
-
-```
-edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;
-endArrow=block;endFill=1;strokeColor=#333333;strokeWidth=2;html=1
-```
-
-### Data Flow
-
-```
-edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;
-endArrow=block;endFill=1;strokeColor=#333333;strokeWidth=2;dashed=1;dashPattern=6 4;html=1
-```
-
-### Dependency
-
-```
-edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;
-endArrow=block;endFill=1;strokeColor=#666666;strokeWidth=1;html=1
-```
-
-## Theme × Diagram-Type Fit
-
-Distilled from the fireworks `style-diagram-matrix` after triage. Covers the four
-fireworks-derived themes ported into `assets/themes/` plus the closest existing
-themes. Pick by diagram type; avoid the **Poor** combinations.
-
-| Theme (`--theme`) | Register | Best for | Avoid (Poor) |
-|---|---|---|---|
-| `tech-blue` (default) | Light, cool | Architecture, flowchart, data flow, general | — |
-| `notion-clean` | Light, grayscale minimal | Class/ER, sequence, use-case, comparison tables, Notion/wiki embeds | — |
-| `blueprint` | Dark navy, cyan, sharp | Formal architecture, UML (class/sequence/state), network topology, data flow | Mind map, comparison tables (grid fights radial/tabular layout) |
-| `dark-terminal` | Near-black, neon, monospace | Dev-blog architecture, agent/memory systems, network topology, data flow | Use-case (stick figures wash out on dark) |
-| `dark-luxury` | Pure-black, champagne gold | Premium/editorial architecture, agent systems, mind map, network, keynote heroes | Comparison tables, use-case, standard UML (dark bg non-standard) |
-| `arch-dark` | Dark slate, multicolor | Cloud/service architecture (existing house dark theme) | — |
-| `nature` | Light, green | Warm/organic light docs | — |
-| `high-contrast` | Accessibility | Any diagram needing max legibility | — |
-
-Notes:
-
-- **Academic policy is unchanged.** Academic/paper figures still default to the
-  `academic` / `academic-color` themes (SimSun + Times CJK stack, IEEE conventions).
-  The themes above target product/architecture/dev-doc contexts and do not override
-  academic overlay selection.
-- **Glassmorphism, Flat Icon, Claude Official, OpenAI Official were not ported** —
-  see `.trellis/tasks/07-11-fw-style-presets/research/style-triage.md` for the
-  token-level rationale (overlap or non-portable gradients/blur/rgba).
-- Dark themes rely on solid color tokens only; source SVG gradients, glow/blur
-  filters and drop-shadows are intentionally dropped (recorded in the triage).

package/template/.agents/skills/drawio/references/docs/upstream-capability-compatibility.md

@@ -1,61 +0,0 @@
-# Upstream Capability Compatibility
-
-This is the authoritative functional-equivalence map from the 37 Python scripts in upstream `drawio-skill` 1.34.0 to this repository's 2.7.0 base skill. It maps jobs, not command names or intermediate formats.
-
-Mapping meanings:
-
-- `bridge`: an existing base capability already owns the job.
-- `adapt`: the useful input or transform semantics were retained behind the canonical boundary.
-- `replace`: the job was rebuilt around canonical YAML, offline execution, stable identity, or a stricter trust boundary.
-- `defer`: the job is not shipped; the reason and evidence gap remain explicit.
-
-Evidence labels are deliberately narrow. `command-executed` means the checked-in deterministic path ran. It does not prove Desktop, Graphviz, a provider environment, a visual model, a browser/MCP provider, or PR automation unless that executor is named.
-
-## Authoritative Matrix
-
-| Upstream script | Mapping | Owner or replacement entry | Reason | Evidence state |
-| --- | --- | --- | --- | --- |
-| `aiicons.py` | `replace` | base AI icon catalog and `icon-resolver.js` | Replaces CDN lookup with 309 fixed, licensed, offline canonical SVG brands and deterministic aliases. | catalog, security, render, and Desktop fixture checks command-executed; model review missing evidence |
-| `autolayout.py` | `replace` | canonical renderer and vendored JavaScript ELK | Removes the default Graphviz XML generator and keeps one layout and renderer path. | canonical ELK and XML suites command-executed; Graphviz parity missing evidence |
-| `buildup.py` | `defer` | no shipped entry | Animation and GIF export require a separate vocabulary, optional image tooling, and visual evidence. | missing evidence |
-| `c4.py` | `replace` | canonical page bundle v1 and structured page links | Replaces direct Python XML generation with stable page and object identity plus round-trip validation. | multi-page schema, import, render, sidecar, and round-trip suites command-executed; Desktop multi-page export missing evidence |
-| `ciimports.py` | `adapt` | `ci.js` through canonical graph projection | Retains GitHub Actions and GitLab job relationships with stable provider, workflow, and job identity. | saved fixture and canonical render tests command-executed; includes and real-repository corpus missing evidence |
-| `composeimports.py` | `adapt` | `compose.js` through canonical graph projection | Retains service, dependency, and volume semantics with shared project and service identity. | saved fixture and canonical render tests command-executed; profiles and includes missing evidence |
-| `compress.py` | `defer` | no shipped entry | Heuristic clustering cannot honestly claim a semantically correct executive narrative without a separate contract and review evidence. | missing evidence |
-| `dockerimports.py` | `adapt` | `docker-inspect.js` and graph drift | Normalizes saved inspect JSON to shared Compose service identity without daemon capture or container-instance persistence. | saved snapshot, drift, sentinel, ELK, and XML tests command-executed; real daemon and swarm evidence missing evidence |
-| `drawio2mermaid.py` | `adapt` | `postprocess mermaid` | Projects canonical single-page or selected bundle content to deterministic Mermaid without parallel XML parsing. | postprocess projection and CLI tests command-executed |
-| `drawio2pptx.py` | `defer` | no shipped entry | PPTX needs draw.io Desktop images, presentation layout rules, and an optional presentation library. | missing evidence |
-| `drawiodiff.py` | `replace` | stable projection drift and canonical drift rendering | Replaces cell-id or label matching with stable node, edge, and important-attribute identity states. | file-backed report, canonical spec, ELK, XML, and sentinel tests command-executed; provider, Desktop, and model evidence missing evidence |
-| `drawiohtml.py` | `replace` | `postprocess html` | Produces script-free, self-contained HTML from canonical pages with escaping and no external assets. | deterministic HTML, injection, and CLI tests command-executed; browser execution missing evidence |
-| `encode_drawio_url.py` | `bridge` | `scripts/runtime/diagrams-net-url.js` | The existing fragment encoder already creates a diagrams.net handoff without a server query payload. | URL unit tests command-executed; live browser handoff missing evidence |
-| `explain.py` | `adapt` | `postprocess explain` | Reports only observable canonical structure and metadata as deterministic Markdown. | postprocess projection and CLI tests command-executed |
-| `goimports.py` | `adapt` | `go-code.js` through canonical graph projection | Uses an optional pinned Node parser and never invokes the Go toolchain or Graphviz. | small source fixtures and parser integration command-executed; workspace and build-tag corpus missing evidence |
-| `heatmap.py` | `adapt` | `postprocess heatmap` | Applies bounded local metrics by stable address or identity while preserving canonical metadata. | mutation, safety, renderer, and CLI tests command-executed |
-| `jsimports.py` | `adapt` | `js-code.js` through canonical graph projection | Uses the pinned ESM lexer, stable project-relative identity, and the existing ELK path. | small source fixtures and parser integration command-executed; CJS and path-alias corpus missing evidence |
-| `k8simports.py` | `adapt` | `kubernetes.js` for declared and saved live JSON | Shares scope, namespace, kind, and name identity across declared and live projections. | JSON, YAML, live snapshot, identity, and render tests command-executed; real cluster and CRD scope evidence missing evidence |
-| `openapiimports.py` | `adapt` | `openapi.js` through canonical graph projection | Uses method and normalized path identity instead of traversal ordinals. | saved fixture and canonical render tests command-executed; callbacks, webhooks, and external refs missing evidence |
-| `prdiff.py` | `defer` | no shipped entry | Git refs, rendering providers, permissions, dependency downloads, and PR comments require a governed opt-in workflow. | missing evidence |
-| `pyclasses.py` | `adapt` | `python-code.js` and fixed Python AST worker | Retains class inheritance with qualified module identity and an isolated optional parser. | small source fixtures and worker integration command-executed; large and ambiguous corpus missing evidence |
-| `pyimports.py` | `adapt` | `python-code.js` and fixed Python AST worker | Retains intra-project imports while removing Graphviz and mutable graph-JSON coupling. | small source fixtures and worker integration command-executed; large repository corpus missing evidence |
-| `raster2drawio.py` | `adapt` | `--input-format raster-extraction` | Accepts strict versioned visual-extraction JSON, then reuses canonical validation, ELK, renderer, and sidecars. | file-backed parser, CLI, geometry, and canonical render tests command-executed; OCR and model fidelity missing evidence |
-| `relabel.py` | `adapt` | `postprocess relabel` | Updates labels by stable page and object address without changing identity, geometry, links, or endpoints. | mutation, preservation, error, and CLI tests command-executed |
-| `repair_png.py` | `adapt` | vision-preview PNG inspector and exact IEND repair | Keeps repair only for the known valid truncated-IEND shape after structural PNG validation. | five Desktop previews and PNG structure checks command-executed; provider-backed visual model missing evidence |
-| `restyle.py` | `adapt` | `postprocess restyle` | Applies allowlisted style tokens and presets while preserving icons, identity, geometry, links, and metadata. | mutation, safety, renderer, and CLI tests command-executed |
-| `runbook.py` | `defer` | no shipped entry | Click-through flows need explicit start, branch, decision, and ambiguity semantics beyond a generic HTML viewer. | missing evidence |
-| `rustimports.py` | `adapt` | `rust-code.js` through canonical graph projection | Uses an optional pinned Node parser and never invokes Cargo, rustc, or Graphviz. | small source fixtures and parser integration command-executed; workspace, cfg, and inline-module corpus missing evidence |
-| `seqlayout.py` | `defer` | no shipped entry | A sequence authoring model needs its own UML semantics and validation rather than a postprocess shortcut. | missing evidence |
-| `shapesearch.py` | `bridge` | existing bundled catalog search | Reuses the single 10,446-entry shape index and existing ranking, validation, and suggestions. | catalog search and validation suites command-executed |
-| `sqlerd.py` | `adapt` | `sql-ddl.js` through canonical graph projection | Retains tables, keys, and relationships with schema-qualified identity and a bounded parser contract. | saved DDL fixture and canonical render tests command-executed; broad dialect corpus missing evidence |
-| `svgflow.py` | `defer` | no shipped entry | Animated SVG needs a sanitizer, animation vocabulary, provider export contract, and visual evidence. | missing evidence |
-| `tfimports.py` | `adapt` | `terraform-config.js` through canonical graph projection | Retains resource, module, and reference semantics with module-qualified stable addresses. | saved fixture and canonical render tests command-executed; multi-module corpus and real provider evidence missing evidence |
-| `tfstate.py` | `adapt` | `terraform-state.js` and graph drift | Parses saved state or plan JSON with declared identity and allowlisted attributes, without provider capture. | saved snapshot, exact identity, drift, and render tests command-executed; real provider state and aggregation evidence missing evidence |
-| `timelapse.py` | `defer` | no shipped entry | Git history checkout, importer replay, rendering, cleanup, and runtime cost need a governed isolated workflow. | missing evidence |
-| `tubemap.py` | `defer` | no shipped entry | This is a new semantic authoring and layout tool, not an existing-diagram postprocess transform. | missing evidence |
-| `validate.py` | `bridge` | `validateSpec`, document validation, and `validateXml` | The canonical pipeline already validates specs, page bundles, links, layouts, and rendered XML. | validation, schema, bundle, and XML suites command-executed |
-
-## Shared Boundaries
-
-- All adapters end at canonical spec or page bundle before JavaScript ELK and `specToDrawioXml`.
-- The base owns runtime, catalogs, schemas, identity, layout, renderer, and detailed references. The academic overlay owns publication policy only.
-- Offline authoring does not require Python, Graphviz, network, Desktop, browser, MCP, or a model. Optional parsers and export providers fail or fall back explicitly.
-- The shipped postprocess surface is exactly `mermaid`, `explain`, `relabel`, `restyle`, `heatmap`, and `html`. Deferred rows above are not implicit or hidden commands.