diagrams-drawio/references/capabilities.md

# drawio-main — Capabilities

This file lists all capabilities an agent can use from this skill.

---

## Capability 1 — Deterministic YAML generation

Build native `.drawio` XML from a validated semantic Diagram IR:

```bash
node dist/cli/commands.js --action build --file architecture.yaml --output architecture.drawio
```

IR v1 remains compatible. IR v2 adds multiple pages, containers and semantic kinds, explicit geometry, waypoints, provenance/properties/extensions, and `linear`, `layered`, `tree`, `grid`, or `manual` layout. Dependency-aware placement and obstacle-aware orthogonal routing are deterministic. The builder rejects reserved/duplicate IDs, unknown parents/endpoints, malformed geometry, and unsupported versions before writing output. See `schemas/diagram-ir-v2.schema.json` and `examples/platform-v2.yaml`.

---

## Capability 2 — Direct XML generation

Create `.drawio` files (and optionally export to PNG/SVG/PDF) from a description or requirements.

See [SKILL.md](../SKILL.md) for the generation workflow, XML format, page sizes, element shapes, and well-formedness rules.
See [rules-layout.md](./rules-layout.md) for mandatory connector and layout rules.

---

## Capability 3 — Semantic lifecycle

The native TypeScript core supports loss-aware Draw.io import and deterministic round trips; transactional stable-ID edit batches; linked audience views; semantic query, architecture policy, and failure what-if analysis; three-way synchronization; accessible self-contained story HTML; and a non-launching doctor report.

See [semantic-lifecycle.md](./semantic-lifecycle.md) for command contracts, safety behavior, built-in policy identifiers, and examples.

---

## Capability 4 — Diagram analysis (drawio-tools CLI)

A **TypeScript / Node.js** CLI tool for programmatic analysis of `.drawio` files.  
Entry point: `node dist/cli/commands.js` (run from the skill's `scripts/` directory), or `task run -- --file=… --action=…`.

### Usage

```bash
cd <skill>/scripts
node dist/cli/commands.js --file <path> --action <action> [--page <index>] [--output <path>]
# short flags: -f, -a, -p, -o, -h
```

`--page` selects the diagram tab (0-based, default 0). Ignored by `summary` (processes all pages).  
Always prints YAML to stdout. Exit code `0` on success, `1` on error.

### Actions

#### Authoring

| Action | Scope | Description |
|---|---|---|
| `build` | YAML Diagram IR | Validate and convert a YAML specification to native `.drawio`; requires `--output` |

#### Semantic lifecycle

| Action | Scope | Description |
|---|---|---|
| `import` | Bare or wrapped Draw.io | Preserve semantic and unknown XML information in validated IR v2; requires YAML/JSON `--output` |
| `edit` | Diagram IR v2 | Apply one atomic stable-ID batch from `--spec`; supports `--dry-run` and Draw.io/YAML/JSON output |
| `views` | Diagram IR v2 | Project linked `executive`, `system`, `deployment`, `dataflow`, and `security` pages |
| `query` | Diagram IR v2 | Filter by `--kind`/`--property`, or find a deterministic path with `--from` and `--to` |
| `test` | Diagram IR v2 | Execute built-in architecture policy rules; `--strict` treats warnings as failures |
| `what-if` | Diagram IR v2 | Calculate outgoing impact from `--fail`, honoring failure-isolating edges |
| `sync` | Base/manual/incoming IR | Three-way synchronization with explicit `--prune` and `--dry-run` |
| `story` | Diagram IR v2 | Write self-contained accessible offline HTML; optional `--fail` overlay |
| `doctor` | Local environment | Report optional backend availability without launching processes or requiring a model file |

#### Inventory

| Action | Scope | Description |
|---|---|---|
| `summary` | All pages | Full inventory of shapes + edges for every page/tab |
| `page-summary` | Single page (`--page`) | Full inventory of shapes + edges for one page |
| `page-hierarchy` | Page 0 | Recursive containment tree with totalLevels (nesting depth count) |
| `page-hierarchy-full` | Page 0 | Same as page-hierarchy + full geometry (x, y, width, height) per shape at each nesting level |
| `page-connectors-summary` | Page 0 | Per-connector details: type, label, waypoints, source/target names |

#### Validation

| Action | Scope | Description |
|---|---|---|
| `validate` | All pages | **Mandatory final gate** — XML well-formedness + maxGraph compile + sanity check (vertices/edges > 0). Run before finishing any diagram work |
| `quality` | All pages | Objective clipping, overflow, placeholder, external-asset, palette, page-density, and edge-density checks with explicit severity |
| `page-connectors-validation` | Page 0 | Connector-shape overlaps + connector crossings |
| `page-labels-validation` | Page 0 | Empty labels, duplicate labels, labels > 80 chars |
| `page-shape-bbox-validation` | Page 0 | Non-containment bounding box overlaps between shapes |
| `page-orphans` | Page 0 | Isolated shapes (no edges) + dangling connectors (missing endpoints) |

#### Layout

| Action | Scope | Description |
|---|---|---|
| `page-recommendations` | Page 0 | Smallest standard page size (A4→A3→A2→A1→custom) that fits content with 80 px margin |

> For install/build instructions, source structure, and how to add new actions, see [maintenance.md](./maintenance.md).

---

## Capability 5 — Native service libraries

The package includes additional strict TypeScript APIs under `scripts/src/services/`:

- `source-importers/` — conservative, bounded source/configuration topology extraction with diagnostics and no code execution;
- `themes/` and `shape-catalog/` — five validated themes and an offline generic shape catalog;
- `transforms/` — reverse Mermaid/Markdown, semantic diff, complete-map relabeling, and accessible bounded heatmaps;
- `profiles/` — C4, sequence, tube map, compression, runbook, timelapse, and build-up profiles.

These services are covered by the native test suite but are not registered CLI actions. Their exact peer-relative coverage and deliberate omissions are listed in [agents365-capability-coverage.md](./agents365-capability-coverage.md).