# isokit A guarded generator for Azure-marketing-style isometric architecture diagrams, rendered as self-contained SVG (embedded fonts, no runtime dependencies). Designed to be driven by an AI agent in conversation: you describe the architecture and critique the renders; the agent authors the layout script against the in-repo grammar ([STYLE.md](STYLE.md)). Published specs — a stable-URL document any agent can be pointed at — are coming ([ROADMAP.md](ROADMAP.md), Phase 4) so agents can cleanly and sensibly generate diagrams from the user's instructions without cloning this repo. Diagrams are plain-TypeScript layout scripts against a declarative registry: place named units on a snapped grid, connect them by name, annotate them once — the library derives plate edges, flow routes, arrowheads, numbered pointer chips, and the legend rail. Invariants that make diagrams look right are *enforced*, not documented: violating one fails generation instead of shipping a subtly broken render. ## Why an agent, not another auto-layout DSL? Auto-layout tools solve topology legibility — don't overlap nodes, route edges sanely — which is why their output all looks the same. isokit targets a presentation-grade visual style where quality lives in placement judgment: which side an annotation should approach from, where a label reads clearly, how a flow should enter a face. No layout algorithm optimizes for that, but an agent reading a style guide can, and a human can direct it by critique ("this arrow points along the shape, not at it") instead of by learning a DSL. The renderer's job is everything *checkable*: hard errors on grid violations, collisions, and overflow give the agent a floor it cannot fall through, and error messages are written as turns in a conversation so it can self-correct without eyes. Auto-placement ([ROADMAP.md](ROADMAP.md), Phase 2) keeps raising that floor; the judgment loop stays. ## Usage Requires Node ≥ 23.6 (runs TypeScript directly via native type stripping — no build step). ```bash node layouts/hybrid_onprem_azure.ts ``` Each layout script writes one SVG. Output directory resolution: `$ISOKIT_OUT` if set, else the first `isokit.local` file found walking up from the working directory (first line = output dir), else `./out/`. A minimal layout: ```typescript import { setTheme, configure, out, grid, svgOpen, write, box, cyl, GLYPHS, unit, connect, annotate, annotations, renderUnits, A2, A3 } from "../src/isokit.ts"; setTheme("azure"); // theme tokens are live bindings — order vs. imports doesn't matter configure(46, 440, 48); const S = svgOpen(1400, 700); S.push(grid()); unit("app", box, 5, 2, { rim: A2, glyph: GLYPHS["app"] }); // integer cell coords; 2x2 cells unit("db", cyl, 5, 6, { rim: A3 }); S.push(connect("app", "db")); // auto edge points + L-route S.push(renderUnits()); annotate("app", "App Service", "serves the workload.", [3.5, 1.5]); annotate("db", "Azure SQL", "system of record.", [3.5, 7.5]); S.push(annotations()); write(out("Minimal.svg"), S); ``` ## YAML Diagrams can also be authored as semantic YAML instead of a TypeScript layout script — no coordinates in the common case, meant to be authored by an AI agent from a topology description (or by hand): ```yaml isokit: 1 title: "MINIMAL" units: web: { shape: box, glyph: app, accent: 1 } db: { shape: cyl, accent: 3 } groups: app-tier: { label: APP TIER, units: [web, db] } flows: - { from: web, to: db } ``` Render it: ```bash node src/cli.ts render examples/minimal.yaml ``` (`isokit render examples/minimal.yaml` once the package is linked.) The full format contract — every key, enum, the layout-derivation order, and the complete error table — is [SPEC.md](SPEC.md). ## Authoring with AI The YAML's primary author is meant to be an AI agent. Hand any model this one URL (or paste the file into its context) along with your topology description, and it has everything it needs — task rules, the full format contract, and worked examples: ``` https://raw.githubusercontent.com/zeiosmb/isokit/main/llms.txt ``` Paste the returned YAML into an ` ```isokit ` code block in Obsidian (or a `.yaml` file for the CLI). If the render fails, paste the error block back to the agent — errors are written as instructions it can act on directly. `llms.txt` is generated from SPEC.md and the examples by `npm run build:llms`; `tests/llms.ts` fails the suite if it drifts. ## Obsidian plugin `obsidian/` packages the pure render core as an Obsidian plugin: a ` ```isokit ` code block containing a YAML document renders in-note as the finished SVG. Errors render in-note too, as the same structured block the CLI prints — the `line N` it cites is the line within the code block, so fixes happen without leaving the note. Build and install: ```bash npm run build:obsidian mkdir -p "/.obsidian/plugins/isokit" cp obsidian/main.js manifest.json obsidian/styles.css "/.obsidian/plugins/isokit/" ``` Then enable **isokit** under Settings → Community plugins. The bundle is self-contained (fonts embedded, no network, no filesystem access) and works on mobile. Every rendered block gets small overlay controls in its bottom-right corner: `+`/`−` to zoom (also ctrl/cmd+scroll, or pinch on trackpad/mobile), drag to pan once zoomed, double-click to reset. Diagrams with annotations also get a `»`/`«` legend toggle: collapsing hides the legend rail and narrows the viewBox so the diagram reflows to full width (the SVG itself is untouched — the rail is addressable via its `isokit-legend` class). `tests/obsidian.ts` builds the real bundle and drives the code-block processor — rendering, errors, escaping, and the pan/zoom/legend math — on every `npm test`. `examples/interactive/` holds the same set of renders with equivalent controls baked directly into the SVG itself via an inline `