chalkbridge 1.0.0

package/guides/layout.md

@@ -0,0 +1,75 @@
+# Layout
+
+**Describe the graph. Let the bridge place it.**
+
+Placing twenty boxes by hand means choosing twenty pairs of coordinates one at a
+time, and it comes out looking like it: near-misses, drifting baselines, arrows
+crossing for no reason. You cannot see the canvas, so you cannot see it happen.
+
+## The shape of the work
+
+1. Create the elements with `role` and `label`. Give them ids you can refer to.
+   Coordinates can be anything — put them all at the origin if you like.
+2. Connect them with `chalk_connect`.
+3. Call `chalk_arrange` with `op: "layout-layered"` and the ids.
+
+The layout takes ranks from the direction of the arrows, orders within a rank to
+reduce crossings, and spaces from the house metrics. It is deterministic: the
+same graph lands the same way twice, so a re-run does not shuffle a diagram the
+user has started reading.
+
+Above roughly eight nodes, hand-placement is worse than this in every case. Below
+that it is a coin toss, and the layout is still less work.
+
+## Placing by hand
+
+Sometimes the position *is* the meaning — a timeline, a layered stack, a
+deliberate before/after pair. Then place explicitly, and keep to the grid the
+house style uses: 60 px between columns, 100 px between rows. Coordinates that
+are multiples of 20 stay aligned when the user nudges something.
+
+Two things worth knowing:
+
+- **x grows right, y grows down.** A box at `y: 40` is *above* one at `y: 300`.
+- **The origin is not special.** Negative coordinates are fine, and are often the
+  tidiest way to extend a diagram leftwards without moving what is already there.
+
+## Arranging what already exists
+
+`chalk_arrange` also does the small tidying jobs, on the elements you name:
+
+| Want | Op |
+|---|---|
+| a ragged column straightened | `align-left`, `align-center-v` |
+| a row levelled | `align-top`, `align-center-h` |
+| even gaps | `distribute-h`, `distribute-v` |
+| a set of similar things laid out | `grid` |
+| something brought out from behind | `bring-to-front`, `send-to-back` |
+
+These are the calls to reach for after the user says "this is a mess". They
+change nothing but geometry, so they are safe on elements the user drew — but
+they *will* move things the user positioned deliberately, so say what you are
+about to straighten.
+
+## Frames and groups
+
+- A **frame** is a labelled region a reader sees. Use it to split a diagram into
+  parts that can be understood one at a time.
+- A **group** is elements that move together. The reader never sees it.
+
+If you are adding a frame so that things move together, you want a group. If you
+are adding a group so the reader understands a boundary, you want a frame.
+
+## Adding to a diagram that already exists
+
+Read it first — `chalk_describe_scene` gives you every element's bounds. Then put
+new work in empty space rather than on top of something, and connect it. Running
+a layout over a diagram the user has already arranged will move their work; if
+the result needs one, arrange only the elements you added.
+
+## Do not use Mermaid
+
+Chalkbridge has no Mermaid import, deliberately. The conversion works by
+rendering Mermaid to SVG and reading the geometry back, so what you would get is
+Mermaid's layout — the flat, evenly-spaced look this canvas exists to avoid.
+Describe the graph and arrange it.

package/guides/styling.md

