feat: add deterministic Diagram IR v2 authoring

README.md

@@ -1,6 +1,6 @@
 # drawio-main
 
-CLI tools for programmatic analysis and verification of `.drawio` files.
+TypeScript tools for deterministic YAML-to-Draw.io generation, analysis, and verification.
 
 Built with TypeScript using [`@maxgraph/core`](https://github.com/maxGraph/maxGraph) — the official TypeScript successor to mxGraph (the library draw.io is built on) — for accurate XML parsing and absolute coordinate resolution.
 
@@ -37,12 +37,31 @@ cd scripts
 task run -- --file="diagram.drawio" --action=<action> [--page <index>]
 # or directly:
 node dist/cli/commands.js --file diagram.drawio --action <action> [--page <index>]
+
+# Build from semantic YAML Diagram IR:
+node dist/cli/commands.js --action build --file architecture.yaml --output architecture.drawio
 ```
 
 Output is always YAML to stdout.
 
 ## Actions
 
+### Authoring
+
+#### `build`
+
+Validates a versioned YAML Diagram IR and emits deterministic native Draw.io XML.
+
+- **v1 remains supported** for single-page linear diagrams.
+- **v2** adds multiple pages, containers and semantic kinds, explicit geometry, edge waypoints, provenance/properties/extensions, and typed layout options.
+- `linear`, `layered`, `tree`, `grid`, and `manual` layouts are supported. Layered/tree layouts use deterministic dependency-aware placement.
+- Generated connectors receive deterministic obstacle-aware orthogonal waypoints when a clear route is available.
+- Duplicate/reserved IDs, invalid dimensions, unknown parents, and unknown edge endpoints fail before output is written.
+
+See `examples/platform-v2.yaml` and `schemas/diagram-ir-v2.schema.json`.
+
+---
+
 ### Inventory
 
 #### `summary`
@@ -84,6 +103,14 @@ Connector types: `directed` (both endpoints connected), `partial` (one missing),
 
 ### Validation
 
+#### `quality`
+
+Runs objective visual-quality checks across every page: page clipping, likely text overflow, placeholder text, external image URLs, palette spread, page density, and edge density. Findings have explicit `error` or `warning` severity; the action never invents a minimum defect count.
+
+**Output:** `summary` (pages, shapes, edges, errors, warnings), `issues[]`
+
+---
+
 #### `page-connectors-validation`
 
 Detects two categories of layout defects on the first page: