squinch 0.18.0 → 0.19.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 +103 -65
- package/dist/skill.generated.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
2
|
+
<img src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.
|
|
9
|
+
<a href="https://github.com/jquatier/squinch/blob/v0.19.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.
|
|
54
|
-
<img src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
53
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/docs/assets/prompt-dark.gif">
|
|
54
|
+
<img src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.
|
|
64
|
+
[skill](https://github.com/jquatier/squinch/tree/v0.19.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.
|
|
69
|
+
[examples/products-api](https://github.com/jquatier/squinch/tree/v0.19.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.
|
|
78
|
-
<img src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
77
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/docs/assets/zoom-dark.gif">
|
|
78
|
+
<img src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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,12 +91,50 @@ 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.
|
|
94
|
+
drift — see [examples/microservices](https://github.com/jquatier/squinch/tree/v0.19.0/examples/microservices) for the source.
|
|
95
|
+
|
|
96
|
+
## Tables and fields
|
|
97
|
+
|
|
98
|
+
A table, collection or topic can carry its schema. Write a `fields { }` block
|
|
99
|
+
inside the leaf, one field per line: a name, the type as your store spells it,
|
|
100
|
+
then free words for keys and constraints, and an optional quoted caption.
|
|
101
|
+
|
|
102
|
+
```squinch
|
|
103
|
+
container db "Orders DB" {
|
|
104
|
+
orders = sys/table "orders" datastore {
|
|
105
|
+
fields {
|
|
106
|
+
id uuid pk
|
|
107
|
+
customer_id uuid fk ref customers.id
|
|
108
|
+
gate text nullable "null = all gates"
|
|
109
|
+
total numeric(10,2)
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- **Markers are your vocabulary, not the language's.** `pk`, `fk`, `nullable`,
|
|
116
|
+
`unique`, `hash`, `sort`, `ttl`, `index gsi1` — any word draws as a chip, so
|
|
117
|
+
Postgres, DynamoDB, MongoDB and Kafka all fit. A composite key is `pk` on
|
|
118
|
+
each of its columns.
|
|
119
|
+
- **`ref <path>`** names the column or table a field points at. It is text on
|
|
120
|
+
the row; the relationship itself is an edge between the two tables.
|
|
121
|
+
- **Fields draw where the table's container is open.** A view scoped to the
|
|
122
|
+
database (`view db { scope shop.db }`) shows every field. Wherever the
|
|
123
|
+
database is expanded (`expand db`, `expand *`) each table shows a compact
|
|
124
|
+
list: the first six, or the ones its `preview: [id status]` names. A table
|
|
125
|
+
at the top level shows them when the view says `preview <table>`.
|
|
126
|
+
- **The landscape never changes.** A collapsed card looks the same with or
|
|
127
|
+
without fields, and `preview: none` keeps a table plain everywhere but its
|
|
128
|
+
own database view.
|
|
129
|
+
|
|
130
|
+
`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.19.0/docs/SPEC.md); the lookbook's
|
|
132
|
+
[Fields case](https://github.com/jquatier/squinch/blob/v0.19.0/lookbook/cases/43-fields.squinch) shows all three placements.
|
|
95
133
|
|
|
96
134
|
## Features
|
|
97
135
|
|
|
98
136
|
- **LLMs write it fluently.** Give your coding agent the bundled
|
|
99
|
-
[skill](https://github.com/jquatier/squinch/tree/v0.
|
|
137
|
+
[skill](https://github.com/jquatier/squinch/tree/v0.19.0/packages/skill) and ask for a diagram of your system. The language was
|
|
100
138
|
designed for agents to author rather than retrofitted for them, so what comes
|
|
101
139
|
back is a correct diagram, not one you have to redraw.
|
|
102
140
|
- **1,358 real vendor icons.** AWS, Azure, Google Cloud, Kubernetes and product logos, not
|
|
@@ -172,7 +210,7 @@ The other surfaces, each its own one-liner:
|
|
|
172
210
|
and VSCodium.
|
|
173
211
|
- **CI** — `uses: jquatier/squinch/.github/actions/squinch-check@main` fails
|
|
174
212
|
the build when a committed SVG is stale;
|
|
175
|
-
[`squinch-diff`](https://github.com/jquatier/squinch/tree/v0.
|
|
213
|
+
[`squinch-diff`](https://github.com/jquatier/squinch/tree/v0.19.0/.github/actions/squinch-diff) comments what changed,
|
|
176
214
|
architecturally, on the PR. Pin the `version` input: rendering is
|
|
177
215
|
deterministic *per tool version*, so a floating `latest` can change your
|
|
178
216
|
goldens on someone else's release day.
|
|
@@ -252,8 +290,8 @@ view products {
|
|
|
252
290
|
```
|
|
253
291
|
|
|
254
292
|
<picture>
|
|
255
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
256
|
-
<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.
|
|
293
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.19.0/examples/products-api/products-api.products.light.svg">
|
|
257
295
|
</picture>
|
|
258
296
|
|
|
259
297
|
## Why
|
|
@@ -286,23 +324,23 @@ conflict.squinch:9:5 error: contradictory place hints: `s.a` vs `s.b` reference
|
|
|
286
324
|
|
|
287
325
|
## What it can draw
|
|
288
326
|
|
|
289
|
-
Every picture below is a committed render from [lookbook/](https://github.com/jquatier/squinch/tree/v0.
|
|
327
|
+
Every picture below is a committed render from [lookbook/](https://github.com/jquatier/squinch/tree/v0.19.0/lookbook), rebuilt
|
|
290
328
|
and byte-compared on every push — so none of them can quietly stop being true.
|
|
291
329
|
|
|
292
330
|
<table>
|
|
293
331
|
<tr>
|
|
294
332
|
<td width="50%" valign="top">
|
|
295
333
|
<picture>
|
|
296
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
297
|
-
<img alt="Deployment boundaries" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
334
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/17-zones.landscape.dark.svg">
|
|
335
|
+
<img alt="Deployment boundaries" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/17-zones.landscape.light.svg" width="100%">
|
|
298
336
|
</picture>
|
|
299
337
|
<b>Deployment boundaries</b><br>
|
|
300
338
|
<code>zone</code> — cloud, VPC, on-prem, nested, each kind-tinted, with chips that straddle the border
|
|
301
339
|
</td>
|
|
302
340
|
<td width="50%" valign="top">
|
|
303
341
|
<picture>
|
|
304
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
305
|
-
<img alt="A notification pipeline: events queue, a worker archives and pushes to the customer" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
342
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.19.0/examples/notifications/notifications.pipeline.light.svg" width="100%">
|
|
306
344
|
</picture>
|
|
307
345
|
<b>Motion that carries meaning</b><br>
|
|
308
346
|
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
|
|
@@ -311,16 +349,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
|
|
|
311
349
|
<tr>
|
|
312
350
|
<td width="50%" valign="top">
|
|
313
351
|
<picture>
|
|
314
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
315
|
-
<img alt="Numbered flows" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
352
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/18-flows.shop.dark.svg">
|
|
353
|
+
<img alt="Numbered flows" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/18-flows.shop.light.svg" width="100%">
|
|
316
354
|
</picture>
|
|
317
355
|
<b>Numbered flows</b><br>
|
|
318
356
|
<code>flow</code> declares a request path; <code>show flow</code> badges the steps in order along the edges
|
|
319
357
|
</td>
|
|
320
358
|
<td width="50%" valign="top">
|
|
321
359
|
<picture>
|
|
322
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
323
|
-
<img alt="Legend and titleblock" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
360
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/16-legend-titleblock.pay.dark.svg">
|
|
361
|
+
<img alt="Legend and titleblock" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/16-legend-titleblock.pay.light.svg" width="100%">
|
|
324
362
|
</picture>
|
|
325
363
|
<b>Legend and titleblock</b><br>
|
|
326
364
|
<code>legend auto</code> keys only the styles the diagram actually uses; <code>titleblock</code> is drafting-style metadata
|
|
@@ -329,16 +367,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
|
|
|
329
367
|
<tr>
|
|
330
368
|
<td width="50%" valign="top">
|
|
331
369
|
<picture>
|
|
332
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
333
|
-
<img alt="Channel trunks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
370
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/22-channel.bussed.dark.svg">
|
|
371
|
+
<img alt="Channel trunks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/22-channel.bussed.light.svg" width="100%">
|
|
334
372
|
</picture>
|
|
335
373
|
<b>Channel trunks</b><br>
|
|
336
374
|
<code>channel a, b, c -> db</code> collapses many converging edges into one trunk instead of a fan
|
|
337
375
|
</td>
|
|
338
376
|
<td width="50%" valign="top">
|
|
339
377
|
<picture>
|
|
340
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
341
|
-
<img alt="Edge routing" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
378
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/14-sidecar-routes.app.dark.svg">
|
|
379
|
+
<img alt="Edge routing" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/14-sidecar-routes.app.light.svg" width="100%">
|
|
342
380
|
</picture>
|
|
343
381
|
<b>Edge routing</b><br>
|
|
344
382
|
<code>place</code> puts the sidecar beside its owner; <code>route … from east to west</code> picks the sides
|
|
@@ -347,16 +385,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
|
|
|
347
385
|
<tr>
|
|
348
386
|
<td width="50%" valign="top">
|
|
349
387
|
<picture>
|
|
350
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
351
|
-
<img alt="Beyond the clouds" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
388
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/21-logos.landscape.dark.svg">
|
|
389
|
+
<img alt="Beyond the clouds" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/21-logos.landscape.light.svg" width="100%">
|
|
352
390
|
</picture>
|
|
353
391
|
<b>Beyond the clouds</b><br>
|
|
354
392
|
<code>pack logos</code> for the non-cloud half of a stack, plated and tinted; the <code>×n</code> badge aggregates lifted edges
|
|
355
393
|
</td>
|
|
356
394
|
<td width="50%" valign="top">
|
|
357
395
|
<picture>
|
|
358
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
359
|
-
<img alt="Craft details" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
396
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/20-align-hops.s.dark.svg">
|
|
397
|
+
<img alt="Craft details" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/20-align-hops.s.light.svg" width="100%">
|
|
360
398
|
</picture>
|
|
361
399
|
<b>Craft details</b><br>
|
|
362
400
|
<code>align</code> snaps nodes onto one axis, and crossing edges hop rather than blur into a junction
|
|
@@ -365,16 +403,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
|
|
|
365
403
|
<tr>
|
|
366
404
|
<td width="50%" valign="top">
|
|
367
405
|
<picture>
|
|
368
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
369
|
-
<img alt="Tag lenses and notes" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
406
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/10-highlight-notes.pci.dark.svg">
|
|
407
|
+
<img alt="Tag lenses and notes" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/10-highlight-notes.pci.light.svg" width="100%">
|
|
370
408
|
</picture>
|
|
371
409
|
<b>Tag lenses and notes</b><br>
|
|
372
410
|
<code>highlight #pci</code> dims everything off-topic; notes anchor to the node they are about
|
|
373
411
|
</td>
|
|
374
412
|
<td width="50%" valign="top">
|
|
375
413
|
<picture>
|
|
376
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
377
|
-
<img alt="Vendor badges on generic marks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
414
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/30-badges.lakehouse.dark.svg">
|
|
415
|
+
<img alt="Vendor badges on generic marks" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.0/lookbook/out/30-badges.lakehouse.light.svg" width="100%">
|
|
378
416
|
</picture>
|
|
379
417
|
<b>Vendors with no icon pack</b><br>
|
|
380
418
|
<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
|
|
@@ -383,16 +421,16 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
|
|
|
383
421
|
<tr>
|
|
384
422
|
<td width="50%" valign="top">
|
|
385
423
|
<picture>
|
|
386
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
387
|
-
<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.
|
|
424
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.19.0/lookbook/out/34-view-axes.audit.light.svg" width="100%">
|
|
388
426
|
</picture>
|
|
389
427
|
<b>The audit view</b><br>
|
|
390
428
|
<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
|
|
391
429
|
</td>
|
|
392
430
|
<td width="50%" valign="top">
|
|
393
431
|
<picture>
|
|
394
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
395
|
-
<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.
|
|
432
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.19.0/lookbook/out/33-card-shelf.landscape.light.svg" width="100%">
|
|
396
434
|
</picture>
|
|
397
435
|
<b>Cards that carry their metadata</b><br>
|
|
398
436
|
<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>
|
|
@@ -403,7 +441,7 @@ Events arrive as <code>packets</code>, the archive job drifts <code>slow</code>,
|
|
|
403
441
|
Also in the language: `cols` to pin the other axis, `datastore` / `external`
|
|
404
442
|
node kinds, descriptions, and container nesting. Async edges (`~>`) are dashed
|
|
405
443
|
and animate at a constant speed — CSS keyframes, never script. Full grammar in
|
|
406
|
-
[docs/SPEC.md](https://github.com/jquatier/squinch/blob/v0.
|
|
444
|
+
[docs/SPEC.md](https://github.com/jquatier/squinch/blob/v0.19.0/docs/SPEC.md).
|
|
407
445
|
|
|
408
446
|
## Written by agents, and tested that way
|
|
409
447
|
|
|
@@ -414,11 +452,11 @@ Errors are built for the agent loop, not just for humans: every diagnostic
|
|
|
414
452
|
carries a location, the problem, and a likely fix, with did-you-mean suggestions
|
|
415
453
|
for unknown icons, views and identifiers. `squinch check --format json` emits
|
|
416
454
|
exactly the same information a person sees.
|
|
417
|
-
[`SKILL.md`](https://github.com/jquatier/squinch/blob/v0.
|
|
455
|
+
[`SKILL.md`](https://github.com/jquatier/squinch/blob/v0.19.0/packages/skill/skills/squinch/SKILL.md), with the `references/`
|
|
418
456
|
beside it, is the whole contract an
|
|
419
457
|
agent needs — `npx squinch skill` installs it for every skills-compatible agent
|
|
420
458
|
(or paste it into whatever your harness calls context), then ask for a diagram
|
|
421
|
-
in plain language; [the package README](https://github.com/jquatier/squinch/tree/v0.
|
|
459
|
+
in plain language; [the package README](https://github.com/jquatier/squinch/tree/v0.19.0/packages/skill) has the details.
|
|
422
460
|
|
|
423
461
|
The **gauntlet** is the acceptance test: thirty-eight architecture prompts —
|
|
424
462
|
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
|
|
@@ -438,7 +476,7 @@ channels, more packs, the positional-tag grammar, large-system prompts,
|
|
|
438
476
|
database tables and a real repository landed.
|
|
439
477
|
|
|
440
478
|
The committed corpus scores **38/38** with zero human layout fixes. Every round is
|
|
441
|
-
written up in [gauntlet/README.md](https://github.com/jquatier/squinch/blob/v0.
|
|
479
|
+
written up in [gauntlet/README.md](https://github.com/jquatier/squinch/blob/v0.19.0/gauntlet/README.md) — what was asked, how it
|
|
442
480
|
was run, and what came back.
|
|
443
481
|
|
|
444
482
|
## Deterministic by construction
|
|
@@ -506,15 +544,15 @@ a filter. The same two nodes, both ways:
|
|
|
506
544
|
<th align="center"><code>dark</code></th>
|
|
507
545
|
</tr>
|
|
508
546
|
<tr>
|
|
509
|
-
<td align="center"><img alt="The same two-node diagram in the Light theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
510
|
-
<td align="center"><img alt="The same two-node diagram in the Dark theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.
|
|
547
|
+
<td align="center"><img alt="The same two-node diagram in the Light theme" src="https://raw.githubusercontent.com/jquatier/squinch/v0.19.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.19.0/lookbook/out/01-minimal.tiny.dark.svg" width="180"></td>
|
|
511
549
|
</tr>
|
|
512
550
|
</table>
|
|
513
551
|
|
|
514
552
|
`--adaptive` folds the pair into one file behind `prefers-color-scheme`, so an
|
|
515
553
|
embedded diagram follows the reader's OS without you picking a side.
|
|
516
554
|
|
|
517
|
-
The [lookbook](https://github.com/jquatier/squinch/tree/v0.
|
|
555
|
+
The [lookbook](https://github.com/jquatier/squinch/tree/v0.19.0/lookbook) renders 35 deliberately awkward cases — dense meshes,
|
|
518
556
|
long labels, deep nesting, coplanar rows — to 86 committed SVGs across the
|
|
519
557
|
themes, and CI fails if any of them changes unintentionally.
|
|
520
558
|
|
|
@@ -525,12 +563,12 @@ redistributed and one shipped on Google's stated purpose for it:
|
|
|
525
563
|
|
|
526
564
|
| Pack | Count | Terms |
|
|
527
565
|
| --- | --- | --- |
|
|
528
|
-
| [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.
|
|
529
|
-
| [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.
|
|
530
|
-
| [`pack-logos`](https://github.com/jquatier/squinch/tree/v0.
|
|
531
|
-
| [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.
|
|
532
|
-
| [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.
|
|
533
|
-
| [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.
|
|
566
|
+
| [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.19.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.19.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.19.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.19.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.19.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.19.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 |
|
|
534
572
|
|
|
535
573
|
```console
|
|
536
574
|
$ squinch icons search factory
|
|
@@ -590,17 +628,17 @@ carry a script, and it is a separate class rather than a loophole: the SVGs
|
|
|
590
628
|
inside it are byte-for-byte what `render -o x.svg` produces, the viewer is
|
|
591
629
|
their sibling and never their content, and a test asserts nothing executable
|
|
592
630
|
survives removing the two `<script>` elements
|
|
593
|
-
([docs/notes/html-export.md](https://github.com/jquatier/squinch/blob/v0.
|
|
631
|
+
([docs/notes/html-export.md](https://github.com/jquatier/squinch/blob/v0.19.0/docs/notes/html-export.md)). Exported `.svg` never
|
|
594
632
|
contains script, full stop.
|
|
595
633
|
|
|
596
634
|
## Docs
|
|
597
635
|
|
|
598
|
-
- [DSL specification (v0 draft)](https://github.com/jquatier/squinch/blob/v0.
|
|
599
|
-
- [Design language](https://github.com/jquatier/squinch/blob/v0.
|
|
600
|
-
- [Engineering constraints](https://github.com/jquatier/squinch/blob/v0.
|
|
601
|
-
- [Engineering notes](https://github.com/jquatier/squinch/tree/v0.
|
|
602
|
-
- [Examples](https://github.com/jquatier/squinch/tree/v0.
|
|
603
|
-
- [Contributing](https://github.com/jquatier/squinch/blob/v0.
|
|
636
|
+
- [DSL specification (v0 draft)](https://github.com/jquatier/squinch/blob/v0.19.0/docs/SPEC.md)
|
|
637
|
+
- [Design language](https://github.com/jquatier/squinch/blob/v0.19.0/docs/DESIGN.md)
|
|
638
|
+
- [Engineering constraints](https://github.com/jquatier/squinch/blob/v0.19.0/docs/ENGINEERING.md) — performance budgets, verification, and what is deliberately not built
|
|
639
|
+
- [Engineering notes](https://github.com/jquatier/squinch/tree/v0.19.0/docs/notes) — decisions with their rejected alternatives
|
|
640
|
+
- [Examples](https://github.com/jquatier/squinch/tree/v0.19.0/examples) and the [lookbook](https://github.com/jquatier/squinch/tree/v0.19.0/lookbook)
|
|
641
|
+
- [Contributing](https://github.com/jquatier/squinch/blob/v0.19.0/CONTRIBUTING.md) · [Security policy](https://github.com/jquatier/squinch/blob/v0.19.0/SECURITY.md) · [Icon notices](https://github.com/jquatier/squinch/blob/v0.19.0/NOTICE)
|
|
604
642
|
|
|
605
643
|
## Acknowledgments
|
|
606
644
|
|
|
@@ -609,19 +647,19 @@ Squinch's model/view approach builds on the ideas of the
|
|
|
609
647
|
|
|
610
648
|
## License
|
|
611
649
|
|
|
612
|
-
Squinch itself is [Apache-2.0](https://github.com/jquatier/squinch/blob/v0.
|
|
650
|
+
Squinch itself is [Apache-2.0](https://github.com/jquatier/squinch/blob/v0.19.0/LICENSE). The bundled icon artwork is **not** —
|
|
613
651
|
each pack is redistributed verbatim under its own terms, and that credit
|
|
614
652
|
travels with anything that serves the artwork (the playground carries it under
|
|
615
653
|
"icon credits"):
|
|
616
654
|
|
|
617
655
|
| Pack | Attribution | Terms |
|
|
618
656
|
| --- | --- | --- |
|
|
619
|
-
| [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.
|
|
620
|
-
| [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.
|
|
621
|
-
| [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.
|
|
622
|
-
| [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.
|
|
623
|
-
| [`pack-logos`](https://github.com/jquatier/squinch/tree/v0.
|
|
624
|
-
| [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.
|
|
657
|
+
| [`pack-aws`](https://github.com/jquatier/squinch/tree/v0.19.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.19.0/packages/pack-aws/NOTICE) — attribution required, no derivatives |
|
|
658
|
+
| [`pack-azure`](https://github.com/jquatier/squinch/tree/v0.19.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.19.0/packages/pack-azure/NOTICE) — architecture diagrams, training and documentation only |
|
|
659
|
+
| [`pack-k8s`](https://github.com/jquatier/squinch/tree/v0.19.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.19.0/packages/pack-k8s/NOTICE) — attribution required |
|
|
660
|
+
| [`pack-gcp`](https://github.com/jquatier/squinch/tree/v0.19.0/packages/pack-gcp) | Google — [Google Cloud icon library](https://cloud.google.com/icons) | [No published grant](https://github.com/jquatier/squinch/blob/v0.19.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.19.0/packages/pack-logos) | [Simple Icons](https://simpleicons.org) | [CC0-1.0](https://github.com/jquatier/squinch/blob/v0.19.0/packages/pack-logos/NOTICE) — the marks remain their owners' trademarks |
|
|
662
|
+
| [`pack-sys`](https://github.com/jquatier/squinch/tree/v0.19.0/packages/pack-sys) | [Lucide](https://lucide.dev), portions from Feather | [ISC](https://github.com/jquatier/squinch/blob/v0.19.0/packages/pack-sys/NOTICE) (Feather portions MIT) |
|
|
625
663
|
|
|
626
664
|
Kubernetes and the Kubernetes logo are trademarks of The Linux Foundation;
|
|
627
665
|
Google Cloud and its product names are trademarks of Google LLC; brand marks
|
package/dist/skill.generated.js
CHANGED
|
@@ -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 does a trailing comma. 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 and `direction`, written by short name; see Layout hints). Everything else\n — `channel`, `align`, `wrap`, `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`). 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\nchange no picture until you stand beside them: a view scoped to the table's\ncontainer draws every field, `preview <table>` elsewhere draws six\n(`preview: [a b]` on the table picks), and the landscape is untouched.\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 a fan-out only when the targets do not\n call each other, and a real system's usually do. Never answer it by listing\n every target in one `rows` band — that forces exactly the strip you are\n trying to avoid. Leave the targets unhinted and let the engine rank them.\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\nHint conflicts are the single biggest source of failed `check` runs in this\nproject's history — almost always a `rows` that pins every node, colliding with\none feedback edge. The engine ranks a clean pipeline correctly on its own;\nevery hint you add is a constraint you have to keep true.\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; a\n // same-rank edge is routed for you\n route api -> db \"write\" from south // label disambiguates parallels\n }\n}\nview steps { include *\n layout { wrap 5 } } // a long chain or a wide fan-out, folded\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. Do **not** use\n it to fold a long chain or a wide fan-out into several bands by hand: the\n edges that skip a band detour around it and the fold reads worse than the\n wide version. That is what `wrap N` is for — it folds the chain as a\n serpentine, or the fan-out onto a bus, and routes the fold cleanly.\n- **`wrap N` puts N in each band, and N sets the shape** — for a chain and a\n fan-out alike. For a slide, roughly 16:9, use N ≈ √(nodes being folded),\n rounded up: a 14-step chain is `wrap 4`, and so are twelve workers under\n one dispatcher. Half per band (`wrap 7` on fourteen) is a ribbon, not a\n slide. Leave `direction right` out of a wide fold: a band is a rank, and\n under `direction right` ranks are columns, so `wrap 7` becomes two tall\n columns of seven.\n- **Every edge must point down your bands** — check each band against your\n arrows before you write it. The bands are a claim about direction, and a node\n pointing back *up* the list is a check error, not a nudge. This bites on\n monitoring, feedback and retry paths: `mon -> api` under\n `rows [api] [svc] [db] [mon]` is refused. Two fixes, both fine: put the\n observer in the **same** band as what it watches (`rows [api mon] [svc] [db]`\n — equal ranks are legal and route side to side), or leave it out of `rows`\n and let the engine rank it.\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 is refused. If you want them beside each other, 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` 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. Two members of one system asked to\n share a row with an edge between them is a warning: same-rank edges route\n between systems, not inside one, so put one below the other or collapse the\n system in that view.\n- **Rank hints don't reach inside a zone.** A zone lays out as a single block —\n `rows`/`cols`/`place` order zones *relative to each other*, and the engine\n arranges the members within. To rank a zone, name **one** member of it (or\n the zone's own id): `rows [gw] [prod_vpc]` puts the whole boundary below the\n gateway. Listing every member does nothing but earn a warning. If the ranking\n matters more than the boundary, drop the zone. Two zones *may* share a band\n with edges running between them — `rows [batch orders]` on two namespaces\n holds, and the edge routes through the gutter like one between expanded\n containers.\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, and same-rank edges route side to side\n automatically — a `from`/`to` on one 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 hint conflicts `check` refuses\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 routes itself; adding `route … from east to west` does nothing, because `place` makes them same-rank |\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| \"`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| \"hint conflict: `a` → `b` runs upward — row 6 to row 4\" error | Your bands contradict your arrows. `rows` runs top to bottom, so every edge must point down the list. Usually a monitor or feedback path: put it in the **same** band as what it points at (equal ranks are legal), or drop it from `rows` and let the engine rank it |\n| \"hint conflict: `rows` puts `a` and `b` in one band, but `k` sits on the path between them and is in no band — `b` lands a tier later\" error | Something you did not list sits between two things you put side by side — usually a shared bus or queue (`a ~> k ~> b`). A band is one tier, so `b` cannot be beside `a` and below `k` at once. Paste the `rows` line the fix writes out: it lists `k` too, in its own band or beside whichever side the arrows allow. On a big landscape, expect this the moment you band the areas and forget the bus |\n| \"hint conflict: `a` → `b` runs upward inside `s`\" error | The system's bands contradict its own arrows, same rule as the view's `rows`: put `b` in a row below `a`, or drop one of them from that block |\n| \"`a` and `b` are asked to share a row inside `s`, but the edge between them cannot be routed there\" warning | Same-rank edges route between systems, not inside one. Put `b` in the row below `a`, or collapse `s` in this view |\n| A wire jogs slightly instead of running straight | `align a b` — b takes a's axis exactly (a is the anchor) |\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 route through the gutters and land on the cards |\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 fan-out runs off the page | `layout { wrap 5 }` — folds one chain into a serpentine, or one source's fan-out into bands under it (the skipping edges become a bus). Two shapes only; anything else warns and names the `rows` line to write instead. Never beside `rows`/`cols`. For a 16:9 slide, N ≈ √(steps) rounded up, and no `direction right` |\n| \"`wrap 5` has no effect — this view is not a single chain or a single fan-out (…)\" warning | `wrap` folds exactly one chain (a → b → c …) or one source fanning out to leaves. Write the bands by hand: `rows [a b] [c d]` |\n| Diagram too cramped / too airy | `density spacious` / `density compact` |\n| \"rank hints on … have no effect\" warning | Those nodes are all inside one zone, which lays out as a single block. Order the zones instead, or drop the boundary |\n| \"align skipped … outside zone\" warning | The snap would have dragged a member out of its own boundary. Align it with something inside the zone |\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 — including \"has no room for a trunk\" | The trunk needs the whole picture: every member edge visible in this view, at least two of them, and the sources sitting *above* the target. Check `rows`, and that nothing is `exclude`d |\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| 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 you stand beside the table: a view scoped to its container (`view db { scope shop.db }`) shows every field; anywhere else, `preview <table>` shows six. The landscape never draws them, by design |\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 does a trailing comma. 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 and `direction`, written by short name; see Layout hints). Everything else\n — `channel`, `align`, `wrap`, `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 a fan-out only when the targets do not\n call each other, and a real system's usually do. Never answer it by listing\n every target in one `rows` band — that forces exactly the strip you are\n trying to avoid. Leave the targets unhinted and let the engine rank them.\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\nHint conflicts are the single biggest source of failed `check` runs in this\nproject's history — almost always a `rows` that pins every node, colliding with\none feedback edge. The engine ranks a clean pipeline correctly on its own;\nevery hint you add is a constraint you have to keep true.\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; a\n // same-rank edge is routed for you\n route api -> db \"write\" from south // label disambiguates parallels\n }\n}\nview steps { include *\n layout { wrap 5 } } // a long chain or a wide fan-out, folded\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. Do **not** use\n it to fold a long chain or a wide fan-out into several bands by hand: the\n edges that skip a band detour around it and the fold reads worse than the\n wide version. That is what `wrap N` is for — it folds the chain as a\n serpentine, or the fan-out onto a bus, and routes the fold cleanly.\n- **`wrap N` puts N in each band, and N sets the shape** — for a chain and a\n fan-out alike. For a slide, roughly 16:9, use N ≈ √(nodes being folded),\n rounded up: a 14-step chain is `wrap 4`, and so are twelve workers under\n one dispatcher. Half per band (`wrap 7` on fourteen) is a ribbon, not a\n slide. Leave `direction right` out of a wide fold: a band is a rank, and\n under `direction right` ranks are columns, so `wrap 7` becomes two tall\n columns of seven.\n- **Every edge must point down your bands** — check each band against your\n arrows before you write it. The bands are a claim about direction, and a node\n pointing back *up* the list is a check error, not a nudge. This bites on\n monitoring, feedback and retry paths: `mon -> api` under\n `rows [api] [svc] [db] [mon]` is refused. Two fixes, both fine: put the\n observer in the **same** band as what it watches (`rows [api mon] [svc] [db]`\n — equal ranks are legal and route side to side), or leave it out of `rows`\n and let the engine rank it.\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 is refused. If you want them beside each other, 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` 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. Two members of one system asked to\n share a row with an edge between them is a warning: same-rank edges route\n between systems, not inside one, so put one below the other or collapse the\n system in that view.\n- **Rank hints don't reach inside a zone.** A zone lays out as a single block —\n `rows`/`cols`/`place` order zones *relative to each other*, and the engine\n arranges the members within. To rank a zone, name **one** member of it (or\n the zone's own id): `rows [gw] [prod_vpc]` puts the whole boundary below the\n gateway. Listing every member does nothing but earn a warning. If the ranking\n matters more than the boundary, drop the zone. Two zones *may* share a band\n with edges running between them — `rows [batch orders]` on two namespaces\n holds, and the edge routes through the gutter like one between expanded\n containers.\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, and same-rank edges route side to side\n automatically — a `from`/`to` on one 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 hint conflicts `check` refuses\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 routes itself; adding `route … from east to west` does nothing, because `place` makes them same-rank |\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| \"`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| \"hint conflict: `a` → `b` runs upward — row 6 to row 4\" error | Your bands contradict your arrows. `rows` runs top to bottom, so every edge must point down the list. Usually a monitor or feedback path: put it in the **same** band as what it points at (equal ranks are legal), or drop it from `rows` and let the engine rank it |\n| \"hint conflict: `rows` puts `a` and `b` in one band, but `k` sits on the path between them and is in no band — `b` lands a tier later\" error | Something you did not list sits between two things you put side by side — usually a shared bus or queue (`a ~> k ~> b`). A band is one tier, so `b` cannot be beside `a` and below `k` at once. Paste the `rows` line the fix writes out: it lists `k` too, in its own band or beside whichever side the arrows allow. On a big landscape, expect this the moment you band the areas and forget the bus |\n| \"hint conflict: `a` → `b` runs upward inside `s`\" error | The system's bands contradict its own arrows, same rule as the view's `rows`: put `b` in a row below `a`, or drop one of them from that block |\n| \"`a` and `b` are asked to share a row inside `s`, but the edge between them cannot be routed there\" warning | Same-rank edges route between systems, not inside one. Put `b` in the row below `a`, or collapse `s` in this view |\n| A wire jogs slightly instead of running straight | `align a b` — b takes a's axis exactly (a is the anchor) |\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 route through the gutters and land on the cards |\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 fan-out runs off the page | `layout { wrap 5 }` — folds one chain into a serpentine, or one source's fan-out into bands under it (the skipping edges become a bus). Two shapes only; anything else warns and names the `rows` line to write instead. Never beside `rows`/`cols`. For a 16:9 slide, N ≈ √(steps) rounded up, and no `direction right` |\n| \"`wrap 5` has no effect — this view is not a single chain or a single fan-out (…)\" warning | `wrap` folds exactly one chain (a → b → c …) or one source fanning out to leaves. Write the bands by hand: `rows [a b] [c d]` |\n| Diagram too cramped / too airy | `density spacious` / `density compact` |\n| \"rank hints on … have no effect\" warning | Those nodes are all inside one zone, which lays out as a single block. Order the zones instead, or drop the boundary |\n| \"align skipped … outside zone\" warning | The snap would have dragged a member out of its own boundary. Align it with something inside the zone |\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 — including \"has no room for a trunk\" | The trunk needs the whole picture: every member edge visible in this view, at least two of them, and the sources sitting *above* the target. Check `rows`, and that nothing is `exclude`d |\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| 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.
|
|
3
|
+
"version": "0.19.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.
|
|
46
|
+
"@squinch/core": "0.19.0"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"tsx": "^4.23.1",
|