@@ -0,0 +1,85 @@
+# Styling
+
+The short version: **say what a thing is, not what colour it should be.**
+
+## Roles, not hex
+
+```json
+{ "type": "rectangle", "x": 120, "y": 140, "role": "compute",
+  "label": "Distiller" }
+```
+
+| Role | Means | Reads as |
+|---|---|---|
+| `compute` | it runs code — services, workers, functions | blue |
+| `storage` | it holds state — databases, buckets, caches | green |
+| `edge` | it moves things — queues, gateways, load balancers | amber |
+| `external` | not yours — third-party APIs, the user, another team's system | plain outline |
+| `hotspot` | the thing under discussion — the bug, the bottleneck, the risk | red |
+
+A role sets stroke, fill, weight, roughness and corner radius together, so
+everything you draw looks like it came from the same hand as everything the user
+drew. Passing raw colours instead gets you a diagram that is *your* colours, and
+the next diagram will be slightly different ones.
+
+`hotspot` is worth using sparingly and deliberately. If three things are red,
+nothing is.
+
+## When to override
+
+Every Excalidraw property is accepted on the same element object, and an explicit
+value always beats what the role implies. Override when the *deviation carries
+meaning*:
+
+```json
+{ "type": "rectangle", "x": 120, "y": 140, "role": "compute",
+  "label": "Legacy sync worker", "strokeStyle": "dashed", "opacity": 60,
+  "link": "https://github.com/you/nexus/blob/main/src/legacy/sync.ts" }
+```
+
+Conventions that read the same way to everyone:
+
+- **`strokeStyle: "dashed"`** — planned, deprecated, or not really there yet.
+- **`opacity: 60`** — deliberately in the background. Faded means "context", not
+  "less important to me personally".
+- **`strokeWidth: 4`** — the spine of the diagram, the path the reader should
+  follow first.
+- **`backgroundColor: "transparent"`** — a container, not a thing.
+
+Override for decoration and you have spent the diagram's whole vocabulary on
+nothing, and the next real distinction has nothing left to say it with.
+
+## Links are the best thing here
+
+`link` on any element turns it into a jump to a file, a PR, a dashboard, a doc:
+
+```json
+{ "link": "https://github.com/you/nexus/blob/main/src/distiller/index.ts" }
+```
+
+A box labelled "Distiller" is a claim. A box labelled "Distiller" that opens the
+file is a diagram someone can still trust in six months. Link generously — repo
+files especially. Linked elements are flagged `↗link` in `chalk_describe_scene`,
+so you can see at a glance which parts of a diagram are anchored to the code and
+which are just assertions.
+
+## Text
+
+Font, size and face come from the house style; you rarely need to set them. When
+you do:
+
+- `fontSize: 16` for a note that should not compete with the labels.
+- `fontSize: 28` for a heading over a region.
+
+Do not use font size for emphasis inside a diagram — use `role: "hotspot"` or
+`strokeWidth`, which stay legible when the canvas is zoomed out.
+
+## Locked and dark mode
+
+`locked: true` stops an element being dragged. Use it for backdrops and legends —
+things a user will click by accident and never mean to move. It is not a
+permission system; the user can unlock anything.
+
+Colours are chosen from the palette Excalidraw itself uses, so they hold up in
+both themes. `chalk_scene_settings` can switch the scene between them, but that
+is the user's preference to change — ask before you flip it.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "chalkbridge",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Self-hosted Excalidraw canvas for Claude Code to draw and reason on architecture diagrams.",
+  "license": "MIT",
+  "keywords": [
+    "excalidraw",
+    "mcp",
+    "claude",
+    "diagram",
+    "architecture",
+    "whiteboard",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "ui-dist",
+    "guides",
+    "packs",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "bin": {
+    "chalkbridge": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "node ../../packaging/copy-guides.mjs && node ../../packaging/copy-packs.mjs && tsup",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "node -e \"for (const d of ['dist','guides','packs']) require('node:fs').rmSync(d,{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@fastify/static": "^10.1.3",
+    "@fastify/websocket": "^11.3.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
+    "fastify": "^5.12.1",
+    "fractional-indexing": "3.2.0",
+    "open": "^11.0.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@chalkbridge/pack-toolkit": "workspace:*",
+    "@chalkbridge/shared": "workspace:*",
+    "@excalidraw/excalidraw": "0.18.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2"
+  }
+}

package/packs/generic/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Chalkbridge contributors
+
+The SVG files in this directory were drawn for Chalkbridge and are released under the
+same licence as the project itself. They are bundled into the `chalkbridge` npm package
+(DISTRIBUTION.md §1) rather than published separately, because a diagram tool that can
+draw nothing on the day it is installed has not finished installing.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packs/generic/chalk-pack.json

