chalkbridge 1.0.0

package/dist/pt-BR-5N22H2LF-IOFFSIBR.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/pt-BR-5N22H2LF.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var pt_BR_5N22H2LF_default = stub;
+
+export { pt_BR_5N22H2LF_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=pt-BR-5N22H2LF-IOFFSIBR.js.map
+//# sourceMappingURL=pt-BR-5N22H2LF-IOFFSIBR.js.map

package/dist/pt-PT-UZXXM6DQ-Z3JYHPJA.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/pt-PT-UZXXM6DQ.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var pt_PT_UZXXM6DQ_default = stub;
+
+export { pt_PT_UZXXM6DQ_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=pt-PT-UZXXM6DQ-Z3JYHPJA.js.map
+//# sourceMappingURL=pt-PT-UZXXM6DQ-Z3JYHPJA.js.map

package/dist/ro-RO-JPDTUUEW-TNJOBCBY.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/ro-RO-JPDTUUEW.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var ro_RO_JPDTUUEW_default = stub;
+
+export { ro_RO_JPDTUUEW_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=ro-RO-JPDTUUEW-TNJOBCBY.js.map
+//# sourceMappingURL=ro-RO-JPDTUUEW-TNJOBCBY.js.map

package/dist/ru-RU-B4JR7IUQ-LQHFF6I5.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/ru-RU-B4JR7IUQ.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var ru_RU_B4JR7IUQ_default = stub;
+
+export { ru_RU_B4JR7IUQ_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=ru-RU-B4JR7IUQ-LQHFF6I5.js.map
+//# sourceMappingURL=ru-RU-B4JR7IUQ-LQHFF6I5.js.map

package/dist/si-LK-N5RQ5JYF-7AJ6QJ6S.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/si-LK-N5RQ5JYF.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var si_LK_N5RQ5JYF_default = stub;
+
+export { si_LK_N5RQ5JYF_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=si-LK-N5RQ5JYF-7AJ6QJ6S.js.map
+//# sourceMappingURL=si-LK-N5RQ5JYF-7AJ6QJ6S.js.map

package/dist/sk-SK-C5VTKIMK-UOMPMDMS.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/sk-SK-C5VTKIMK.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var sk_SK_C5VTKIMK_default = stub;
+
+export { sk_SK_C5VTKIMK_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=sk-SK-C5VTKIMK-UOMPMDMS.js.map
+//# sourceMappingURL=sk-SK-C5VTKIMK-UOMPMDMS.js.map

package/dist/sl-SI-NN7IZMDC-GCLRUNU3.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/sl-SI-NN7IZMDC.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var sl_SI_NN7IZMDC_default = stub;
+
+export { sl_SI_NN7IZMDC_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=sl-SI-NN7IZMDC-GCLRUNU3.js.map
+//# sourceMappingURL=sl-SI-NN7IZMDC-GCLRUNU3.js.map

package/dist/subset-shared.chunk-RYC3QF4F.js

@@ -0,0 +1,5 @@
+export { CB as Commands, QB as subsetToBase64, NQ as subsetToBinary, AI as toBase64 } from './chunk-OSMXI5VA.js';
+import './chunk-QGOK75XS.js';
+import './chunk-7D4SUZUM.js';
+//# sourceMappingURL=subset-shared.chunk-RYC3QF4F.js.map
+//# sourceMappingURL=subset-shared.chunk-RYC3QF4F.js.map

package/dist/subset-worker.chunk-TIUZJQSN.js

@@ -0,0 +1,18 @@
+import { CB, NQ } from './chunk-OSMXI5VA.js';
+import './chunk-QGOK75XS.js';
+import './chunk-7D4SUZUM.js';
+
+// ../../node_modules/.pnpm/@excalidraw+excalidraw@0.18_05239941d63f104d3afcb44149fd3ea5/node_modules/@excalidraw/excalidraw/dist/prod/subset-worker.chunk.js
+var s = import.meta.url ? new URL(import.meta.url) : void 0;
+typeof window > "u" && typeof self < "u" && (self.onmessage = async (e) => {
+  switch (e.data.command) {
+    case CB.Subset:
+      let a = await NQ(e.data.arrayBuffer, e.data.codePoints);
+      self.postMessage(a, { transfer: [a] });
+      break;
+  }
+});
+
+export { s as WorkerUrl };
+//# sourceMappingURL=subset-worker.chunk-TIUZJQSN.js.map
+//# sourceMappingURL=subset-worker.chunk-TIUZJQSN.js.map

package/dist/sv-SE-XGPEYMSR-3B5GU363.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/sv-SE-XGPEYMSR.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var sv_SE_XGPEYMSR_default = stub;
+
+export { sv_SE_XGPEYMSR_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=sv-SE-XGPEYMSR-3B5GU363.js.map
+//# sourceMappingURL=sv-SE-XGPEYMSR-3B5GU363.js.map

package/dist/ta-IN-2NMHFXQM-53HPRXR6.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/ta-IN-2NMHFXQM.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var ta_IN_2NMHFXQM_default = stub;
+
+export { ta_IN_2NMHFXQM_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=ta-IN-2NMHFXQM-53HPRXR6.js.map
+//# sourceMappingURL=ta-IN-2NMHFXQM-53HPRXR6.js.map

package/dist/th-TH-HPSO5L25-QHD7HILB.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/th-TH-HPSO5L25.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var th_TH_HPSO5L25_default = stub;
+
+export { th_TH_HPSO5L25_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=th-TH-HPSO5L25-QHD7HILB.js.map
+//# sourceMappingURL=th-TH-HPSO5L25-QHD7HILB.js.map

package/dist/tr-TR-DEFEU3FU-Q22C3NWC.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/tr-TR-DEFEU3FU.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var tr_TR_DEFEU3FU_default = stub;
+
+export { tr_TR_DEFEU3FU_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=tr-TR-DEFEU3FU-Q22C3NWC.js.map
+//# sourceMappingURL=tr-TR-DEFEU3FU-Q22C3NWC.js.map

package/dist/uk-UA-QMV73CPH-LREVZK2B.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/uk-UA-QMV73CPH.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var uk_UA_QMV73CPH_default = stub;
+
+export { uk_UA_QMV73CPH_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=uk-UA-QMV73CPH-LREVZK2B.js.map
+//# sourceMappingURL=uk-UA-QMV73CPH-LREVZK2B.js.map

package/dist/vi-VN-M7AON7JQ-2CB5FIZH.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/vi-VN-M7AON7JQ.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var vi_VN_M7AON7JQ_default = stub;
+
+export { vi_VN_M7AON7JQ_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=vi-VN-M7AON7JQ-2CB5FIZH.js.map
+//# sourceMappingURL=vi-VN-M7AON7JQ-2CB5FIZH.js.map

package/dist/zh-CN-LNUGB5OW-A3VGS2O7.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/zh-CN-LNUGB5OW.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var zh_CN_LNUGB5OW_default = stub;
+
+export { zh_CN_LNUGB5OW_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=zh-CN-LNUGB5OW-A3VGS2O7.js.map
+//# sourceMappingURL=zh-CN-LNUGB5OW-A3VGS2O7.js.map

package/dist/zh-HK-E62DVLB3-3PKQ62NI.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/zh-HK-E62DVLB3.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var zh_HK_E62DVLB3_default = stub;
+
+export { zh_HK_E62DVLB3_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=zh-HK-E62DVLB3-3PKQ62NI.js.map
+//# sourceMappingURL=zh-HK-E62DVLB3-3PKQ62NI.js.map

package/dist/zh-TW-RAJ6MFWO-2XI3I7Z6.js

@@ -0,0 +1,20 @@
+import './chunk-7D4SUZUM.js';
+
+// chalkbridge-headless-stub:./locales/zh-TW-RAJ6MFWO.js
+var refuse = () => {
+  throw new Error(
+    "chalkbridge: this module is excluded from the headless bundle \u2014 UI translations are for the canvas, and the bridge renders no interface (packaging/headless-trim.ts)"
+  );
+};
+var stub = new Proxy(function() {
+  refuse();
+}, {
+  get: (_target, key) => key === "then" ? void 0 : stub,
+  apply: refuse,
+  construct: refuse
+});
+var zh_TW_RAJ6MFWO_default = stub;
+
+export { zh_TW_RAJ6MFWO_default as default, stub as loadSceneOrLibraryFromBlob, stub as parseMermaidToExcalidraw };
+//# sourceMappingURL=zh-TW-RAJ6MFWO-2XI3I7Z6.js.map
+//# sourceMappingURL=zh-TW-RAJ6MFWO-2XI3I7Z6.js.map

package/guides/arrows.md

@@ -0,0 +1,85 @@
+# Arrows
+
+**`chalk_connect` is the only way to make one.**
+
+```
+chalk_connect(fromId: "distiller", toId: "pgvector", label: "embeddings")
+```
+
+That binds both ends to the elements. A bound arrow follows its boxes when the
+user drags them — which is the entire point, because the user *will* drag them,
+and an arrow that stays behind turns a correct diagram into a wrong one silently.
+
+Creating an `arrow` element with coordinates gives you a line that happens to
+point at something today. Chalkbridge refuses hand-written `startBinding` and
+`endBinding` for that reason, and the error will point you back here.
+
+## Say what the arrow means
+
+An unlabelled arrow says "these are related", which the reader already assumed
+from the fact that you drew it. Label it with what actually moves or happens:
+
+- **data**: `"embeddings"`, `"raw events"`, `"user profile"`
+- **a call**: `"POST /ingest"`, `"gRPC"`, `"invokes"`
+- **timing**: `"nightly"`, `"on write"`, `"retry ×3"`
+
+Leave it unlabelled only when the diagram states the relationship some other way
+— a pipeline where every arrow is obviously "then".
+
+## Direction
+
+The arrow points the way the *thing* goes, not the way the call goes. A worker
+that polls a queue draws `queue → worker`, even though the worker initiated it:
+readers follow the payload.
+
+When both matter, two arrows, labelled. When neither does, `endArrowhead: null`
+gives you a plain connector.
+
+## Arrowheads
+
+| Ends | Says |
+|---|---|
+| default | one way |
+| `startArrowhead: "arrow"` | both ways, genuinely bidirectional |
+| `endArrowhead: null` | associated, no flow |
+| `"triangle"` | a stronger, structural relationship — inheritance, ownership |
+| `"dot"`, `"circle"` | a terminus: this is where it stops |
+| `crowfoot_one`, `crowfoot_many` | cardinality, if you are drawing data models |
+
+Do not mix crowfoot notation into an architecture diagram. Pick one vocabulary
+per canvas.
+
+## Shape
+
+`arrowType` sets how the line runs:
+
+- `"round"` — the default. Curves; reads well in a hand-drawn diagram.
+- `"sharp"` — straight, with corners. Better for dense, formal diagrams.
+- `"elbow"` — right angles that route around things. Use it for bus-like layouts
+  where many arrows share a corridor, and keep it consistent across the canvas.
+
+## Style
+
+The same conventions as everything else:
+
+- `strokeStyle: "dashed"` — asynchronous, eventual, or planned. Dashed is the
+  most useful arrow modifier you have: sync versus async is the question a reader
+  most often has.
+- `strokeStyle: "dotted"` — a weak or optional relationship.
+- `strokeWidth: 4` — the main path through the diagram.
+
+## Arrows in what you read back
+
+`chalk_describe_scene` reports a bound arrow by its endpoints rather than its
+coordinates — `c1d4 [arrow] a3f9 -> b7c2 "embeddings"` — because an arrow's
+geometry says nothing a reader wants.
+
+`chalk_get_selection` goes further and splits them: edges *inside* the selection
+say what the selected thing is, and edges *crossing the boundary* name what is on
+the other end. When the user selects three boxes and asks "what are these", the
+crossing edges are usually the answer.
+
+An arrow bound at only one end, or at neither, is reported as an ordinary element
+with coordinates. If you see that in a description, something was drawn by hand
+and has come loose — reconnecting it with `chalk_connect` is a real fix, and a
+good thing to offer.

package/guides/elements.md

@@ -0,0 +1,92 @@
+# Elements
+
+What to draw with, and what Chalkbridge does for you so you do not have to.
+
+## Pick the type by what it means
+
+| Type | Use it for |
+|---|---|
+| `rectangle` | services, components, anything that *does* something or *holds* something |
+| `ellipse` | actors and outside systems — a person, a third-party API, "the internet" |
+| `diamond` | a decision or a branch. If nothing forks, do not reach for it |
+| `text` | free-standing notes and section captions, never a box's caption |
+| `arrow` | a relationship. Made with `chalk_connect`, never by hand |
+| `frame` | a named region — a VPC, a service boundary, a phase |
+
+Rectangles carry most diagrams. Reaching for shape variety to make a picture
+interesting makes it harder to read; variety should mean something.
+
+## Labels are not text elements
+
+A labelled box is **one** call:
+
+```json
+{ "type": "rectangle", "x": 120, "y": 140, "role": "storage",
+  "label": "Postgres + pgvector" }
+```
+
+Excalidraw stores that as two elements — the rectangle and a text element bound
+inside it — but that binding is Chalkbridge's job, not yours. Creating a text
+element and positioning it over a box gives you two things the user can drag
+apart, and a diagram that comes unstuck the first time they tidy it up.
+
+`chalk_describe_scene` reports the pair as one row, so what you read back matches
+what you asked for.
+
+Use a `text` element only for something with no box: a caption above a group, a
+note in the margin, a heading. If it is *about* a specific element, use
+`chalk_annotate` instead — it binds the note so the two stay together.
+
+## Size is inferred, and usually should be
+
+Omit `width` and `height` and you get the house size for the role — 180×80 for a
+service box. Set them when the content genuinely needs it: a long label, a frame
+around a region, a box you are deliberately making prominent.
+
+Do not compute sizes to make a layout work. That is `chalk_arrange`'s job — see
+`layout`.
+
+## Ids
+
+Every element has an id. You may supply one on create, and it is worth doing when
+you are about to connect things:
+
+```json
+[{ "type": "rectangle", "id": "ingest-queue", "role": "edge", "label": "SQS" }]
+```
+
+…then `chalk_connect("ingest-queue", "distiller")` reads as the thing it is.
+
+If you do not supply ids, they are generated, and `chalk_describe_scene` shows a
+short four-character form (`a3f9`) beside the full one. The short form is for
+talking to the user. Always pass the **full** id back to a tool.
+
+## What you may not send
+
+Chalkbridge refuses these rather than ignoring them, so a mistake is visible:
+
+- `seed`, `version`, `versionNonce`, `updated`, `isDeleted`, `index` — the server
+  manages them. Sending a `version` does not pin anything; use `expectedVersion`
+  on `chalk_update_elements` for that.
+- `boundElements`, `containerId`, `startBinding`, `endBinding` — bindings are
+  derived. Pass `label` for a caption and use `chalk_connect` for an arrow. Hand-
+  written bindings are the single most common way to produce a scene that opens
+  broken in Excalidraw.
+
+## Who drew what
+
+Every element carries an author. Anything Chalkbridge created is `claude`;
+anything without that marker is `human` — the user drew it.
+
+This matters before you change something. `chalk_describe_scene` reports the
+author on every row, and an element marked `human` is somebody's deliberate work.
+Read it first, and prefer adding to it over rewriting it.
+
+## Frames
+
+A frame is a named region, and elements inside it report its handle (`F1`, `F2`)
+in the description. Use one when a diagram has parts a reader should take in
+separately — an ingestion side and a storage side, a per-environment column.
+
+Frames are for the reader. Do not use one to group elements you merely want to
+move together; that is what `chalk_group` is for.

package/guides/icons.md

@@ -0,0 +1,111 @@
+# Icons
+
+The short version: **most boxes in an architecture diagram should not be icons.**
+
+## When an icon earns its place
+
+An icon is worth using when the reader recognises the *picture* faster than the
+*word*, and only then:
+
+- a third party whose logo is the fastest way to say which one — Stripe, Postgres,
+  Kafka;
+- a repeated actor at the edge of the diagram — the user, a browser, a phone;
+- a thing whose shape is its meaning — a queue, a clock, a padlock.
+
+Everything else reads better as a labelled box with a `role`. A box carries a
+*name* ("Distiller", "nightly reconciler") and an icon carries a *category*, and
+in a system diagram the name is the interesting half. A diagram made entirely of
+vendor logos tells you which products are involved and nothing about what they
+do — it reads as a shopping list.
+
+The house style exists for the same reason: a box with `role: "storage"` and the
+label `orders` says *our* database, and the Postgres elephant says *a* database.
+
+## Finding one
+
+```
+chalk_search_icons({ query: "queue" })
+chalk_search_icons({ query: "postgres", pack: "devicon" })
+```
+
+Names and tags are indexed; descriptions are not. Plain words work best — search
+for what the thing **is**, not what it is called in a particular vendor's
+taxonomy. Every word is matched independently and the results are ranked, so a
+two-word query like `serverless queue` finds both the function and the queue
+rather than nothing.
+
+Results are paginated. `nextOffset` is `null` when you have seen everything.
+
+## When nothing matches
+
+The bundled `generic` pack is deliberately small — about twenty hand-drawn marks
+that cover the shapes an architecture diagram actually repeats. When a search
+comes back empty, the result says what to do, and it is one call:
+
+```
+chalk_install_pack({ pack: "devicon" })       // technology logos, MIT
+chalk_install_pack({ pack: "simple-icons" })  // brand marks, CC0
+```
+
+Packs install **once per machine**, not per project, so the second repo on the
+same laptop pays nothing.
+
+The vendor sets are different, and the difference is legal rather than technical:
+
+```
+chalk_install_pack({ pack: "aws" })
+```
+
+returns *instructions* and downloads nothing. AWS, Azure and Google all permit
+their icons **in** architecture diagrams while restricting redistribution, so
+Chalkbridge ships the recipe — the tag rules, the synonyms, the source URL — and
+asks the user to fetch the archive themselves. Relay the steps; do not offer to
+download it. Once they have unzipped it:
+
+```
+chalk_install_pack({ pack: "aws", from: "/home/you/Downloads/Asset-Package" })
+```
+
+Point `from` at the **unzipped folder**, not at the `.zip`.
+
+## Placing one
+
+```
+chalk_place_icon({ iconId: "generic/queue", x: 400, y: 220, label: "ingest" })
+```
+
+Always give it a `label`. An unlabelled icon says a thing of this kind was here
+and not *which* thing, and the person reading the diagram in three months is
+usually asking which.
+
+`size` is the longest side in px and defaults to the house icon size; the aspect
+ratio comes from the artwork, so a wide glyph is not squashed into a square.
+Place icons roughly and let `chalk_arrange` tidy them, exactly as with boxes.
+
+The icon id is recorded on the element, so `chalk_describe_scene` reports it as
+`[icon:aws/lambda]` rather than `[image]`. That is what lets you reason about an
+icon later without looking at pixels — and it is why placing an image any other
+way is worse than it looks.
+
+## Arrows still bind
+
+An icon is an ordinary element as far as everything else is concerned:
+`chalk_connect` binds to it, `chalk_frame` contains it, `chalk_group` groups it.
+There is no separate icon mode.
+
+## Community libraries
+
+A `.excalidrawlib` from libraries.excalidraw.com is hand-drawn Excalidraw
+elements rather than flat artwork, so it is placed as *elements* — real strokes
+the user can pull apart and edit, which is the reason somebody published it.
+Those are imported from the command line, because they come from a URL a human
+chose:
+
+```
+chalkbridge icons import-lib my-shapes --from https://libraries.excalidraw.com/…
+```
+
+Library items are placed at the size they were drawn; `size` does not apply to
+them. Scaling an Excalidraw element means scaling its font sizes, stroke widths
+and point arrays, and doing that arithmetically produces something the author
+would not recognise.