[verified] feat: add semantic diagram lifecycle

README.md

@@ -1,6 +1,6 @@
 # drawio-main
 
-TypeScript tools for deterministic YAML-to-Draw.io generation, analysis, and verification.
+TypeScript tools for deterministic Diagram IR-to-Draw.io generation, loss-aware round trips, transactional editing, semantic analysis, synchronization, offline publishing, and visual 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.
 
@@ -38,8 +38,12 @@ 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:
+# Build from semantic YAML/JSON Diagram IR:
 node dist/cli/commands.js --action build --file architecture.yaml --output architecture.drawio
+
+# Loss-aware import and transactional edit:
+node dist/cli/commands.js --action import --file architecture.drawio --output architecture.yaml
+node dist/cli/commands.js --action edit --file architecture.yaml --spec ../examples/edit-batch.yaml --output edited.drawio
 ```
 
 Output is always YAML to stdout.
@@ -62,6 +66,24 @@ See `examples/platform-v2.yaml` and `schemas/diagram-ir-v2.schema.json`.
 
 ---
 
+### Semantic lifecycle
+
+| Action | Purpose | Key options |
+|---|---|---|
+| `import` | Loss-aware Draw.io to Diagram IR v2 | `--output model.yaml|json` |
+| `edit` | Atomic stable-ID edit batch | `--spec`, `--output`, `--dry-run` |
+| `views` | Linked executive/system/deployment/dataflow/security views | `--views`, `--output` |
+| `query` | Kind/property filtering and deterministic shortest paths | `--kind`, `--property`, `--from`, `--to` |
+| `test` | Seven built-in architecture policies | `--spec`, `--strict` |
+| `what-if` | Failure propagation with isolation boundaries | `--fail` |
+| `sync` | Three-way synchronization preserving manual presentation | `--base`, `--spec`, `--output`, `--prune`, `--dry-run` |
+| `story` | Self-contained accessible offline HTML | `--output`, optional `--fail` |
+| `doctor` | Report optional backend availability without launching it | no `--file` required |
+
+Commands fail closed on ambiguous identities, invalid view/policy names, input/output aliases, and malformed operations. See [`references/semantic-lifecycle.md`](references/semantic-lifecycle.md) for complete contracts and examples.
+
+---
+
 ### Inventory
 
 #### `summary`
@@ -166,3 +188,4 @@ Standard sizes: A4 (1169×827), A3 (1654×1169), A2 (2339×1654), A1 (3307×2339
 
 - Bare `<mxGraphModel>` XML files
 - `<mxfile><diagram>…</diagram></mxfile>` wrappers (draw.io desktop format, base64+deflate encoded, multi-page supported)
+- Loss-aware semantic import preserves unknown wrapper/page/model XML in explicit `$drawio` envelopes for deterministic round trips