@@ -0,0 +1,115 @@
+{
+  "name": "generic",
+  "kind": "bundled",
+  "version": "1.0.0",
+  "license": "MIT",
+  "source": "bundled with chalkbridge",
+  "description": "The hand-drawn set that ships inside chalkbridge. Enough to draw a system on day one without installing anything (DISTRIBUTION.md §1).",
+  "svgDir": "svg",
+  "tagRules": { "fromPathSegments": false, "strip": [] },
+  "synonyms": {
+    "user": ["person", "customer", "actor", "human", "account", "client", "visitor"],
+    "users": ["team", "group", "people", "actors", "customers", "audience"],
+    "database": [
+      "db",
+      "sql",
+      "postgres",
+      "mysql",
+      "sqlite",
+      "store",
+      "table",
+      "persistence",
+      "rdbms"
+    ],
+    "cache": ["redis", "memcached", "memory", "hot", "ttl", "lookaside"],
+    "queue": [
+      "sqs",
+      "messaging",
+      "message",
+      "broker",
+      "kafka",
+      "pubsub",
+      "buffer",
+      "async",
+      "topic",
+      "backlog"
+    ],
+    "bucket": ["s3", "blob", "object", "archive", "storage", "cold"],
+    "server": [
+      "host",
+      "vm",
+      "machine",
+      "node",
+      "backend",
+      "service",
+      "compute",
+      "instance",
+      "daemon"
+    ],
+    "worker": [
+      "job",
+      "background",
+      "processor",
+      "serverless",
+      "lambda",
+      "function",
+      "faas",
+      "task",
+      "consumer",
+      "gear"
+    ],
+    "load-balancer": [
+      "lb",
+      "nginx",
+      "ingress",
+      "proxy",
+      "router",
+      "fanout",
+      "distribute",
+      "haproxy",
+      "envoy"
+    ],
+    "cron": ["schedule", "scheduled", "timer", "clock", "periodic", "nightly", "batch", "interval"],
+    "browser": ["web", "client", "frontend", "ui", "page", "spa", "dashboard"],
+    "mobile": ["phone", "app", "ios", "android", "device", "handset"],
+    "globe": ["internet", "external", "public", "world", "dns", "cdn", "network", "edge"],
+    "cloud": [
+      "saas",
+      "provider",
+      "hosted",
+      "external",
+      "aws",
+      "gcp",
+      "azure",
+      "vendor",
+      "thirdparty"
+    ],
+    "api": [
+      "endpoint",
+      "rest",
+      "graphql",
+      "gateway",
+      "http",
+      "interface",
+      "contract",
+      "rpc",
+      "grpc"
+    ],
+    "lock": ["auth", "security", "secure", "private", "encrypted", "permission", "acl"],
+    "key": ["credential", "token", "secret", "apikey", "access", "signing", "kms"],
+    "file": ["document", "doc", "artifact", "log", "report", "csv", "payload"],
+    "folder": ["directory", "repo", "namespace", "group", "package", "module"],
+    "alert": ["warning", "error", "incident", "alarm", "oncall", "hotspot", "failure", "pager"],
+    "metrics": [
+      "dashboard",
+      "chart",
+      "telemetry",
+      "observability",
+      "monitoring",
+      "analytics",
+      "grafana",
+      "stats"
+    ]
+  },
+  "icons": {}
+}

package/packs/generic/svg/alert.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M24 7L44 40H4z"/><path d="M24 20v9"/><path d="M24 34h.01"/></svg>

package/packs/generic/svg/api.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 11c-5 0-6 3-6 6.5S9.5 22 6.5 24c3 2 4.5 3 4.5 6.5S12 37 17 37"/><path d="M31 11c5 0 6 3 6 6.5s1.5 4.5 4.5 6.5c-3 2-4.5 3-4.5 6.5S36 37 31 37"/><path d="M22 19.5h.01M26 24h.01M22 28.5h.01"/></svg>

package/packs/generic/svg/browser.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="9" width="38" height="30" rx="3"/><path d="M5 18h38"/><path d="M11 13.5h.01M16 13.5h.01M21 13.5h.01"/></svg>

package/packs/generic/svg/bucket.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 13h30l-3.5 26.5c-.2 1.4-1.4 2.5-2.9 2.5H15.4c-1.5 0-2.7-1.1-2.9-2.5z"/><ellipse cx="24" cy="12" rx="15" ry="5"/></svg>

package/packs/generic/svg/cache.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="7" y="11" width="34" height="26" rx="4"/><path d="M25 16l-6 9h6l-3 8 9-11h-6z"/></svg>

