@itsthecsguy/linework 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,9 @@
-# Linework
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/logo-dark.svg">
+    <img alt="Linework" src="docs/brand/logo-light.svg" height="64">
+  </picture>
+</h1>
 
 Software diagrams your AI agent writes and you can edit by hand, in Claude Code, Codex, Cursor, Antigravity, Copilot, Grok Build or any other agent.
 
@@ -11,28 +16,69 @@ Your agent writes a short YAML spec. Linework lays it out, styles it and writes
 
 ## Quick start
 
-You need Node 20+ and Chrome, Edge or another Chromium browser. Then give your agent the skill:
+### 1. Check what you need
+
+- **Node 22.20 or newer** for the skills installer in step 2. Linework itself runs on Node 20+. Check with `node -v`.
+- **Chrome, Edge or another Chromium browser.** Linework uses it in the background to measure text and draw. If you have neither, run `npx -y @itsthecsguy/linework install-browser`.
+- **Using Codex?** Its sandbox stops Chrome from starting. Run `npx -y @itsthecsguy/linework install-browser` once, outside Codex. Linework's own headless Chromium does start inside the sandbox.
+
+### 2. Give your agent the skill
 
 ```bash
 npx skills add itsthecsguy/linework
 ```
 
-That's it. The [skills](https://github.com/vercel-labs/skills) installer finds the agents on your machine and puts the skill where each one looks: Claude Code, Codex, Cursor, Antigravity, Gemini CLI, GitHub Copilot, Grok Build, OpenCode, Windsurf and about 70 more. Add `-g` to install it for every project instead of this one.
+The [skills](https://github.com/vercel-labs/skills) installer finds the agents on your machine, asks which ones to set up, and puts the skill where each one looks. It covers Claude Code, Codex, Cursor, Antigravity, Gemini CLI, GitHub Copilot, Grok Build, OpenCode, Windsurf and about 70 more.
+
+It installs for the current project by default. Add `-g` to install it for every project. To skip the prompts, name the agents:
+
+```bash
+npx skills add itsthecsguy/linework -g -a claude-code -a codex -y
+```
+
+### 3. Check that it works
+
+This builds a two-box diagram without an agent:
+
+```bash
+printf 'type: flow\nnodes: { a: Hello, b: World }\nedges:\n  - a -> b\n' | npx -y @itsthecsguy/linework build - -o hello.drawio.svg --png hello.png
+```
+
+It should print `check: 0 errors, 0 warnings` and write `hello.drawio.svg` and `hello.png`. The first run takes a few seconds longer while `npx` downloads the package. If it says no browser was found, run `npx -y @itsthecsguy/linework install-browser` and try again.
+
+### 4. Ask for a diagram
 
-Now ask for a diagram:
+Start a new agent session so it loads the skill, then ask:
 
 > Add an architecture diagram of the checkout flow to docs/design.md.
 
-The agent reads the skill, writes the spec, runs `npx -y @itsthecsguy/linework build`, looks at the PNG preview, fixes what's off and embeds the `.drawio.svg`. There's no separate install step. The first run downloads the package through `npx`.
+The agent writes the spec, runs Linework, looks at the PNG preview, fixes what's off and embeds the `.drawio.svg` in the doc. You don't install anything else. The skill runs Linework through `npx`.
 
-**Agent can't run shell commands?** Use the MCP server instead. See [Connect over MCP](#connect-over-mcp).
+### Optional: install the command
 
-**No skill support at all?** Add this line to your `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`:
+The skill works without this, but a global install skips the `npx` download check on every run and puts `linework` on your PATH:
 
-```markdown
-For diagrams, use Linework: run `npx -y @itsthecsguy/linework skill` to get the guide's path, and read SKILL.md there before your first diagram.
+```bash
+npm install -g @itsthecsguy/linework
 ```
 
+### Updating
+
+```bash
+npx skills update linework
+```
+
+If you installed the command globally, update it with `npm install -g @itsthecsguy/linework@latest`.
+
+### Other setups
+
+- **Agent can't run shell commands?** Use the MCP server. See [Connect over MCP](#connect-over-mcp).
+- **Agent doesn't load skills?** Add this line to your `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`:
+
+  ```markdown
+  For diagrams, use Linework: run `npx -y @itsthecsguy/linework skill` to get the guide's path, and read SKILL.md there before your first diagram.
+  ```
+
 ## How it works
 
 A spec is a few lines of YAML:
@@ -66,14 +112,14 @@ Set `theme:` in the spec.
 | `soft` | slides. Borderless pastel cards, tinted by kind. |
 | `dark` | dark-mode pages |
 | `sketch` | early drafts. Hand-drawn lines and a handwriting font. |
-| `blueprint` | technical deep dives. Light lines on deep blue, monospace. |
-| `c4` | C4-model diagrams |
+| `blueprint` | technical deep dives. Blue ink on pale drafting paper, monospace. |
+| `c4` | C4-model diagrams, in quiet blues and grays |
 
 Color is for meaning. Nodes stay neutral by default, and errors and successes are red and green in every style. Mark the part the doc is about with `highlight: true` on a node or `==>` on an edge, and it's drawn in the style's accent color. Use `color: red` (or blue, violet, pink, orange, amber, green, teal, gray) for categories.
 
 Linework sizes every box from the real width of its text in the font it renders with, wrapping long labels instead of widening boxes. Each SVG carries a subset of that font (about 10 to 15KB), so text fits the same way on GitHub, in a browser or in a doc. `check` flags labels that overflow, overlap a box, another label, another edge or a group border, and `build` moves edge labels until they're clear.
 
-Linework needs Node 20+ and a Chromium-based browser, which it uses headless to measure text and render. It tries Playwright's Chromium, then Chrome, then Edge. If none is found, run `npx playwright install chromium`, or set `LINEWORK_CHROME` to a browser binary.
+Linework needs Node 20+ and a Chromium-based browser, which it uses headless to measure text and render. It tries Playwright's Chromium, then Chrome, then Edge. If none is found, run `linework install-browser`, or set `LINEWORK_CHROME` to a browser binary. If a browser is found but crashes on launch, an agent's sandbox is usually blocking it. Linework then retries Playwright's Chromium in single-process mode, which starts inside Codex's sandbox.
 
 ## Connect over MCP
 
@@ -148,6 +194,7 @@ Docs can't hold an SVG, so the diagram lives in Google Drive and draw.io's Googl
 | `linework mcp [--root dir]` | MCP server over stdio |
 | `linework kinds [type]` | node kinds per diagram type |
 | `linework schema` | JSON Schema of the spec |
+| `linework install-browser` | download the headless Chromium build this version uses |
 
 ## Status
 

package/dist/api.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseSpecText } from './spec/parse.js';
 import { layout } from './layout/layout.js';
-import { patchEdges, serialize, stampEdgeRoutes, toMxfile } from './drawio/write.js';
+import { edgeCellId, patchEdges, serialize, stampEdgeRoutes, toMxfile } from './drawio/write.js';
 import { absBox, fingerprint, readDrawio, specBase } from './drawio/read.js';
 import { manualEdits, toDiagram, toYaml } from './drawio/show.js';
 import { merge } from './drawio/merge.js';
@@ -96,7 +96,7 @@ export async function build(specText, opts) {
             }
         }
         else
-            xml = toMxfile(diagram, l);
+            xml = await straightenDetours(b, toMxfile(diagram, l), detourEdges(diagram, l));
         xml = (await fixLabels(b, xml)).xml;
         xml = stampEdgeRoutes(xml);
         return finish(b, xml, { mode, warnings, direction: mode === 'merge' ? (old.meta.aiviz_direction ?? l.direction) : l.direction, edits, old, stats });
@@ -117,6 +117,43 @@ export async function build(specText, opts) {
         };
     }
 }
+/**
+ * Edges whose route is far longer than the gap between their ends. Layered layout
+ * draws one edge of every cycle backwards, so the reply in a call-and-callback pair
+ * (api -> stripe, stripe -> api) can loop around a whole group.
+ */
+export function detourEdges(d, l) {
+    const out = [];
+    for (const e of d.edges) {
+        const r = l.edges.get(e.id), a = l.nodes.get(e.from), z = l.nodes.get(e.to);
+        if (!r || !a || !z || r.points.length < 2)
+            continue;
+        let len = 0;
+        for (let i = 0; i < r.points.length - 1; i++)
+            len += Math.abs(r.points[i + 1].x - r.points[i].x) + Math.abs(r.points[i + 1].y - r.points[i].y);
+        const gap = Math.max(0, Math.abs(a.x + a.w / 2 - (z.x + z.w / 2)) - (a.w + z.w) / 2) +
+            Math.max(0, Math.abs(a.y + a.h / 2 - (z.y + z.h / 2)) - (a.h + z.h) / 2);
+        if (len > 2 * gap + 240)
+            out.push(edgeCellId(e.id));
+    }
+    return out;
+}
+/**
+ * Reroute detours with libavoid. Keep the new routes when they're much shorter and
+ * cost at most a couple of crossings each: a short hop with a crossing reads better
+ * than a line wrapped around half the diagram.
+ */
+async function straightenDetours(b, xml, ids) {
+    if (!ids.length)
+        return xml;
+    const candidate = await rerouteInto(b, xml, ids);
+    const [before, after] = [await b.inspect(xml), await b.inspect(candidate)];
+    const length = (cells) => cells.filter((c) => ids.includes(c.id)).reduce((sum, c) => sum + (c.points ?? []).reduce((s, p, i, a) => (i ? s + Math.abs(p.x - a[i - 1].x) + Math.abs(p.y - a[i - 1].y) : 0), 0), 0);
+    const [c0, c1] = [check(before), check(after)];
+    const errors = (c) => c.findings.filter((f) => f.level === 'error').length;
+    const keep = errors(c1) <= errors(c0) && c1.stats.crossings <= c0.stats.crossings + 2 * ids.length && length(after) < 0.6 * length(before);
+    return keep ? candidate : xml;
+}
 async function rerouteInto(b, xml, edgeIds) {
     return patchEdges(xml, await b.reroute(xml, edgeIds), edgeIds);
 }

package/dist/cli.js

@@ -48,6 +48,10 @@ Usage:
       List node kinds for each diagram type.
   linework schema
       Print the spec's JSON Schema.
+
+  linework install-browser
+      Download the headless Chromium build that matches this version. Needed only
+      when no Chrome or Edge is installed, or to run inside an agent's sandbox.
 `;
 async function main(argv) {
     const [cmd, ...rest] = argv;
@@ -238,6 +242,15 @@ async function main(argv) {
         case 'schema':
             console.log(JSON.stringify(jsonSchema(), null, 2));
             return;
+        case 'install-browser': {
+            const { browserInstallCommand } = await import('./render/browser.js');
+            const { spawnSync } = await import('node:child_process');
+            const [bin, ...args] = browserInstallCommand();
+            console.log('downloading headless Chromium for linework...');
+            const r = spawnSync(bin, args, { stdio: 'inherit' });
+            process.exitCode = r.status ?? 1;
+            return;
+        }
         default:
             fail(`unknown command "${cmd}"\n\n${USAGE}`);
     }

package/dist/drawio/theme.js

@@ -31,7 +31,8 @@ const LIGHT_SW = {
     pink: { tint: '#FDF2F8', line: '#F9A8D4', ink: '#9D174D', solid: '#DB2777', edge: '#DB2777' },
     red: { tint: '#FEF2F2', line: '#FCA5A5', ink: '#991B1B', solid: '#DC2626', edge: '#DC2626' },
     orange: { tint: '#FFF7ED', line: '#FDBA74', ink: '#9A3412', solid: '#C2410C', edge: '#EA580C' },
-    amber: { tint: '#FFFBEB', line: '#FCD34D', ink: '#92400E', solid: '#B45309', edge: '#D97706' },
+    // Ochre, not orange: the two read as one color at line weight otherwise
+    amber: { tint: '#FFFBEB', line: '#FCD34D', ink: '#92400E', solid: '#B45309', edge: '#A16207' },
     green: { tint: '#F0FDF4', line: '#86EFAC', ink: '#166534', solid: '#15803D', edge: '#16A34A' },
     teal: { tint: '#F0FDFA', line: '#5EEAD4', ink: '#115E59', solid: '#0F766E', edge: '#0D9488' },
     gray: { tint: '#F4F4F5', line: '#D4D4D8', ink: '#3F3F46', solid: '#52525B', edge: '#71717A' },
@@ -59,17 +60,17 @@ const DARK_SW = {
     teal: { tint: '#042F2E', line: '#115E59', ink: '#99F6E4', solid: '#0F766E', edge: '#2DD4BF' },
     gray: { tint: '#27272A', line: '#52525B', ink: '#E4E4E7', solid: '#52525B', edge: '#A1A1AA' },
 };
-// Blueprint: light lines on deep blue. Color only changes the line.
+// Blueprint: a drafting sheet. Blue ink on pale paper; color only changes the line.
 const BP_LINE = {
-    blue: '#93C5FD',
-    violet: '#C4B5FD',
-    pink: '#F9A8D4',
-    red: '#FCA5A5',
-    orange: '#FDBA74',
-    amber: '#FDE68A',
-    green: '#86EFAC',
-    teal: '#5EEAD4',
-    gray: '#CBD5E1',
+    blue: '#1D4ED8',
+    violet: '#6D28D9',
+    pink: '#BE185D',
+    red: '#B91C1C',
+    orange: '#C2410C',
+    amber: '#A16207',
+    green: '#15803D',
+    teal: '#0F766E',
+    gray: '#64748B',
 };
 function lightPaint(sw, neutral, text, muted, accent) {
     return (color, highlight) => {
@@ -167,7 +168,7 @@ const SKETCH = {
     edge: '#3F3F46',
     edgeText: '#3F3F46',
     edgeWidth: 1.5,
-    accent: 'red',
+    accent: 'blue',
     kindColors: true,
     radius: 8,
     group: { fill: 'none', stroke: '#71717A', dashed: true, text: '#3F3F46' },
@@ -179,8 +180,9 @@ const SKETCH = {
         if (color === 'ink')
             return { fill: SKETCH_INK, stroke: SKETCH_INK, text: '#FFFFFF', sub: '#5C5C66', strokeWidth: 1.5, extra: solid };
         if (hl) {
-            const s = LIGHT_SW[color === 'neutral' ? 'red' : color];
-            return { fill: s.line, stroke: s.solid, text: SKETCH_INK, sub: s.ink, strokeWidth: 2.5, extra: solid };
+            const c = color === 'neutral' ? 'blue' : color;
+            // A marker pass: a stronger tint than any kind's, under the accent's line
+            return { fill: c === 'blue' ? '#B9C6FF' : LIGHT_SW[c].line, stroke: LIGHT_SW[c].solid, text: SKETCH_INK, sub: LIGHT_SW[c].ink, strokeWidth: 2.5, extra: solid };
         }
         if (color === 'neutral')
             return { fill: '#FFFFFF', stroke: SKETCH_INK, text: SKETCH_INK, sub: '#5C5C66', strokeWidth: 1.5, extra: solid };
@@ -189,37 +191,38 @@ const SKETCH = {
     edgePaint: (color, hl) => {
         if (!color && !hl)
             return { stroke: SKETCH.edge, text: SKETCH.edgeText, width: 1.5 };
-        const s = LIGHT_SW[color ?? 'red'];
+        const s = LIGHT_SW[color ?? 'blue'];
         return { stroke: s.solid, text: s.ink, width: hl ? 2.5 : 1.5 };
     },
     extra: 'sketch=1;curveFitting=1;jiggle=2;',
 };
-const BP_BG = '#0F3460';
-const BP_INK = '#EAF2FF';
-const BP_HI = '#FFD43B';
+const BP_PAPER = '#F6F8FC';
+const BP_INK = '#1B2F55';
+const BP_LINE_INK = '#3F5F96';
+const BP_HI = '#1D4ED8';
 const BLUEPRINT = {
     name: 'blueprint',
     type: MONO,
-    canvas: BP_BG,
+    canvas: BP_PAPER,
     text: BP_INK,
-    muted: '#9DB8DF',
-    edge: '#9DB8DF',
-    edgeText: '#C9DBF5',
+    muted: '#5A6F92',
+    edge: '#6F86AD',
+    edgeText: '#4A5F84',
     edgeWidth: 1.25,
-    accent: 'amber',
+    accent: 'blue',
     kindColors: false,
     radius: 4,
-    group: { fill: 'none', stroke: '#5B82B8', dashed: true, text: '#9DB8DF' },
-    note: { fill: '#16467E', stroke: '#5B82B8', text: BP_INK },
-    well: '#16467E',
+    group: { fill: 'none', stroke: '#9DB0D0', dashed: true, text: '#5A6F92' },
+    note: { fill: '#EAF0FA', stroke: '#9DB0D0', text: BP_INK },
+    well: '#EAF0FA',
     paint: (color, hl) => {
         if (hl)
-            return { fill: BP_HI, stroke: BP_HI, text: BP_BG, sub: '#3A4A63', strokeWidth: 1 };
+            return { fill: BP_HI, stroke: BP_HI, text: '#FFFFFF', sub: 'rgba(255,255,255,0.8)', strokeWidth: 1 };
         if (color === 'ink')
-            return { fill: BP_INK, stroke: BP_INK, text: BP_BG, sub: BP_BG, strokeWidth: 1 };
+            return { fill: BP_INK, stroke: BP_INK, text: '#FFFFFF', sub: '#C9D5EA', strokeWidth: 1 };
         if (color === 'neutral')
-            return { fill: BP_BG, stroke: BP_INK, text: BP_INK, sub: '#9DB8DF', strokeWidth: 1.25 };
-        return { fill: BP_BG, stroke: BP_LINE[color], text: BP_INK, sub: BP_LINE[color], strokeWidth: 1.25 };
+            return { fill: '#FFFFFF', stroke: BP_LINE_INK, text: BP_INK, sub: '#5A6F92', strokeWidth: 1.25 };
+        return { fill: '#FFFFFF', stroke: BP_LINE[color], text: BP_INK, sub: BP_LINE[color], strokeWidth: 1.25 };
     },
     edgePaint: (color, hl) => {
         if (hl)
@@ -228,12 +231,14 @@ const BLUEPRINT = {
     },
     extra: '',
 };
-// C4-PlantUML's colours for architecture kinds; other diagram types use `clean`.
+// C4's convention (a dark person, blue containers, gray external systems) in
+// quieter tones than C4-PlantUML's, so a highlight still stands out, with white text at 4.5:1 or better on each.
+// Other diagram types use `clean`.
 const C4_KIND = {
-    person: { fill: '#08427B', stroke: '#073B6F', text: '#FFFFFF', type: 'Person' },
-    external: { fill: '#999999', stroke: '#8A8A8A', text: '#FFFFFF', type: 'External system' },
+    person: { fill: '#1E3466', stroke: '#1E3466', text: '#FFFFFF', type: 'Person' },
+    external: { fill: '#6B7383', stroke: '#6B7383', text: '#FFFFFF', type: 'External system' },
 };
-const C4_CONTAINER = { fill: '#438DD5', stroke: '#3C7FC0', text: '#FFFFFF', type: 'Container' };
+const C4_CONTAINER = { fill: '#456A9E', stroke: '#456A9E', text: '#FFFFFF', type: 'Container' };
 const C4 = { ...CLEAN, name: 'c4', group: { fill: 'none', stroke: '#444444', dashed: true, text: '#444444' }, edge: '#707070', edgeText: '#444444' };
 const THEMES_BY_NAME = { clean: CLEAN, soft: SOFT, dark: DARK, sketch: SKETCH, blueprint: BLUEPRINT, c4: C4 };
 export function palette(theme = 'clean') {

package/dist/lint/check.js

@@ -111,6 +111,10 @@ export function check(cells) {
         for (const n of nodes)
             if (inter(e.textBox, grow(n.box, 3)) > 4)
                 findings.push({ level: 'warning', rule: 'label-on-node', message: `label "${e.label}" on edge ${edgeName(e, byId)} covers ${name(n)}`, labelEdges: [e.id] });
+        // Same for a group's title.
+        for (const g of containers)
+            if (!scaffold(g) && g.label && g.textBox && inter(e.textBox, grow(g.textBox, 2)) > 4)
+                findings.push({ level: 'warning', rule: 'label-on-node', message: `label "${e.label}" on edge ${edgeName(e, byId)} covers the title of ${name(g)}`, labelEdges: [e.id] });
         // A label sitting on another edge, or on a group's border, hides part of that line.
         const tb = grow(e.textBox, -2);
         const lines = [

package/dist/render/browser.js

@@ -4,6 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 import { chromium } from 'playwright-core';
 import { FONT_STACK } from '../drawio/theme.js';
 import { FACES, embedFonts, fontFaceCss, fontsDir } from './fonts.js';
@@ -188,6 +189,14 @@ export class DrawioBrowser {
         return this.browser.close();
     }
 }
+/** Playwright-core's own installer, so the Chromium build always matches the version we run. */
+export function browserInstallCommand() {
+    const pkg = createRequire(import.meta.url).resolve('playwright-core/package.json');
+    return [process.execPath, path.join(path.dirname(pkg), 'cli.js'), 'install', 'chromium', '--only-shell'];
+}
+function installHint() {
+    return 'linework install-browser';
+}
 async function launchChromium() {
     const errors = [];
     const attempts = [];
@@ -204,7 +213,24 @@ async function launchChromium() {
             errors.push(e.message.split('\n')[0]);
         }
     }
-    throw new Error('linework needs a Chromium-based browser to lay out and render diagrams, and none was found.\n' +
-        'Fix one of these ways:\n  npx playwright install chromium\n  install Google Chrome\n  set LINEWORK_CHROME=/path/to/chrome\n' +
-        `(tried: ${errors.join(' | ')})`);
+    // A browser that exists but dies on launch is almost always a sandbox (Codex,
+    // seatbelt, containers without --no-sandbox) blocking it, not a missing install.
+    const crashed = errors.some((m) => !/doesn't exist|is not found|not installed|ENOENT/i.test(m));
+    if (crashed) {
+        // Playwright's headless shell still starts under macOS seatbelt (Codex's sandbox)
+        // when it runs as one process. Only as a fallback: single-process mode is less robust.
+        try {
+            return await chromium.launch({ args: ['--single-process', '--no-zygote'] });
+        }
+        catch (e) {
+            errors.push(e.message.split('\n')[0]);
+        }
+    }
+    throw new Error(crashed
+        ? 'linework found a Chromium-based browser but it could not start. If this runs inside a sandbox (an AI agent\'s sandbox, a container), the sandbox is probably blocking it.\n' +
+            `Fix: run this command outside the sandbox, or allow it to launch a browser. Linework can start inside some sandboxes (Codex's included) if Playwright's own Chromium is installed: run \`${installHint()}\` once, outside the sandbox.\n` +
+            `(tried: ${errors.join(' | ')})`
+        : 'linework needs a Chromium-based browser to lay out and render diagrams, and none was found.\n' +
+            `Fix one of these ways:\n  ${installHint()}\n  install Google Chrome\n  set LINEWORK_CHROME=/path/to/chrome\n` +
+            `(tried: ${errors.join(' | ')})`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsthecsguy/linework",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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

@@ -1,32 +1,47 @@
 ---
 name: linework
-description: Create and edit software diagrams (architecture, flowcharts, state machines, sequence diagrams, ER/database schemas) as .drawio.svg files that render in Markdown, HTML and GitHub, and that people can open and edit by hand in draw.io. Use when a design doc, README or ADR needs a diagram, or when asked to change an existing .drawio.svg.
+description: Draw software diagrams (architecture, system design, data flow, flowcharts, state machines, sequence diagrams, ER and database schemas) as .drawio.svg files that render in Markdown, HTML and GitHub and that people can edit by hand in draw.io. Use whenever a design doc, README, ADR, wiki page or PR needs a diagram, when asked to draw, visualize or diagram a system, when converting a Mermaid diagram, or when changing an existing .drawio.svg. Use it instead of writing Mermaid, PlantUML or ASCII art unless the user asks for one of those.
+compatibility: Needs Node 20+, a Chromium-based browser (Chrome, Edge, or Playwright's Chromium via `linework install-browser`) and network access to fetch the package with npx.
 ---
 
 # 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`. 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.
 
-Run it as `npx -y @itsthecsguy/linework` unless `linework` is already on PATH. The first run needs a Chromium-based browser. If it says none was found, run `npx playwright install chromium`.
+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.
+
+## Running it
+
+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.
+
+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.
+
+Never fall back to writing SVG or draw.io XML by hand. Tell the user what failed and what they can do about it.
 
 ## Workflow
 
-1. **Decide what the diagram is for.** One diagram makes one point. Pick the type:
+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: `npx -y @itsthecsguy/linework import doc.md --block 1 -o docs/diagrams/x.drawio.svg`.
-2. **Write the spec** to a scratch file, or pipe it on stdin. The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
-3. **Build with a preview:**
+   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: `checkout.yaml` (architecture), `serverless-aws.yaml` (architecture with AWS icons), `refund-flow.yaml` (flow), `payment-state.yaml` (state), `pay-sequence.yaml` (sequence), `billing-er.yaml` (ER). The `.drawio.svg` is the source of truth, so you don't need to keep the YAML.
+4. **Build with a preview:**
    ```bash
-   npx -y @itsthecsguy/linework build spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png
+   linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png
    ```
-4. **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.
-5. **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.
-6. **Embed the `.drawio.svg`**, never the PNG (see "Putting it in a doc").
+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.
 
 ## Spec
 
@@ -58,12 +73,12 @@ edges:                        # "from ARROW to: label"
 - `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 `npx -y @itsthecsguy/linework icons aws lambda` to search names. Use icons when the doc is about a specific cloud; leave them off for logical diagrams.
+- 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`: light lines on deep blue, monospace. For technical deep dives that want a distinct look.
+  - `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.
@@ -156,16 +171,16 @@ edges:
 
 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.
 
-More examples and rules are in `references/spec.md`. Read `references/style-guide.md` before drawing anything non-trivial.
+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
-npx -y @itsthecsguy/linework show docs/diagrams/checkout.drawio.svg > /tmp/spec.yaml   # current spec, hand edits included
+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
-npx -y @itsthecsguy/linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png
+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.)
@@ -182,19 +197,21 @@ The `# linework-base:` line tells `build` your spec includes the latest hand edi
 
 `--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, `npx -y @itsthecsguy/linework tidy file.drawio.svg` reroutes just the broken edges and changes nothing else.
+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 architecture](diagrams/checkout.drawio.svg)`
-- HTML: `<img src="diagrams/checkout.drawio.svg" alt="Checkout architecture">`
+- 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 `npx -y @itsthecsguy/linework git-setup` once, so `git diff` on diagrams shows readable spec changes.
-- Google Docs can't hold SVG. `npx -y @itsthecsguy/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.
+- 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, `npx -y @itsthecsguy/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.
+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
 
@@ -212,3 +229,5 @@ If the user wants to adjust a diagram by hand, `npx -y @itsthecsguy/linework edi
 | `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 |

package/skills/linework/examples/checkout.yaml

@@ -8,7 +8,7 @@ nodes:
   user:    { label: Shopper, kind: person }
   web:     { label: Web app, kind: client, tech: Next.js }
   gw:      { label: API gateway, kind: service, tech: Envoy, in: vpc }
-  api:     { label: Checkout API, kind: service, tech: Go, in: vpc }
+  api:     { label: Checkout API, kind: service, tech: Go, in: vpc, highlight: true }
   worker:  { label: Fulfillment worker, kind: service, tech: Go, in: vpc }
   queue:   { label: order-events, kind: queue, tech: Kafka, in: vpc }
   db:      { label: Orders, kind: database, tech: Postgres, in: data }
@@ -17,11 +17,11 @@ nodes:
   email:   { label: SendGrid, kind: external, tech: Email }
 edges:
   - user -> web: browses
-  - web -> gw: HTTPS
-  - gw -> api: gRPC
+  - web ==> gw: HTTPS
+  - gw ==> api: gRPC
   - api -> cache: read session
   - api -> db: SQL
-  - api -> stripe: charge
+  - api ==> stripe: charge
   - api -.-> queue: OrderPlaced
   - queue -.-> worker: consume
   - worker -> db: update status

package/skills/linework/examples/pay-sequence.yaml

@@ -3,12 +3,12 @@ title: Card payment
 participants:
   user:   { label: Shopper, kind: person }
   web:    { label: Web app, kind: client }
-  api:    { label: Checkout API }
+  api:    { label: Checkout API, highlight: true }
   stripe: { label: Stripe, kind: external }
   db:     { label: Orders DB, kind: database }
 messages:
   - user -> web: Click "Pay"
-  - web -> api: POST /checkout
+  - web ==> api: POST /checkout
   - api -> db: insert order (pending)
   - db --> api: order id
   - api -> stripe: create PaymentIntent

package/skills/linework/examples/refund-flow.yaml

@@ -9,7 +9,7 @@ nodes:
   auto:     { label: Auto-approve }
   review:   { label: Queue for manual review }
   approved: { label: Approved?, kind: decision }
-  refund:   { label: Issue refund via Stripe }
+  refund:   { label: Issue refund via Stripe, highlight: true }
   notify:   { label: Email customer }
   deny:     { label: Deny with reason, kind: error }
   done:     { label: Done, kind: terminal }