# Format and tool selection

The harness separates **semantic source**, **editable source**, and **publication artifact**.

| Format | Best use | Strengths | Failure mode / constraint |
|---|---|---|---|
| VizSpec JSON | Canonical meaning and evidence | Tool-neutral, lintable, traceable, deterministic | Not intended for manual presentation |
| SVG | Default publication in web/Markdown/docs | Scalable, searchable, accessible metadata, text diff | Keep scripts, external references, and `foreignObject` out |
| draw.io / diagrams.net | Enterprise architecture and official cloud stencils | Familiar manual editing, strong connector semantics, broad vendor libraries | Plain exported SVG loses editing semantics unless diagram data/source is preserved |
| Mermaid | Sequence, state, ERD, compact flow near Markdown | Small textual source, GitHub/GitLab rendering, easy review | Layout control and accessibility vary by renderer/version |
| D2 | Auto-laid-out architecture and data flow | Concise source, SVG-first output, good layout defaults | Requires D2 for native rendering beyond generated source |
| Graphviz DOT | Dense dependency and relationship graphs | Mature graph layout and crossing reduction | Less suitable for manual architecture storytelling |
| Excalidraw | Concept sketch, workshop, informal explanation | Fast visual ideation and approachable editing | Hand-drawn semantics can imply lower precision; JSON diffs are noisy |
| Structurizr DSL / C4 | Multiple architecture views from one model | One model can generate context/container/component/deployment views | Introduce when the repository needs a durable multi-view architecture model |
| PlantUML/Kroki | Broad diagrams-as-code ecosystems | Many diagram families and server rendering | Server/runtime dependency and syntax-specific portability |
| PNG | Compatibility fallback | Universal display | Raster, weak accessibility, poor scaling; never the only source |
| PDF | Print and controlled distribution | Stable pagination and vector output | Weak as an editable or repository-native source |

## Default policy

1. Always preserve VizSpec JSON.
2. Always publish SVG unless the target platform forbids it.
3. Preserve one editable source selected by intent:
   - architecture/deployment/network → draw.io;
   - sequence/state/ERD/compact flow → Mermaid;
   - data-flow/auto-layout architecture → D2;
   - dense dependency → DOT;
   - conceptual workshop visual → Excalidraw.
4. Generate PNG or PDF only as downstream delivery formats.
5. Use official provider icon packs only for explicitly named services; keep the provider's product label visible.