package/packs/generic/svg/cloud.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15.5 37C10.3 37 6 32.9 6 27.9c0-4.6 3.6-8.4 8.3-9 1.6-5.5 6.8-9.4 12.9-9.4 7.2 0 13.1 5.5 13.4 12.4 3.2 1 5.4 3.9 5.4 7.2 0 4.3-3.6 7.9-8.1 7.9z"/></svg>

package/packs/generic/svg/cron.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="24" cy="24" r="17"/><path d="M24 13.5V24l7 4.5"/></svg>

package/packs/generic/svg/database.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="24" cy="12" rx="14" ry="5.5"/><path d="M10 12v24c0 3 6.3 5.5 14 5.5s14-2.5 14-5.5V12"/><path d="M10 24c0 3 6.3 5.5 14 5.5s14-2.5 14-5.5"/></svg>

package/packs/generic/svg/file.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 5h16l9 9v29H12z"/><path d="M28 5v9h9"/><path d="M18 25h12M18 32h12"/></svg>

package/packs/generic/svg/folder.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12a3 3 0 0 1 3-3h10l4 5h17a3 3 0 0 1 3 3v20a3 3 0 0 1-3 3H8a3 3 0 0 1-3-3z"/></svg>

package/packs/generic/svg/globe.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="24" cy="24" r="17"/><path d="M7 24h34"/><path d="M24 7c4.6 4.9 7 10.6 7 17s-2.4 12.1-7 17c-4.6-4.9-7-10.6-7-17s2.4-12.1 7-17z"/></svg>

package/packs/generic/svg/key.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="16" cy="20" r="9"/><path d="M22.4 26.4L40 44"/><path d="M35 39l4-4M30 34l4-4"/></svg>

package/packs/generic/svg/load-balancer.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="17" y="4" width="14" height="10" rx="2"/><rect x="3" y="34" width="12" height="10" rx="2"/><rect x="18" y="34" width="12" height="10" rx="2"/><rect x="33" y="34" width="12" height="10" rx="2"/><path d="M24 14v8M9 34v-4h30v4M24 26v8"/></svg>

package/packs/generic/svg/lock.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="21" width="30" height="21" rx="4"/><path d="M16 21v-6a8 8 0 0 1 16 0v6"/><path d="M24 29v5"/></svg>

package/packs/generic/svg/metrics.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 41h36"/><path d="M13 41V26M22 41V14M31 41V31M40 41V20"/></svg>

package/packs/generic/svg/mobile.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="14" y="4" width="20" height="40" rx="4"/><path d="M21 8.5h6"/><path d="M24 38.5h.01"/></svg>

package/packs/generic/svg/queue.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="6" y="12" width="9" height="24" rx="2"/><rect x="19.5" y="12" width="9" height="24" rx="2"/><rect x="33" y="12" width="9" height="24" rx="2"/><path d="M15.5 24h3.5M29 24h3.5"/></svg>

package/packs/generic/svg/server.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="7" y="9" width="34" height="13" rx="3"/><rect x="7" y="26" width="34" height="13" rx="3"/><path d="M13 15.5h.01M13 32.5h.01"/><path d="M20 15.5h14M20 32.5h14"/></svg>

package/packs/generic/svg/user.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="24" cy="17" r="7"/><path d="M10 40c1.5-8 7-12 14-12s12.5 4 14 12"/></svg>

package/packs/generic/svg/users.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="19" cy="17" r="6.5"/><path d="M6 40c1.4-7.4 6.4-11 13-11s11.6 3.6 13 11"/><path d="M32 12.5a6.5 6.5 0 0 1 .3 12.4"/><path d="M35 30c4.4 1.2 7.2 4.5 8 10"/></svg>

package/packs/generic/svg/worker.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="#1e1e1e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="24" cy="24" r="6"/><path d="M24 5.5v5M24 37.5v5M42.5 24h-5M10.5 24h-5M37.1 10.9l-3.5 3.5M14.4 33.6l-3.5 3.5M37.1 37.1l-3.5-3.5M14.4 14.4l-3.5-3.5"/></svg>

package/packs/recipes/aws.yml

