create-yss-spec 2.1.4 → 2.1.6

package/template/.codex/skills/drawio/references/workflows/create.md

@@ -1,195 +0,0 @@
-# Workflow: /drawio create
-
-## Provider Icon Preflight
-
-Before writing a cloud, Kubernetes, Cisco, or raw `mxgraph.*` icon, query the offline catalog from the base skill directory. Record the returned YAML syntax in the spec, then run normal validation; unknown covered names are errors, not guesses to leave for Desktop rendering.
-
-```bash
-node scripts/cli.js search pod --prefix kubernetes
-node scripts/cli.js search "s3, lambda"
-```
-
-Create diagrams from text, Mermaid, CSV, or explicit YAML spec using the Draw.io design system.
-
-## Trigger
-
-- **Command**: `/drawio create ...`
-- **Keywords**: `create`, `generate`, `make`, `draw`, `生成`, `创建`
-
-## Route Selection
-
-Determine the route before asking questions:
-
-1. **Fast Path**
-   - Use when the request already specifies the diagram type and at least 3 of: audience/profile, theme, layout, complexity.
-   - Use when the estimated graph is small (`<= 12` nodes) and not stencil-heavy.
-2. **Full Path**
-   - Use for ambiguous, large, academic, replication-like, or routing-sensitive diagrams.
-3. **Academic Branch**
-   - Force-enable when prompt contains `paper`, `academic`, `IEEE`, `journal`, `thesis`, `figure`, `manuscript`, `research`.
-   - Default `meta.profile = academic-paper`.
-   - Classify the figure as `architecture`, `roadmap`, or `workflow` before final layout and set `meta.figureType`.
-4. **Scientific Diagram Branch**
-   - Enable when the prompt mentions model architecture, CNN, YOLO, Transformer, encoder-decoder, attention, feature fusion, algorithm mechanism, ablation, experiment pipeline, or research framework.
-   - Keep this branch in the base skill unless the request is publication-facing; route paper/thesis/journal/manuscript requests through the Academic Branch.
-   - Classify the drawing intent before YAML:
-     - model or system architecture -> modules, semantic node types, compact layer labels;
-     - method workflow or experiment pipeline -> ordered steps, branches, feedback, validation;
-     - operation or mechanism figure -> explicit `bounds`, small native cells, formulas, callouts, and off-line edge labels;
-     - reference redraw -> use `/drawio replicate` inventory rules and `meta.source: replicated`.
-   - For complex figures, write a short diagram plan before rendering: figure purpose, major sections/modules, key arrows, formula/callout placement, and verification artifact.
-5. **Math / Formula Branch**
-   - Enable when the prompt mentions `formula`, `equation`, `LaTeX`, `AsciiMath`, `MathJax`, `loss function`, `derivation`, `symbol legend`, `公式`, `行内公式`, or `行间公式`.
-   - Load `references/docs/math-typesetting.md` as the syntax source of truth.
-   - Load `references/docs/design-system/formulas.md` for formula-node placement and sizing.
-6. **Stencil Branch**
-   - Enable when the prompt mentions AWS, Azure, GCP, Cisco, Kubernetes, or vendor icons.
-   - Use `references/docs/stencil-library-guide.md` to decide whether `search_shape_catalog` would help or whether semantic/icon fallbacks are sufficient.
-
-## Procedure
-
-```text
-Step 1: Identify Input Mode
-├── Natural language
-├── YAML spec
-├── Mermaid (flowchart/sequence/class/state/ER/gantt)
-└── CSV hierarchy/org chart
-
-Step 2: Determine profile and theme defaults
-├── academic-paper -> theme academic by default
-├── academic-paper + explicit color request -> academic-color
-├── engineering-review -> theme tech-blue by default
-└── otherwise -> theme from request or tech-blue
-
-Step 3: Classify academic figure intent when profile=academic-paper
-├── structure / modules / runtime interaction -> meta.figureType=architecture
-├── stage progression / milestones / study phases -> meta.figureType=roadmap
-└── ordered execution / branching / fallback / loop -> meta.figureType=workflow
-
-Step 4: Classify scientific diagram intent when relevant
-├── model architecture -> modules for stages, semantic types for layers/operators
-├── method workflow / experiment pipeline -> ordered steps, decisions, loops
-├── system architecture paper figure -> tier/layer grouping and compact responsibilities
-├── mechanism / operation figure -> native cells, formulas, callouts, explicit bounds
-└── reference-image redraw -> switch to replicate inventory rules
-
-Step 5: Decide Fast Path vs Full Path
-├── Fast Path -> skip AskUserQuestion and skip ASCII confirmation
-└── Full Path -> continue to Step 6
-
-Step 6: Design Consultation (Full Path only)
-├── Ask only unresolved questions:
-│   • audience/profile
-│   • theme
-│   • layout
-│   • figureType when academic intent is still ambiguous
-│   • scientific drawing intent when model/workflow/operation intent is ambiguous
-│   • expected complexity
-└── Store decisions in designIntent and pre-fill YAML meta
-
-Step 7: Academic / Math / Stencil references
-├── math/formula request -> load math typesetting + formula integration guide
-├── academic-paper -> load academic figure playbook + export checklist + IEEE + math typesetting
-├── scientific model/operation request -> consult academic figure playbook patterns even when profile is non-academic
-└── stencil-heavy -> decide whether shape search is needed
-    ├── if `search_shape_catalog` exists, use it for exact vendor/device lookup
-    └── otherwise use design-system icons or semantic fallbacks
-
-Step 8: Build the YAML spec
-├── Normalize Mermaid/CSV inputs to YAML spec
-├── Ensure meta.theme, meta.layout, meta.profile are present
-├── Ensure meta.figureType is present when profile=academic-paper
-├── For model architectures, prefer `modules` plus semantic types such as `input`, `conv`, `pool`, `attention`, `feature`, `tensor3d`, `operator`, `loss`, and `output`
-├── For operation figures, use explicit `bounds` for grids/formulas/callouts instead of relying only on auto layout
-├── Use semantic node types and typed connectors
-└── Add manual positions when branching or dense routing requires it
-
-Step 9: ASCII Draft (Full Path only)
-├── Render semantic ASCII draft
-├── Include Design Summary:
-│   • theme
-│   • profile
-│   • figureType
-│   • layout
-│   • node/edge/module counts
-│   • validation status
-│   • scientific diagram intent when applicable
-└── Pause for confirmation only when logic or structure is still ambiguous
-
-Step 10: Validation
-├── validateColorScheme()
-├── validateLayoutConsistency()
-├── validateConnectionPointPolicy()
-├── validateEdgeQuality()
-├── validateAcademicProfile() when profile=academic-paper
-└── checkComplexity()
-
-Step 11: Edge Audit
-├── No corner connection points
-├── No shared face slots on the same corridor
-├── Last segment >= 30px
-├── Labels offset from edge lines
-├── No waypoint + explicit connection-point mixing
-└── Prefer straight arrows when alignment allows it
-
-Step 12: Render
-├── node <skill-dir>/scripts/cli.js input --input-format <yaml|mermaid|csv> output.drawio --validate --write-sidecars --sidecar-dir .drawio-tmp/output
-├── For paper-quality diagrams prefer output.svg --validate --write-sidecars --sidecar-dir .drawio-tmp/output
-├── For thesis / A4 / Word / PNG requests, add a matching PNG only when draw.io Desktop export is available
-├── Note: standalone SVG (without --use-desktop) replays anchors/waypoints and approximates orthogonal routes (L/Z bends).
-│   For exact Desktop routing (jetty spacing, obstacle avoidance), add --use-desktop or refine in draw.io.
-└── When embedded export matters and draw.io Desktop exists, add --use-desktop for SVG or export to PNG/PDF/JPG
-
-Step 13: Exported-Artifact Verification / Optional Live Handoff
-├── Inspect the exported SVG first when it is available and readable by the current environment
-├── If a raster/final-fidelity check is needed and draw.io Desktop is available -> export PNG/PDF/JPG or embedded SVG through the CLI
-├── For structured findings or repeated rework, follow `visual-review.md` and patch canonical YAML by stable ID
-├── Do not create browser or Playwright screenshots when an exported SVG/PNG/PDF/JPG exists
-├── live backend has `replace_diagram_xml` + user wants browser or inline refinement
-│   └── use the provider-specific tool mapping from `references/docs/mcp-tools.md`
-├── browser/live screenshots are a last-resort review aid only when the user explicitly requested live review and no exported artifact can be inspected
-└── otherwise present .drawio + standalone SVG and report any remaining manual visual check
-```
-
-## Academic Branch Rules
-
-When `meta.profile = academic-paper`:
-
-- `meta.figureType` is required and must be exactly `architecture`, `roadmap`, or `workflow`.
-- `meta.title` is required for figure captioning.
-- `meta.description` is recommended for figure context.
-- `meta.legend` is required when icons are used or connector types are mixed.
-- Prefer `academic` theme unless the request explicitly asks for a color paper figure.
-- Default final deliverables are `.drawio` and `.svg`; keep `.spec.yaml` and `.arch.json` in a project-local work directory unless a sidecar bundle is explicitly requested.
-- Add `.png` only for thesis, A4, Word, raster-first, screenshot rebuild, or explicit PNG requests.
-- Do not rely on color alone to distinguish semantics.
-- Treat A4 readability and grayscale print safety as final review gates, not optional polish.
-
-## Scientific Diagram Rules
-
-- Use native draw.io primitives for the main figure: modules, shapes, text/formula nodes, connectors, waypoints, and `labelOffset`.
-- Model architectures should use modules for stages such as Input, Backbone, Fusion/Neck, Head, Loss, or Output. Do not flatten every layer into identical generic boxes when semantic layer types are available.
-- Operation/mechanism figures should keep the visual grammar small and explicit: one operation window, one output, one formula/callout, and arrows with labels offset away from connector lines.
-- Experiment pipelines should separate data/setup, method, variants, validation, and metrics. Keep ablation branches visually parallel and converge them before evaluation.
-- Reference-image scientific redraws should follow `/drawio replicate`: inventory first, `meta.source: replicated`, explicit `meta.canvas` when coordinate fidelity matters, and no full-page embedded reference image.
-- Keep labels short enough for paper or slide use. Prefer a caption/legend or nearby `text` node over long prose inside architecture blocks.
-
-## Math / Formula Branch Rules
-
-When the request includes formulas, equations, or math-heavy labels:
-
-- Use `$$...$$` only for standalone equations or labels that are entirely formula content.
-- Use `\(...\)` for sentence-level inline math inside a longer label.
-- Use `` `...` `` only when the user explicitly prefers AsciiMath or when the notation is simple.
-- Do not generate bare LaTeX, `$...$`, or `\[...\]` in final YAML/XML output.
-- Tell the user to enable `Extras > Mathematical Typesetting` when raw formulas may be edited in draw.io.
-- For PDF exports where selectable math matters, recommend `math-output=html`.
-
-## Notes
-
-- YAML remains the canonical intermediate representation.
-- `.drawio` is the editable final artifact; `.spec.yaml` and `.arch.json` remain the canonical offline sidecars in the work directory unless the user explicitly requests a beside-output bundle.
-- Mermaid and CSV inputs are convenience adapters, not separate rendering pipelines.
-- For formula-bearing labels, use only the three supported syntaxes: `$$...$$`, `\(...\)`, and `` `...` ``.
-- Stencil-heavy requests may use shape search when available, but the create flow must still succeed without it.
-- Academic figures should not blend structure, progression, and control flow into one ambiguous visual grammar.

package/template/.codex/skills/drawio/references/workflows/edit.md

@@ -1,174 +0,0 @@
-# Workflow: /drawio edit
-
-## Provider Icon Changes
-
-When adding or replacing a provider/device icon, search before editing YAML: `node scripts/cli.js search <keyword> [--prefix <library>]`. Keep the returned skill syntax, rerun validation, and use `--allow-unknown-shapes` only to retain an intentional legacy raw stencil.
-
-Edit existing diagrams with natural-language modifications while preserving design-system consistency and explicit live-backend fallback rules.
-
-## Trigger
-
-- **Command**: `/drawio edit ...`
-- **Keywords**: `edit`, `modify`, `update`, `change`, `编辑`, `修改`
-
-## Live Capability Gate
-
-Incremental live edit is allowed only when the active provider supports **both**:
-
-- `read_diagram_xml`
-- `patch_diagram_cells`
-
-If either capability is missing, do **not** attempt to edit the browser state directly. Import the `.drawio` file into a YAML bundle first, then regenerate offline.
-
-## Procedure
-
-```text
-Step 1: Identify Target
-├── Option A: Existing offline bundle (.drawio + .spec.yaml)
-│   └── Preferred path when the skill created the original diagram
-├── Option B: Existing .drawio file without sidecar
-│   └── Import to YAML spec first, then regenerate
-├── Option C: Current live session
-│   └── Only when the active provider has `read_diagram_xml + patch_diagram_cells`
-└── Option D: Raw XML provided inline
-    └── Treat as expert-mode patch input, usually normalize to offline bundle after the first edit
-
-Step 2: Choose Edit Mode
-├── Sidecar exists -> edit YAML spec, regenerate .drawio, keep sidecars in sync
-├── No sidecar -> import .drawio to YAML spec bundle, then edit spec and regenerate
-├── Live session + required capabilities -> read current XML, patch incrementally, export if needed
-└── Live provider lacks required capabilities -> treat it as preview only and return to offline import/regenerate
-
-Step 3: Understand Current State
-├── Offline sidecar path -> read .spec.yaml and .arch.json first
-├── Import path -> run CLI import, then read .spec.yaml and .arch.json
-├── Live path -> read current browser XML before planning edits
-└── Detect current theme/profile/layout before applying changes
-
-Step 4: Parse Edit Instructions
-├── Add operations (new nodes/edges)
-├── Modify operations (change labels/styles)
-├── Delete operations (remove elements)
-├── Layout operations (rearrange / regenerate)
-└── Theme operations (switch theme)
-
-Step 5: Draft Modification & Confirm (For restructure)
-├── If the edit involves major structural reorganization:
-│   ├── Present the modified logical flow as an ASCII text-art graph
-│   └── Pause for user's confirmation before applying
-└── For minor edits (labels/colors/themes), proceed directly
-
-Step 6: Apply Changes
-├── Offline sidecar path -> update YAML, rerun CLI with --write-sidecars
-├── Import path -> write a fresh YAML spec bundle, then regenerate outputs
-├── Live path -> batch cell patches only after reading the latest XML
-└── Keep .drawio, .spec.yaml, and .arch.json aligned after each accepted edit
-
-Step 7: Verify and Iterate
-├── Export a work-dir preview if needed (Desktop PNG/SVG or standalone SVG)
-├── Follow `visual-review.md` for structured issues, stable-ID YAML patches, and stopping rules
-├── User reviews changes
-└── Rerun validation and overwrite the same preview after each accepted modification
-```
-
-## Design-System Preservation
-
-### Theme Consistency
-
-When editing, preserve the current theme unless the user asks to switch it:
-
-| Edit Type    | Theme Behavior                           |
-| ------------ | ---------------------------------------- |
-| Add node     | Uses current theme's node style          |
-| Add edge     | Uses current theme's connector style     |
-| Modify style | Suggest theme-compatible colors          |
-| Switch theme | Re-applies all styles from the new theme |
-
-### Semantic Type Changes
-
-Change a node's semantic type to update its shape:
-
-```text
-/drawio edit
-Change "User Service" from service to database type
-```
-
-### Batch Operations
-
-For efficiency, batch multiple changes in one planning pass. If the active live provider has the required capabilities, those changes may be turned into one patch batch. Otherwise regenerate from the YAML bundle once.
-
-## Preferred Operation Mapping
-
-| Operation              | Preferred Path                           | Notes                                |
-| ---------------------- | ---------------------------------------- | ------------------------------------ |
-| Update label           | YAML sidecar (or import to sidecar)      | Preserves style                      |
-| Update style           | YAML sidecar (or import to sidecar)      | Use theme tokens                     |
-| Change type            | YAML sidecar (or import to sidecar)      | Updates shape                        |
-| Add node               | YAML sidecar                             | Apply semantic type                  |
-| Add edge               | YAML sidecar                             | Apply connector type                 |
-| Delete                 | YAML sidecar (or import to sidecar)      | Keeps bundle coherent                |
-| Move                   | YAML sidecar (or import to sidecar)      | Snap to 8px grid                     |
-| Switch theme           | Regenerate from YAML                     | Re-apply all tokens                  |
-| Live incremental patch | Live provider with required capabilities | Requires current XML read-back first |
-
-> When editing labels or styles, keep text and labels transparent and content-sized: text, callouts, captions, and legends use `fillColor=none` + `labelBackgroundColor=none` (no white box), and a text box should be just wider than its content, not stretched to match a container. See `../docs/design-system/tokens.md` § Text & Label Styling.
-
-## Examples
-
-### Quick Label Update
-
-```text
-/drawio edit
-Rename "User Auth" to "Authentication Service"
-```
-
-### Import Then Edit
-
-```text
-/drawio edit
-Import this existing .drawio file, rename API to Auth, then regenerate the SVG
-```
-
-### Theme-Aware Style Update
-
-```text
-/drawio edit
-Apply these changes:
-- All service nodes: use primary color
-- All database nodes: use secondary color
-- All data flows: use dashed connector style
-```
-
-### Complex Restructure
-
-```text
-/drawio edit with restructure
-Reorganize into 3 modules with academic theme and horizontal layout
-```
-
-## Troubleshooting
-
-### No live incremental edit capability
-
-- Import the current `.drawio` into `.spec.yaml` + `.arch.json`
-- Apply the change offline
-- Regenerate outputs instead of trying to patch the browser state
-
-### Existing `.drawio` has no sidecar
-
-- Run CLI import first
-- Treat the imported YAML bundle as the new canonical source
-
-### Style looks wrong after edit
-
-- Verify theme is consistent
-- Check whether the node type changed accidentally
-- Re-apply the theme if mixed styles appeared after a manual patch
-
-## Related
-
-- [Live Backend Reference](../docs/mcp-tools.md)
-- [Migration Readiness](../docs/migration-readiness.md)
-- [Design System Overview](../docs/design-system/README.md)
-- [Themes Reference](../docs/design-system/themes.md)
-- [Specification Format](../docs/design-system/specification.md)

