@itsthecsguy/linework 0.1.4 → 0.2.0

package/dist/layout/layout.js

@@ -156,7 +156,11 @@ function nodeSizes(d, tm, fonts) {
             continue;
         }
         if (shape === 'diamond') {
-            const t = textOf(n, fonts.maxText * 0.7);
+            // A diamond holds little text for its size. Past two lines, wrap wider:
+            // three lines in a wider diamond take less room than four in a tall one.
+            let t = textOf(n, fonts.maxText * 0.7);
+            if (t.lines > 2)
+                t = textOf(n, fonts.maxText);
             const w = snap(Math.max(128, t.width * 1.5 + 40));
             sizes.set(n.id, { w, h: snap(Math.max(72, w * 0.5, t.lines * fonts.line * 2 + 24)) });
             continue;
@@ -274,6 +278,45 @@ async function run(d, dir, sizes, labels, groupMin, groupTop, order, pins = new
         if (call)
             flipped.add(pairs === 'reply' ? e.id : call.id);
     });
+    // The edge that closes a loop (a retry, "new findings, investigate again")
+    // points back at a box that was declared earlier and already appears in an
+    // earlier edge. Lay it out reversed, so the main path keeps running forward
+    // whichever branch ELK happens to walk first.
+    const index = new Map(d.nodes.map((n, i) => [n.id, i]));
+    const firstUse = new Map();
+    d.edges.forEach((e, i) => {
+        for (const id of [e.from, e.to])
+            if (!firstUse.has(id))
+                firstUse.set(id, i);
+    });
+    const back = d.edges
+        .map((e, i) => ({ e, i }))
+        .filter(({ e, i }) => e.from !== e.to && index.get(e.to) < index.get(e.from) && firstUse.get(e.to) < i)
+        // Call-and-reply pairs are handled above.
+        .filter(({ e }) => !d.edges.some((x) => x.from === e.to && x.to === e.from))
+        // Last written first: once the loop's closing edge is cut, an earlier
+        // backward edge inside the same loop is no longer part of a cycle and stays.
+        .reverse()
+        .map(({ e }) => e);
+    const cut = new Set();
+    const reaches = (from, to) => {
+        const seen = new Set([from]);
+        for (const q = [from]; q.length;) {
+            const cur = q.pop();
+            if (cur === to)
+                return true;
+            for (const x of d.edges)
+                if (x.from === cur && !cut.has(x.id) && !seen.has(x.to))
+                    (seen.add(x.to), q.push(x.to));
+        }
+        return false;
+    };
+    for (const e of back) {
+        if (!reaches(e.to, e.from))
+            continue;
+        cut.add(e.id);
+        flipped.add(e.id);
+    }
     root.edges = d.edges.map((e, i) => {
         const src = pinFor(pins, e.from, e.id, 'from') ?? e.from, dst = pinFor(pins, e.to, e.id, 'to') ?? e.to;
         const flip = flipped.has(e.id);

package/dist/lint/check.js

@@ -63,9 +63,25 @@ export function check(cells) {
         if (p?.container && !inside(n.box, p.box, 2))
             findings.push({ level: 'warning', rule: 'outside-group', message: `${name(n)} sticks out of its group ${name(p)}` });
     }
+    // A box drawn inside a group reads as a member of it.
+    const groups = containers.filter((g) => !scaffold(g));
+    for (const n of nodes) {
+        const mine = ancestors(n.id);
+        for (const g of groups)
+            if (!mine.has(g.id) && inter(n.box, g.box) > 0.25 * n.box.w * n.box.h)
+                findings.push({ level: 'warning', rule: 'in-other-group', message: `${name(n)} sits inside ${name(g)} but isn't in that group; move it out, or put it in the group` });
+    }
     for (const e of edges) {
         const pts = e.points;
         const skip = new Set([e.source, e.target, ...ancestors(e.source), ...ancestors(e.target)]);
+        // A line through a group it has no end in looks like it connects to something there.
+        for (const g of groups) {
+            if (skip.has(g.id))
+                continue;
+            const r = shrink(g.box, 6);
+            if (pts.some((p, i) => i < pts.length - 1 && segHitsBox(p, pts[i + 1], r)))
+                findings.push({ level: 'warning', rule: 'edge-through-group', message: `edge ${edgeName(e, byId)} runs through ${name(g)}, which neither end is in` });
+        }
         for (const n of nodes) {
             if (skip.has(n.id))
                 continue;

package/dist/mcp/server.js

@@ -30,7 +30,7 @@ const PKG = (() => {
     }
     throw new Error('linework: bundled skill not found. Reinstall linework.');
 })();
-const TOOL_NAMES = `In this MCP server the CLI commands in the guide are tools: build -> build_diagram, show -> show_diagram, check -> check_diagram, render -> render_diagram, tidy -> tidy_diagram, import -> import_mermaid, icons -> list_icons, edit -> edit_diagram, publish -> publish_diagram. Pass the spec text to build_diagram directly instead of writing a file.\n\n`;
+const TOOL_NAMES = `In this MCP server the CLI commands in the guide are tools: build -> build_diagram, show -> show_diagram, check -> check_diagram, render -> render_diagram, tidy -> tidy_diagram, import -> import_mermaid, icons -> list_icons, edit -> edit_diagram, publish -> publish_diagram. Pass the spec text to build_diagram directly instead of writing a file. There are no set, add or rm tools: for a small change, call show_diagram, edit its output and pass that to build_diagram, which keeps the layout the same way.\n\n`;
 export function createServer(opts) {
     let browser;
     const getBrowser = () => (browser ??= DrawioBrowser.launch({ scale: 2 }));
@@ -66,13 +66,13 @@ export function createServer(opts) {
         description: 'Returns the linework guide: diagram types, the YAML spec format with examples, and the style rules. Read it before your first diagram.',
         inputSchema: z.object({
             topic: z
-                .enum(['overview', 'spec', 'style', 'google-docs'])
+                .enum(['overview', 'spec', 'style', 'google-docs', 'troubleshooting'])
                 .default('overview')
-                .describe('overview: workflow and cheat sheet. spec: the full spec reference. style: what makes a good diagram. google-docs: getting diagrams into Google Docs.'),
+                .describe('overview: workflow and cheat sheet. spec: the full spec reference. style: what makes a good diagram. google-docs: getting diagrams into Google Docs. troubleshooting: what to do when a command fails.'),
         }),
         annotations: { readOnlyHint: true },
     }, async ({ topic }) => {
-        const file = { overview: 'SKILL.md', spec: 'references/spec.md', style: 'references/style-guide.md', 'google-docs': 'references/google-docs.md' }[topic];
+        const file = { overview: 'SKILL.md', spec: 'references/spec.md', style: 'references/style-guide.md', 'google-docs': 'references/google-docs.md', troubleshooting: 'references/troubleshooting.md' }[topic];
         const body = fs.readFileSync(path.join(PKG, 'skills', 'linework', file), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, '');
         return { content: [text(TOOL_NAMES + body)] };
     });

package/dist/patch.js

@@ -0,0 +1,167 @@
+// One-line changes to an existing diagram: set a field, add or remove a box or
+// an edge. Each reads the file's current spec (hand edits included), changes it
+// and builds, so the layout merges the same way a show / edit / build round does.
+import YAML, { isMap, isScalar, isSeq } from 'yaml';
+import { build, show } from './api.js';
+export class PatchError extends Error {
+}
+const TOP = new Set(['title', 'theme', 'direction']);
+const TEXT = new Set(['label', 'tech', 'title']);
+// "from ARROW to" or "from ARROW to: label". ER cardinalities count as arrows too.
+const EDGE = /^(\S+)\s+(\S*(?:->|=>|--|\.\.)\S*|<->)\s+([^\s:]+)(?::\s*(.*))?$/;
+function mapAt(doc, key, create = false) {
+    const m = doc.get(key);
+    if (isMap(m))
+        return m;
+    if (!create)
+        return undefined;
+    const made = doc.createNode({});
+    doc.set(key, made);
+    return made;
+}
+function seqAt(doc, key, create = false) {
+    const s = doc.get(key);
+    if (isSeq(s))
+        return s;
+    if (!create)
+        return undefined;
+    const made = doc.createNode([]);
+    doc.set(key, made);
+    return made;
+}
+const edgeEnds = (item) => {
+    if (isScalar(item) && typeof item.value === 'string') {
+        const m = EDGE.exec(item.value.trim());
+        return m ? { from: m[1], to: m[3] } : undefined;
+    }
+    // Unquoted, "a -> b: label" is a one-pair YAML map whose key is the edge.
+    if (isMap(item) && item.items.length === 1 && isScalar(item.items[0].key) && typeof item.items[0].key.value === 'string') {
+        const m = EDGE.exec(item.items[0].key.value.trim());
+        if (m)
+            return { from: m[1], to: m[3] };
+    }
+    if (isMap(item) && item.has('from') && item.has('to'))
+        return { from: String(item.get('from')), to: String(item.get('to')) };
+    return undefined;
+};
+/** Apply the ops to a spec's YAML text and return the new text. */
+export function patchSpec(yaml, ops) {
+    const doc = YAML.parseDocument(yaml);
+    const sequence = doc.get('type') === 'sequence';
+    const nodesKey = sequence ? 'participants' : 'nodes';
+    const edgesKey = sequence ? 'messages' : 'edges';
+    const has = (key, id) => !!mapAt(doc, key)?.has(id);
+    const known = () => [...(mapAt(doc, nodesKey)?.items ?? []), ...(mapAt(doc, 'groups')?.items ?? [])].map((p) => String(isScalar(p.key) ? p.key.value : p.key)).join(', ');
+    for (const { op, args } of ops) {
+        if (!args.length)
+            throw new PatchError(`${op} needs at least one argument`);
+        for (const arg of args) {
+            if (op === 'set') {
+                const eq = arg.indexOf('=');
+                if (eq < 1)
+                    throw new PatchError(`can't read "${arg}". Write it as id.field=value, for example api.label="Checkout API", or theme=dark.`);
+                const path = arg.slice(0, eq), raw = arg.slice(eq + 1);
+                const dot = path.lastIndexOf('.');
+                const field = dot < 0 ? path : path.slice(dot + 1);
+                const value = TEXT.has(field) ? raw : YAML.parse(raw);
+                if (dot < 0) {
+                    if (!TOP.has(path))
+                        throw new PatchError(`"${path}" isn't a diagram setting. Settings: title, theme, direction. For a box, write id.field=value.`);
+                    if (raw === '')
+                        doc.delete(path);
+                    else
+                        doc.set(path, value);
+                    continue;
+                }
+                const id = path.slice(0, dot);
+                const key = has(nodesKey, id) ? nodesKey : has('groups', id) ? 'groups' : undefined;
+                if (!key)
+                    throw new PatchError(`no box or group named "${id}". There are: ${known()}`);
+                const owner = mapAt(doc, key);
+                const found = owner.get(id, true);
+                let entry;
+                if (isMap(found))
+                    entry = found;
+                else {
+                    // "id: Label" and "id:" are short for a map.
+                    const label = isScalar(found) && found.value != null ? { label: found.value } : {};
+                    entry = doc.createNode(label, { flow: true });
+                    owner.set(id, entry);
+                }
+                if (raw === '')
+                    entry.delete(field);
+                else
+                    entry.set(field, value);
+            }
+            else if (op === 'add') {
+                const text = arg.trim();
+                if (EDGE.test(text)) {
+                    seqAt(doc, edgesKey, true).add(doc.createNode(text));
+                    continue;
+                }
+                const group = /^group\s+/.test(text);
+                const parsed = YAML.parse(group ? text.replace(/^group\s+/, '') : text);
+                const entries = typeof parsed === 'string' ? [[parsed, {}]] : parsed && typeof parsed === 'object' ? Object.entries(parsed) : [];
+                if (!entries.length)
+                    throw new PatchError(`can't read "${arg}". A box: "fraud: { label: Fraud check, in: vpc }". An edge: "api -> fraud: score". A group: "group vpc: { label: Production VPC }".`);
+                const key = group ? 'groups' : nodesKey;
+                for (const [id, v] of entries) {
+                    if (has(nodesKey, id) || has('groups', id))
+                        throw new PatchError(`"${id}" already exists. Use set to change it.`);
+                    const val = typeof v === 'string' ? { label: v } : (v ?? {});
+                    mapAt(doc, key, true).set(id, doc.createNode(val, { flow: true }));
+                }
+            }
+            else {
+                const text = arg.trim();
+                const m = EDGE.exec(text);
+                if (m) {
+                    const list = seqAt(doc, edgesKey);
+                    const i = list?.items.findIndex((it) => {
+                        const e = edgeEnds(it);
+                        return e && e.from === m[1] && e.to === m[3];
+                    });
+                    if (!list || i === undefined || i < 0)
+                        throw new PatchError(`no edge from "${m[1]}" to "${m[3]}"`);
+                    list.delete(i);
+                    continue;
+                }
+                if (has(nodesKey, text)) {
+                    mapAt(doc, nodesKey).delete(text);
+                    const list = seqAt(doc, edgesKey);
+                    if (list)
+                        for (let i = list.items.length - 1; i >= 0; i--) {
+                            const e = edgeEnds(list.items[i]);
+                            if (e && (e.from === text || e.to === text))
+                                list.delete(i);
+                        }
+                }
+                else if (has('groups', text)) {
+                    // Its members move up to the group it was in, or out to the top level.
+                    const groups = mapAt(doc, 'groups');
+                    const self = groups.get(text);
+                    const up = isMap(self) ? self.get('in') : undefined;
+                    groups.delete(text);
+                    for (const k of [nodesKey, 'groups'])
+                        for (const p of mapAt(doc, k)?.items ?? [])
+                            if (isMap(p.value) && p.value.get('in') === text) {
+                                if (up)
+                                    p.value.set('in', up);
+                                else
+                                    p.value.delete('in');
+                            }
+                    if (!groups.items.length)
+                        doc.delete('groups');
+                }
+                else
+                    throw new PatchError(`no box, group or edge matches "${arg}". There are: ${known()}`);
+            }
+        }
+    }
+    return doc.toString({ lineWidth: 0 });
+}
+/** Change a diagram file in place. The existing layout is kept. */
+export async function patchFile(file, ops, opts = {}) {
+    const yaml = patchSpec(show(file).yaml, ops);
+    return build(yaml, { ...opts, out: file });
+}

package/dist/report.js

@@ -8,6 +8,8 @@ export function buildLines(res, png) {
             parts.push(`placed ${m.placed.join(', ')}`);
         if (m.grown.length)
             parts.push(`grew ${m.grown.join(', ')}`);
+        if (m.shrunk.length)
+            parts.push(`closed up ${m.shrunk.join(', ')}`);
         if (m.removed.length)
             parts.push(`removed ${m.removed.join(', ')}`);
         if (m.rerouted)

package/dist/spec/parse.js

@@ -243,6 +243,8 @@ export function parseSpec(raw) {
             const out = edges.filter((e) => e.from === n.id);
             if (out.some((e) => !e.label))
                 warnings.push({ path: `nodes.${n.id}`, message: 'label every edge leaving a decision, e.g. "yes"/"no"' });
+            if (n.label.length > 40)
+                warnings.push({ path: `nodes.${n.id}`, message: `a diamond holds little text; shorten "${n.label.slice(0, 24)}..." to a short question and put the detail in the step before it` });
         }
     }
     highlightWarning(real, edges, warnings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsthecsguy/linework",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Software diagrams an AI can write and a person can edit. YAML spec in, .drawio.svg out, editable in draw.io.",
   "keywords": [
     "diagram",

package/skills/linework/SKILL.md

@@ -6,49 +6,49 @@ compatibility: Needs Node 20+, a Chromium-based browser (Chrome, Edge, or Playwr
 
 # Linework
 
-You describe the diagram as a small YAML spec. Linework does the layout, styling and rendering, and writes a `.drawio.svg`. That's a normal SVG for docs, with the editable draw.io model embedded inside it. Never write coordinates, SVG or draw.io XML yourself.
+You describe the diagram as a small YAML spec. Linework does the layout, styling and rendering, and writes a `.drawio.svg`: a normal SVG for docs with the editable draw.io model inside it. Never write coordinates, SVG or draw.io XML yourself, and don't fall back to Mermaid, PlantUML or ASCII art unless the user asks for one.
 
-Use Linework instead of Mermaid, PlantUML or ASCII art. Write Mermaid only if the user asks for it, or if the doc lives somewhere that renders Mermaid and can't show images.
+`linework` below means `npx -y @itsthecsguy/linework` (plain `linework` if it's on the PATH). Keep specs and preview PNGs in your temp directory, not in the repo. If a command fails to download, find a browser or accept an option this guide names, read `references/troubleshooting.md`.
 
-## Running it
+## New diagram
 
-In this guide, `linework` means `npx -y @itsthecsguy/linework`. Run plain `linework` only if `command -v linework` (or `where linework` on Windows) finds it. `/tmp` stands for your temp directory (`%TEMP%` on Windows). Keep specs and preview PNGs there, not in the repo.
+1. **Look for existing diagrams.** Search for `*.drawio.svg`. If one already shows what you need, change it (next section). Save new ones where the others live, else `docs/diagrams/`.
+2. **Pick the type.** One diagram makes one point.
+   - `architecture`: components and how they talk.
+   - `flow`: a process with steps and decisions.
+   - `state`: the lifecycle of one thing.
+   - `sequence`: who calls whom, in order, for one scenario.
+   - `er`: tables, columns and relationships.
+3. **Write the spec**, starting from the closest file in `examples/` next to this guide: `checkout.yaml` and `platform.yaml` (architecture), `serverless-aws.yaml` and `gcp-ingest.yaml` (cloud icons), `refund-flow.yaml` and `deploy-flow.yaml` (flow), `payment-state.yaml` and `job-state.yaml` (state), `pay-sequence.yaml` and `auth-seq.yaml` (sequence), `billing-er.yaml` and `shop-er.yaml` (ER). A Mermaid block converts directly: `linework import doc.md --block 1 -o out.drawio.svg`.
+4. **Build:** `linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png`
+5. **Read the output.** `spec error` lines say exactly what to fix. `check:` lists layout problems. Fix every error and the warnings that matter, then rebuild. Look at the PNG if you can view images.
+6. **Embed the `.drawio.svg`**, never the PNG: `![Checkout API charges cards through Stripe and writes orders to Postgres](diagrams/checkout.drawio.svg)`. Write alt text that says what the diagram shows in one sentence.
+7. **Tell the user** where the file is and that they can edit it by hand in draw.io (`linework edit <file>` opens it in their browser).
 
-If a command fails:
-- **The download fails** (`ENOTFOUND`, `EAI_AGAIN`, `ETIMEDOUT`, `403`): you probably have no network, often because of a sandbox. Ask the user to let the command run with network access, or to run `npm install -g @itsthecsguy/linework` themselves.
-- **"none was found":** no browser is installed. Run `linework install-browser`, or ask the user to install Chrome.
-- **"found a Chromium-based browser but it could not start":** a sandbox is blocking it. Ask the user to run `npx -y @itsthecsguy/linework install-browser` once outside the sandbox (Linework's own Chromium starts inside Codex's sandbox), or to let the command run outside the sandbox. Don't tell them to install Chrome; they already have a browser.
-- **An option or field is rejected that this guide says exists:** this guide may be newer or older than the installed package. Run `linework skill` to get the path of the guide that ships with the package, and read its SKILL.md. That copy always matches.
+## Changing a diagram
 
-Never fall back to writing SVG or draw.io XML by hand. Tell the user what failed and what they can do about it.
+The `.drawio.svg` is the source of truth. Every command below keeps what is already there in place, including boxes someone moved by hand in draw.io. Only what you change moves.
 
-## Workflow
+For one or two changes, edit the file directly:
 
-1. **Look for existing diagrams first.** Search the repo for `*.drawio.svg`. If one already shows what you need, change it (see "Editing an existing diagram") instead of drawing a new one. Save new diagrams where the existing ones live. With none yet, use `docs/diagrams/`, or the folder of the doc you're editing if the repo has no `docs/`.
-2. **Decide what the diagram is for.** One diagram makes one point. Pick the type:
-   - `architecture`: components and how they talk. Services, data stores, queues, external systems, trust boundaries.
-   - `flow`: a process with steps and decisions.
-   - `state`: the lifecycle of one thing, like an order, payment or job.
-   - `sequence`: who calls whom, in what order, for one scenario.
-   - `er`: database tables, their columns and how they relate.
-
-   If the doc already has a Mermaid diagram, convert it instead of rewriting it: `linework import doc.md --block 1 -o docs/diagrams/x.drawio.svg`.
-3. **Write the spec** to `/tmp/spec.yaml`, or pipe it on stdin with `-` as the file. Start from the closest file in `examples/` next to this guide:
-   - architecture: `checkout.yaml` (small), `platform.yaml` (clients, nested groups, 17 nodes), `serverless-aws.yaml` (AWS icons), `gcp-ingest.yaml` (GCP icons)
-   - flow: `refund-flow.yaml` (branches), `deploy-flow.yaml` (a retry loop back to an earlier step)
-   - state: `payment-state.yaml`, `job-state.yaml` (pause/resume pairs and a self-transition)
-   - sequence: `pay-sequence.yaml` (alt, note), `auth-seq.yaml` (loop with a nested opt)
-   - ER: `billing-er.yaml` (small), `shop-er.yaml` (7 tables, composite keys)
-
-   The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
-4. **Build with a preview:**
-   ```bash
-   linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png
-   ```
-5. **Read the output.** `spec error` lines tell you exactly what to fix. `check:` lists layout problems. Fix every `error` and the warnings that matter, then rebuild.
-6. **Look at the PNG** if you can view images. Check that the diagram tells the story you meant, flows in a sensible direction and doesn't sprawl. If `check` says `too-wide`, remove `direction` (or set `TB`) or split it. If you can't view images, rely on `check` and keep the diagram small.
-7. **Embed the `.drawio.svg`**, never the PNG (see "Putting it in a doc").
-8. **Tell the user** where the file is, what it shows, and that they can edit it by hand in draw.io.
+```bash
+linework set d.drawio.svg api.label="Checkout API v2" api.highlight=true   # id.field=value; empty value clears; also theme= title= direction=
+linework add d.drawio.svg "fraud: { label: Fraud check, in: vpc }" "api -> fraud: score"
+linework rm  d.drawio.svg cache "api -> stripe"                              # a box goes with its edges
+```
+
+For a larger change, round-trip the spec. Always start from the file, never from an old copy of the spec:
+
+```bash
+linework show d.drawio.svg > /tmp/spec.yaml    # current spec, hand edits included
+# edit it; keep the "# linework-base:" line at the top
+linework build /tmp/spec.yaml -o d.drawio.svg --png /tmp/d.png
+```
+
+- The `merged into the existing layout:` line says what was kept, placed, grown and rerouted. Pass it on to the user.
+- If the user moved boxes by hand and left lines or labels in odd places, `linework tidy d.drawio.svg` reroutes those edges and re-places those labels. Boxes stay put.
+- `--relayout` throws the layout away and starts over. Use it only if the user asks: it undoes their work.
+- When the user says they finished editing in draw.io, run `show` and carry on from its output.
 
 ## Spec
 
@@ -57,184 +57,41 @@ type: architecture            # architecture | flow | state | sequence | er
 title: Checkout               # optional
 direction: auto               # auto (default) | TB | LR | BT | RL
 theme: clean                  # clean (default) | soft | dark | sketch | blueprint | c4
-groups:                       # optional boxes around nodes; can nest with `in`
+groups:                       # optional boxes around nodes; nest with `in`
   vpc: { label: Production VPC }
-  data: { label: Data tier, in: vpc }
-nodes:                        # id: { label, kind, tech, in }  (all optional)
-  user:   { label: Shopper, kind: person }
+nodes:                        # id: { label, kind, tech, in }, all optional
   web:    { label: Web app, kind: client, tech: Next.js }
   api:    { label: Checkout API, tech: Go, in: vpc, highlight: true }
   queue:  { label: order-events, kind: queue, tech: Kafka, in: vpc }
-  db:     { label: Orders, kind: database, tech: Postgres, in: data }
-  stripe: { kind: external, tech: Payments API }   # label defaults to "Stripe"
+  db:     { label: Orders, kind: database, tech: Postgres, in: vpc }
+  stripe: { kind: external }   # label defaults to "Stripe"
 edges:                        # "from ARROW to: label"
-  - user -> web
-  - web ==> api: HTTPS          # ==> highlighted: the path the doc is about
+  - web ==> api: HTTPS         # ==> highlighted: the path the doc is about
   - api -> db: SQL
-  - api -.-> queue: OrderPlaced  # -.-> async/event, dashed
+  - api -.-> queue: OrderPlaced # -.-> async or event, dashed
   - api -> stripe: charge
 ```
 
-- Ids use letters, digits, `_`, `.` and `-`. The label defaults to the id with its first letter capitalized.
-- Arrows: `->` call or flow, `==>` the same but highlighted, `-.->` async or event, `<->` two-way, `--` no arrowhead. Put spaces around the arrow.
-- `tech` is the small, quieter second line. Use it for the technology, not a description.
-- Node order matters a little. Layout tries to keep the declaration order, so list nodes roughly in reading order.
-- Quote an edge if its label contains `: ` or `#`, for example `- "api -> db: SELECT: orders"`.
-- Architecture nodes can carry a cloud icon: `icon: aws.lambda`, `gcp.cloud_run`, `k8s.pod`, `azure.<name>`. Run `linework icons aws lambda` to search names. Use icons when the doc is about a specific cloud; leave them off for logical diagrams.
-- Styles (`theme:`): use `clean` unless asked. It's minimal: white boxes, hairline borders, groups as gray grounds, IBM Plex Sans, and color only where it means something.
-  - `soft`: borderless pastel cards, tinted by kind. For slides and docs that want color coding.
-  - `dark`: for dark-mode docs and slides.
-  - `sketch`: hand-drawn lines and handwriting. For early proposals ("this is a draft") and whiteboard-style explainers.
-  - `blueprint`: blue ink on pale drafting paper, monospace. For technical deep dives that want a distinct look.
-  - `c4`: C4-model conventions; labels each box with its element type.
-- Color is for meaning, so most nodes stay neutral:
-  - `highlight: true` on a node, group or participant, or `==>` on an edge or message, makes it the first thing a reader sees. Highlight the one path or component the surrounding text is about: often one node and the 2 or 3 edges into and out of it. `build` warns when you highlight so much that nothing stands out.
-  - `color: <name>` tints a node, group or edge to mark a category, like red for failure paths or green for what's new in this proposal. Say what the color means in the doc text. Names: `blue`, `violet`, `pink`, `red`, `orange`, `amber`, `green`, `teal`, `gray`.
-  - Kinds `error` and `success` are red and green in every style.
-  - An edge with a color uses the object form: `- { from: api, to: dlq, label: on failure, style: async, color: red }`.
-
-Node kinds, also listed by `linework kinds`:
+- Arrows: `->` call or flow, `==>` highlighted, `-.->` async, `<->` two-way, `--` no arrowhead. Spaces around the arrow. Quote an edge whose label contains `: ` or `#`.
+- List nodes and edges in reading order. Layout follows it, and an edge that points back at an earlier node is drawn as the loop.
+- `tech` is the quiet second line: the technology, not a description.
+- Color is for meaning. `highlight: true` or `==>` marks the one path the text is about. `color: red|green|blue|...` marks a category; say what it means in the doc.
+- Cloud icons on architecture nodes: `icon: aws.lambda`, `gcp.cloud_run`, `k8s.pod`, `azure.<name>`. Search with `linework icons aws lambda`.
 
 | type | kinds (default first) |
 |---|---|
 | architecture | `service`, `person`, `client`, `function`, `database`, `cache`, `storage`, `queue`, `external` |
 | flow | `step`, `decision`, `terminal`, `data`, `error` |
-| state | `state`, `success`, `error` (start and end come from `[*]`) |
-| sequence | `service`, `person`, `client`, `function`, `database`, `queue`, `external` |
-| er | `entity`, `view`, `external` |
+| state | `state`, `success`, `error`; start and end are `"[*] -> first"` and `"last -> [*]"`, quoted |
+| sequence | `participants:` and `messages:` instead of nodes and edges; `-->` is a reply |
+| er | `fields:` on nodes (`- id: uuid pk`), crow's-foot edges (`users }o--|| orgs: belongs to`) |
 
-Flow and state specifics:
+In a flow, keep decision text to a short question and label every edge leaving it (`window -> refund: "yes"`).
 
-```yaml
-type: flow
-nodes:
-  start:  { label: Refund requested, kind: terminal }
-  window: { label: Within 30 days?, kind: decision }
-  refund: { label: Issue refund }
-  deny:   { label: Deny with reason, kind: error }
-edges:
-  - start -> window
-  - window -> refund: "yes"     # label every edge leaving a decision
-  - window -> deny: "no"
-```
+## More
 
-```yaml
-type: state
-nodes:
-  pending: {}
-  paid: { kind: success }
-  failed: { kind: error }
-edges:
-  - "[*] -> pending"            # quote edges that use [*]
-  - pending -> paid: payment_succeeded
-  - pending -> failed: declined
-  - "paid -> [*]"
-```
-
-Sequence diagrams use `participants` (in left-to-right order) and `messages`:
-
-```yaml
-type: sequence
-participants:
-  web:    { label: Web app, kind: client }
-  api:    { label: Checkout API }
-  stripe: { kind: external }
-messages:
-  - web ==> api: POST /checkout       # -> call; ==> highlighted call
-  - api -> stripe: create PaymentIntent
-  - stripe --> api: client_secret     # --> reply (dashed)
-  - api --> web: 200 OK
-  - note over api, stripe: retried with an idempotency key
-  - alt:                              # alt and par take branches
-      - when: payment succeeded
-        do:
-          - stripe -.-> api: webhook  # -.-> async
-      - when: declined
-        do:
-          - api --> web: 402
-  - loop: every 30s                   # loop, opt, critical, break take one block
-    do:
-      - web -> api: poll status
-```
-
-Activation bars come from call/reply pairs automatically: each `a -> b` closed by a later `b --> a`. Participants take `color` and `highlight` like nodes.
-
-ER diagrams put `fields` on nodes and use Mermaid's crow's-foot notation for edges:
-
-```yaml
-type: er
-nodes:
-  users:
-    fields:
-      - id: uuid pk
-      - org_id: uuid fk
-      - email: text unique
-  orgs:
-    label: organizations
-    fields: [ "id: uuid pk", "name: text" ]
-edges:
-  - users }o--|| orgs: belongs to     # many users to exactly one org
-```
-
-Field flags: `pk`, `fk`, `unique`, `null`. Cardinality ends: `||` one, `|o` zero or one, `}o` / `o{` many, `}|` / `|{` one or many. Use `--` for identifying relationships, `..` for the rest.
-
-Every option and more examples are in `references/spec.md`, and full specs for each type are in `examples/`. Read `references/style-guide.md` before drawing anything non-trivial.
-
-## Editing an existing diagram
-
-Always start from the file, never from an old copy of the spec:
-
-```bash
-linework show docs/diagrams/checkout.drawio.svg > /tmp/spec.yaml   # current spec, hand edits included
-# edit /tmp/spec.yaml; keep the "# linework-base:" line at the top
-linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png
-```
-
-If someone has arranged the diagram by hand in draw.io, `build` merges your changes into their layout instead of starting over. (For sequence diagrams, hand-placed lifeline columns stay; rows always follow message order.)
-- Existing nodes stay exactly where they are.
-- New nodes go next to the node they connect to.
-- Removed nodes disappear.
-- Groups grow to fit new members.
-- Only new edges, and edges whose routes went stale, get rerouted.
-- Their colours, label edits and notes survive.
-
-The `merged into the existing layout:` line tells you what happened. Mention it to the user.
-
-The `# linework-base:` line tells `build` your spec includes the latest hand edits. Without it, `build` won't delete shapes someone added by hand that your spec doesn't mention. It keeps them and prints a note. If you see that note, run `show` again and redo your edit from its output.
-
-`--relayout` throws the hand-made layout away and lays everything out from scratch. **Only use it if the user asks,** because it undoes their layout work.
-
-If someone moved shapes by hand and left edges crossing through boxes, `linework tidy file.drawio.svg` reroutes just the broken edges and changes nothing else.
-
-## Putting it in a doc
-
-- Markdown (GitHub, GitLab, most renderers): `![Checkout API calls Stripe to charge cards and writes orders to Postgres](diagrams/checkout.drawio.svg)`
-- HTML: `<img src="diagrams/checkout.drawio.svg" alt="Checkout API calls Stripe to charge cards and writes orders to Postgres">`
-- Write alt text that says what the diagram shows, in one sentence, not just its title. Someone using a screen reader should get the point from it.
-- If you used `color:` for categories, add a sentence under the diagram saying what each color means.
-- Tell the user they can edit it by hand: open the file in VS Code with the "Draw.io Integration" extension, in draw.io desktop, or at app.diagrams.net. It saves back into the same file, and your later edits will keep their layout.
-- In a git repo, offer to run `linework git-setup` once, so `git diff` on diagrams shows readable spec changes.
-- Google Docs can't hold SVG. `linework publish file.drawio.svg` copies it into the user's Google Drive folder, and draw.io's Google Docs add-on inserts it from there and refreshes it after changes. Setup and the update steps are in `references/google-docs.md`; walk the user through them the first time.
-
-## Letting the user edit
-
-If the user wants to adjust a diagram by hand, `linework edit file.drawio.svg` opens it in draw.io in their browser, served from their machine. Saving there writes the file. When they say they're done, run `show` and carry on from its output; their changes are in it.
-
-## Commands
-
-| command | does |
-|---|---|
-| `build <spec\|-> -o out.drawio.svg [--png p.png] [--relayout]` | layout (or merge into an existing file), write, lint |
-| `show <file> [--geometry]` | print the spec, stamped with `linework-base` |
-| `tidy <file>` | reroute edges that pass through nodes; nothing else changes |
-| `import <file.mmd\|doc.md> [--block N] [-o out.drawio.svg]` | convert Mermaid (flowchart, state, sequence, ER) |
-| `icons <aws\|gcp\|k8s\|azure> [filter]` | list icon names |
-| `edit <file>` | open the diagram in draw.io in the user's browser; saving writes the file |
-| `publish <file...> [--to dir] [--pull]` | copy diagrams into Google Drive for the Docs add-on; `--pull` brings Drive edits back |
-| `git-setup` | make `git diff` show diagram changes as spec changes |
-| `render <file> -o out.png [--scale 2]` | preview image |
-| `check <file>` | lint only; exit 1 on errors |
-| `kinds [type]` | list node kinds |
-| `schema` | JSON Schema of the spec |
-| `skill` | print the path of the guide that matches the installed version |
-| `install-browser` | download the headless Chromium this version uses |
+- `references/spec.md`: every option, sequence blocks (`alt`, `loop`, notes), ER fields and cardinalities, themes, colors.
+- `references/style-guide.md`: what makes a diagram read well. Read it before anything non-trivial.
+- `references/troubleshooting.md`: download, browser and sandbox failures.
+- `references/google-docs.md`: putting a diagram in Google Docs with `linework publish`.
+- `linework help` lists every command, including `check`, `render`, `kinds`, `schema` and `git-setup` (readable `git diff` for diagrams).

package/skills/linework/references/troubleshooting.md

@@ -0,0 +1,11 @@
+# When a command fails
+
+`linework` in the guide means `npx -y @itsthecsguy/linework`. Run plain `linework` only if `command -v linework` (or `where linework` on Windows) finds it.
+
+- **The download fails** (`ENOTFOUND`, `EAI_AGAIN`, `ETIMEDOUT`, `403`): there is probably no network, often because of a sandbox. Ask the user to let the command run with network access, or to run `npm install -g @itsthecsguy/linework` themselves.
+- **"none was found":** no browser is installed. Run `linework install-browser`, or ask the user to install Chrome.
+- **"found a Chromium-based browser but it could not start":** a sandbox is blocking it. Ask the user to run `npx -y @itsthecsguy/linework install-browser` once outside the sandbox (Linework's own Chromium starts inside Codex's sandbox), or to let the command run outside the sandbox. Don't tell them to install Chrome; they already have a browser.
+- **An option or field is rejected that the guide says exists:** the guide may be newer or older than the installed package. Run `linework skill` to get the path of the guide that ships with the package, and read its SKILL.md. That copy always matches.
+- **A build hangs or behaves oddly after an upgrade:** builds reuse a background process that keeps the browser running. `linework daemon stop` ends it, and `LINEWORK_NO_DAEMON=1` or `--no-daemon` runs without it.
+
+Never fall back to writing SVG or draw.io XML by hand. Tell the user what failed and what they can do about it.