@@ -0,0 +1,63 @@
+# AWS Architecture Icons — a RECIPE, not content. There are no SVGs in this file and
+# there never will be (CLAUDE.md invariant 36, CLAUDE.ARCHITECTURE.md L5).
+#
+# The terms permit using these icons *in* architecture diagrams while restricting
+# redistribution and modification. Chalkbridge therefore ships the knowledge of how to
+# ingest the set and asks the user to download it themselves — one extra step for them,
+# zero licensing exposure for this project.
+name: aws
+license: "AWS Architecture Icons — see the AWS trademark and asset terms at the source URL"
+source: https://aws.amazon.com/architecture/icons/
+instructions:
+  - "AWS Architecture Icons are not auto-installable: the vendor terms do not permit Chalkbridge to redistribute or fetch them for you."
+  - "1. Download the Asset Package from https://aws.amazon.com/architecture/icons/ and accept the terms there."
+  - "2. Unzip it anywhere you like."
+  - "3. Run: chalkbridge icons install aws --from <path-to-the-unzipped-folder>"
+  - "Or call chalk_install_pack again with `from` set to that path once the user has downloaded it."
+tagRules:
+  # Arch_Compute/Arch_AWS-Lambda_48.svg → name "lambda", tags including "compute"
+  fromPathSegments: true
+  strip:
+    - "Arch_"
+    - "Arch-Category_"
+    - "Res_"
+    - "_48"
+    - "_64"
+    - "_32"
+    - "_16"
+    - "AWS-"
+    - "Amazon-"
+    - "-Light"
+    - "-Dark"
+    - "_Light"
+    - "_Dark"
+synonyms:
+  lambda: [serverless, function, faas, worker, job]
+  sqs: [queue, messaging, broker, async, buffer]
+  sns: [pubsub, topic, notification, fanout]
+  eventbridge: [events, bus, routing, trigger]
+  s3: [bucket, object, blob, storage, archive]
+  dynamodb: [database, nosql, keyvalue, table, store]
+  rds: [database, sql, postgres, mysql, relational]
+  aurora: [database, sql, relational, cluster]
+  elasticache: [cache, redis, memcached, memory]
+  ec2: [server, vm, instance, compute, host]
+  ecs: [container, docker, cluster, orchestration]
+  eks: [kubernetes, container, cluster, orchestration]
+  fargate: [container, serverless, compute]
+  cloudfront: [cdn, edge, cache, distribution]
+  route-53: [dns, routing, domain, resolver]
+  api-gateway: [api, endpoint, rest, http, gateway]
+  elastic-load-balancing: [lb, "load-balancer", proxy, ingress, alb, nlb]
+  cognito: [auth, identity, login, users, oidc]
+  iam: [auth, permission, policy, role, security]
+  kms: [key, secret, encryption, crypto]
+  secrets-manager: [secret, credential, token, vault]
+  cloudwatch: [metrics, monitoring, logs, observability, alarm]
+  step-functions: [workflow, orchestration, "state-machine", saga]
+  kinesis: [stream, streaming, events, ingest]
+  glue: [etl, pipeline, transform, catalog]
+  athena: [query, analytics, sql, adhoc]
+  redshift: [warehouse, analytics, olap, database]
+  sagemaker: [ml, model, training, inference, ai]
+  bedrock: [ai, llm, model, inference, genai]

package/packs/recipes/azure.yml