package/template/.codex/skills/drawio/references/workflows/replicate.md

@@ -1,239 +0,0 @@
-# Workflow: /drawio replicate
-
-## Provider Icon Evidence
-
-Do not infer a raw stencil name from a screenshot. For each cloud, Kubernetes, or network icon that must remain vendor-specific, run `node scripts/cli.js search <keyword>` and use the returned YAML syntax. If the catalog cannot confirm it, retain the semantic role rather than inventing an icon.
-
-Replicate existing images or diagrams using structured extraction with design-system styling, native editable draw.io geometry, and explicit live-backend boundaries.
-
-## Trigger
-
-- **Command**: `/drawio replicate ...`
-- **Keywords**: `replicate`, `recreate`, `复刻`, `复现`, `重绘`
-
-## Procedure
-
-```text
-Step 1: Receive Input
-├── Image upload (required)
-└── Optional: accompanying text description
-
-Step 2: Configuration
-├── Select domain (software architecture, research, etc.)
-├── Select theme (tech-blue default, academic for papers)
-├── Select color mode (preserve-original default, theme-first optional)
-└── Specify language (Chinese/English)
-
-Step 3: Structured Extraction
-├── Analyze image structure
-├── Record source canvas:
-│   ├── source image width and height
-│   ├── background/canvas color
-│   └── intended `meta.canvas` value (`auto` or WIDTHxHEIGHT)
-├── Extract source color summary:
-│   ├── background/canvas color
-│   ├── 3-6 dominant flat colors
-│   ├── node / edge / module color assignments
-│   └── confidence notes for uncertain regions
-├── Native Reference Inventory:
-│   ├── panel or region bounds in top-left coordinates
-│   ├── native shapes, labels, styles, and uncertainty notes
-│   ├── connector endpoints, waypoints, labels, and offsets
-│   ├── dense motifs that will be approximated with native simplified shapes
-│   └── any temporary tracing image that must not remain as final full-page content
-├── Text Fidelity Pass:
-│   ├── extract every text-bearing element as shape label, edge label, standalone text, or formula annotation
-│   ├── record text bounds, baseline/anchor, alignment, font family, font size, italic/bold state, and spacing
-│   ├── plain text boxes are always transparent (`fillColor=none;strokeColor=none;labelBackgroundColor=none`); never assign the canvas/background color to a text fill — the converter ignores such fills and warns; use a `formula` node or a shape node when a filled label is intended
-│   ├── vertical CJK labels are one character per line (`label: "可\n视\n化"`); never a narrow box relying on wrap, never `horizontal=0`
-│   ├── record relative offset from the nearest arrow, connector, node, module, or canvas boundary
-│   └── preserve math delimiters for formulas (`$$...$$`, `\(...\)`, or AsciiMath backticks)
-├── Extract to YAML specification format:
-│   ├── `meta.source: replicated`
-│   ├── `meta.canvas` from the source page size when coordinate fidelity matters
-│   ├── nodes with semantic types
-│   ├── edges with connector types
-│   ├── modules for grouping
-│   ├── standalone text/formula nodes with explicit `bounds` when needed
-│   ├── edge labels with `labelPosition` and `labelOffset` when needed
-│   └── explicit style overrides for high-confidence colors
-├── Apply semantic shape mapping
-└── Mark missing info as "Not specified" (未提及)
-
-Step 4: Logic Verification (Mandatory)
-├── Translate structural analysis into a pure ASCII logical flow graph
-├── Summarize the extracted palette and where each color will be applied
-├── Summarize text placement: boxes, formulas, edge-label offsets, and any uncertain baselines
-└── Pause for user's confirmation to ensure no misinterpretation
-
-Step 5: Stencil Decision
-├── If the diagram is vendor/device heavy:
-│   ├── use `search_shape_catalog` when available
-│   └── otherwise fall back to documented icon mappings or semantic shapes
-└── If the diagram is conceptual or academic, skip shape search and stay semantic
-
-Step 6: Convert to Diagram
-├── Parse specification via scripts/dsl/spec-to-drawio.js
-├── Apply selected theme
-├── Keep `meta.replication.background` as canvas background when provided
-├── Use `meta.canvas: WIDTHxHEIGHT` as the minimum draw.io page size when mapping reference coordinates
-├── Calculate 8px grid positions for structure
-├── Preserve explicit top-left `bounds` for high-fidelity text boxes and formula annotations
-├── Size each text box just wider than its content, not the full source region, so it stays an independent movable element (see ../docs/design-system/tokens.md § Text & Label Styling)
-├── Apply `labelOffset` so connector labels sit 12-20px off the line by default
-├── Generate .drawio + .spec.yaml + .arch.json offline first
-├── Export standalone SVG first; if a raster/final-fidelity check is needed and draw.io Desktop is available, export PNG/PDF/JPG or embedded SVG through the CLI
-├── Do not create browser or Playwright screenshots when an exported SVG/PNG/PDF/JPG exists
-└── Only use a live backend for preview/refinement when the user explicitly wants it
-
-Step 7: Review and Refine
-├── Compare the original image with the exported SVG or Desktop-exported image when a viewer or vision path can inspect it
-├── Follow `visual-review.md` to record source-mismatch and placement issues, then patch canonical YAML by stable ID
-├── Compare text placement: no labels on top of lines, no formulas touching borders, matching relative title/caption/callout positions
-├── For scientific figures, compare stage grouping, formula/callout placement, legend/caption fidelity, and whether model/operation elements are native editable cells
-├── Default to /drawio edit in offline mode
-├── Live providers with `render_inline_preview` may help review only after exported-artifact verification is unavailable or insufficient
-└── Providers without `read_diagram_xml + patch_diagram_cells` still do not replace the offline edit path
-
-Step 8: Validate
-├── Check cell ID uniqueness
-├── Check edge source/target reference validity
-├── Check every connector is a native bound edge (`source` + `target` set); `--validate` warns on floating edges and on arrow shapes (`singleArrow`/`triangle`/`mxgraph.arrows2.*`) posing as connectors
-├── Check straightness: no-waypoint orthogonal edges must be collinear (same absolute exit/entry coordinate); `--validate` reports avoidable bends
-├── Check plain text boxes are transparent (`fillColor=none`); `--validate` warns on white-filled `text;` cells
-├── Check required root cells present
-├── Check `--validate` does not report a full-page embedded image cell
-├── Check text-label clearance: no edge label overlaps its connector or another label, no formula is clipped or pasted to a boundary (label-collision lint reports these)
-├── For screenshot/academic replication, record at least one original-vs-export visual comparison from exported SVG/PNG/PDF/JPG when vision or a viewer can inspect it
-├── Use browser/live screenshots only as a last-resort review aid when the user explicitly requested live review and no exported artifact can be inspected
-└── Use --validate CLI flag or validateXml() from DSL converter
-```
-
-## Design-System Integration
-
-### Native Reference Rebuild Contract
-
-Do not satisfy a reference rebuild by placing the uploaded image as the whole draw.io page. The final `.drawio` must be editable native content: shapes, text, connectors, modules/groups, waypoints, labels, styles, and simplified motifs.
-
-Temporary image use is allowed only for analysis or tracing. If an image layer is used while drafting, remove it before delivery or keep it clearly outside the final page. The final validation pass should reject a full-page image cell that covers the canvas.
-
-Use this inventory shape for complex rebuilds:
-
-```yaml
-source:
-  file: reference.png
-  canvas: 1200x800
-  background: "#FFFFFF"
-regions:
-  - id: left-panel
-    label: Data preparation
-    bounds: { x: 32, y: 72, width: 336, height: 560 }
-shapes:
-  - id: extract
-    label: Extract
-    type: service
-    bounds: { x: 80, y: 144, width: 168, height: 56 }
-connectors:
-  - from: extract
-    to: train
-    label: features
-    waypoints:
-      - { x: 320, y: 172 }
-    labelOffset: { x: 0, y: -16 }
-palette:
-  - hex: "#FDBA74"
-    role: warm process fill
-    appliesTo: nodes
-    confidence: high
-approximations:
-  - "Heatmap thumbnail becomes a 5x4 grid of small native rectangles."
-```
-
-Convert that inventory into the canonical YAML spec. Use `meta.canvas` to preserve the reference coordinate system:
-
-```yaml
-meta:
-  source: replicated
-  canvas: 1200x800
-  replication:
-    colorMode: preserve-original
-    background: "#FFFFFF"
-```
-
-`meta.canvas` is a minimum page size, not a crop. If native shapes extend beyond it, the renderer expands the page to keep content editable and visible.
-
-### Theme Selection by Domain
-
-| Domain                           | Recommended Theme | Reason                          |
-| -------------------------------- | ----------------- | ------------------------------- |
-| 软件架构 (Software Architecture) | tech-blue         | Professional technical style    |
-| 商业流程 (Business Process)      | tech-blue         | Clean corporate look            |
-| 科研流程 (Research Workflow)     | academic          | IEEE-compatible, grayscale-safe |
-| 工业流程 (Industrial Process)    | tech-blue         | Clear technical diagrams        |
-| 项目管理 (Project Management)    | tech-blue         | Standard project visuals        |
-| 教学设计 (Teaching Design)       | nature            | Friendly, accessible colors     |
-
-### Scientific Redraw Priorities
-
-For research-framework screenshots, model architecture figures, operation diagrams, or algorithm illustrations, preserve meaning before decoration:
-
-1. Rebuild the figure as native editable cells, not a pasted page image.
-2. Preserve text-bearing regions: title, caption, legend, section headers, formula blocks, callouts, and edge labels.
-3. Use `bounds` for standalone labels, formulas, small grid cells, matrix cells, heatmap motifs, or annotations whose location carries meaning.
-4. Use semantic deep-learning types when they match the source: `input`, `tensor3d`, `conv`, `pool`, `attention`, `feature`, `operator`, `loss`, and `output`.
-5. Use modules for visual sections such as Backbone, Fusion, Head, Experiment Setup, Validation, or Metrics.
-6. Preserve or normalize the source palette intentionally. If exact colors are uncertain, record confidence in `meta.replication.palette` and keep the final figure grayscale-safe for academic use.
-7. Keep connector labels off the line with `labelOffset`; give formula and legend boxes breathing room before polishing colors.
-
-### Semantic Shape Mapping
-
-During extraction, map visual elements to semantic types:
-
-| Visual Element                | Semantic Type                                 | Draw.io Shape                |
-| ----------------------------- | --------------------------------------------- | ---------------------------- |
-| Rectangle/Box                 | `service`                                     | Rounded rectangle            |
-| Cylinder/Drum                 | `database`                                    | Cylinder                     |
-| Diamond                       | `decision`                                    | Rhombus                      |
-| Oval/Rounded rect             | `terminal`                                    | Stadium                      |
-| Parallelogram                 | `queue`                                       | Parallelogram                |
-| Person/Stick figure           | `user`                                        | Circle                       |
-| Document shape                | `document`                                    | Wave rect                    |
-| Math formula                  | `formula`                                     | White rect with border       |
-| Caption, callout, legend note | `text`                                        | Standalone text box          |
-| CNN/Transformer layer         | `conv`, `pool`, `attention`, `norm`, `matrix` | Deep-learning semantic block |
-| Feature map / tensor          | `tensor3d`                                    | Cube-like feature-map block  |
-| Add/concat/gate operator      | `operator`                                    | Small circular operator      |
-
-### Connector Type Mapping
-
-| Visual Style  | Connector Type  | Output Style             |
-| ------------- | --------------- | ------------------------ |
-| Solid arrow   | `primary`       | Solid 2px, open arrow    |
-| Dashed arrow  | `data`          | Dashed 2px, open arrow   |
-| Dotted line   | `optional`      | Dotted 1px, open arrow   |
-| Diamond end   | `dependency`    | Solid 1px, diamond       |
-| Double-headed | `bidirectional` | Solid 1.5px, no arrow    |
-
-All connectors are native bound edges (`source`/`target` node ids) — never standalone arrow shapes. Connector heads default to a bold open "V" (`endArrow=open;endSize=12`); explicitly-requested `block`/`classic` and UML/ER markers stay filled (`endFill=1;endSize=12`); override via `edge.style.endArrow` / `edge.style.endSize`. Two opposite arrows between the same pair of shapes ("bidirectional pair") render as two parallel straight lines ≥30px apart automatically.
-
-## Extraction Rules
-
-1. Only use content from the input. Never invent missing labels or structures.
-2. Mark missing facts as `Not specified` / `未提及`.
-3. Keep YAML spec as the canonical result, even if a live preview is opened later.
-4. Preserve the source palette by default and store it in `meta.replication`.
-5. Use `meta.canvas: WIDTHxHEIGHT` when the source coordinate system matters; keep `auto` for ordinary regenerated diagrams.
-6. Never deliver the final rebuild as a full-page embedded image.
-7. If a live provider is used, treat it as preview/refinement only unless it also satisfies the edit-session capability gate from `/drawio edit`.
-8. Treat standalone text, captions, callouts, legends, and formula annotations as first-class replicated elements; do not force them into nearby shapes when their separate position carries meaning.
-9. Use `bounds: {x, y, width, height}` for high-fidelity text boxes. `bounds` uses top-left coordinates; `position` remains a center-point convenience for ordinary nodes.
-10. For labeled connectors, omitting `labelOffset` now yields a content-aware default (8px clearance plus half the label extent, matching draw.io's center-on-offset-point behavior). Give an explicit `labelOffset` only to pick a side (negative to flip outward) or to clear a neighboring line; on bent fallback edges offset perpendicular to the middle segment.
-11. Fix failures in this order: (a) wrong/missing text, (b) formula delimiters/font, (c) `bounds` and baselines, (d) `labelOffset`, (e) connector waypoints/routing, (f) color/style polish, (g) accidental full-page image cells.
-
-## Related
-
-- [Migration Readiness](../docs/migration-readiness.md)
-- [Live Backend Reference](../docs/mcp-tools.md)
-- [Design System Overview](../docs/design-system/README.md)
-- [Specification Format](../docs/design-system/specification.md)
-- [Stencil Library Guide](../docs/stencil-library-guide.md)