squinch 0.20.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  <p align="center">
2
- <img src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/docs/assets/mark-stack.svg" alt="Squinch — AI-Native Architecture Diagrams" width="190">
2
+ <img src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/docs/assets/mark-stack.svg" alt="Squinch — AI-Native Architecture Diagrams" width="190">
3
3
  </p>
4
4
 
5
5
  # squinch
6
6
 
7
7
  <p align="center">
8
8
  <a href="https://github.com/jquatier/squinch/actions/workflows/ci.yml"><img src="https://github.com/jquatier/squinch/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
9
- <a href="https://github.com/jquatier/squinch/blob/v0.20.0/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0"></a>
9
+ <a href="https://github.com/jquatier/squinch/blob/v0.21.0/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0"></a>
10
10
  <img src="https://img.shields.io/badge/status-pre--alpha-orange" alt="Pre-alpha">
11
11
  <img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-informational" alt="macOS, Linux and Windows">
12
12
  <img src="https://img.shields.io/badge/node-%E2%89%A522-brightgreen" alt="Node 22 or newer">
@@ -50,8 +50,8 @@ the other surfaces are in [Install](#install).
50
50
 
51
51
  <p align="center">
52
52
  <picture>
53
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/docs/assets/prompt-dark.gif">
54
- <img src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/docs/assets/prompt-light.gif"
53
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/docs/assets/prompt-dark.gif">
54
+ <img src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/docs/assets/prompt-light.gif"
55
55
  alt="A paragraph is typed into a prompt box — describing a products API on AWS where shoppers hit CloudFront, then an ALB and a Fargate service inside the prod-main VPC, reading a DynamoDB table and searching an OpenSearch index kept current by a Lambda on the table's stream. A status line reads Thinking, then Using squinch skill, then Finalizing diagram. The box shrinks to a caption and the finished diagram rises underneath it, every element from the sentence drawn with its real vendor icon."
56
56
  width="900">
57
57
  </picture>
@@ -61,12 +61,12 @@ the other surfaces are in [Install](#install).
61
61
  </p>
62
62
 
63
63
  Hand your coding agent the bundled
64
- [skill](https://github.com/jquatier/squinch/tree/v0.20.0/packages/skill) and describe the system in a paragraph. It writes the
64
+ [skill](https://github.com/jquatier/squinch/tree/v0.21.0/packages/skill) and describe the system in a paragraph. It writes the
65
65
  `.squinch` model, `squinch check` tells it what is wrong in terms it can act on,
66
66
  and `squinch render` produces the diagram as SVG, PNG or interactive HTML —
67
67
  deterministic, reviewable in a pull request, and living in git beside the code
68
68
  it describes. The diagram above is
69
- [examples/products-api](https://github.com/jquatier/squinch/tree/v0.20.0/examples/products-api); its source is
69
+ [examples/products-api](https://github.com/jquatier/squinch/tree/v0.21.0/examples/products-api); its source is
70
70
  [further down this page](#from-source-to-diagram), and CI holds the two
71
71
  together.
72
72
 
@@ -74,8 +74,8 @@ together.
74
74
 
75
75
  <p align="center">
76
76
  <picture>
77
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/docs/assets/zoom-dark.gif">
78
- <img src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/docs/assets/zoom-light.gif"
77
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/docs/assets/zoom-dark.gif">
78
+ <img src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/docs/assets/zoom-light.gif"
79
79
  alt="On a landscape of five systems, clicking the Catalog Service card opens it into its own internals — API, products table, search index and stream sync, with the product stream animating between table and index — while the gateway and order service stay as muted context. The breadcrumb closes it again, and clicking Account Service opens that one the same way. Finally the view cuts to full detail: all four systems open at once as labelled frames on one page, the cross-service calls routed between them, before the breadcrumb returns to the landscape."
80
80
  width="900">
81
81
  </picture>
@@ -91,7 +91,7 @@ a collapsed system is a card previewing what is inside; opening it shows the
91
91
  internals while the neighbours it talks to stay on screen as muted context; and
92
92
  edges that crossed the boundary re-anchor themselves, aggregating behind a count
93
93
  badge when several collapse into one. Nothing is duplicated, so nothing can
94
- drift — see [examples/microservices](https://github.com/jquatier/squinch/tree/v0.20.0/examples/microservices) for the source.
94
+ drift — see [examples/microservices](https://github.com/jquatier/squinch/tree/v0.21.0/examples/microservices) for the source.
95
95
 
96
96
  ## Tables and fields
97
97
 
@@ -118,6 +118,19 @@ container db "Orders DB" {
118
118
  each of its columns.
119
119
  - **`ref <path>`** names the column or table a field points at. It is text on
120
120
  the row; the relationship itself is an edge between the two tables.
121
+ - **Relationships are marked on that edge**, when you know how many rows take
122
+ part: `from:` and `to:`, one word per end, drawn as crow's-foot marks.
123
+
124
+ ```squinch
125
+ orders -> customers "customer_id" { from: many to: one }
126
+ orders -> coupons "coupon_id" { from: many to: zero-or-one } // nullable key
127
+ order_items -> orders "order_id" { from: one-or-many to: exactly-one }
128
+ products -- tags { from: many to: many }
129
+ ```
130
+
131
+ `one` and `many` say nothing about optionality; `exactly-one`,
132
+ `zero-or-one`, `one-or-many` and `zero-or-many` state it. Both ends or
133
+ neither, between two tables, on a plain `->` or `--` edge.
121
134
  - **Fields draw where the table's container is open.** A view scoped to the
122
135
  database (`view db { scope shop.db }`) shows every field. Wherever the
123
136
  database is expanded (`expand db`, `expand *`) each table shows a compact
@@ -128,13 +141,14 @@ container db "Orders DB" {
128
141
  own database view.
129
142
 
130
143
  `squinch check` warns when fields are written that no view can draw. The full
131
- rules are in [docs/SPEC.md](https://github.com/jquatier/squinch/blob/v0.20.0/docs/SPEC.md); the lookbook's
132
- [Fields case](https://github.com/jquatier/squinch/blob/v0.20.0/lookbook/cases/43-fields.squinch) shows all three placements.
144
+ rules are in [docs/SPEC.md](https://github.com/jquatier/squinch/blob/v0.21.0/docs/SPEC.md); the lookbook's
145
+ [Fields case](https://github.com/jquatier/squinch/blob/v0.21.0/lookbook/cases/43-fields.squinch) shows all three placements, and
146
+ the [Relationships case](https://github.com/jquatier/squinch/blob/v0.21.0/lookbook/cases/44-relationships.squinch) all six marks.
133
147
 
134
148
  ## Features
135
149
 
136
150
  - **LLMs write it fluently.** Give your coding agent the bundled
137
- [skill](https://github.com/jquatier/squinch/tree/v0.20.0/packages/skill) and ask for a diagram of your system. The language was
151
+ [skill](https://github.com/jquatier/squinch/tree/v0.21.0/packages/skill) and ask for a diagram of your system. The language was
138
152
  designed for agents to author rather than retrofitted for them, so what comes
139
153
  back is a correct diagram, not one you have to redraw.
140
154
  - **1,358 real vendor icons.** AWS, Azure, Google Cloud, Kubernetes and product logos, not
@@ -210,7 +224,7 @@ The other surfaces, each its own one-liner:
210
224
  and VSCodium.
211
225
  - **CI** — `uses: jquatier/squinch/.github/actions/squinch-check@main` fails
212
226
  the build when a committed SVG is stale;
213
- [`squinch-diff`](https://github.com/jquatier/squinch/tree/v0.20.0/.github/actions/squinch-diff) comments what changed,
227
+ [`squinch-diff`](https://github.com/jquatier/squinch/tree/v0.21.0/.github/actions/squinch-diff) comments what changed,
214
228
  architecturally, on the PR. Pin the `version` input: rendering is
215
229
  deterministic *per tool version*, so a floating `latest` can change your
216
230
  goldens on someone else's release day.
@@ -290,8 +304,8 @@ view products {
290
304
  ```
291
305
 
292
306
  <picture>
293
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/examples/products-api/products-api.products.dark.svg">
294
- <img alt="Products API — CloudFront to an ALB and a Fargate service in a VPC, reading from a DynamoDB table whose stream feeds an OpenSearch index" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/examples/products-api/products-api.products.light.svg">
307
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/examples/products-api/products-api.products.dark.svg">
308
+ <img alt="Products API — CloudFront to an ALB and a Fargate service in a VPC, reading from a DynamoDB table whose stream feeds an OpenSearch index" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/examples/products-api/products-api.products.light.svg">
295
309
  </picture>
296
310
 
297
311
  ## Why
@@ -324,23 +338,23 @@ conflict.squinch:9:5 error: contradictory place hints: `s.a` vs `s.b` reference
324
338
 
325
339
  ## What it can draw
326
340
 
327
- Every picture below is a committed render from [lookbook/](https://github.com/jquatier/squinch/tree/v0.20.0/lookbook), rebuilt
341
+ Every picture below is a committed render from [lookbook/](https://github.com/jquatier/squinch/tree/v0.21.0/lookbook), rebuilt
328
342
  and byte-compared on every push — so none of them can quietly stop being true.
329
343
 
330
344
  <table>
331
345
  <tr>
332
346
  <td width="50%" valign="top">
333
347
  <picture>
334
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/17-zones.landscape.dark.svg">
335
- <img alt="Deployment boundaries" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/17-zones.landscape.light.svg" width="100%">
348
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/17-zones.landscape.dark.svg">
349
+ <img alt="Deployment boundaries" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/17-zones.landscape.light.svg" width="100%">
336
350
  </picture>
337
351
  <b>Deployment boundaries</b><br>
338
352
  <code>zone</code> — cloud, VPC, on-prem, nested, each kind-tinted, with chips that straddle the border
339
353
  </td>
340
354
  <td width="50%" valign="top">
341
355
  <picture>
342
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/examples/notifications/notifications.pipeline.dark.svg">
343
- <img alt="A notification pipeline: events queue, a worker archives and pushes to the customer" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/examples/notifications/notifications.pipeline.light.svg" width="100%">
356
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/examples/notifications/notifications.pipeline.dark.svg">
357
+ <img alt="A notification pipeline: events queue, a worker archives and pushes to the customer" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/examples/notifications/notifications.pipeline.light.svg" width="100%">
344
358
  </picture>
345
359
  <b>Motion that carries meaning</b><br>
346
360
  Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>, and a <code>comet</code> rides the final push at 150px/s — CSS keyframes, each at its own constant speed, animating right here in this README
@@ -349,16 +363,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
349
363
  <tr>
350
364
  <td width="50%" valign="top">
351
365
  <picture>
352
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/18-flows.shop.dark.svg">
353
- <img alt="Numbered flows" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/18-flows.shop.light.svg" width="100%">
366
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/18-flows.shop.dark.svg">
367
+ <img alt="Numbered flows" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/18-flows.shop.light.svg" width="100%">
354
368
  </picture>
355
369
  <b>Numbered flows</b><br>
356
370
  <code>flow</code> declares a request path; <code>show flow</code> badges the steps in order along the edges
357
371
  </td>
358
372
  <td width="50%" valign="top">
359
373
  <picture>
360
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/16-legend-titleblock.pay.dark.svg">
361
- <img alt="Legend and titleblock" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/16-legend-titleblock.pay.light.svg" width="100%">
374
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/16-legend-titleblock.pay.dark.svg">
375
+ <img alt="Legend and titleblock" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/16-legend-titleblock.pay.light.svg" width="100%">
362
376
  </picture>
363
377
  <b>Legend and titleblock</b><br>
364
378
  <code>legend auto</code> keys only the styles the diagram actually uses; <code>titleblock</code> is drafting-style metadata
@@ -367,16 +381,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
367
381
  <tr>
368
382
  <td width="50%" valign="top">
369
383
  <picture>
370
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/22-channel.bussed.dark.svg">
371
- <img alt="Channel trunks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/22-channel.bussed.light.svg" width="100%">
384
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/22-channel.bussed.dark.svg">
385
+ <img alt="Channel trunks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/22-channel.bussed.light.svg" width="100%">
372
386
  </picture>
373
387
  <b>Channel trunks</b><br>
374
388
  <code>channel a, b, c -&gt; db</code> collapses many converging edges into one trunk instead of a fan
375
389
  </td>
376
390
  <td width="50%" valign="top">
377
391
  <picture>
378
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/14-sidecar-routes.app.dark.svg">
379
- <img alt="Edge routing" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/14-sidecar-routes.app.light.svg" width="100%">
392
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/14-sidecar-routes.app.dark.svg">
393
+ <img alt="Edge routing" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/14-sidecar-routes.app.light.svg" width="100%">
380
394
  </picture>
381
395
  <b>Edge routing</b><br>
382
396
  <code>place</code> puts the sidecar beside its owner; <code>route … from east to west</code> picks the sides
@@ -385,16 +399,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
385
399
  <tr>
386
400
  <td width="50%" valign="top">
387
401
  <picture>
388
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/21-logos.landscape.dark.svg">
389
- <img alt="Beyond the clouds" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/21-logos.landscape.light.svg" width="100%">
402
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/21-logos.landscape.dark.svg">
403
+ <img alt="Beyond the clouds" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/21-logos.landscape.light.svg" width="100%">
390
404
  </picture>
391
405
  <b>Beyond the clouds</b><br>
392
406
  <code>pack logos</code> for the non-cloud half of a stack, plated and tinted; the <code>×n</code> badge aggregates lifted edges
393
407
  </td>
394
408
  <td width="50%" valign="top">
395
409
  <picture>
396
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/20-align-hops.s.dark.svg">
397
- <img alt="Craft details" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/20-align-hops.s.light.svg" width="100%">
410
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/20-align-hops.s.dark.svg">
411
+ <img alt="Craft details" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/20-align-hops.s.light.svg" width="100%">
398
412
  </picture>
399
413
  <b>Craft details</b><br>
400
414
  <code>align</code> snaps nodes onto one axis, and crossing edges hop rather than blur into a junction
@@ -403,16 +417,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
403
417
  <tr>
404
418
  <td width="50%" valign="top">
405
419
  <picture>
406
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/10-highlight-notes.pci.dark.svg">
407
- <img alt="Tag lenses and notes" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/10-highlight-notes.pci.light.svg" width="100%">
420
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/10-highlight-notes.pci.dark.svg">
421
+ <img alt="Tag lenses and notes" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/10-highlight-notes.pci.light.svg" width="100%">
408
422
  </picture>
409
423
  <b>Tag lenses and notes</b><br>
410
424
  <code>highlight #pci</code> dims everything off-topic; notes anchor to the node they are about
411
425
  </td>
412
426
  <td width="50%" valign="top">
413
427
  <picture>
414
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/30-badges.lakehouse.dark.svg">
415
- <img alt="Vendor badges on generic marks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/30-badges.lakehouse.light.svg" width="100%">
428
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/30-badges.lakehouse.dark.svg">
429
+ <img alt="Vendor badges on generic marks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/30-badges.lakehouse.light.svg" width="100%">
416
430
  </picture>
417
431
  <b>Vendors with no icon pack</b><br>
418
432
  <code>badge: logos/databricks</code> marks a generic <code>sys/*</code> concept as someone's platform — the licence-clean way to draw a vendor that ships no redistributable icons
@@ -421,16 +435,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
421
435
  <tr>
422
436
  <td width="50%" valign="top">
423
437
  <picture>
424
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/34-view-axes.audit.dark.svg">
425
- <img alt="An audit view: only the PCI-tagged systems survive, with the untagged caller reduced to a muted context card" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/34-view-axes.audit.light.svg" width="100%">
438
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/34-view-axes.audit.dark.svg">
439
+ <img alt="An audit view: only the PCI-tagged systems survive, with the untagged caller reduced to a muted context card" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/34-view-axes.audit.light.svg" width="100%">
426
440
  </picture>
427
441
  <b>The audit view</b><br>
428
442
  <code>only #pci</code> keeps the tagged slice and drops the rest — a view <code>scope</code> could never name, because tags cut across systems. The untagged caller survives only as a muted context card: the assessor sees the entry point, drawn as periphery
429
443
  </td>
430
444
  <td width="50%" valign="top">
431
445
  <picture>
432
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/33-card-shelf.landscape.dark.svg">
433
- <img alt="Card anatomy: a system card with its own icon, a domain chip on the shelf, and a +N overflow count" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/33-card-shelf.landscape.light.svg" width="100%">
446
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/33-card-shelf.landscape.dark.svg">
447
+ <img alt="Card anatomy: a system card with its own icon, a domain chip on the shelf, and a +N overflow count" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/33-card-shelf.landscape.light.svg" width="100%">
434
448
  </picture>
435
449
  <b>Cards that carry their metadata</b><br>
436
450
  <code>icon:</code> gives a system its own mark, <code>domain:</code> stamps the shelf, and past three children the preview truncates to <code>+N</code>
@@ -441,7 +455,7 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
441
455
  Also in the language: `cols` to pin the other axis, `datastore` / `external`
442
456
  node kinds, descriptions, and container nesting. Async edges (`~>`) are dashed
443
457
  and animate at a constant speed — CSS keyframes, never script. Full grammar in
444
- [docs/SPEC.md](https://github.com/jquatier/squinch/blob/v0.20.0/docs/SPEC.md).
458
+ [docs/SPEC.md](https://github.com/jquatier/squinch/blob/v0.21.0/docs/SPEC.md).
445
459
 
446
460
  ## Written by agents, and tested that way
447
461
 
@@ -452,11 +466,11 @@ Errors are built for the agent loop, not just for humans: every diagnostic
452
466
  carries a location, the problem, and a likely fix, with did-you-mean suggestions
453
467
  for unknown icons, views and identifiers. `squinch check --format json` emits
454
468
  exactly the same information a person sees.
455
- [`SKILL.md`](https://github.com/jquatier/squinch/blob/v0.20.0/packages/skill/skills/squinch/SKILL.md), with the `references/`
469
+ [`SKILL.md`](https://github.com/jquatier/squinch/blob/v0.21.0/packages/skill/skills/squinch/SKILL.md), with the `references/`
456
470
  beside it, is the whole contract an
457
471
  agent needs — `npx squinch skill` installs it for every skills-compatible agent
458
472
  (or paste it into whatever your harness calls context), then ask for a diagram
459
- in plain language; [the package README](https://github.com/jquatier/squinch/tree/v0.20.0/packages/skill) has the details.
473
+ in plain language; [the package README](https://github.com/jquatier/squinch/tree/v0.21.0/packages/skill) has the details.
460
474
 
461
475
  The **gauntlet** is the acceptance test: thirty-eight architecture prompts —
462
476
  thirty-seven in plain language and one that hands the agent a real repository — each solved *cold* by a fresh agent given only SKILL.md
@@ -476,7 +490,7 @@ channels, more packs, the positional-tag grammar, large-system prompts,
476
490
  database tables and a real repository landed.
477
491
 
478
492
  The committed corpus scores **38/38** with zero human layout fixes. Every round is
479
- written up in [gauntlet/README.md](https://github.com/jquatier/squinch/blob/v0.20.0/gauntlet/README.md) — what was asked, how it
493
+ written up in [gauntlet/README.md](https://github.com/jquatier/squinch/blob/v0.21.0/gauntlet/README.md) — what was asked, how it
480
494
  was run, and what came back.
481
495
 
482
496
  ## Deterministic by construction
@@ -544,15 +558,15 @@ a filter. The same two nodes, both ways:
544
558
  <th align="center"><code>dark</code></th>
545
559
  </tr>
546
560
  <tr>
547
- <td align="center"><img alt="The same two-node diagram in the Light theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/01-minimal.tiny.light.svg" width="180"></td>
548
- <td align="center"><img alt="The same two-node diagram in the Dark theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.20.0/lookbook/out/01-minimal.tiny.dark.svg" width="180"></td>
561
+ <td align="center"><img alt="The same two-node diagram in the Light theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/01-minimal.tiny.light.svg" width="180"></td>
562
+ <td align="center"><img alt="The same two-node diagram in the Dark theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.21.0/lookbook/out/01-minimal.tiny.dark.svg" width="180"></td>
549
563
  </tr>
550
564
  </table>
551
565
 
552
566
  `--adaptive` folds the pair into one file behind `prefers-color-scheme`, so an
553
567
  embedded diagram follows the reader's OS without you picking a side.
554
568
 
555
- The [lookbook](https://github.com/jquatier/squinch/tree/v0.20.0/lookbook) renders 35 deliberately awkward cases — dense meshes,
569
+ The [lookbook](https://github.com/jquatier/squinch/tree/v0.21.0/lookbook) renders 35 deliberately awkward cases — dense meshes,
556
570
  long labels, deep nesting, coplanar rows — to 86 committed SVGs across the
557
571
  themes, and CI fails if any of them changes unintentionally.
558
572
 
@@ -563,12 +577,12 @@ redistributed and one shipped on Google's stated purpose for it:
563
577
 
564
578
  | Pack | Count | Terms |
565
579
  | --- | --- | --- |
566
- | [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-aws) | 316 | CC-BY-ND 2.0 — the same basis AWS uses for its own PlantUML icons |
567
- | [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-azure) | 636 | Microsoft's icon terms: copy and distribute **for architecture diagrams, training and documentation** |
568
- | [`pack-logos`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-logos) | 147 | CC0, from [Simple Icons](https://simpleicons.org) — the non-cloud half of a stack |
569
- | [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-sys) | 195 | ISC, from [Lucide](https://lucide.dev) — the generic set: servers, hardware, network gear, shapes, data/ML and commerce concepts |
570
- | [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-k8s) | 39 | Apache-2.0 / CC-BY-4.0 — the official [Kubernetes community icons](https://github.com/kubernetes/community/tree/main/icons), published to standardize cluster diagrams |
571
- | [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-gcp) | 45 | Google's [icon library](https://cloud.google.com/icons), published "for your diagrams, technical documentation, and more" — no redistribution grant; see its NOTICE for the footing |
580
+ | [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-aws) | 316 | CC-BY-ND 2.0 — the same basis AWS uses for its own PlantUML icons |
581
+ | [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-azure) | 636 | Microsoft's icon terms: copy and distribute **for architecture diagrams, training and documentation** |
582
+ | [`pack-logos`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-logos) | 147 | CC0, from [Simple Icons](https://simpleicons.org) — the non-cloud half of a stack |
583
+ | [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-sys) | 195 | ISC, from [Lucide](https://lucide.dev) — the generic set: servers, hardware, network gear, shapes, data/ML and commerce concepts |
584
+ | [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-k8s) | 39 | Apache-2.0 / CC-BY-4.0 — the official [Kubernetes community icons](https://github.com/kubernetes/community/tree/main/icons), published to standardize cluster diagrams |
585
+ | [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-gcp) | 45 | Google's [icon library](https://cloud.google.com/icons), published "for your diagrams, technical documentation, and more" — no redistribution grant; see its NOTICE for the footing |
572
586
 
573
587
  ```console
574
588
  $ squinch icons search factory
@@ -628,17 +642,17 @@ carry a script, and it is a separate class rather than a loophole: the SVGs
628
642
  inside it are byte-for-byte what `render -o x.svg` produces, the viewer is
629
643
  their sibling and never their content, and a test asserts nothing executable
630
644
  survives removing the two `<script>` elements
631
- ([docs/notes/html-export.md](https://github.com/jquatier/squinch/blob/v0.20.0/docs/notes/html-export.md)). Exported `.svg` never
645
+ ([docs/notes/html-export.md](https://github.com/jquatier/squinch/blob/v0.21.0/docs/notes/html-export.md)). Exported `.svg` never
632
646
  contains script, full stop.
633
647
 
634
648
  ## Docs
635
649
 
636
- - [DSL specification (v0 draft)](https://github.com/jquatier/squinch/blob/v0.20.0/docs/SPEC.md)
637
- - [Design language](https://github.com/jquatier/squinch/blob/v0.20.0/docs/DESIGN.md)
638
- - [Engineering constraints](https://github.com/jquatier/squinch/blob/v0.20.0/docs/ENGINEERING.md) — performance budgets, verification, and what is deliberately not built
639
- - [Engineering notes](https://github.com/jquatier/squinch/tree/v0.20.0/docs/notes) — decisions with their rejected alternatives
640
- - [Examples](https://github.com/jquatier/squinch/tree/v0.20.0/examples) and the [lookbook](https://github.com/jquatier/squinch/tree/v0.20.0/lookbook)
641
- - [Contributing](https://github.com/jquatier/squinch/blob/v0.20.0/CONTRIBUTING.md) · [Security policy](https://github.com/jquatier/squinch/blob/v0.20.0/SECURITY.md) · [Icon notices](https://github.com/jquatier/squinch/blob/v0.20.0/NOTICE)
650
+ - [DSL specification (v0 draft)](https://github.com/jquatier/squinch/blob/v0.21.0/docs/SPEC.md)
651
+ - [Design language](https://github.com/jquatier/squinch/blob/v0.21.0/docs/DESIGN.md)
652
+ - [Engineering constraints](https://github.com/jquatier/squinch/blob/v0.21.0/docs/ENGINEERING.md) — performance budgets, verification, and what is deliberately not built
653
+ - [Engineering notes](https://github.com/jquatier/squinch/tree/v0.21.0/docs/notes) — decisions with their rejected alternatives
654
+ - [Examples](https://github.com/jquatier/squinch/tree/v0.21.0/examples) and the [lookbook](https://github.com/jquatier/squinch/tree/v0.21.0/lookbook)
655
+ - [Contributing](https://github.com/jquatier/squinch/blob/v0.21.0/CONTRIBUTING.md) · [Security policy](https://github.com/jquatier/squinch/blob/v0.21.0/SECURITY.md) · [Icon notices](https://github.com/jquatier/squinch/blob/v0.21.0/NOTICE)
642
656
 
643
657
  ## Acknowledgments
644
658
 
@@ -647,19 +661,19 @@ Squinch's model/view approach builds on the ideas of the
647
661
 
648
662
  ## License
649
663
 
650
- Squinch itself is [Apache-2.0](https://github.com/jquatier/squinch/blob/v0.20.0/LICENSE). The bundled icon artwork is **not** —
664
+ Squinch itself is [Apache-2.0](https://github.com/jquatier/squinch/blob/v0.21.0/LICENSE). The bundled icon artwork is **not** —
651
665
  each pack is redistributed verbatim under its own terms, and that credit
652
666
  travels with anything that serves the artwork (the playground carries it under
653
667
  "icon credits"):
654
668
 
655
669
  | Pack | Attribution | Terms |
656
670
  | --- | --- | --- |
657
- | [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-aws) | Amazon Web Services — [AWS Architecture Icons](https://aws.amazon.com/architecture/icons/) | [CC-BY-ND 2.0](https://github.com/jquatier/squinch/blob/v0.20.0/packages/pack-aws/NOTICE) — attribution required, no derivatives |
658
- | [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-azure) | Microsoft — [Azure Architecture Icons](https://learn.microsoft.com/en-us/azure/architecture/icons/) | [Microsoft's icon terms](https://github.com/jquatier/squinch/blob/v0.20.0/packages/pack-azure/NOTICE) — architecture diagrams, training and documentation only |
659
- | [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-k8s) | © the Kubernetes Authors — [community icons](https://github.com/kubernetes/community/tree/main/icons) | [Apache-2.0 or CC-BY-4.0](https://github.com/jquatier/squinch/blob/v0.20.0/packages/pack-k8s/NOTICE) — attribution required |
660
- | [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-gcp) | Google — [Google Cloud icon library](https://cloud.google.com/icons) | [No published grant](https://github.com/jquatier/squinch/blob/v0.20.0/packages/pack-gcp/NOTICE) — architecture diagrams and documentation, the purpose Google publishes them for |
661
- | [`pack-logos`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-logos) | [Simple Icons](https://simpleicons.org) | [CC0-1.0](https://github.com/jquatier/squinch/blob/v0.20.0/packages/pack-logos/NOTICE) — the marks remain their owners' trademarks |
662
- | [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.20.0/packages/pack-sys) | [Lucide](https://lucide.dev), portions from Feather | [ISC](https://github.com/jquatier/squinch/blob/v0.20.0/packages/pack-sys/NOTICE) (Feather portions MIT) |
671
+ | [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-aws) | Amazon Web Services — [AWS Architecture Icons](https://aws.amazon.com/architecture/icons/) | [CC-BY-ND 2.0](https://github.com/jquatier/squinch/blob/v0.21.0/packages/pack-aws/NOTICE) — attribution required, no derivatives |
672
+ | [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-azure) | Microsoft — [Azure Architecture Icons](https://learn.microsoft.com/en-us/azure/architecture/icons/) | [Microsoft's icon terms](https://github.com/jquatier/squinch/blob/v0.21.0/packages/pack-azure/NOTICE) — architecture diagrams, training and documentation only |
673
+ | [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-k8s) | © the Kubernetes Authors — [community icons](https://github.com/kubernetes/community/tree/main/icons) | [Apache-2.0 or CC-BY-4.0](https://github.com/jquatier/squinch/blob/v0.21.0/packages/pack-k8s/NOTICE) — attribution required |
674
+ | [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-gcp) | Google — [Google Cloud icon library](https://cloud.google.com/icons) | [No published grant](https://github.com/jquatier/squinch/blob/v0.21.0/packages/pack-gcp/NOTICE) — architecture diagrams and documentation, the purpose Google publishes them for |
675
+ | [`pack-logos`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-logos) | [Simple Icons](https://simpleicons.org) | [CC0-1.0](https://github.com/jquatier/squinch/blob/v0.21.0/packages/pack-logos/NOTICE) — the marks remain their owners' trademarks |
676
+ | [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.21.0/packages/pack-sys) | [Lucide](https://lucide.dev), portions from Feather | [ISC](https://github.com/jquatier/squinch/blob/v0.21.0/packages/pack-sys/NOTICE) (Feather portions MIT) |
663
677
 
664
678
  Kubernetes and the Kubernetes logo are trademarks of The Linux Foundation;
665
679
  Google Cloud and its product names are trademarks of Google LLC; brand marks
@@ -3,5 +3,5 @@
3
3
  // carries the skill it installs with zero runtime file resolution; CI re-runs
4
4
  // the generator and diffs. Keyed by path relative to the skill directory,
5
5
  // posix separators, SKILL.md first.
6
- export const SKILL_FILES = { "SKILL.md": "---\nname: squinch\ndescription: Author architecture diagrams as code with the Squinch DSL. Use this whenever the user wants an architecture or system diagram — creating one from prose, editing or reviewing a .squinch file, drawing cloud infrastructure (AWS, Azure, Kubernetes, hybrid estates), documenting services for a README or a design review, or any picture of systems, services and the connections between them — even when they never say \"squinch\". Write the .squinch model, validate it with `squinch check`, render it with `squinch render` (SVG in both themes plus the interactive HTML by default; PNG only when asked), and fix what you see with the layout cookbook.\ncompatibility: Requires Node.js 22+ and the squinch CLI on PATH, or npx squinch with no install\n---\n\n# Squinch — architecture diagrams as code\n\nSquinch renders `.squinch` files into deterministic SVG diagrams. You write the\n*model* (systems, components, connections); the engine lays it out. When the\nauto-layout isn't what you want, you steer it with **relative** hints — there are\nno pixel coordinates anywhere in the language.\n\n## The loop\n\nWork like a compiler user, not an artist:\n\n```bash\nsquinch check diagram.squinch --format json # parse + lint; machine-readable\nsquinch render diagram.squinch -o out.svg # deterministic SVG; theme: the view's, else dark\nsquinch render diagram.squinch --view NAME --theme light -o out.svg # themes: light | dark\nsquinch render diagram.squinch --sync # every view × both themes, next to the source\nsquinch render diagram.squinch -o out.html # one interactive file: every view, both themes\nsquinch render diagram.squinch -o out.png --scale 2 # PNG, only when asked (--width also works)\nsquinch icons search \"<term>, <term>, …\" # find icon ids — batch every unknown in one call\nsquinch diff --format json # what changed in the architecture\n```\n\nIf `squinch` is not on PATH, prefix every command with `npx` — `npx squinch\ncheck …` — or install it once with `npm i -g squinch`.\n\n### What to hand over\n\nUnless the user names a format or a theme, a finished diagram is **all** of:\n\n```bash\nsquinch render diagrams/ --sync # <name>.<view>.light.svg + .dark.svg per view\nsquinch render diagrams/ -o diagram.html # every view, both palettes, click-to-zoom, presentation mode\n```\n\n- **Both themes, always.** Dark is designed, not inverted, and the reader's\n environment picks — never choose one for them. For a README or a docs site\n that should follow the reader's colour scheme, `--adaptive -o x.svg` folds\n the pair into one SVG behind `prefers-color-scheme`.\n- **The HTML is the thing to open.** It is one self-contained file with every\n view and a theme switch, and it needs no server — point the user at it\n first. A project with several views is unreadable as a pile of SVGs.\n- **PNG is the exception**, not the default: render one only when the user\n asks for an image, slides, or a surface that cannot show SVG. A PNG you\n render to check your own work is a different thing (quality bar 3) and\n stays out of the hand-over.\n- Every render carries the tool version that drew it (`data-squinch` on the\n root `<svg>`), and `render --check` re-renders and compares, so committed\n SVGs can gate CI. For a throwaway diagram that lives nowhere, two explicit\n `--theme` renders plus the HTML are the lighter recipe.\n- **Write the files; leave committing to the user.** Don't commit, push or\n make a branch unless they ask — they will want to look first.\n\nThen end your reply with three to five bullets, one or two plain sentences\neach, the way you would say it to a colleague — and nothing before them that\nsays the same thing:\n\n- Open `diagram.html` — it has the landscape and orders views, light and dark.\n- I guessed that the services run on Lambda and that Postgres means RDS; the\n request named neither.\n- I looked at both views. The one rough spot is the Kafka wire running round\n the right edge; moving it made the services row harder to read, so I left it.\n- If this is more than you need, I can take out the load generator and the\n tracing collector, or show less detail by grouping the services into three\n areas.\n\nThe first three are never skipped: where to open it; what you guessed — every\nproduct, cloud or runtime the request did not name — or \"Nothing guessed\" when\nthat is true; and what you saw when you looked, or that you could not look.\nThe last — an offer to cut it down, naming your own most peripheral boxes, not\na category — ends every hand-over of an open-ended request or a big system,\nand is left off a small diagram that drew what was asked. One more bullet may\nsay how you grouped a big system, or a warning you kept. Don't describe the\ncomponents or the layout: the diagram shows them.\n\n0. If the system is big — a whole repo, a platform — decide its *areas* before\n you write a node, because no layout hint rescues everything on one page: see\n \"When the system is big\".\n1. Write the model first, with **no `layout` block at all** — most diagrams\n never need one. Your edges already say what the tiers are, and the engine\n ranks from them: a node sits below everything that points at it. Render it\n and look. Add hints only to fix something you can see is wrong, one at a\n time, naming only the nodes you actually care about. Icon ids outside the\n AWS basics — anything `azure/`, `gcp/`, `k8s/`, `logos/` or `sys/` — are\n looked up before the first `check`, never written from memory: open\n `references/icons.md`, which lists them per pack, or run `squinch icons\n search` with every unknown in one call. An id guessed from the word you\n would say — a `sys/` or `azure/` name that reads right and does not exist —\n is the most common way a first `check` fails.\n2. `check` after every edit. Diagnostics tell you the location, the problem, and\n usually the fix (`did you mean ...?`). Trust them. When one is not\n self-explanatory, open `references/cookbook.md` — symptom → fix, keyed on\n the diagnostic's own words.\n3. Exit code 0 and **no diagnostics at all** = clean. Errors block the render;\n warnings do not, which is exactly why they matter — a warning means the file\n is valid but probably not the diagram you were asked for. Fix warnings\n before you stop.\n4. A stderr line starting `update:` (a newer squinch is on npm) or `skill:`\n (this SKILL.md was installed by a different squinch) — or the `update` /\n `skill` fields in `check --format json` — is information, not a diagnostic:\n exit 0 with no diagnostics is still clean. Mention it to the user once and\n carry on. Never upgrade squinch or re-run `squinch skill` unasked: an\n upgrade can change render bytes, and that is the user's call.\n\n## Quality bar before you call it done\n\n1. `squinch check` exits 0 with no diagnostics.\n2. **Every view** you declared is rendered in both `--theme light` and\n `--theme dark`, plus the interactive `.html` — and all of it is handed\n over, not just checked (see \"What to hand over\").\n3. **Look at the picture, not the markup.** SVG source cannot show you a\n detour. Rasterise each view beside the source and open the image —\n `squinch render diagram.squinch --view NAME -o NAME.check.png` — then\n delete the `.check.png` files when you are done. Keep them inside your\n working directory: a path like `/tmp` is often one you may not read. One\n theme is enough, both share one layout. Tiers read top-to-bottom (or\n left-to-right), no edge takes a baffling detour, async flows (`~>`) are\n dashed, related things sit together. If you could not view the image, say\n so in the hand-over and make no claim about how the layout looks.\n4. Labels are short noun phrases. A `subtitle:` of a few words says what a\n leaf runs on or who owns it; anything longer goes in `description`, never\n the label.\n5. Model semantics honestly: request/response is `->`; anything that queues,\n buffers or fans out is `~>`. If the prose says stream, queue, topic, event,\n publishes, emits, feeds, notifies or subscribes — Kinesis, Kafka, SQS, SNS,\n EventBridge, Service Bus — that edge is `~>`, and a pipeline drawn entirely\n with `->` is almost always wrong.\n6. **Every actor the prose names is in the diagram.** People are easy to drop:\n \"customers browse\", \"developers push\", \"an analyst queries\" each name a\n `person`, and a stack diagram that draws only the technology has left out\n who uses it. Re-read the request and check each noun appears — a human is a\n `person`, not a box and not omitted.\n7. **Nothing is in the diagram that the request does not support.** A reader\n takes every box as a fact, so a CDN, WAF, cache or queue that nothing in\n the request implies is a guess presented as truth — leave it out. The same\n goes for glue: an API or worker you put between two things the request\n names, and a product you picked where it named only a kind (\"Postgres\" is\n not \"RDS\"). A `link:` is the same: use a URL the request or the code gives\n you, never one you composed. When the picture cannot be drawn without\n filling a gap, draw the plainest reading and say what you guessed in the\n hand-over.\n\n## Language\n\n```squinch\n// comments are // only (# belongs to tags)\npack aws // icon packs this file draws from (aws |\npack azure // azure | gcp | logos | k8s). Optional — any\n // installed pack resolves without it — but\n // declaring documents intent and catches a\n // misspelled pack name at check time.\n\nperson customer \"Customer\" // human actor. This form is top-level\n // only — inside a system write it as\n // `who = person \"Operator\"`. Either\n // takes a block: `{ description: \"…\" }`\ngw = aws/api-gateway \"Edge Gateway\" // components may sit at the top level too —\n // that's how things stay individually\n // visible at landscape altitude (see\n // \"Grouping vs. nesting\" under Views)\n\nsystem shop \"Order Service\" { // systems/containers nest arbitrarily\n description: \"Checkout and orders\" // optional; shows on the collapsed card\n icon: aws/api-gateway // the card's own mark; without it the\n // first child's icon stands in\n glyph: sys/code // kind mark, in a chip at the card's\n // top right; a bad ref is a check error\n domain: \"orders\" // optional owner/team tag on the card's\n // shelf, beside the child icons\n tags: #core // tags inherit to everything inside\n\n api = aws/api-gateway \"API Gateway\" // id = pack/icon \"Label\"\n create = aws/lambda \"Create Handler\" {\n description: \"Validates and persists\"\n subtitle: \"Lambda · Node 20\" // a few words under the label, always\n // drawn: runtime, owner, region\n link: \"https://runbooks.acme.dev/create\" // makes the title a hyperlink, in\n // quotes, http(s) only, leaves only: a\n // card's click zooms. Only a URL you were\n // given (quality bar 7)\n tags: #pci\n }\n db = aws/dynamodb \"Orders Table\" datastore #pci\n // a tag can sit in kind position like that, or in the block — same thing:\n idx = aws/opensearch \"Search Index\" datastore {\n tags: #pci // kind and attr block go in either order\n }\n wh = sys/database \"SQL Warehouse\" datastore {\n badge: logos/databricks // small vendor mark on the icon plate —\n // see \"Platforms with no icon pack\" below\n }\n legacy = box \"Old Billing\" external // `box` = no icon\n // kinds: `external` (not ours — draws a hatched surface, and also goes on a\n // whole system: `system stripe \"Stripe\" external { … }`) and `datastore`\n // (holds state — a note to the reader and to `squinch diff`; your icon\n // choice is what actually shows it). For a human, use the `person` forms\n // above rather than a kind.\n\n api -> create // sync edge (solid)\n api -> create, get, search // fan-out\n db ~> sync \"DynamoDB stream\" // async edge (dashed); label optional\n api -> create { tags: #hot-path } // edges take tags and attrs too\n api -> db { color: amber } // a hue on the stroke + head — see Colour\n a <-> b // bidirectional; a -- b undirected\n}\n\ncustomer -> shop.api \"places order\" // cross-system edges use dotted paths\n\nzone prod_vpc \"VPC prod\" vpc { // deployment boundary — cross-cuts the\n contains shop // ownership tree; renders as the classic\n} // dashed frame around its members\n```\n\nRules that matter:\n- **Ids are unique within their container**; refer to nested things as `shop.api`\n from outside, bare `api` from inside.\n- Statements end at newline (or `;`). Labels are quoted strings.\n- **Commas are optional wherever whitespace already separates** — `rows [a, b]`,\n `align a, b`, `highlight #a, #b`, `{ style: dashed, animate: slow }` all parse,\n as do a trailing comma and no comma at all (`{ style: dashed animate: slow }`). They stay *required* in a path list (`a -> b, c`,\n `contains`, `channel`, `only`, `expand`), and stay wrong inside a tag value: write\n `tags: #a #b`, never `tags: #a, #b`.\n- Parallel edges between the same pair are fine — give each a label.\n- **A system you are not breaking down is a node, not an empty system.**\n `system partner \"Partner System\" external { }` gives you a card with nothing\n behind it and a zoom that goes nowhere; `check` warns that the system is\n empty. Write `partner = box \"Partner System\" external` instead.\n- A `layout { }` block goes inside a `view` (arranging the view) **or inside a\n `system`** (arranging that system's own interior — `rows`, `cols`, `place`,\n `direction` and `wrap`, written by short name; see Layout hints). Everything\n else — `channel`, `align`, `density`, `highlight`, `note`, `expand` —\n belongs to a view alone.\n\nTables — a database is one node until the reader asks what is *in* it. Then\nwrite it as a `container` holding one `sys/table` per table: it still draws as\none card where it sits, a dive opens it onto the tables, and a foreign key is\nan ordinary labelled edge. A caller points at the container (`svc -> db`) or\nat the table it touches (`svc -> db.orders`). `datastore` moves to the tables\n— on a container it is a check error — and `icon:` keeps the database's own\nmark on the card. A database nobody asked to open stays a node, and so does a\ntable with no database above it. On a serverless or managed store where the\ntable is itself the resource you deploy, write one node per table inside the\nservice that owns it, with no container invented to hold them.\n\n```squinch\nsystem shop \"Order Service\" {\n svc = aws/lambda \"Order Handler\"\n container db \"Orders DB\" {\n icon: aws/rds\n description: \"Postgres 16 · 3 tables\"\n customers = sys/table \"customers\" datastore\n orders = sys/table \"orders\" datastore {\n subtitle: \"partitioned monthly\"\n fields {\n id uuid pk\n customer_id uuid fk ref customers\n status enum(pending, paid, shipped)\n total numeric(10,2)\n }\n }\n payments = sys/table \"payments\" datastore\n orders -> customers \"customer_id\" // a foreign key, child to parent\n payments -> orders \"order_id\"\n }\n svc -> db.orders \"writes\"\n}\nview db { scope shop.db } // standing in the database: every field\n```\n\nColumns — only when the request asks what is *in* a store. Any leaf takes a\n`fields { }` block (a table, a collection, a topic's payload): one field per\nline, the name, the type as the store spells it, then markers in its own words\n(`pk`, `hash`, `ttl`, `unique`, `index gsi1`) and an optional `\"caption\"`.\nCopy them from the repo's migrations, Prisma or proto files, never from memory,\nand translate the punctuation (`?` → `nullable`, `@id` → `pk`). Mark every key\ncolumn — each column of a composite key carries `pk` — and say what a null or\na key pattern *means* in the caption (`gate text nullable \"null = all gates\"`);\na caption that fits is drawn on the row. A nested field\nis a dotted name (`address.city`). `ref <id>` names the column a foreign key\npoints at — the edge between the two tables stays the relationship. Fields\ndraw where the table's container is open: every field in a view scoped to it,\nand a compact list (the first six, or the table's `preview: [a b]`) wherever\nit is expanded. A table at the top level needs `preview <table>`; the\nlandscape and collapsed cards never change. `preview: none` keeps a table\nplain inside an expanded system.\n\nEdge motion — `~>` edges animate on their own (dashes drift toward the target,\noff under `prefers-reduced-motion`). Opt out with `{ animate: false }`, or pick\na variant: `reverse` (acks flowing back), `slow`/`fast` (cadence), `packets`\n(discrete messages), `pulse` (a heartbeat — works on solid sync edges too),\n`comet` (a dot rides the route — the only motion a plain solid edge can take).\nSync edges take `style: dotted` (`dashed` warns next to `~>` edges — dashes\nare the async convention), and a dotted sync edge may also animate. One `animate:` value per edge, and don't decorate every edge — motion\nis for the hops where cadence or direction *means* something.\n\n```squinch\nprobe -> legacy \"healthcheck\" { animate: pulse }\nsensor ~> ingest \"telemetry\" { animate: packets }\ncart -> pay \"checkout\" { animate: comet } // no `style:` needed\nmirror -> replica \"sync\" {\n style: dashed\n animate: slow\n}\n```\n\nColour — `color:` takes one of nine hues, `red | amber | green | teal | blue |\nviolet | pink | gray | accent`, never hex (each is a designed light/dark pair,\nand a literal cannot be right on both). It goes on anything: a leaf, a person\nor a `system` gets a spine down its left edge, an edge its stroke and head, a\nzone its outline. Use it to say *these belong together* or *this is the path*\nwithout dimming everything else the way `highlight` does. The stronger form is\nthe view statement `color #tag red`, which colours every visible thing carrying\nthe tag, one tag per line — it wins over an element's own `color:`, and with\n`legend auto` each coloured tag earns a legend entry. Colour is annotation:\nasync stays dashed, context stays muted, so a greyscale print loses only the\nemphasis.\n\nZones mark deployment boundaries: `zone id \"Label\" kind { contains a, b.c }`,\nkinds `account | region | vpc | subnet | network | cloud | onprem | custom`.\nOptional attrs: `icon:` — **any** pack icon (`azure/vnet`, `logos/docker`; AWS\nships purpose-made group marks like `aws/vpc`, `aws/region`,\n`aws/private-subnet`, `aws/corporate-data-center`) — `label: top-right`\n(corners: top-left default, top-right, bottom-left, bottom-right), and\n`color: teal` (the nine hues above; never hex). A zone's `kind` already picks\nits tint — `account` red, the network kinds blue, `cloud` violet, the rest\ngray — so two nested zones of related kinds come out nearly the same shade:\nset `color:` on the inner one to tell them apart. `detail: \"10.0.0.0/16\"` adds a second, monospaced\nsegment to the chip for the boundary's hard fact — a CIDR, an account id, a\nregion. It is dropped rather than truncated on a boundary too narrow for both,\nsince a clipped CIDR is a different network, not a shortened label.\n\n**Zones nest by sharing members, never by naming each other.** `contains` takes\nnodes, so an outer boundary repeats the inner one's members:\n\n```\nzone account \"Azure Subscription\" account { contains gw, aks, sql }\nzone vnet \"Virtual Network\" network { contains aks, sql }\n```\n\n`aks` and `sql` are in both, so `vnet` draws inside `account`. Naming the inner\nzone — `contains gw, vnet` — is accepted as shorthand for exactly that\nexpansion. Everywhere *else* a zone id is an error: you cannot draw an edge to\na boundary. Zones must nest cleanly or stay disjoint in any one view, may not\ncut through an expanded container, and only appear where their members are\nvisible.\n\n## Views (altitudes)\n\nEvery system automatically gets a zoomable view. Declare views to customize or to\nadd lenses — and declare one for any part the ask singles out (\"I care most\nabout orders\"): `render --sync` writes only declared views, so an auto view the\nreader was promised never reaches them as SVGs. `view orders { title \"…\" }` is\nenough.\n\n```squinch\nview landscape { // views take no positional label — the title is a\n title \"System Landscape\" // statement. It draws top-left as the diagram's\n // name, with or without a `titleblock`.\n include * // all TOP-LEVEL entities, as collapsed cards\n}\n\nview shop { // name matching a system = that system's view\n scope shop // implied by the name here; explicit for clarity\n only #pci // KEEP only these — the view's filter. `scope` says\n // where you stand, `only` says which of it you keep.\n // Takes ids too: `only api, vault`\n exclude legacy // trim noise (removes the subtree)\n expand workers // inline one child container in a frame — one\n // level; nesting two explicit expands is an error.\n // Several: `expand workers, ledger`, or one per line\n detail ledger.post // draw an outside node itself, not its system card\n highlight #pci // spotlight matches, dim the rest — this still\n // shows EVERYTHING; \"only the PCI parts\" is `only`\n color #pci red // colour everything tagged #pci, dim nothing —\n // one tag per line; wins over an element's own color:\n note right-of db \"Single-table design; see ADR-42\"\n note top-right \"Audit scope: Q3\" { style: warning }\n context off // drop the muted neighbour cards this view earned\n // (default is `context auto`)\n legend auto // footer key of the styles actually used\n titleblock { // a meta chip under the title. version/commit/\n subtitle: \"Landscape view\" // date are reserved — their values stand alone,\n version: \"2026-07\" // and `commit` sets in mono. Any other key\n commit: \"a41f0c2\" // keeps its key beside its value.\n owner: team-orders // Nothing here is derived: no git, no clock.\n }\n}\n```\n\nWhen the reader wants **everything on one page** — every container open to\nleaf depth, no clicking around — declare a full-detail view with `expand *`\n(declare it after the landscape so the breadcrumb keeps pointing home). It\ncomposes with the other verbs: `scope orders` + `expand *` opens one subtree.\n\n```squinch\nview full {\n title \"Full detail\"\n expand * // open every container, frames nesting as they go;\n // empty containers stay cards, edges de-aggregate\n}\n```\n\nBetween a card and an open frame there is one more altitude: **`preview\n<path>`** (a comma list, or `preview *`) draws a card **detailed** — the children its\n`preview:` attr names (§ containers; up to three, `auto` takes the first three\ndeclared) as readable rows under the head, `+N more` on the shelf for the\nrest. It is still a card: every wire lands on it, nothing attaches to a row,\nand a dive opens the container. Reach for it on the *landscape*, when the\nreader should see what a system is made of without opening it — a domain and\nits capabilities, a platform and its services — and only where those children\ncarry a `description:` or `subtitle:`; three bare names say little more than\nthe chips. Do not put it on every view: a dense view has no room for a card\ntwice its height, and `preview` beside `expand` on the same container is an\nerror.\n\n```squinch\nsystem orders \"Orders\" {\n description: \"Order lifecycle, cart to refund\"\n preview: [checkout fulfillment returns] // what the card calls out; pricing folds into +1\n system checkout \"Checkout\" {\n description: \"Cart to confirmed order\"\n api = aws/lambda \"Checkout API\"\n }\n system fulfillment \"Fulfillment\" {\n description: \"Pick, pack, dispatch\"\n worker = aws/lambda \"Dispatcher\"\n }\n system returns \"Returns\" {\n description: \"Refunds and RMAs\"\n api = aws/lambda \"Returns API\"\n }\n system pricing \"Pricing\" {\n description: \"Prices, promotions, tax\"\n api = aws/lambda \"Pricing API\"\n }\n}\nview landscape {\n include *\n preview orders // the Orders card, with its three parts named\n}\n```\n\nNumbered flows badge a request's path over **edges that already exist** — a\nflow annotates the model, it never creates connections. A step with no edge\nbehind it is a check error telling you to declare the edge first (steps count\nin declaration order; bare ids bind when unambiguous, otherwise use full\npaths):\n\n```squinch\nsystem shop \"Shop\" {\n api = aws/api-gateway \"API\"; create = aws/lambda \"Create\"\n db = aws/dynamodb \"Orders\"; files = aws/s3 \"Files\"\n api -> create // these edges…\n create -> db\n create ~> files\n}\nflow checkout \"Checkout\" {\n api -> create -> db // …are what the flow numbers: steps 1, 2\n create ~> files // step 3 — branches keep counting\n}\nview shop { show flow checkout }\n```\n\n`flow` blocks live at the **top level**, beside your systems — not inside a\n`system` and not inside a `view` (the view only says `show flow <id>`). From out\nthere, write steps as full paths (`shop.api -> shop.create`). A step may cross a\nview's `scope`. A flow is also a story: in the playground's **Present** mode the\narrow keys walk a `show flow` view one hop at a time — nothing extra to author.\n\nGrouping vs. nesting: `include *` shows only *top-level* entities, so wrapping\nseveral services in a parent `system` purely to group them collapses them into\none card at landscape altitude. If they should stay individually visible but\nshare a boundary, keep them top-level and group them with a `zone`.\n\n### When the system is big\n\nA reader can only take in so much at once, so on a large system — a whole\nrepo, a platform — size is a modelling decision, made before layout. A small\nsystem needs none of this: keep it flat.\n\n- **Group before you draw.** Sort the components into the areas the system\n already has — its top-level folders, its teams, its domains — and make each\n a `system`. Use the names the code uses. If nothing hands you the areas,\n find them: things that call each other and change together. The landscape\n then draws one card per area with the calls between them merged (`×4`), and\n every area gets its own zoomable view for free.\n- **It holds at every altitude.** Opening an area should read as easily as the\n landscape does. Every service inside one `backend` system has only moved\n the problem down a click — group by what things are *for* (identity,\n catalogue, buying, fulfilment), and nest a system inside a system when an\n area is itself big.\n- **What a thing owns lives inside it.** A service's own database, cache or\n worker belongs in that service's area, not beside it on the landscape. What\n everyone shares — a gateway, an event bus — stays top-level.\n- **One caller with many targets is the shape that runs off the page**: a UI\n or gateway calling every service draws them all in one row. Grouping the\n targets is the fix; `wrap N` folds the row when they really are peers.\n Never answer it by listing every target in one `rows` band — that forces\n exactly the strip you are trying to avoid.\n- **Hand over altitudes, not one page.** Declare the landscape first, then a\n view for each area worth opening; the interactive HTML lets the reader\n click down. `view full { expand * }` is for when they ask for everything at\n once. Say in your hand-over how you grouped it, so the reader can ask you\n to open an area up rather than start over.\n- **Let the landscape say what each area is made of.** Give every area a\n `description:`, and when its parts are things the reader would recognise —\n the services of a platform, the capabilities of a domain — name the three\n that matter in `preview: [a b c]` and put `preview *` on the landscape view.\n Each card then lists those three under its name, still as one card, and the\n reader knows what is inside before clicking. Only there: a zoomed view has no\n room for cards twice the height.\n\nZoomed views automatically show outside neighbours as muted **context** cards —\ndon't add them yourself; if one appears that you don't want, `context off`.\n\n## Layout hints (in a `layout { }` block — a view's, or a system's own)\n\nThe engine lays a clean diagram out well on its own — ranks follow the arrows,\nfans are centred, wires do not cross boxes. Add a hint when the render shows\nsomething you want changed, not before: every hint is a constraint the engine\nthen keeps, even where its own choice would have crossed fewer wires.\n\n```squinch\nview shop {\n layout {\n direction down // down (default) | right\n density comfortable // compact | comfortable | spacious\n lines orthogonal // orthogonal (default) | curved | straight\n rows [api] [create get search] [db files idx] // horizontal bands, top to bottom\n cols [create db] [get files] // vertical bands, left to right (shared axis)\n place sync right-of db // right-of | left-of | above | below\n align gw db // exact shared axis; first one is the anchor\n channel create, get, search -> db // one trunk into a shared target, not N lines\n // (the edges stay declared in the model;\n // this only merges how they are drawn)\n route api -> db from south to north // which side an edge exits/enters —\n // only for edges that SPAN rows\n route api -> db \"write\" from south // label disambiguates parallels\n }\n}\nview steps { include *\n layout { wrap 5 } } // no row wider than 5: wide ones fold\n```\n\n- `rows` is the workhorse: one bracket group per horizontal band, listed top to\n bottom; order inside a bracket is left to right. Unlisted nodes place\n themselves — only list a node when you care where it lands. Two nodes in\n one band may have an edge between them, and an edge may point back *up* the\n bands (a monitor, a retry path): both are drawn. Do not fold a wide row into\n several bands by hand; that is `wrap`.\n- **`wrap N` means no row holds more than N.** It folds every wider row — in\n the view and inside every system the view opens — a chain as a serpentine,\n a fan-out into bands under its source with one trunk feeding them. A\n system may carry its own (`layout { wrap 4 }`), which follows it into every\n view. Never beside `rows`/`cols` in one block. For a slide, roughly 16:9,\n use N ≈ √(nodes being folded), rounded up: a 14-step chain is `wrap 4`, and\n so are twelve workers under one dispatcher. Leave `direction right` out of\n a wide fold: a band is a rank, and under `direction right` ranks are\n columns, so `wrap 7` becomes two tall columns of seven.\n- `cols` is its transpose: one bracket group per vertical band, left to right.\n Members of a column share an exact axis, so a service and its database line\n up. `rows` and `cols` compose — they pin different axes, so using both gives\n you a full grid, and a cell is empty when nobody is placed in it.\n- **`cols` and `align` work across bands, never within one.** Six collectors\n that all feed one normaliser are siblings on a single rank — they are already\n drawn side by side, and no two of them can share an axis, so `cols [c1 … c6]`\n warns and leaves them where they were. If you want them beside each other,\n that is `rows [c1 … c6]`. The\n trap is worst under `direction right`, where a rank *looks* like a column on\n screen: the words name the model, not the picture.\n- **A system's interior is arranged by the system itself.** Give the system\n its own `layout { }` with `rows`/`cols`/`place`/`wrap` in short names, and that\n arrangement follows it into every view that opens it — expanded beside its\n siblings, or standing inside it in the system's own view. Direct members\n only: a nested container gets its own block. The view then only ranks\n systems against each other, and never restates an interior:\n\n```squinch\nsystem checkout \"Checkout\" {\n api = aws/api-gateway \"API\"; svc = aws/lambda \"Orders\"\n bus = aws/sqs \"Events\"; cache = aws/elasticache \"Sessions\" datastore\n db = aws/dynamodb \"Orders\" datastore\n api -> svc; svc ~> bus; svc -> cache; svc -> db\n layout { rows [api] [svc] [bus cache] [db] } // short names, inside\n}\nsystem pipeline \"Pipeline\" {\n ingest = aws/lambda \"Ingest\"; enrich = aws/lambda \"Enrich\"; publish = aws/lambda \"Publish\"\n ingest -> enrich; enrich -> publish\n layout { direction right } // this interior reads left to right\n}\nview detail {\n expand checkout\n expand shipping\n layout { rows [cdn] [checkout shipping] } // the view ranks the systems\n}\n```\n\n `direction right` in a system's block lays that system's interior out left\n to right wherever it is opened, inside a view that still flows down — the\n way to draw a pipeline as a row. It is a property of the system, not of the\n view: there is no per-view override for an expanded frame.\n A view may still name interior paths (`rows [gw] [checkout.api]`); when its\n hints relate two or more of a system's members they replace that system's\n block in that view, whole — bands are never merged. Naming one member only\n ranks the whole system from outside.\n- **A zone is arranged like a system.** To place the whole boundary, name the\n zone's own id or one member: `rows [gw] [prod_vpc]` puts it below the\n gateway, `rows [batch orders]` sets two namespaces side by side. Hints\n naming two or more of its members arrange them inside it.\n- A node may be in a band **and** carry a `place`, so long as the two agree —\n `rows [db bus]` with `place bus right-of db` is fine; a `place` that puts the\n node somewhere the band does not is refused.\n- `place x right-of y` is the whole side-car idiom (stream processors, caches,\n DLQs). Do **not** add `route y ~> x from east to west` to it: `place` puts\n the two on the same row, where the edge already runs straight across — a\n `from`/`to` on a same-row edge is ignored, and says so.\n\nThe cookbook in `references/cookbook.md` is the next step when a diagnostic is\nnot self-explanatory or the render shows a shape you cannot name the hint for —\nsymptom → fix, keyed on the diagnostic's own words.\n\n## Icons\n\n**Read `references/icons.md` when you need an icon id outside the AWS basics**:\nit lists the ids and aliases per pack, the Google Cloud category rule in full,\nthe Kubernetes short names, the `sys/` rows by theme, and the Databricks recipe\nworked out component by component. Open it before you write the node, not after\n`check` refuses the id.\n\nWhen the request names a **specific product**, search for it — don't write the id\nfrom memory. `check` only tells you an id exists, never that it's the one the\nreader asked for, so a plausible-but-wrong mark passes silently and ships. The\nconfusable pairs are the ones to watch: CloudFront (`aws/cloudfront`, a CDN) is\nnot Cloudflare (`logos/cloudflare`, a different company); `aws/aurora` is not\n`aws/rds`. One `squinch icons search cloudfront` settles it.\n\nThe AWS ids you'll use constantly: `lambda` · `dynamodb` · `s3` · `sqs` · `sns` ·\n`api-gateway` · `opensearch` · `aurora` · `rds` · `elasticache` · `cloudfront` ·\n`eventbridge` · `kinesis` · `step-functions` · `ecs` · `eks` · `fargate` · `ecr` ·\n`athena` · `glue` · `redshift` · `sagemaker` · `bedrock` · `rekognition` ·\n`cognito` · `secrets-manager` · `route-53` · `waf` · `elastic-load-balancing`\n(alias `elb`) · `batch` · `efs` · `app-runner`.\n\nSix packs, and the ids you'll reach for in each:\n\n- **`aws/`** — 316 icons; the basics above.\n- **`azure/`** — 636 icons, named like the portal (`azure/app-services`,\n `azure/storage-accounts`, `azure/monitor`), with short forms for the ones\n everybody abbreviates: `azure/aks` · `azure/vm` · `azure/vnet` ·\n `azure/cosmos` · `azure/functions` · `azure/sql` · `azure/blob` ·\n `azure/service-bus` · `azure/event-hub` · `azure/key-vault` ·\n `azure/front-door` · `azure/app-gateway` · `azure/load-balancer` ·\n `azure/aci` · `azure/acr` · `azure/api-management` · `azure/log-analytics` ·\n `azure/redis`.\n- **`gcp/`** — 45 icons, because Google's own system works that way: nineteen\n products have a unique mark (`gcp/cloud-run`, `gcp/gke`, `gcp/bigquery`,\n `gcp/cloud-sql`, `gcp/spanner`, `gcp/vertex-ai`…), and *every other product\n draws its category's glyph* under the name you know it by (`gcp/pubsub`\n draws Data Analytics). Put the product name in the label and let the icon\n say the category.\n- **`k8s/`** — 39 icons under kubectl's short names, for what runs *inside* a\n cluster: `k8s/pod` · `k8s/deploy` · `k8s/svc` · `k8s/sts` · `k8s/ds` ·\n `k8s/cm` · `k8s/secret` · `k8s/ing` · `k8s/ns` · `k8s/sa` · `k8s/pv` ·\n `k8s/pvc` · `k8s/hpa` · `k8s/job` · `k8s/cronjob` · `k8s/crd` · `k8s/node` ·\n `k8s/etcd` · `k8s/control-plane` · `k8s/api` · `k8s/sched` · `k8s/kubelet`.\n `logos/kubernetes` when the cluster is one box in a wider estate.\n- **`logos/`** — 147 product marks plated in their brand colour, the non-cloud\n half of a stack: `logos/postgres` · `logos/mysql` · `logos/mongodb` ·\n `logos/redis` · `logos/kafka` · `logos/rabbitmq` · `logos/elasticsearch` ·\n `logos/docker` · `logos/terraform` · `logos/nginx` · `logos/github` ·\n `logos/gitlab` · `logos/grafana` · `logos/prometheus` · `logos/datadog` ·\n `logos/sentry` · `logos/stripe` · `logos/snowflake` · `logos/cloudflare` ·\n `logos/vercel` · `logos/react` · `logos/python` · `logos/go` · `logos/rust`.\n Slack, Twilio, Salesforce, Heroku, gRPC and dbt have no mark upstream — use\n `box` or the label.\n- **`sys/`** — 195 generic Lucide icons for what no vendor draws, and it needs\n no `pack` statement. Ids are Lucide's own names, so a word you would say\n (`process`, `analytics`, `device`, `web`) is usually *not* one — pick from\n these: compute `server` `container` `cpu` `code` `app-window` `terminal`\n `cog` `webhook` `workflow`; hardware `laptop` `monitor` `smartphone`\n `hard-drive` `printer`; network `network` `router` `wifi` `radio-tower`\n `globe` `share-2`; security `lock` `key-round` `shield` `shield-check`;\n data `database` `folder` `search` `archive` `table` `file`; places `factory`\n `warehouse` `building-2` `house` `earth`; process and observability `clock`\n `timer` `repeat` `activity` `gauge` `chart-line` `siren` `bug`; commerce\n `shopping-cart` `credit-card` `wallet` `receipt-text` `truck`\n `package-check` `barcode`; shapes `box` `circle` `square` `hexagon`\n `diamond` `star`. Aliases: `gear`→`cog`, `db`→`database`,\n `rack`/`vm`/`host`→`server`, `firewall`→`shield`, `vault`→`lock-keyhole`,\n `cron`→`clock`, `lb`→`share-2`, `cart`, `payment`, `order`, `shipping`.\n\nPick one cloud's pack and stay with it — don't draw the same concept as\n`aws/…` in one box and `azure/…` in the next. Composing a cloud pack with\n`logos` and `sys` is normal; it's how you draw a hybrid estate. A platform with\nno pack at all — Databricks, Snowflake, dbt, Confluent publish no icons anyone\nmay redistribute — is drawn as the concept from `sys/*` with the vendor's mark as\na `badge:` where `logos/*` has one; never a lookalike from another vendor, never\nan invented id.\n", "references/cookbook.md": "# Layout cookbook (symptom → fix)\n\nOpen this when `check` reports a diagnostic you do not recognise, or when the\nrender shows something you cannot name the hint for. Every row is keyed on the\ndiagnostic's own words or on what you see; search this file for either. The\nrows assume the Layout-hints section of `SKILL.md`, which explains the hints\nthemselves.\n\n## Contents\n\n- [Placing and banding](#placing-and-banding) — `rows`, `cols`, `place`, `align`, `wrap`, direction — and the hints `check` refuses or warns about\n- [Edges and wires](#edges-and-wires) — fan-in, trunks, self-edges, chaining, `route`, step badges\n- [Zones](#zones) — boundaries that overlap, cut through a frame, or have nothing to show\n- [Labels, attributes and ids](#labels-attributes-and-ids) — cut-off text, attrs on the wrong element, tags, prefixes\n- [Views and altitude](#views-and-altitude) — empty views, `expand`, `only`/`highlight`/`color`, `include`, `detail`, context cards\n- [Icons](#icons) — an id you cannot find\n\n## Placing and banding\n\n| Symptom | Fix |\n|---|---|\n| Layers feel arbitrary / related things scattered | Add `rows`, one group per conceptual tier (entry, handlers, storage) |\n| One node belongs beside another (stream sync, DLQ, cache) | `place X right-of Y` — that is all. The connecting edge runs straight across; adding `route … from east to west` does nothing, because `place` puts them on one row |\n| \"`route x -> y` sides are ignored — it is a same-rank edge\" warning | Drop the `from`/`to`. Sides only apply to edges that span rows |\n| \"`route x -> y` could not use the side it asks for here\" warning | That wall already carries a wire running straight across to a neighbour, or the edge is part of a `channel` or a `wrap` trunk, or that end is a system rather than a node. Drop the `from`/`to`, or free the wall (move the neighbour to another row, take the edge out of the `channel`) |\n| \"`x` is placed `right-of y`, but `rows` puts it somewhere else\" error | The two hints disagree. Restating a band is fine — `rows [db bus]` alongside `place bus right-of db` is accepted, since both say the same thing — so fix whichever one is wrong, or drop `x` from the band |\n| \"`x` is listed in `rows` but is placed relative to `y`, which is not\" error | Put `y` in a band too, or take `x` out of its band. A banded node can only be placed against another banded one |\n| \"cols `[a b c]` — all 3 sit on the same rank, so they cannot share an axis\" warning | You wanted them side by side; that is `rows [a b c]`. `rows` is a **rank** — things drawn beside each other. `cols`/`align` stack a node onto another's axis *across* ranks. The confusion is worst with `direction right`, where a rank looks like a column on screen — the words describe the model, not the picture |\n| \"`x` appears in `rows` twice\" error — likewise \"appears in `cols` twice\" | A node can hold only one rank position; remove one of the two occurrences |\n| A wire jogs slightly instead of running straight | `align a b` — b takes a's axis exactly (a is the anchor) |\n| \"align `[a b]` — `b` could not be put on `a`'s axis\" warning — likewise for `cols` | They sit in different systems or zones, or another hint holds them apart. Align the containers themselves, or drop one of the hints |\n| An edge runs back up the page (a monitor, a retry, a feedback path) | That is how it is drawn: out of the top of the lower node, into the bottom of the upper one. To shorten it, put the observer in the same band as what it watches (`rows [api mon] [svc] [db]`), or leave it out of `rows` |\n| Edge exits a silly side | `route a -> b from south to north` (sides: north/south/east/west) |\n| Everything takes a long detour around the canvas | Check whether an edge points *against* the flow. Reversing one back-edge to face the direction traffic actually travels beats any hint |\n| A full-detail view came out tall — want it wide | Add `layout { rows … }` banding the expanded systems side by side; calls between them cross the gutters and land on the nodes they name |\n| An expanded system's insides are in the wrong order or tier | Give the system its own `layout { rows … }` in short names — it follows the system into every view. Or name the interior paths in the view's `rows` (`[app.api] [app.db app.cache]`), which replaces the system's block for that view |\n| A pipeline inside a system should read left to right while the view flows down | `layout { direction right }` inside that system — its interior becomes a row wherever it is opened; the view keeps its own direction |\n| A long chain renders as a tall strip, or a wide row runs off the page | `layout { wrap 5 }` — no row holds more than 5. A chain folds into a serpentine; any other wide row folds into bands, fed by one trunk. It reaches every system the view opens; one system alone takes it in its own block (`layout { wrap 4 }`). Never beside `rows`/`cols`. For a 16:9 slide, N ≈ √(nodes) rounded up, and no `direction right` |\n| \"`wrap 5` has no effect — no row here is wider than 5\" warning | Nothing to fold. Lower the number, or drop the line |\n| Diagram too cramped / too airy | `density spacious` / `density compact` |\n\n## Edges and wires\n\n| Symptom | Fix |\n|---|---|\n| \"an edge has one source — `x, y` cannot fan in\" error | Fan-out exists (`a -> b, c`), fan-in does not: write one edge per source. If the point is the *drawing* — many arrows converging as one trunk — that is `channel x, y -> z` in the view's layout |\n| Several things all write to one store, crossing each other | `channel a, b, c -> db` — they merge into one trunk |\n| \"channel into `x`\" warning | The trunk needs the target visible in this view and at least two of its member edges. Check that nothing is `exclude`d or folded into a collapsed card |\n| \"`x` connects to itself — a self-edge is not drawn\" warning | Squinch draws connections between things, not loops on one thing. Put it on the node: `note right-of x \"retries\"`, or fold it into the label |\n| \"edges do not chain — `a -> b -> c` is one statement per hop\" error | Only a `flow` chains hops. Write each connection on its own line — `a -> b`, then `b -> c` — and, if the sequence itself is the point, declare a `flow` that walks them |\n| \"N edges match route …\" error | Add the edge's label to the `route` statement |\n| A numbered step's badge sits past its target node | The edge label is too wide for that run — shorten it, or the badge gets evicted and the reading order looks wrong |\n\n## Zones\n\n| Symptom | Fix |\n|---|---|\n| \"zones `a` and `b` contain exactly the same members\" error | Two names for one boundary. Neither can sit inside the other, so merge them into a single `zone`, or narrow one's `contains` so it is genuinely a sub-boundary |\n| \"zones `a` and `b` partially overlap — visible zones must nest or stay disjoint\" error | Boundaries must nest or stay apart, never half-lap. The fix line lists which members are shared and which are exclusive — either give the inner zone only members the outer one also has, or move the odd one out |\n| \"zone … cuts through expanded container\" | The zone holds *some* children of a container you `expand`ed — contain the whole container, or drop the `expand` in that view |\n| \"zone … has no visible members\" | Its members are inside collapsed cards at this altitude — `expand` one, scope the view to them, or contain the container itself |\n| A zone's members are in the wrong order or tier | Name them in the view's `rows`/`cols`/`place` — hints relating two or more members of a zone arrange them inside it. To move the whole boundary, name the zone's id: `rows [gw] [prod_vpc]` |\n| \"`a` → `b` is not drawn — one end is inside the other\" warning | The edge points from a system at something inside it (or the reverse) while that system is open. Point it at a member instead, or collapse the system in this view |\n| Need a VPC / network boundary / cloud-vs-on-prem split | `zone id \"Label\" vpc { contains a, b }` — kinds: account, region, vpc, subnet, network, cloud, onprem, custom |\n\n## Labels, attributes and ids\n\n| Symptom | Fix |\n|---|---|\n| \"`owner` has a tag value — tags live in `tags:`\" error | Only the `tags:` key collects tags. A `#value` under any other key is either a tag that belongs in `tags:`, or plain text that needs quotes |\n| \"N ids are missing their `sys` prefix\" error | Ids declared inside a `system` are addressed from outside it by their full path. Inside `shop`, write `api`; from a `zone`, a `view` or another system, write `shop.api`. The error folds every id that made the same mistake into one line because it is one mistake |\n| \"`datastore` on `system s` — only `external` applies to a system\" error | Only `external` describes a whole system. The other kinds describe one node: put it on a node inside, or drop it |\n| \"label is N characters — it will be cut off\" warning | A leaf widens, then wraps to two lines, and past that the reader loses the tail; a card's name gets one line. Keep it a short noun phrase and move the detail into `description:` |\n| \"subtitle is N characters — it will be cut off\" warning | A subtitle is one line and widens a leaf only up to 240. Keep it to a few words — runtime, owner, region — and move the rest into `description:` |\n| \"`show descriptions` no longer draws anything\" warning | Descriptions are prose: they show as a system's card tagline and in hover, never inside a leaf. Drop the line, and give the leaves a short `subtitle:` — runtime, owner, region — for the line under the label |\n| \"unknown zone attribute `description`\" warning | A zone's chip holds its label and a mono `detail:` (a CIDR, an account id) — nothing else. Prose about the boundary goes in a `note` anchored to a member |\n| A table's `fields` are written but nothing draws | Fields draw where the table's container is open: a view scoped to it (`view db { scope shop.db }`) shows every field, and expanding it (`expand db`) shows a compact list. A top-level table needs `preview <table>`. The landscape never draws them, by design |\n| \"`x`'s fields are never drawn — no view shows them\" warning | No view opens the table's container with the table in it, and nothing previews it. The fix names the line: `preview x` for a top-level table, or stop filtering it out of its container's view |\n| \"preview `x` is redundant\" warning | Its fields already draw here — the view is scoped to its container, or the container is expanded. Drop the line; `preview` never changes how many show |\n| \"`schema { }` is not a block a leaf takes\" error | The block is `fields { }`, inside the table's own braces, one field per line: `id uuid pk` |\n| \"comments are `//` — `--` is an arrow here\" error | SQL's `--` is an arrow in squinch. Write `id uuid pk // primary key`, or put the note in a quoted caption: `id uuid pk \"primary key\"` |\n| \"`?` is not squinch\" / \"`@` attributes are not squinch\" error | Pasted Prisma or ORM syntax. An optional field says `nullable`, `@id` is `pk`, any other `@attr` is a bare marker word. The fix writes the whole corrected line |\n| \"`scope x` names a leaf — a view stands inside a container\" error | To see a table's fields, scope its container: `scope shop.db`. The table draws every field there |\n| \"`subtitle` is a leaf attribute\" warning | Only a leaf draws a line under its name. On a system or container that line is `description:` (it shows on the collapsed card); a `person` has none |\n\n## Views and altitude\n\n| Symptom | Fix |\n|---|---|\n| \"view `v` has nothing to draw\" warning | Everything got filtered out. Check `scope` (a leaf has no insides — scope a system, not a node), then `include`/`only`/`exclude`. An empty `system x { }` does this too: make it a node instead |\n| Too many boxes at once | Group into `system`s by area and let the landscape show their cards — see \"When the system is big\". Splitting into views alone does not help while everything is still top-level |\n| Everything open on one page, no clicking into containers | `view full { expand * }` — every container becomes a nested frame, every edge shows natively |\n| \"expand `x` inside `x`'s own view — this view stands inside `x` already\" warning | A view named after a container *is* that container's own view: you are already inside it. To draw `x` opened up among its neighbours, name the view something else: `view overview { expand x }` |\n| \"`expand *` already opens every container — the explicit `expand` lines are redundant\" warning | Drop the explicit `expand x` lines; the star covers them |\n| \"`expand *` opened nothing — no containers are visible here\" warning | The model (or this scope) has no containers to open — drop the line |\n| Show **only** one concern (an auditor's view: \"only the PCI parts\") | `only #pci`. Anything outside the scope that the survivors still talk to stays as a muted context card — that boundary crossing is usually the point of the view; `context off` drops those too |\n| Emphasise one concern while keeping its context | `highlight #pci` — spotlights matches, dims the rest, shows everything |\n| Tell two groups apart, or mark one path, without dimming anything | `color #team-a teal` in the view (tags inherit through containers), or `{ color: red }` on the element. Nine hues, never hex |\n| \"color #x: nothing visible here is tagged #x\" warning | Same cause as the `highlight` row: the tag is misspelled, or its carriers are not in this view — check `tags:` and the view's `include`/`only` |\n| \"`x` is tagged #a (red) and #b (blue) — #b wins\" warning | Two `color` lines landed on one element. Give both tags the same hue, or narrow one of them |\n| Narrow a view with `include #tag` | It does not narrow. `include` **adds**; an include that changes nothing warns and points at `only` |\n| Show one specific node from another system, not its whole card | `detail ledger.post` |\n| A neighbour system clutters a zoomed view | `exclude thatSystem` or `context off` |\n| \"highlight #x: nothing visible here is tagged #x\" warning | Everything would dim and nothing stand out. The tag is misspelled, or the things carrying it are not in this view — check the tag against your `tags:`, and the view's `include`/`only` |\n| Not sure which views exist | `squinch check <path>` lists them (`--format json` puts them in `views`) |\n\n## Icons\n\n| Symptom | Fix |\n|---|---|\n| Icon unknown | Collect every icon you're unsure of and search once: `squinch icons search \"queue, vector search, llm\"` — commas separate terms, spaces stay a phrase. `no exact match — closest:` rows are ranked next moves. The check error's `did you mean` is usually right |\n", "references/icons.md": "# Icons, pack by pack\n\nOpen this when you need an icon id outside the AWS basics in `SKILL.md`:\nthe ids and aliases each pack ships, the Google Cloud category rule, the\nKubernetes short names, the `sys/` rows by theme, and the recipe for a vendor\nwith no pack. Searching is still the first move — `squinch icons search \"a, b, c\"`\nbatches every unknown in one call — and this file says what the search will\nfind and which id to prefer when several match.\n\n## Contents\n\n- [AWS](#aws) — the ids you'll use constantly, and the confusable pairs\n- [Azure](#azure) — portal names, and the short forms everybody abbreviates\n- [Google Cloud](#google-cloud) — nineteen unique marks; everything else draws its category glyph\n- [Kubernetes](#kubernetes) — kubectl short names for what runs inside a cluster\n- [Logos — products and open source](#logos--products-and-open-source) — brand marks for the non-cloud half of a stack\n- [sys — the generic set](#sys--the-generic-set) — Lucide icons for what no vendor draws, by theme\n- [Platforms with no icon pack](#platforms-with-no-icon-pack) — Databricks, Snowflake, dbt, Confluent: `sys/*` plus a `badge:`\n\n## AWS\n\nWhen the request names a **specific product**, search for it — don't write the id\nfrom memory. `check` only tells you an id exists, never that it's the one the\nreader asked for, so a plausible-but-wrong mark passes silently and ships. The\nconfusable pairs are the ones to watch: CloudFront (`aws/cloudfront`, a CDN) is\nnot Cloudflare (`logos/cloudflare`, a different company); `aws/aurora` is not\n`aws/rds`. One `squinch icons search cloudfront` settles it.\n\n`lambda` · `dynamodb` · `s3` · `sqs` · `sns` · `api-gateway` · `opensearch` ·\n`aurora` · `rds` · `elasticache` · `cloudfront` · `eventbridge` · `kinesis` ·\n`step-functions` · `ecs` · `eks` · `fargate` · `ecr` · `athena` · `glue` ·\n`redshift` · `sagemaker` · `bedrock` · `rekognition` · `cognito` ·\n`secrets-manager` · `route-53` · `waf` · `elastic-load-balancing` (alias `elb`) ·\n`batch` · `efs` · `app-runner`\n\nShort aliases exist for the famous ones (`s3`, `sqs`, `sns`, `eks`, `ecs`, `ecr`,\n`elb`, `glacier`, `opensearch`).\n\n## Azure\n\n**Azure** has its own pack (636 icons). Short forms exist for the ones everybody\nabbreviates: `azure/aks` · `azure/vm` · `azure/vnet` · `azure/cosmos` ·\n`azure/functions` · `azure/sql` · `azure/blob` · `azure/service-bus` ·\n`azure/event-hub` · `azure/key-vault` · `azure/front-door` · `azure/app-gateway` ·\n`azure/load-balancer` · `azure/aci` · `azure/acr` · `azure/api-management` ·\n`azure/log-analytics` · `azure/redis`. Canonical ids read like the portal —\n`azure/app-services`, `azure/storage-accounts`, `azure/monitor`,\n`azure/application-insights`; `squinch icons search --pack azure <term>` scopes\nthe search. Pick one cloud's pack and stay with it — don't draw the same\nconcept as `aws/…` in one box and `azure/…` in the next. Combining a cloud pack\nwith `logos` is a different thing and completely normal: it's how you draw a\nhybrid estate, with `logos/postgres` on the on-prem side and `azure/sql` in the\ncloud.\n\n## Google Cloud\n\n**Google Cloud** has its own pack (45 icons), and it works differently from\nthe other two clouds because Google's own icon system does: nineteen core\nproducts carry a unique four-colour mark, and *every other product draws as\nits category's glyph*. The unique marks: `gcp/cloud-run` (`run`) · `gcp/gke` ·\n`gcp/compute-engine` (`gce`, `vm`) · `gcp/cloud-storage` (`gcs`, `bucket`) ·\n`gcp/cloud-sql` (`sql`) · `gcp/spanner` · `gcp/alloydb` · `gcp/bigquery` (`bq`)\n· `gcp/vertex-ai` (`vertex`) · `gcp/looker` · `gcp/apigee` · `gcp/anthos` ·\n`gcp/distributed-cloud` (`gdc`) · `gcp/hyperdisk` (`persistent-disk`) ·\n`gcp/ai-hypercomputer` · `gcp/security-command-center` (`scc`) ·\n`gcp/security-operations` (`secops`) · `gcp/threat-intelligence` ·\n`gcp/mandiant`. Everything else resolves by the name you know it by and draws\nthe category glyph: `gcp/pubsub`, `gcp/dataflow` and `gcp/dataproc` all draw\nthe Data Analytics mark; `gcp/cloud-functions` (`functions`) and\n`gcp/app-engine` the Serverless one; `gcp/firestore`, `gcp/bigtable` and\n`gcp/memorystore` the Databases one; `gcp/load-balancer` (`lb`), `gcp/cloud-cdn`,\n`gcp/cloud-armor` and `gcp/cloud-nat` the Networking one; `gcp/iam`, `gcp/kms`\nand `gcp/secret-manager` the Security one; `gcp/cloud-build` and\n`gcp/artifact-registry` the DevOps one; `gcp/cloud-logging` and\n`gcp/cloud-monitoring` the Observability one. That is how Google draws them\nnow, so it is not a shortfall to work around — **put the product name in the\nlabel** and let the icon say the category; don't borrow a look-alike from\n`aws/` or `azure/`. A VPC is a boundary: `zone net \"prod-vpc\" network {\ncontains …, icon: gcp/vpc }`. The same one-cloud rule applies, and composing\nwith `logos` is normal. Use `gcp/*` when the diagram is about what runs\n*inside* Google Cloud; use `logos/googlecloud` when Google Cloud is one box in\na wider estate. `squinch icons search --pack gcp <term>` scopes the search;\nthe bare word `gcp` lists the whole pack.\n\n## Kubernetes\n\n**Kubernetes internals** come from the `k8s` pack (39 official community\nicons — the blue heptagons from the k8s docs). Canonical ids are kubectl's\nshort names, and the long names alias to them, so both spellings check clean:\n`k8s/pod` · `k8s/deploy` (`deployment`) · `k8s/svc` (`service`) · `k8s/sts`\n(`statefulset`) · `k8s/ds` (`daemonset`) · `k8s/rs` (`replicaset`) · `k8s/cm`\n(`configmap`) · `k8s/secret` · `k8s/ing` (`ingress`) · `k8s/ns` (`namespace`) ·\n`k8s/sa` (`serviceaccount`) · `k8s/pv` · `k8s/pvc` · `k8s/sc` · `k8s/netpol` ·\n`k8s/hpa` · `k8s/job` · `k8s/cronjob` · `k8s/crd` · `k8s/node` · `k8s/etcd` ·\n`k8s/control-plane` · `k8s/api` (`apiserver`) · `k8s/sched` (`scheduler`) ·\n`k8s/kubelet` · `k8s/k-proxy` (`kubeproxy`).\nUse `k8s/*` when the diagram is about what runs *inside* a cluster; use\n`logos/kubernetes` when the cluster is one box in a wider estate. A namespace\nis a boundary, not a workload — prefer `zone team-a \"team-a\" custom { contains\n…, icon: k8s/ns }` over a `k8s/ns` node. Composing with a cloud pack is normal:\n`azure/aks` or `aws/eks` as the managed control plane, `k8s/*` for what it runs.\n\n## Logos — products and open source\n\n**Non-AWS things** come from the `logos` pack (147 product marks, plated in\ntheir brand colour): `logos/postgres` · `logos/mysql` · `logos/mongodb` ·\n`logos/redis` · `logos/kafka` · `logos/rabbitmq` · `logos/elasticsearch` ·\n`logos/kubernetes` (`k8s`) · `logos/docker` · `logos/terraform` ·\n`logos/nginx` · `logos/github` · `logos/gitlab` · `logos/grafana` ·\n`logos/prometheus` · `logos/datadog` · `logos/sentry` · `logos/stripe` ·\n`logos/snowflake` · `logos/cloudflare` · `logos/vercel` · `logos/nextdotjs` ·\n`logos/react` · `logos/python` · `logos/nodedotjs` (`node`) · `logos/go` ·\n`logos/rust` · `logos/graphql`.\nSome brands (Slack, Twilio, Salesforce, Heroku, gRPC…) have no icon upstream —\nthey were withdrawn on trademark request. Use `box` for those.\n\n## sys — the generic set\n\n`sys/*` is the generic set — 195 Lucide icons for anything no vendor draws, and\nit needs no `pack` statement. Use it for on-prem and physical things, and as the\nlast resort when nothing else fits. Ids are Lucide's own names:\n\n- **compute / app** — `server`, `container`, `cpu`, `code`, `app-window`,\n `hexagon`, `terminal`, `cog`, `webhook`, `workflow`, `route`\n- **hardware** — `laptop`, `monitor`, `smartphone`, `hard-drive`, `printer`\n- **network** — `network`, `router`, `wifi`, `radio-tower`, `globe`, `share-2`\n- **security** — `lock`, `lock-keyhole`, `key-round`, `shield`, `shield-check`\n- **data** — `database`, `folder`, `search`, `archive`, `table`, `file`\n- **places** — `factory`, `warehouse`, `building-2`, `house`, `earth`\n- **process / observability** — `clock`, `timer`, `repeat`, `activity`, `gauge`,\n `chart-line`, `siren`, `bug`\n- **commerce** — `shopping-cart`, `shopping-bag`, `credit-card`, `wallet`,\n `receipt-text`, `banknote`, `coins`, `badge-percent`, `ticket`, `truck`,\n `package-check`, `barcode`, `calculator`, `gift`, `heart`, `headset`\n- **shapes, when nothing fits** — `box`, `circle`, `square`, `triangle`,\n `diamond`, `hexagon`, `star`\n\nShort aliases exist for words you would type instead: `gear`→`cog`,\n`cube`→`box`, `db`→`database`, `rack`/`vm`/`host`→`server`, `disk`→`hard-drive`,\n`firewall`→`shield`, `vault`→`lock-keyhole`, `cron`→`clock`, `lb`→`share-2`,\n`cart`→`shopping-cart`, `checkout`→`shopping-bag`, `payment`→`credit-card`,\n`order`/`invoice`→`receipt-text`, `shipping`→`truck`, `ads`→`megaphone`.\n\n## Platforms with no icon pack\n\nSome vendors publish no icons anyone may redistribute, so no pack exists and none\never will — Databricks, Snowflake, dbt and Confluent are the ones that come up.\nDon't reach for a lookalike from another vendor and don't invent an id. Draw the\n*concept* from `sys/*` and mark it with the vendor's mark from `logos/*`:\n\n```squinch\nwh = sys/database \"SQL warehouse\" { badge: logos/databricks, subtitle: \"Databricks SQL\" }\n```\n\nThe `subtitle:` is optional; it names the product where the mark alone only\nnames the vendor.\n\nDatabricks, worked out — every base below is a real `sys/` id or alias:\n\n| component | write |\n| --- | --- |\n| Delta table | `sys/table … { badge: logos/databricks }` |\n| Unity Catalog | `sys/catalog` |\n| SQL warehouse | `sys/database` |\n| Vector search | `sys/waypoints` |\n| Model serving | `sys/model` |\n| MLflow experiment | `sys/experiment` |\n| Notebook | `sys/notebook` |\n| Workflows job | `sys/workflow` |\n| Structured streaming | `sys/stream` |\n\nThe same recipe covers any vendor whose mark is in the logos pack —\n`logos/snowflake` is there, dbt and Confluent are not. Search before writing a\nbadge; if there's no mark, skip the badge and let the label carry the vendor.\nBadge only what the platform actually owns: a Kafka or S3 node keeps its own\nicon, and that contrast is what makes the platform boundary readable.\n" };
6
+ export const SKILL_FILES = { "SKILL.md": "---\nname: squinch\ndescription: Author architecture diagrams as code with the Squinch DSL. Use this whenever the user wants an architecture or system diagram — creating one from prose, editing or reviewing a .squinch file, drawing cloud infrastructure (AWS, Azure, Kubernetes, hybrid estates), documenting services for a README or a design review, or any picture of systems, services and the connections between them — even when they never say \"squinch\". Write the .squinch model, validate it with `squinch check`, render it with `squinch render` (SVG in both themes plus the interactive HTML by default; PNG only when asked), and fix what you see with the layout cookbook.\ncompatibility: Requires Node.js 22+ and the squinch CLI on PATH, or npx squinch with no install\n---\n\n# Squinch — architecture diagrams as code\n\nSquinch renders `.squinch` files into deterministic SVG diagrams. You write the\n*model* (systems, components, connections); the engine lays it out. When the\nauto-layout isn't what you want, you steer it with **relative** hints — there are\nno pixel coordinates anywhere in the language.\n\n## The loop\n\nWork like a compiler user, not an artist:\n\n```bash\nsquinch check diagram.squinch --format json # parse + lint; machine-readable\nsquinch render diagram.squinch -o out.svg # deterministic SVG; theme: the view's, else dark\nsquinch render diagram.squinch --view NAME --theme light -o out.svg # themes: light | dark\nsquinch render diagram.squinch --sync # every view × both themes, next to the source\nsquinch render diagram.squinch -o out.html # one interactive file: every view, both themes\nsquinch render diagram.squinch -o out.png --scale 2 # PNG, only when asked (--width also works)\nsquinch icons search \"<term>, <term>, …\" # find icon ids — batch every unknown in one call\nsquinch diff --format json # what changed in the architecture\n```\n\nIf `squinch` is not on PATH, prefix every command with `npx` — `npx squinch\ncheck …` — or install it once with `npm i -g squinch`.\n\n### What to hand over\n\nUnless the user names a format or a theme, a finished diagram is **all** of:\n\n```bash\nsquinch render diagrams/ --sync # <name>.<view>.light.svg + .dark.svg per view\nsquinch render diagrams/ -o diagram.html # every view, both palettes, click-to-zoom, presentation mode\n```\n\n- **Both themes, always.** Dark is designed, not inverted, and the reader's\n environment picks — never choose one for them. For a README or a docs site\n that should follow the reader's colour scheme, `--adaptive -o x.svg` folds\n the pair into one SVG behind `prefers-color-scheme`.\n- **The HTML is the thing to open.** It is one self-contained file with every\n view and a theme switch, and it needs no server — point the user at it\n first. A project with several views is unreadable as a pile of SVGs.\n- **PNG is the exception**, not the default: render one only when the user\n asks for an image, slides, or a surface that cannot show SVG. A PNG you\n render to check your own work is a different thing (quality bar 3) and\n stays out of the hand-over.\n- Every render carries the tool version that drew it (`data-squinch` on the\n root `<svg>`), and `render --check` re-renders and compares, so committed\n SVGs can gate CI. For a throwaway diagram that lives nowhere, two explicit\n `--theme` renders plus the HTML are the lighter recipe.\n- **Write the files; leave committing to the user.** Don't commit, push or\n make a branch unless they ask — they will want to look first.\n\nThen end your reply with three to five bullets, one or two plain sentences\neach, the way you would say it to a colleague — and nothing before them that\nsays the same thing:\n\n- Open `diagram.html` — it has the landscape and orders views, light and dark.\n- I guessed that the services run on Lambda and that Postgres means RDS; the\n request named neither.\n- I looked at both views. The one rough spot is the Kafka wire running round\n the right edge; moving it made the services row harder to read, so I left it.\n- If this is more than you need, I can take out the load generator and the\n tracing collector, or show less detail by grouping the services into three\n areas.\n\nThe first three are never skipped: where to open it; what you guessed — every\nproduct, cloud or runtime the request did not name — or \"Nothing guessed\" when\nthat is true; and what you saw when you looked, or that you could not look.\nThe last — an offer to cut it down, naming your own most peripheral boxes, not\na category — ends every hand-over of an open-ended request or a big system,\nand is left off a small diagram that drew what was asked. One more bullet may\nsay how you grouped a big system, or a warning you kept. Don't describe the\ncomponents or the layout: the diagram shows them.\n\n0. If the system is big — a whole repo, a platform — decide its *areas* before\n you write a node, because no layout hint rescues everything on one page: see\n \"When the system is big\".\n1. Write the model first, with **no `layout` block at all** — most diagrams\n never need one. Your edges already say what the tiers are, and the engine\n ranks from them: a node sits below everything that points at it. Render it\n and look. Add hints only to fix something you can see is wrong, one at a\n time, naming only the nodes you actually care about. Icon ids outside the\n AWS basics — anything `azure/`, `gcp/`, `k8s/`, `logos/` or `sys/` — are\n looked up before the first `check`, never written from memory: open\n `references/icons.md`, which lists them per pack, or run `squinch icons\n search` with every unknown in one call. An id guessed from the word you\n would say — a `sys/` or `azure/` name that reads right and does not exist —\n is the most common way a first `check` fails.\n2. `check` after every edit. Diagnostics tell you the location, the problem, and\n usually the fix (`did you mean ...?`). Trust them. When one is not\n self-explanatory, open `references/cookbook.md` — symptom → fix, keyed on\n the diagnostic's own words.\n3. Exit code 0 and **no diagnostics at all** = clean. Errors block the render;\n warnings do not, which is exactly why they matter — a warning means the file\n is valid but probably not the diagram you were asked for. Fix warnings\n before you stop.\n4. A stderr line starting `update:` (a newer squinch is on npm) or `skill:`\n (this SKILL.md was installed by a different squinch) — or the `update` /\n `skill` fields in `check --format json` — is information, not a diagnostic:\n exit 0 with no diagnostics is still clean. Mention it to the user once and\n carry on. Never upgrade squinch or re-run `squinch skill` unasked: an\n upgrade can change render bytes, and that is the user's call.\n\n## Quality bar before you call it done\n\n1. `squinch check` exits 0 with no diagnostics.\n2. **Every view** you declared is rendered in both `--theme light` and\n `--theme dark`, plus the interactive `.html` — and all of it is handed\n over, not just checked (see \"What to hand over\").\n3. **Look at the picture, not the markup.** SVG source cannot show you a\n detour. Rasterise each view beside the source and open the image —\n `squinch render diagram.squinch --view NAME -o NAME.check.png` — then\n delete the `.check.png` files when you are done. Keep them inside your\n working directory: a path like `/tmp` is often one you may not read. One\n theme is enough, both share one layout. Tiers read top-to-bottom (or\n left-to-right), no edge takes a baffling detour, async flows (`~>`) are\n dashed, related things sit together. If you could not view the image, say\n so in the hand-over and make no claim about how the layout looks.\n4. Labels are short noun phrases. A `subtitle:` of a few words says what a\n leaf runs on or who owns it; anything longer goes in `description`, never\n the label.\n5. Model semantics honestly: request/response is `->`; anything that queues,\n buffers or fans out is `~>`. If the prose says stream, queue, topic, event,\n publishes, emits, feeds, notifies or subscribes — Kinesis, Kafka, SQS, SNS,\n EventBridge, Service Bus — that edge is `~>`, and a pipeline drawn entirely\n with `->` is almost always wrong.\n6. **Every actor the prose names is in the diagram.** People are easy to drop:\n \"customers browse\", \"developers push\", \"an analyst queries\" each name a\n `person`, and a stack diagram that draws only the technology has left out\n who uses it. Re-read the request and check each noun appears — a human is a\n `person`, not a box and not omitted.\n7. **Nothing is in the diagram that the request does not support.** A reader\n takes every box as a fact, so a CDN, WAF, cache or queue that nothing in\n the request implies is a guess presented as truth — leave it out. The same\n goes for glue: an API or worker you put between two things the request\n names, and a product you picked where it named only a kind (\"Postgres\" is\n not \"RDS\"). A `link:` is the same: use a URL the request or the code gives\n you, never one you composed. When the picture cannot be drawn without\n filling a gap, draw the plainest reading and say what you guessed in the\n hand-over.\n\n## Language\n\n```squinch\n// comments are // only (# belongs to tags)\npack aws // icon packs this file draws from (aws |\npack azure // azure | gcp | logos | k8s). Optional — any\n // installed pack resolves without it — but\n // declaring documents intent and catches a\n // misspelled pack name at check time.\n\nperson customer \"Customer\" // human actor. This form is top-level\n // only — inside a system write it as\n // `who = person \"Operator\"`. Either\n // takes a block: `{ description: \"…\" }`\ngw = aws/api-gateway \"Edge Gateway\" // components may sit at the top level too —\n // that's how things stay individually\n // visible at landscape altitude (see\n // \"Grouping vs. nesting\" under Views)\n\nsystem shop \"Order Service\" { // systems/containers nest arbitrarily\n description: \"Checkout and orders\" // optional; shows on the collapsed card\n icon: aws/api-gateway // the card's own mark; without it the\n // first child's icon stands in\n glyph: sys/code // kind mark, in a chip at the card's\n // top right; a bad ref is a check error\n domain: \"orders\" // optional owner/team tag on the card's\n // shelf, beside the child icons\n tags: #core // tags inherit to everything inside\n\n api = aws/api-gateway \"API Gateway\" // id = pack/icon \"Label\"\n create = aws/lambda \"Create Handler\" {\n description: \"Validates and persists\"\n subtitle: \"Lambda · Node 20\" // a few words under the label, always\n // drawn: runtime, owner, region\n link: \"https://runbooks.acme.dev/create\" // makes the title a hyperlink, in\n // quotes, http(s) only, leaves only: a\n // card's click zooms. Only a URL you were\n // given (quality bar 7)\n tags: #pci\n }\n db = aws/dynamodb \"Orders Table\" datastore #pci\n // a tag can sit in kind position like that, or in the block — same thing:\n idx = aws/opensearch \"Search Index\" datastore {\n tags: #pci // kind and attr block go in either order\n }\n wh = sys/database \"SQL Warehouse\" datastore {\n badge: logos/databricks // small vendor mark on the icon plate —\n // see \"Platforms with no icon pack\" below\n }\n legacy = box \"Old Billing\" external // `box` = no icon\n // kinds: `external` (not ours — draws a hatched surface, and also goes on a\n // whole system: `system stripe \"Stripe\" external { … }`) and `datastore`\n // (holds state — a note to the reader and to `squinch diff`; your icon\n // choice is what actually shows it). For a human, use the `person` forms\n // above rather than a kind.\n\n api -> create // sync edge (solid)\n api -> create, get, search // fan-out\n db ~> sync \"DynamoDB stream\" // async edge (dashed); label optional\n api -> create { tags: #hot-path } // edges take tags and attrs too\n api -> db { color: amber } // a hue on the stroke + head — see Colour\n a <-> b // bidirectional; a -- b undirected\n}\n\ncustomer -> shop.api \"places order\" // cross-system edges use dotted paths\n\nzone prod_vpc \"VPC prod\" vpc { // deployment boundary — cross-cuts the\n contains shop // ownership tree; renders as the classic\n} // dashed frame around its members\n```\n\nRules that matter:\n- **Ids are unique within their container**; refer to nested things as `shop.api`\n from outside, bare `api` from inside.\n- Statements end at newline (or `;`). Labels are quoted strings.\n- **Commas are optional wherever whitespace already separates** — `rows [a, b]`,\n `align a, b`, `highlight #a, #b`, `{ style: dashed, animate: slow }` all parse,\n as do a trailing comma and no comma at all (`{ style: dashed animate: slow }`). They stay *required* in a path list (`a -> b, c`,\n `contains`, `channel`, `only`, `expand`), and stay wrong inside a tag value: write\n `tags: #a #b`, never `tags: #a, #b`.\n- Parallel edges between the same pair are fine — give each a label.\n- **A system you are not breaking down is a node, not an empty system.**\n `system partner \"Partner System\" external { }` gives you a card with nothing\n behind it and a zoom that goes nowhere; `check` warns that the system is\n empty. Write `partner = box \"Partner System\" external` instead.\n- A `layout { }` block goes inside a `view` (arranging the view) **or inside a\n `system`** (arranging that system's own interior — `rows`, `cols`, `place`,\n `direction` and `wrap`, written by short name; see Layout hints). Everything\n else — `channel`, `align`, `density`, `highlight`, `note`, `expand` —\n belongs to a view alone.\n\nTables — a database is one node until the reader asks what is *in* it. Then\nwrite it as a `container` holding one `sys/table` per table: it still draws as\none card where it sits, a dive opens it onto the tables, and a foreign key is\nan ordinary labelled edge. A caller points at the container (`svc -> db`) or\nat the table it touches (`svc -> db.orders`). `datastore` moves to the tables\n— on a container it is a check error — and `icon:` keeps the database's own\nmark on the card. A database nobody asked to open stays a node, and so does a\ntable with no database above it. On a serverless or managed store where the\ntable is itself the resource you deploy, write one node per table inside the\nservice that owns it, with no container invented to hold them.\n\n```squinch\nsystem shop \"Order Service\" {\n svc = aws/lambda \"Order Handler\"\n container db \"Orders DB\" {\n icon: aws/rds\n description: \"Postgres 16 · 3 tables\"\n customers = sys/table \"customers\" datastore\n orders = sys/table \"orders\" datastore {\n subtitle: \"partitioned monthly\"\n fields {\n id uuid pk\n customer_id uuid fk ref customers\n status enum(pending, paid, shipped)\n total numeric(10,2)\n }\n }\n payments = sys/table \"payments\" datastore\n orders -> customers \"customer_id\" // a foreign key, child to parent\n payments -> orders \"order_id\"\n }\n svc -> db.orders \"writes\"\n}\nview db { scope shop.db } // standing in the database: every field\n```\n\nColumns — only when the request asks what is *in* a store. Any leaf takes a\n`fields { }` block (a table, a collection, a topic's payload): one field per\nline, the name, the type as the store spells it, then markers in its own words\n(`pk`, `hash`, `ttl`, `unique`, `index gsi1`) and an optional `\"caption\"`.\nCopy them from the repo's migrations, Prisma or proto files, never from memory,\nand translate the punctuation (`?` → `nullable`, `@id` → `pk`). Mark every key\ncolumn — each column of a composite key carries `pk` — and say what a null or\na key pattern *means* in the caption (`gate text nullable \"null = all gates\"`);\na caption that fits is drawn on the row. A nested field\nis a dotted name (`address.city`). `ref <id>` names the column a foreign key\npoints at — the edge between the two tables stays the relationship. Fields\ndraw where the table's container is open: every field in a view scoped to it,\nand a compact list (the first six, or the table's `preview: [a b]`) wherever\nit is expanded. A table at the top level needs `preview <table>`; the\nlandscape and collapsed cards never change. `preview: none` keeps a table\nplain inside an expanded system.\n\nRelationships — when the request or the schema states how many rows take\npart, say it on the edge between the two tables with `from:` and `to:`, one\nword per end, both ends or neither. They draw as crow's-foot marks at the\nwire's ends, where both tables are drawn.\n\n```squinch\norders -> customers \"customer_id\" { from: many to: one } // many orders, one customer\norders -> coupons \"coupon_id\" { from: many to: zero-or-one } // the key is nullable\norder_items -> orders \"order_id\" { from: one-or-many to: exactly-one } // the request states both\nproducts -- tags { from: many to: many }\n```\n\n`from:` counts the rows of the table the edge starts at, `to:` those of the\ntable it ends at. Six words: `one` and `many` say nothing about optionality;\n`exactly-one`, `zero-or-one`, `one-or-many` and `zero-or-many` state it. Write\n`one` or `many` unless the request or the schema states optionality. A\nnullable key is the usual reason for `zero-or-one`. \"At least one\" is almost\nnever in a schema: write `one-or-many` only when the request says it. Put\nmarks on an edge only when the request or the schema gives the cardinality; a\ntables request that states none draws none. Many-to-many is a direct `--`\nedge, or a join table with two edges, as the source has it — never invent a\njoin table. The marks are the whole statement: keep the label for the key\ncolumn, not for \"1:N\". The edge is a plain `->` or `--` between two tables —\nno `style:`, no `animate:`, not a service or a person.\n\nEdge motion — `~>` edges animate on their own (dashes drift toward the target,\noff under `prefers-reduced-motion`). Opt out with `{ animate: false }`, or pick\na variant: `reverse` (acks flowing back), `slow`/`fast` (cadence), `packets`\n(discrete messages), `pulse` (a heartbeat — works on solid sync edges too),\n`comet` (a dot rides the route — the only motion a plain solid edge can take).\nSync edges take `style: dotted` (`dashed` warns next to `~>` edges — dashes\nare the async convention), and a dotted sync edge may also animate. One `animate:` value per edge, and don't decorate every edge — motion\nis for the hops where cadence or direction *means* something.\n\n```squinch\nprobe -> legacy \"healthcheck\" { animate: pulse }\nsensor ~> ingest \"telemetry\" { animate: packets }\ncart -> pay \"checkout\" { animate: comet } // no `style:` needed\nmirror -> replica \"sync\" {\n style: dashed\n animate: slow\n}\n```\n\nColour — `color:` takes one of nine hues, `red | amber | green | teal | blue |\nviolet | pink | gray | accent`, never hex (each is a designed light/dark pair,\nand a literal cannot be right on both). It goes on anything: a leaf, a person\nor a `system` gets a spine down its left edge, an edge its stroke and head, a\nzone its outline. Use it to say *these belong together* or *this is the path*\nwithout dimming everything else the way `highlight` does. The stronger form is\nthe view statement `color #tag red`, which colours every visible thing carrying\nthe tag, one tag per line — it wins over an element's own `color:`, and with\n`legend auto` each coloured tag earns a legend entry. Colour is annotation:\nasync stays dashed, context stays muted, so a greyscale print loses only the\nemphasis.\n\nZones mark deployment boundaries: `zone id \"Label\" kind { contains a, b.c }`,\nkinds `account | region | vpc | subnet | network | cloud | onprem | custom`.\nOptional attrs: `icon:` — **any** pack icon (`azure/vnet`, `logos/docker`; AWS\nships purpose-made group marks like `aws/vpc`, `aws/region`,\n`aws/private-subnet`, `aws/corporate-data-center`) — `label: top-right`\n(corners: top-left default, top-right, bottom-left, bottom-right), and\n`color: teal` (the nine hues above; never hex). A zone's `kind` already picks\nits tint — `account` red, the network kinds blue, `cloud` violet, the rest\ngray — so two nested zones of related kinds come out nearly the same shade:\nset `color:` on the inner one to tell them apart. `detail: \"10.0.0.0/16\"` adds a second, monospaced\nsegment to the chip for the boundary's hard fact — a CIDR, an account id, a\nregion. It is dropped rather than truncated on a boundary too narrow for both,\nsince a clipped CIDR is a different network, not a shortened label.\n\n**Zones nest by sharing members, never by naming each other.** `contains` takes\nnodes, so an outer boundary repeats the inner one's members:\n\n```\nzone account \"Azure Subscription\" account { contains gw, aks, sql }\nzone vnet \"Virtual Network\" network { contains aks, sql }\n```\n\n`aks` and `sql` are in both, so `vnet` draws inside `account`. Naming the inner\nzone — `contains gw, vnet` — is accepted as shorthand for exactly that\nexpansion. Everywhere *else* a zone id is an error: you cannot draw an edge to\na boundary. Zones must nest cleanly or stay disjoint in any one view, may not\ncut through an expanded container, and only appear where their members are\nvisible.\n\n## Views (altitudes)\n\nEvery system automatically gets a zoomable view. Declare views to customize or to\nadd lenses — and declare one for any part the ask singles out (\"I care most\nabout orders\"): `render --sync` writes only declared views, so an auto view the\nreader was promised never reaches them as SVGs. `view orders { title \"…\" }` is\nenough.\n\n```squinch\nview landscape { // views take no positional label — the title is a\n title \"System Landscape\" // statement. It draws top-left as the diagram's\n // name, with or without a `titleblock`.\n include * // all TOP-LEVEL entities, as collapsed cards\n}\n\nview shop { // name matching a system = that system's view\n scope shop // implied by the name here; explicit for clarity\n only #pci // KEEP only these — the view's filter. `scope` says\n // where you stand, `only` says which of it you keep.\n // Takes ids too: `only api, vault`\n exclude legacy // trim noise (removes the subtree)\n expand workers // inline one child container in a frame — one\n // level; nesting two explicit expands is an error.\n // Several: `expand workers, ledger`, or one per line\n detail ledger.post // draw an outside node itself, not its system card\n highlight #pci // spotlight matches, dim the rest — this still\n // shows EVERYTHING; \"only the PCI parts\" is `only`\n color #pci red // colour everything tagged #pci, dim nothing —\n // one tag per line; wins over an element's own color:\n note right-of db \"Single-table design; see ADR-42\"\n note top-right \"Audit scope: Q3\" { style: warning }\n context off // drop the muted neighbour cards this view earned\n // (default is `context auto`)\n legend auto // footer key of the styles actually used\n titleblock { // a meta chip under the title. version/commit/\n subtitle: \"Landscape view\" // date are reserved — their values stand alone,\n version: \"2026-07\" // and `commit` sets in mono. Any other key\n commit: \"a41f0c2\" // keeps its key beside its value.\n owner: team-orders // Nothing here is derived: no git, no clock.\n }\n}\n```\n\nWhen the reader wants **everything on one page** — every container open to\nleaf depth, no clicking around — declare a full-detail view with `expand *`\n(declare it after the landscape so the breadcrumb keeps pointing home). It\ncomposes with the other verbs: `scope orders` + `expand *` opens one subtree.\n\n```squinch\nview full {\n title \"Full detail\"\n expand * // open every container, frames nesting as they go;\n // empty containers stay cards, edges de-aggregate\n}\n```\n\nBetween a card and an open frame there is one more altitude: **`preview\n<path>`** (a comma list, or `preview *`) draws a card **detailed** — the children its\n`preview:` attr names (§ containers; up to three, `auto` takes the first three\ndeclared) as readable rows under the head, `+N more` on the shelf for the\nrest. It is still a card: every wire lands on it, nothing attaches to a row,\nand a dive opens the container. Reach for it on the *landscape*, when the\nreader should see what a system is made of without opening it — a domain and\nits capabilities, a platform and its services — and only where those children\ncarry a `description:` or `subtitle:`; three bare names say little more than\nthe chips. Do not put it on every view: a dense view has no room for a card\ntwice its height, and `preview` beside `expand` on the same container is an\nerror.\n\n```squinch\nsystem orders \"Orders\" {\n description: \"Order lifecycle, cart to refund\"\n preview: [checkout fulfillment returns] // what the card calls out; pricing folds into +1\n system checkout \"Checkout\" {\n description: \"Cart to confirmed order\"\n api = aws/lambda \"Checkout API\"\n }\n system fulfillment \"Fulfillment\" {\n description: \"Pick, pack, dispatch\"\n worker = aws/lambda \"Dispatcher\"\n }\n system returns \"Returns\" {\n description: \"Refunds and RMAs\"\n api = aws/lambda \"Returns API\"\n }\n system pricing \"Pricing\" {\n description: \"Prices, promotions, tax\"\n api = aws/lambda \"Pricing API\"\n }\n}\nview landscape {\n include *\n preview orders // the Orders card, with its three parts named\n}\n```\n\nNumbered flows badge a request's path over **edges that already exist** — a\nflow annotates the model, it never creates connections. A step with no edge\nbehind it is a check error telling you to declare the edge first (steps count\nin declaration order; bare ids bind when unambiguous, otherwise use full\npaths):\n\n```squinch\nsystem shop \"Shop\" {\n api = aws/api-gateway \"API\"; create = aws/lambda \"Create\"\n db = aws/dynamodb \"Orders\"; files = aws/s3 \"Files\"\n api -> create // these edges…\n create -> db\n create ~> files\n}\nflow checkout \"Checkout\" {\n api -> create -> db // …are what the flow numbers: steps 1, 2\n create ~> files // step 3 — branches keep counting\n}\nview shop { show flow checkout }\n```\n\n`flow` blocks live at the **top level**, beside your systems — not inside a\n`system` and not inside a `view` (the view only says `show flow <id>`). From out\nthere, write steps as full paths (`shop.api -> shop.create`). A step may cross a\nview's `scope`. A flow is also a story: in the playground's **Present** mode the\narrow keys walk a `show flow` view one hop at a time — nothing extra to author.\n\nGrouping vs. nesting: `include *` shows only *top-level* entities, so wrapping\nseveral services in a parent `system` purely to group them collapses them into\none card at landscape altitude. If they should stay individually visible but\nshare a boundary, keep them top-level and group them with a `zone`.\n\n### When the system is big\n\nA reader can only take in so much at once, so on a large system — a whole\nrepo, a platform — size is a modelling decision, made before layout. A small\nsystem needs none of this: keep it flat.\n\n- **Group before you draw.** Sort the components into the areas the system\n already has — its top-level folders, its teams, its domains — and make each\n a `system`. Use the names the code uses. If nothing hands you the areas,\n find them: things that call each other and change together. The landscape\n then draws one card per area with the calls between them merged (`×4`), and\n every area gets its own zoomable view for free.\n- **It holds at every altitude.** Opening an area should read as easily as the\n landscape does. Every service inside one `backend` system has only moved\n the problem down a click — group by what things are *for* (identity,\n catalogue, buying, fulfilment), and nest a system inside a system when an\n area is itself big.\n- **What a thing owns lives inside it.** A service's own database, cache or\n worker belongs in that service's area, not beside it on the landscape. What\n everyone shares — a gateway, an event bus — stays top-level.\n- **One caller with many targets is the shape that runs off the page**: a UI\n or gateway calling every service draws them all in one row. Grouping the\n targets is the fix; `wrap N` folds the row when they really are peers.\n Never answer it by listing every target in one `rows` band — that forces\n exactly the strip you are trying to avoid.\n- **Hand over altitudes, not one page.** Declare the landscape first, then a\n view for each area worth opening; the interactive HTML lets the reader\n click down. `view full { expand * }` is for when they ask for everything at\n once. Say in your hand-over how you grouped it, so the reader can ask you\n to open an area up rather than start over.\n- **Let the landscape say what each area is made of.** Give every area a\n `description:`, and when its parts are things the reader would recognise —\n the services of a platform, the capabilities of a domain — name the three\n that matter in `preview: [a b c]` and put `preview *` on the landscape view.\n Each card then lists those three under its name, still as one card, and the\n reader knows what is inside before clicking. Only there: a zoomed view has no\n room for cards twice the height.\n\nZoomed views automatically show outside neighbours as muted **context** cards —\ndon't add them yourself; if one appears that you don't want, `context off`.\n\n## Layout hints (in a `layout { }` block — a view's, or a system's own)\n\nThe engine lays a clean diagram out well on its own — ranks follow the arrows,\nfans are centred, wires do not cross boxes. Add a hint when the render shows\nsomething you want changed, not before: every hint is a constraint the engine\nthen keeps, even where its own choice would have crossed fewer wires.\n\n```squinch\nview shop {\n layout {\n direction down // down (default) | right\n density comfortable // compact | comfortable | spacious\n lines orthogonal // orthogonal (default) | curved | straight\n rows [api] [create get search] [db files idx] // horizontal bands, top to bottom\n cols [create db] [get files] // vertical bands, left to right (shared axis)\n place sync right-of db // right-of | left-of | above | below\n align gw db // exact shared axis; first one is the anchor\n channel create, get, search -> db // one trunk into a shared target, not N lines\n // (the edges stay declared in the model;\n // this only merges how they are drawn)\n route api -> db from south to north // which side an edge exits/enters —\n // only for edges that SPAN rows\n route api -> db \"write\" from south // label disambiguates parallels\n }\n}\nview steps { include *\n layout { wrap 5 } } // no row wider than 5: wide ones fold\n```\n\n- `rows` is the workhorse: one bracket group per horizontal band, listed top to\n bottom; order inside a bracket is left to right. Unlisted nodes place\n themselves — only list a node when you care where it lands. Two nodes in\n one band may have an edge between them, and an edge may point back *up* the\n bands (a monitor, a retry path): both are drawn. Do not fold a wide row into\n several bands by hand; that is `wrap`.\n- **`wrap N` means no row holds more than N.** It folds every wider row — in\n the view and inside every system the view opens — a chain as a serpentine,\n a fan-out into bands under its source with one trunk feeding them. A\n system may carry its own (`layout { wrap 4 }`), which follows it into every\n view. Never beside `rows`/`cols` in one block. For a slide, roughly 16:9,\n use N ≈ √(nodes being folded), rounded up: a 14-step chain is `wrap 4`, and\n so are twelve workers under one dispatcher. Leave `direction right` out of\n a wide fold: a band is a rank, and under `direction right` ranks are\n columns, so `wrap 7` becomes two tall columns of seven.\n- `cols` is its transpose: one bracket group per vertical band, left to right.\n Members of a column share an exact axis, so a service and its database line\n up. `rows` and `cols` compose — they pin different axes, so using both gives\n you a full grid, and a cell is empty when nobody is placed in it.\n- **`cols` and `align` work across bands, never within one.** Six collectors\n that all feed one normaliser are siblings on a single rank — they are already\n drawn side by side, and no two of them can share an axis, so `cols [c1 … c6]`\n warns and leaves them where they were. If you want them beside each other,\n that is `rows [c1 … c6]`. The\n trap is worst under `direction right`, where a rank *looks* like a column on\n screen: the words name the model, not the picture.\n- **A system's interior is arranged by the system itself.** Give the system\n its own `layout { }` with `rows`/`cols`/`place`/`wrap` in short names, and that\n arrangement follows it into every view that opens it — expanded beside its\n siblings, or standing inside it in the system's own view. Direct members\n only: a nested container gets its own block. The view then only ranks\n systems against each other, and never restates an interior:\n\n```squinch\nsystem checkout \"Checkout\" {\n api = aws/api-gateway \"API\"; svc = aws/lambda \"Orders\"\n bus = aws/sqs \"Events\"; cache = aws/elasticache \"Sessions\" datastore\n db = aws/dynamodb \"Orders\" datastore\n api -> svc; svc ~> bus; svc -> cache; svc -> db\n layout { rows [api] [svc] [bus cache] [db] } // short names, inside\n}\nsystem pipeline \"Pipeline\" {\n ingest = aws/lambda \"Ingest\"; enrich = aws/lambda \"Enrich\"; publish = aws/lambda \"Publish\"\n ingest -> enrich; enrich -> publish\n layout { direction right } // this interior reads left to right\n}\nview detail {\n expand checkout\n expand shipping\n layout { rows [cdn] [checkout shipping] } // the view ranks the systems\n}\n```\n\n `direction right` in a system's block lays that system's interior out left\n to right wherever it is opened, inside a view that still flows down — the\n way to draw a pipeline as a row. It is a property of the system, not of the\n view: there is no per-view override for an expanded frame.\n A view may still name interior paths (`rows [gw] [checkout.api]`); when its\n hints relate two or more of a system's members they replace that system's\n block in that view, whole — bands are never merged. Naming one member only\n ranks the whole system from outside.\n- **A zone is arranged like a system.** To place the whole boundary, name the\n zone's own id or one member: `rows [gw] [prod_vpc]` puts it below the\n gateway, `rows [batch orders]` sets two namespaces side by side. Hints\n naming two or more of its members arrange them inside it.\n- A node may be in a band **and** carry a `place`, so long as the two agree —\n `rows [db bus]` with `place bus right-of db` is fine; a `place` that puts the\n node somewhere the band does not is refused.\n- `place x right-of y` is the whole side-car idiom (stream processors, caches,\n DLQs). Do **not** add `route y ~> x from east to west` to it: `place` puts\n the two on the same row, where the edge already runs straight across — a\n `from`/`to` on a same-row edge is ignored, and says so.\n\nThe cookbook in `references/cookbook.md` is the next step when a diagnostic is\nnot self-explanatory or the render shows a shape you cannot name the hint for —\nsymptom → fix, keyed on the diagnostic's own words.\n\n## Icons\n\n**Read `references/icons.md` when you need an icon id outside the AWS basics**:\nit lists the ids and aliases per pack, the Google Cloud category rule in full,\nthe Kubernetes short names, the `sys/` rows by theme, and the Databricks recipe\nworked out component by component. Open it before you write the node, not after\n`check` refuses the id.\n\nWhen the request names a **specific product**, search for it — don't write the id\nfrom memory. `check` only tells you an id exists, never that it's the one the\nreader asked for, so a plausible-but-wrong mark passes silently and ships. The\nconfusable pairs are the ones to watch: CloudFront (`aws/cloudfront`, a CDN) is\nnot Cloudflare (`logos/cloudflare`, a different company); `aws/aurora` is not\n`aws/rds`. One `squinch icons search cloudfront` settles it.\n\nThe AWS ids you'll use constantly: `lambda` · `dynamodb` · `s3` · `sqs` · `sns` ·\n`api-gateway` · `opensearch` · `aurora` · `rds` · `elasticache` · `cloudfront` ·\n`eventbridge` · `kinesis` · `step-functions` · `ecs` · `eks` · `fargate` · `ecr` ·\n`athena` · `glue` · `redshift` · `sagemaker` · `bedrock` · `rekognition` ·\n`cognito` · `secrets-manager` · `route-53` · `waf` · `elastic-load-balancing`\n(alias `elb`) · `batch` · `efs` · `app-runner`.\n\nSix packs, and the ids you'll reach for in each:\n\n- **`aws/`** — 316 icons; the basics above.\n- **`azure/`** — 636 icons, named like the portal (`azure/app-services`,\n `azure/storage-accounts`, `azure/monitor`), with short forms for the ones\n everybody abbreviates: `azure/aks` · `azure/vm` · `azure/vnet` ·\n `azure/cosmos` · `azure/functions` · `azure/sql` · `azure/blob` ·\n `azure/service-bus` · `azure/event-hub` · `azure/key-vault` ·\n `azure/front-door` · `azure/app-gateway` · `azure/load-balancer` ·\n `azure/aci` · `azure/acr` · `azure/api-management` · `azure/log-analytics` ·\n `azure/redis`.\n- **`gcp/`** — 45 icons, because Google's own system works that way: nineteen\n products have a unique mark (`gcp/cloud-run`, `gcp/gke`, `gcp/bigquery`,\n `gcp/cloud-sql`, `gcp/spanner`, `gcp/vertex-ai`…), and *every other product\n draws its category's glyph* under the name you know it by (`gcp/pubsub`\n draws Data Analytics). Put the product name in the label and let the icon\n say the category.\n- **`k8s/`** — 39 icons under kubectl's short names, for what runs *inside* a\n cluster: `k8s/pod` · `k8s/deploy` · `k8s/svc` · `k8s/sts` · `k8s/ds` ·\n `k8s/cm` · `k8s/secret` · `k8s/ing` · `k8s/ns` · `k8s/sa` · `k8s/pv` ·\n `k8s/pvc` · `k8s/hpa` · `k8s/job` · `k8s/cronjob` · `k8s/crd` · `k8s/node` ·\n `k8s/etcd` · `k8s/control-plane` · `k8s/api` · `k8s/sched` · `k8s/kubelet`.\n `logos/kubernetes` when the cluster is one box in a wider estate.\n- **`logos/`** — 147 product marks plated in their brand colour, the non-cloud\n half of a stack: `logos/postgres` · `logos/mysql` · `logos/mongodb` ·\n `logos/redis` · `logos/kafka` · `logos/rabbitmq` · `logos/elasticsearch` ·\n `logos/docker` · `logos/terraform` · `logos/nginx` · `logos/github` ·\n `logos/gitlab` · `logos/grafana` · `logos/prometheus` · `logos/datadog` ·\n `logos/sentry` · `logos/stripe` · `logos/snowflake` · `logos/cloudflare` ·\n `logos/vercel` · `logos/react` · `logos/python` · `logos/go` · `logos/rust`.\n Slack, Twilio, Salesforce, Heroku, gRPC and dbt have no mark upstream — use\n `box` or the label.\n- **`sys/`** — 195 generic Lucide icons for what no vendor draws, and it needs\n no `pack` statement. Ids are Lucide's own names, so a word you would say\n (`process`, `analytics`, `device`, `web`) is usually *not* one — pick from\n these: compute `server` `container` `cpu` `code` `app-window` `terminal`\n `cog` `webhook` `workflow`; hardware `laptop` `monitor` `smartphone`\n `hard-drive` `printer`; network `network` `router` `wifi` `radio-tower`\n `globe` `share-2`; security `lock` `key-round` `shield` `shield-check`;\n data `database` `folder` `search` `archive` `table` `file`; places `factory`\n `warehouse` `building-2` `house` `earth`; process and observability `clock`\n `timer` `repeat` `activity` `gauge` `chart-line` `siren` `bug`; commerce\n `shopping-cart` `credit-card` `wallet` `receipt-text` `truck`\n `package-check` `barcode`; shapes `box` `circle` `square` `hexagon`\n `diamond` `star`. Aliases: `gear`→`cog`, `db`→`database`,\n `rack`/`vm`/`host`→`server`, `firewall`→`shield`, `vault`→`lock-keyhole`,\n `cron`→`clock`, `lb`→`share-2`, `cart`, `payment`, `order`, `shipping`.\n\nPick one cloud's pack and stay with it — don't draw the same concept as\n`aws/…` in one box and `azure/…` in the next. Composing a cloud pack with\n`logos` and `sys` is normal; it's how you draw a hybrid estate. A platform with\nno pack at all — Databricks, Snowflake, dbt, Confluent publish no icons anyone\nmay redistribute — is drawn as the concept from `sys/*` with the vendor's mark as\na `badge:` where `logos/*` has one; never a lookalike from another vendor, never\nan invented id.\n", "references/cookbook.md": "# Layout cookbook (symptom → fix)\n\nOpen this when `check` reports a diagnostic you do not recognise, or when the\nrender shows something you cannot name the hint for. Every row is keyed on the\ndiagnostic's own words or on what you see; search this file for either. The\nrows assume the Layout-hints section of `SKILL.md`, which explains the hints\nthemselves.\n\n## Contents\n\n- [Placing and banding](#placing-and-banding) — `rows`, `cols`, `place`, `align`, `wrap`, direction — and the hints `check` refuses or warns about\n- [Edges and wires](#edges-and-wires) — fan-in, trunks, self-edges, chaining, `route`, step badges\n- [Zones](#zones) — boundaries that overlap, cut through a frame, or have nothing to show\n- [Labels, attributes and ids](#labels-attributes-and-ids) — cut-off text, attrs on the wrong element, tags, prefixes\n- [Views and altitude](#views-and-altitude) — empty views, `expand`, `only`/`highlight`/`color`, `include`, `detail`, context cards\n- [Icons](#icons) — an id you cannot find\n\n## Placing and banding\n\n| Symptom | Fix |\n|---|---|\n| Layers feel arbitrary / related things scattered | Add `rows`, one group per conceptual tier (entry, handlers, storage) |\n| One node belongs beside another (stream sync, DLQ, cache) | `place X right-of Y` — that is all. The connecting edge runs straight across; adding `route … from east to west` does nothing, because `place` puts them on one row |\n| \"`route x -> y` sides are ignored — it is a same-rank edge\" warning | Drop the `from`/`to`. Sides only apply to edges that span rows |\n| \"`route x -> y` could not use the side it asks for here\" warning | That wall already carries a wire running straight across to a neighbour, or the edge is part of a `channel` or a `wrap` trunk, or that end is a system rather than a node. Drop the `from`/`to`, or free the wall (move the neighbour to another row, take the edge out of the `channel`) |\n| \"`x` is placed `right-of y`, but `rows` puts it somewhere else\" error | The two hints disagree. Restating a band is fine — `rows [db bus]` alongside `place bus right-of db` is accepted, since both say the same thing — so fix whichever one is wrong, or drop `x` from the band |\n| \"`x` is listed in `rows` but is placed relative to `y`, which is not\" error | Put `y` in a band too, or take `x` out of its band. A banded node can only be placed against another banded one |\n| \"cols `[a b c]` — all 3 sit on the same rank, so they cannot share an axis\" warning | You wanted them side by side; that is `rows [a b c]`. `rows` is a **rank** — things drawn beside each other. `cols`/`align` stack a node onto another's axis *across* ranks. The confusion is worst with `direction right`, where a rank looks like a column on screen — the words describe the model, not the picture |\n| \"`x` appears in `rows` twice\" error — likewise \"appears in `cols` twice\" | A node can hold only one rank position; remove one of the two occurrences |\n| A wire jogs slightly instead of running straight | `align a b` — b takes a's axis exactly (a is the anchor) |\n| \"align `[a b]` — `b` could not be put on `a`'s axis\" warning — likewise for `cols` | They sit in different systems or zones, or another hint holds them apart. Align the containers themselves, or drop one of the hints |\n| An edge runs back up the page (a monitor, a retry, a feedback path) | That is how it is drawn: out of the top of the lower node, into the bottom of the upper one. To shorten it, put the observer in the same band as what it watches (`rows [api mon] [svc] [db]`), or leave it out of `rows` |\n| Edge exits a silly side | `route a -> b from south to north` (sides: north/south/east/west) |\n| Everything takes a long detour around the canvas | Check whether an edge points *against* the flow. Reversing one back-edge to face the direction traffic actually travels beats any hint |\n| A full-detail view came out tall — want it wide | Add `layout { rows … }` banding the expanded systems side by side; calls between them cross the gutters and land on the nodes they name |\n| An expanded system's insides are in the wrong order or tier | Give the system its own `layout { rows … }` in short names — it follows the system into every view. Or name the interior paths in the view's `rows` (`[app.api] [app.db app.cache]`), which replaces the system's block for that view |\n| A pipeline inside a system should read left to right while the view flows down | `layout { direction right }` inside that system — its interior becomes a row wherever it is opened; the view keeps its own direction |\n| A long chain renders as a tall strip, or a wide row runs off the page | `layout { wrap 5 }` — no row holds more than 5. A chain folds into a serpentine; any other wide row folds into bands, fed by one trunk. It reaches every system the view opens; one system alone takes it in its own block (`layout { wrap 4 }`). Never beside `rows`/`cols`. For a 16:9 slide, N ≈ √(nodes) rounded up, and no `direction right` |\n| \"`wrap 5` has no effect — no row here is wider than 5\" warning | Nothing to fold. Lower the number, or drop the line |\n| Diagram too cramped / too airy | `density spacious` / `density compact` |\n\n## Edges and wires\n\n| Symptom | Fix |\n|---|---|\n| \"an edge has one source — `x, y` cannot fan in\" error | Fan-out exists (`a -> b, c`), fan-in does not: write one edge per source. If the point is the *drawing* — many arrows converging as one trunk — that is `channel x, y -> z` in the view's layout |\n| Several things all write to one store, crossing each other | `channel a, b, c -> db` — they merge into one trunk |\n| \"channel into `x`\" warning | The trunk needs the target visible in this view and at least two of its member edges. Check that nothing is `exclude`d or folded into a collapsed card |\n| \"the relationship marks at `x` are crowded\" warning | Too many marked wires meet one wall of `x`. In a `direction right` view a table takes side wires only on its head, which holds four; from five the marks touch. Let that view flow down (drop `direction right`), or move one relationship to another wall naming both sides: `route orders -> x from east to north` in the view's layout. Wider `density` and fewer marks do not help — the wall is as long as it is |\n| \"`x` connects to itself — a self-edge is not drawn\" warning | Squinch draws connections between things, not loops on one thing. Put it on the node: `note right-of x \"retries\"`, or fold it into the label. A table that references itself says it on the row: `manager_id uuid fk ref employees` |\n| \"edges do not chain — `a -> b -> c` is one statement per hop\" error | Only a `flow` chains hops. Write each connection on its own line — `a -> b`, then `b -> c` — and, if the sequence itself is the point, declare a `flow` that walks them |\n| \"N edges match route …\" error | Add the edge's label to the `route` statement |\n| A numbered step's badge sits past its target node | The edge label is too wide for that run — shorten it, or the badge gets evicted and the reading order looks wrong |\n\n## Zones\n\n| Symptom | Fix |\n|---|---|\n| \"zones `a` and `b` contain exactly the same members\" error | Two names for one boundary. Neither can sit inside the other, so merge them into a single `zone`, or narrow one's `contains` so it is genuinely a sub-boundary |\n| \"zones `a` and `b` partially overlap — visible zones must nest or stay disjoint\" error | Boundaries must nest or stay apart, never half-lap. The fix line lists which members are shared and which are exclusive — either give the inner zone only members the outer one also has, or move the odd one out |\n| \"zone … cuts through expanded container\" | The zone holds *some* children of a container you `expand`ed — contain the whole container, or drop the `expand` in that view |\n| \"zone … has no visible members\" | Its members are inside collapsed cards at this altitude — `expand` one, scope the view to them, or contain the container itself |\n| A zone's members are in the wrong order or tier | Name them in the view's `rows`/`cols`/`place` — hints relating two or more members of a zone arrange them inside it. To move the whole boundary, name the zone's id: `rows [gw] [prod_vpc]` |\n| \"`a` → `b` is not drawn — one end is inside the other\" warning | The edge points from a system at something inside it (or the reverse) while that system is open. Point it at a member instead, or collapse the system in this view |\n| Need a VPC / network boundary / cloud-vs-on-prem split | `zone id \"Label\" vpc { contains a, b }` — kinds: account, region, vpc, subnet, network, cloud, onprem, custom |\n\n## Labels, attributes and ids\n\n| Symptom | Fix |\n|---|---|\n| \"`owner` has a tag value — tags live in `tags:`\" error | Only the `tags:` key collects tags. A `#value` under any other key is either a tag that belongs in `tags:`, or plain text that needs quotes |\n| \"N ids are missing their `sys` prefix\" error | Ids declared inside a `system` are addressed from outside it by their full path. Inside `shop`, write `api`; from a `zone`, a `view` or another system, write `shop.api`. The error folds every id that made the same mistake into one line because it is one mistake |\n| \"`datastore` on `system s` — only `external` applies to a system\" error | Only `external` describes a whole system. The other kinds describe one node: put it on a node inside, or drop it |\n| \"label is N characters — it will be cut off\" warning | A leaf widens, then wraps to two lines, and past that the reader loses the tail; a card's name gets one line. Keep it a short noun phrase and move the detail into `description:` |\n| \"subtitle is N characters — it will be cut off\" warning | A subtitle is one line and widens a leaf only up to 240. Keep it to a few words — runtime, owner, region — and move the rest into `description:` |\n| \"`show descriptions` no longer draws anything\" warning | Descriptions are prose: they show as a system's card tagline and in hover, never inside a leaf. Drop the line, and give the leaves a short `subtitle:` — runtime, owner, region — for the line under the label |\n| \"unknown zone attribute `description`\" warning | A zone's chip holds its label and a mono `detail:` (a CIDR, an account id) — nothing else. Prose about the boundary goes in a `note` anchored to a member |\n| A table's `fields` are written but nothing draws | Fields draw where the table's container is open: a view scoped to it (`view db { scope shop.db }`) shows every field, and expanding it (`expand db`) shows a compact list. A top-level table needs `preview <table>`. The landscape never draws them, by design |\n| \"`x`'s fields are never drawn — no view shows them\" warning | No view opens the table's container with the table in it, and nothing previews it. The fix names the line: `preview x` for a top-level table, or stop filtering it out of its container's view |\n| \"preview `x` is redundant\" warning | Its fields already draw here — the view is scoped to its container, or the container is expanded. Drop the line; `preview` never changes how many show |\n| \"`schema { }` is not a block a leaf takes\" error | The block is `fields { }`, inside the table's own braces, one field per line: `id uuid pk` |\n| \"comments are `//` — `--` is an arrow here\" error | SQL's `--` is an arrow in squinch. Write `id uuid pk // primary key`, or put the note in a quoted caption: `id uuid pk \"primary key\"` |\n| \"`?` is not squinch\" / \"`@` attributes are not squinch\" error | Pasted Prisma or ORM syntax. An optional field says `nullable`, `@id` is `pk`, any other `@attr` is a bare marker word. The fix writes the whole corrected line |\n| \"`scope x` names a leaf — a view stands inside a container\" error | To see a table's fields, scope its container: `scope shop.db`. The table draws every field there |\n| \"`subtitle` is a leaf attribute\" warning | Only a leaf draws a line under its name. On a system or container that line is `description:` (it shows on the collapsed card); a `person` has none |\n\n## Views and altitude\n\n| Symptom | Fix |\n|---|---|\n| \"view `v` has nothing to draw\" warning | Everything got filtered out. Check `scope` (a leaf has no insides — scope a system, not a node), then `include`/`only`/`exclude`. An empty `system x { }` does this too: make it a node instead |\n| Too many boxes at once | Group into `system`s by area and let the landscape show their cards — see \"When the system is big\". Splitting into views alone does not help while everything is still top-level |\n| Everything open on one page, no clicking into containers | `view full { expand * }` — every container becomes a nested frame, every edge shows natively |\n| \"expand `x` inside `x`'s own view — this view stands inside `x` already\" warning | A view named after a container *is* that container's own view: you are already inside it. To draw `x` opened up among its neighbours, name the view something else: `view overview { expand x }` |\n| \"`expand *` already opens every container — the explicit `expand` lines are redundant\" warning | Drop the explicit `expand x` lines; the star covers them |\n| \"`expand *` opened nothing — no containers are visible here\" warning | The model (or this scope) has no containers to open — drop the line |\n| Show **only** one concern (an auditor's view: \"only the PCI parts\") | `only #pci`. Anything outside the scope that the survivors still talk to stays as a muted context card — that boundary crossing is usually the point of the view; `context off` drops those too |\n| Emphasise one concern while keeping its context | `highlight #pci` — spotlights matches, dims the rest, shows everything |\n| Tell two groups apart, or mark one path, without dimming anything | `color #team-a teal` in the view (tags inherit through containers), or `{ color: red }` on the element. Nine hues, never hex |\n| \"color #x: nothing visible here is tagged #x\" warning | Same cause as the `highlight` row: the tag is misspelled, or its carriers are not in this view — check `tags:` and the view's `include`/`only` |\n| \"`x` is tagged #a (red) and #b (blue) — #b wins\" warning | Two `color` lines landed on one element. Give both tags the same hue, or narrow one of them |\n| Narrow a view with `include #tag` | It does not narrow. `include` **adds**; an include that changes nothing warns and points at `only` |\n| Show one specific node from another system, not its whole card | `detail ledger.post` |\n| A neighbour system clutters a zoomed view | `exclude thatSystem` or `context off` |\n| \"highlight #x: nothing visible here is tagged #x\" warning | Everything would dim and nothing stand out. The tag is misspelled, or the things carrying it are not in this view — check the tag against your `tags:`, and the view's `include`/`only` |\n| Not sure which views exist | `squinch check <path>` lists them (`--format json` puts them in `views`) |\n\n## Icons\n\n| Symptom | Fix |\n|---|---|\n| Icon unknown | Collect every icon you're unsure of and search once: `squinch icons search \"queue, vector search, llm\"` — commas separate terms, spaces stay a phrase. `no exact match — closest:` rows are ranked next moves. The check error's `did you mean` is usually right |\n", "references/icons.md": "# Icons, pack by pack\n\nOpen this when you need an icon id outside the AWS basics in `SKILL.md`:\nthe ids and aliases each pack ships, the Google Cloud category rule, the\nKubernetes short names, the `sys/` rows by theme, and the recipe for a vendor\nwith no pack. Searching is still the first move — `squinch icons search \"a, b, c\"`\nbatches every unknown in one call — and this file says what the search will\nfind and which id to prefer when several match.\n\n## Contents\n\n- [AWS](#aws) — the ids you'll use constantly, and the confusable pairs\n- [Azure](#azure) — portal names, and the short forms everybody abbreviates\n- [Google Cloud](#google-cloud) — nineteen unique marks; everything else draws its category glyph\n- [Kubernetes](#kubernetes) — kubectl short names for what runs inside a cluster\n- [Logos — products and open source](#logos--products-and-open-source) — brand marks for the non-cloud half of a stack\n- [sys — the generic set](#sys--the-generic-set) — Lucide icons for what no vendor draws, by theme\n- [Platforms with no icon pack](#platforms-with-no-icon-pack) — Databricks, Snowflake, dbt, Confluent: `sys/*` plus a `badge:`\n\n## AWS\n\nWhen the request names a **specific product**, search for it — don't write the id\nfrom memory. `check` only tells you an id exists, never that it's the one the\nreader asked for, so a plausible-but-wrong mark passes silently and ships. The\nconfusable pairs are the ones to watch: CloudFront (`aws/cloudfront`, a CDN) is\nnot Cloudflare (`logos/cloudflare`, a different company); `aws/aurora` is not\n`aws/rds`. One `squinch icons search cloudfront` settles it.\n\n`lambda` · `dynamodb` · `s3` · `sqs` · `sns` · `api-gateway` · `opensearch` ·\n`aurora` · `rds` · `elasticache` · `cloudfront` · `eventbridge` · `kinesis` ·\n`step-functions` · `ecs` · `eks` · `fargate` · `ecr` · `athena` · `glue` ·\n`redshift` · `sagemaker` · `bedrock` · `rekognition` · `cognito` ·\n`secrets-manager` · `route-53` · `waf` · `elastic-load-balancing` (alias `elb`) ·\n`batch` · `efs` · `app-runner`\n\nShort aliases exist for the famous ones (`s3`, `sqs`, `sns`, `eks`, `ecs`, `ecr`,\n`elb`, `glacier`, `opensearch`).\n\n## Azure\n\n**Azure** has its own pack (636 icons). Short forms exist for the ones everybody\nabbreviates: `azure/aks` · `azure/vm` · `azure/vnet` · `azure/cosmos` ·\n`azure/functions` · `azure/sql` · `azure/blob` · `azure/service-bus` ·\n`azure/event-hub` · `azure/key-vault` · `azure/front-door` · `azure/app-gateway` ·\n`azure/load-balancer` · `azure/aci` · `azure/acr` · `azure/api-management` ·\n`azure/log-analytics` · `azure/redis`. Canonical ids read like the portal —\n`azure/app-services`, `azure/storage-accounts`, `azure/monitor`,\n`azure/application-insights`; `squinch icons search --pack azure <term>` scopes\nthe search. Pick one cloud's pack and stay with it — don't draw the same\nconcept as `aws/…` in one box and `azure/…` in the next. Combining a cloud pack\nwith `logos` is a different thing and completely normal: it's how you draw a\nhybrid estate, with `logos/postgres` on the on-prem side and `azure/sql` in the\ncloud.\n\n## Google Cloud\n\n**Google Cloud** has its own pack (45 icons), and it works differently from\nthe other two clouds because Google's own icon system does: nineteen core\nproducts carry a unique four-colour mark, and *every other product draws as\nits category's glyph*. The unique marks: `gcp/cloud-run` (`run`) · `gcp/gke` ·\n`gcp/compute-engine` (`gce`, `vm`) · `gcp/cloud-storage` (`gcs`, `bucket`) ·\n`gcp/cloud-sql` (`sql`) · `gcp/spanner` · `gcp/alloydb` · `gcp/bigquery` (`bq`)\n· `gcp/vertex-ai` (`vertex`) · `gcp/looker` · `gcp/apigee` · `gcp/anthos` ·\n`gcp/distributed-cloud` (`gdc`) · `gcp/hyperdisk` (`persistent-disk`) ·\n`gcp/ai-hypercomputer` · `gcp/security-command-center` (`scc`) ·\n`gcp/security-operations` (`secops`) · `gcp/threat-intelligence` ·\n`gcp/mandiant`. Everything else resolves by the name you know it by and draws\nthe category glyph: `gcp/pubsub`, `gcp/dataflow` and `gcp/dataproc` all draw\nthe Data Analytics mark; `gcp/cloud-functions` (`functions`) and\n`gcp/app-engine` the Serverless one; `gcp/firestore`, `gcp/bigtable` and\n`gcp/memorystore` the Databases one; `gcp/load-balancer` (`lb`), `gcp/cloud-cdn`,\n`gcp/cloud-armor` and `gcp/cloud-nat` the Networking one; `gcp/iam`, `gcp/kms`\nand `gcp/secret-manager` the Security one; `gcp/cloud-build` and\n`gcp/artifact-registry` the DevOps one; `gcp/cloud-logging` and\n`gcp/cloud-monitoring` the Observability one. That is how Google draws them\nnow, so it is not a shortfall to work around — **put the product name in the\nlabel** and let the icon say the category; don't borrow a look-alike from\n`aws/` or `azure/`. A VPC is a boundary: `zone net \"prod-vpc\" network {\ncontains …, icon: gcp/vpc }`. The same one-cloud rule applies, and composing\nwith `logos` is normal. Use `gcp/*` when the diagram is about what runs\n*inside* Google Cloud; use `logos/googlecloud` when Google Cloud is one box in\na wider estate. `squinch icons search --pack gcp <term>` scopes the search;\nthe bare word `gcp` lists the whole pack.\n\n## Kubernetes\n\n**Kubernetes internals** come from the `k8s` pack (39 official community\nicons — the blue heptagons from the k8s docs). Canonical ids are kubectl's\nshort names, and the long names alias to them, so both spellings check clean:\n`k8s/pod` · `k8s/deploy` (`deployment`) · `k8s/svc` (`service`) · `k8s/sts`\n(`statefulset`) · `k8s/ds` (`daemonset`) · `k8s/rs` (`replicaset`) · `k8s/cm`\n(`configmap`) · `k8s/secret` · `k8s/ing` (`ingress`) · `k8s/ns` (`namespace`) ·\n`k8s/sa` (`serviceaccount`) · `k8s/pv` · `k8s/pvc` · `k8s/sc` · `k8s/netpol` ·\n`k8s/hpa` · `k8s/job` · `k8s/cronjob` · `k8s/crd` · `k8s/node` · `k8s/etcd` ·\n`k8s/control-plane` · `k8s/api` (`apiserver`) · `k8s/sched` (`scheduler`) ·\n`k8s/kubelet` · `k8s/k-proxy` (`kubeproxy`).\nUse `k8s/*` when the diagram is about what runs *inside* a cluster; use\n`logos/kubernetes` when the cluster is one box in a wider estate. A namespace\nis a boundary, not a workload — prefer `zone team-a \"team-a\" custom { contains\n…, icon: k8s/ns }` over a `k8s/ns` node. Composing with a cloud pack is normal:\n`azure/aks` or `aws/eks` as the managed control plane, `k8s/*` for what it runs.\n\n## Logos — products and open source\n\n**Non-AWS things** come from the `logos` pack (147 product marks, plated in\ntheir brand colour): `logos/postgres` · `logos/mysql` · `logos/mongodb` ·\n`logos/redis` · `logos/kafka` · `logos/rabbitmq` · `logos/elasticsearch` ·\n`logos/kubernetes` (`k8s`) · `logos/docker` · `logos/terraform` ·\n`logos/nginx` · `logos/github` · `logos/gitlab` · `logos/grafana` ·\n`logos/prometheus` · `logos/datadog` · `logos/sentry` · `logos/stripe` ·\n`logos/snowflake` · `logos/cloudflare` · `logos/vercel` · `logos/nextdotjs` ·\n`logos/react` · `logos/python` · `logos/nodedotjs` (`node`) · `logos/go` ·\n`logos/rust` · `logos/graphql`.\nSome brands (Slack, Twilio, Salesforce, Heroku, gRPC…) have no icon upstream —\nthey were withdrawn on trademark request. Use `box` for those.\n\n## sys — the generic set\n\n`sys/*` is the generic set — 195 Lucide icons for anything no vendor draws, and\nit needs no `pack` statement. Use it for on-prem and physical things, and as the\nlast resort when nothing else fits. Ids are Lucide's own names:\n\n- **compute / app** — `server`, `container`, `cpu`, `code`, `app-window`,\n `hexagon`, `terminal`, `cog`, `webhook`, `workflow`, `route`\n- **hardware** — `laptop`, `monitor`, `smartphone`, `hard-drive`, `printer`\n- **network** — `network`, `router`, `wifi`, `radio-tower`, `globe`, `share-2`\n- **security** — `lock`, `lock-keyhole`, `key-round`, `shield`, `shield-check`\n- **data** — `database`, `folder`, `search`, `archive`, `table`, `file`\n- **places** — `factory`, `warehouse`, `building-2`, `house`, `earth`\n- **process / observability** — `clock`, `timer`, `repeat`, `activity`, `gauge`,\n `chart-line`, `siren`, `bug`\n- **commerce** — `shopping-cart`, `shopping-bag`, `credit-card`, `wallet`,\n `receipt-text`, `banknote`, `coins`, `badge-percent`, `ticket`, `truck`,\n `package-check`, `barcode`, `calculator`, `gift`, `heart`, `headset`\n- **shapes, when nothing fits** — `box`, `circle`, `square`, `triangle`,\n `diamond`, `hexagon`, `star`\n\nShort aliases exist for words you would type instead: `gear`→`cog`,\n`cube`→`box`, `db`→`database`, `rack`/`vm`/`host`→`server`, `disk`→`hard-drive`,\n`firewall`→`shield`, `vault`→`lock-keyhole`, `cron`→`clock`, `lb`→`share-2`,\n`cart`→`shopping-cart`, `checkout`→`shopping-bag`, `payment`→`credit-card`,\n`order`/`invoice`→`receipt-text`, `shipping`→`truck`, `ads`→`megaphone`.\n\n## Platforms with no icon pack\n\nSome vendors publish no icons anyone may redistribute, so no pack exists and none\never will — Databricks, Snowflake, dbt and Confluent are the ones that come up.\nDon't reach for a lookalike from another vendor and don't invent an id. Draw the\n*concept* from `sys/*` and mark it with the vendor's mark from `logos/*`:\n\n```squinch\nwh = sys/database \"SQL warehouse\" { badge: logos/databricks, subtitle: \"Databricks SQL\" }\n```\n\nThe `subtitle:` is optional; it names the product where the mark alone only\nnames the vendor.\n\nDatabricks, worked out — every base below is a real `sys/` id or alias:\n\n| component | write |\n| --- | --- |\n| Delta table | `sys/table … { badge: logos/databricks }` |\n| Unity Catalog | `sys/catalog` |\n| SQL warehouse | `sys/database` |\n| Vector search | `sys/waypoints` |\n| Model serving | `sys/model` |\n| MLflow experiment | `sys/experiment` |\n| Notebook | `sys/notebook` |\n| Workflows job | `sys/workflow` |\n| Structured streaming | `sys/stream` |\n\nThe same recipe covers any vendor whose mark is in the logos pack —\n`logos/snowflake` is there, dbt and Confluent are not. Search before writing a\nbadge; if there's no mark, skip the badge and let the label carry the vendor.\nBadge only what the platform actually owns: a Kafka or S3 node keeps its own\nicon, and that contrast is what makes the platform boundary readable.\n" };
7
7
  export const SKILL_MD = SKILL_FILES["SKILL.md"];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "squinch",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "description": "Architecture diagrams as code for coding agents: install the skill, then check, render, diff and watch .squinch projects — clean, zoomable diagrams with real cloud icons, as deterministic SVG, PNG or interactive HTML.",
5
5
  "keywords": [
6
6
  "architecture",
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "dependencies": {
45
45
  "@resvg/resvg-js": "^2.6.2",
46
- "@squinch/core": "0.20.0"
46
+ "@squinch/core": "0.21.0"
47
47
  },
48
48
  "devDependencies": {
49
49
  "tsx": "^4.23.1",