@@ -0,0 +1,49 @@
+# Microsoft Azure architecture icons — a RECIPE, not content. No SVGs here, ever
+# (CLAUDE.md invariant 36, CLAUDE.ARCHITECTURE.md L5).
+#
+# Microsoft permits the icons in architecture diagrams and explicitly forbids
+# redistributing them as an icon set, which is precisely the line a package manager
+# would cross on the user's behalf if this file contained artwork.
+name: azure
+license: "Microsoft Azure architecture icons — permitted in architecture diagrams, redistribution not permitted; see the source URL"
+source: https://learn.microsoft.com/en-us/azure/architecture/icons/
+instructions:
+  - "Azure architecture icons are not auto-installable: Microsoft permits them in diagrams but not as a redistributed icon set."
+  - "1. Download the icon package from https://learn.microsoft.com/en-us/azure/architecture/icons/ and accept the terms there."
+  - "2. Unzip it anywhere you like."
+  - "3. Run: chalkbridge icons install azure --from <path-to-the-unzipped-folder>"
+  - "Or call chalk_install_pack again with `from` set to that path once the user has downloaded it."
+tagRules:
+  # icons/compute/10021-icon-service-Function-Apps.svg → name "function-apps"
+  fromPathSegments: true
+  strip:
+    - "icon-service-"
+    - "-icon-service-"
+    - "Azure-"
+    - "_Light"
+    - "_Dark"
+synonyms:
+  function-apps: [serverless, function, faas, lambda, worker]
+  service-bus: [queue, messaging, broker, topic, async]
+  event-grid: [events, bus, routing, pubsub, trigger]
+  event-hubs: [stream, streaming, ingest, kafka]
+  storage-accounts: [bucket, blob, object, storage, archive]
+  sql-database: [database, sql, relational, store]
+  cosmos-db: [database, nosql, document, global, store]
+  cache-for-redis: [cache, redis, memory, hot]
+  virtual-machine: [server, vm, instance, compute, host]
+  kubernetes-services: [kubernetes, aks, container, cluster, orchestration]
+  container-instances: [container, docker, compute]
+  app-services: [webapp, server, host, backend]
+  front-door: [cdn, edge, "load-balancer", routing, waf]
+  application-gateway: [lb, "load-balancer", proxy, ingress, waf]
+  dns-zones: [dns, routing, domain, resolver]
+  api-management: [api, gateway, endpoint, rest, throttling]
+  active-directory: [auth, identity, login, sso, entra]
+  key-vault: [key, secret, credential, encryption, vault]
+  monitor: [metrics, monitoring, logs, observability, alerts]
+  logic-apps: [workflow, orchestration, integration, automation]
+  data-factory: [etl, pipeline, transform, ingest]
+  synapse-analytics: [warehouse, analytics, olap, database]
+  machine-learning: [ml, model, training, inference, ai]
+  openai: [ai, llm, model, inference, genai]

package/packs/recipes/devicon.yml

@@ -0,0 +1,54 @@
+# Devicon — MIT, and therefore fully automatic (DISTRIBUTION.md §2.1).
+#
+# `npmPackage` names the upstream project's own package rather than an
+# `@chalkbridge/pack-devicon` republish. Devicon already ships its SVGs to npm under a
+# permissive licence; forking that to put our scope on it would be a copy to keep in
+# step for no benefit to anyone.
+name: devicon
+kind: npm
+license: MIT
+source: https://github.com/devicons/devicon
+npmPackage: devicon
+svgDir: icons
+# Devicon ships up to five renderings of every technology — original, plain, line,
+# wordmark, and the -colored variants of each. Without this filter they all normalise to
+# one name, four are skipped as duplicates, and *which* one survives depends on the order
+# readdir happened to return. The original mark is the one people mean.
+include:
+  - "-original.svg"
+tagRules:
+  # icons/postgresql/postgresql-original.svg → name "postgresql", tag "postgresql"
+  fromPathSegments: true
+  strip:
+    - "-original"
+    - "-plain"
+    - "-line"
+    - "-wordmark"
+    - "-colored"
+synonyms:
+  postgresql: [database, sql, postgres, relational, store]
+  mysql: [database, sql, relational, store]
+  sqlite: [database, sql, embedded, file]
+  mongodb: [database, nosql, document, store]
+  redis: [cache, memory, keyvalue, queue]
+  kafka: [queue, stream, broker, messaging, events]
+  rabbitmq: [queue, broker, messaging, amqp]
+  elasticsearch: [search, index, query, logs]
+  docker: [container, image, runtime, build]
+  kubernetes: [container, cluster, orchestration, k8s]
+  nginx: ["load-balancer", proxy, ingress, webserver]
+  terraform: [infrastructure, iac, provisioning]
+  github: [repo, ci, source, vcs]
+  gitlab: [repo, ci, source, vcs]
+  jenkins: [ci, build, pipeline]
+  grafana: [metrics, dashboard, observability, monitoring]
+  prometheus: [metrics, monitoring, alerting, timeseries]
+  react: [frontend, ui, spa, client]
+  nodejs: [backend, server, javascript, runtime]
+  python: [backend, script, service]
+  go: [backend, service, golang]
+  rust: [backend, service, systems]
+  typescript: [frontend, backend, language]
+  amazonwebservices: [aws, cloud, provider]
+  googlecloud: [gcp, cloud, provider]
+  azure: [cloud, provider, microsoft]