Zumen

Call this once, first. Says what the tool is for, what it will not do, **which doors are closed** (so you do not try them), and what changed in each version.

Takes no parameters.

Returns the format, the type and appearance words you may use, and the rules to follow. Read this before writing a diagram. Writing without it is guesswork.

Takes no parameters.

Returns the paths of diagrams (*.zumen.yaml) underneath. **Look at what already exists first** — if the diagram is already there, edit it rather than creating a new one (changing ids detaches a person's edits). Only paths come back; read the contents with zumen_read.

**Returns the catalogue of the 189 examples bundled with this tool, and their sources.** **Look here first when deciding what to draw.** zumen_spec only tells you how to write a file — the value of zumen is not the syntax but how the drawings that professionals actually use are put together: a periodontal chart, a plywood cutting diagram, a stage lighting plot, a used-car appraisal chart, a timber joint, tactile paving. Each one-liner states **what that drawing must get right**, not its title. With no arguments you get the categories and counts. Narrow with query (Japanese or English). Pass name to get **that example’s YAML source**, so you can copy how it is written. You can also query by feature (views, hatch, chain, openings…) — the syntax is in zumen_spec, but a **working example** only exists here. **Do not churn out generic network diagrams and flowcharts** — adding what existing tools already do proves nothing.

Returns the source (*.zumen.yaml) verbatim. **Always read before changing it** — rewriting without knowing the contents drops the pins a person added and any keys you do not recognise. Pass changes through zumen_propose; there is no tool that writes a file directly.

Returns the positions, sizes, labels and appearance a person set. Read only; there is no way to write here. Leave it alone and change the structure instead.

Returns readability, element counts, edge crossings, box overlaps, group escapes, size, and the autonomy figure. Always look at this after writing. tooTangled only means there are more crossings than edges, which is **not a defect in itself**: of the 333 examples, the 19 where it is true are keyline grids, a spider web, gear pitch circles and measuring graticules — in all 19 the crossing lines *are* the drawing. When it is true, judge for yourself whether the drawing is made of overlapping lines or merely knotted. Any edge id in hiddenLabels has a label that did not fit and is not drawn — shorten it or use fewer edges. **Always check kind**: for a placement drawing positionsInSource is true, meaning you write the positions yourself (nodes[].at as { x, y }) and the machine will not re-arrange them. You can also set sizes with nodes[].size ({ w, h }, which works for structure diagrams too) — without it every room comes out the same size. Never write pins — those belong to the person. If tooSmallToProject is true the text is too small to read when projected. **If tooSmallToPrint is false, the drawing is simply one to be printed rather than projected** (transit maps, appraisal charts, lighting plots and stowage plans land here — 36 of the 95 examples do). **Only when both are true is there really something to fix.** Do NOT fix it by enlarging the text (that grows the diagram and lowers the ratio further). **Try wrap: true first** — if the diagram is just one long row, wrapping brings it back (a chain of 8 goes from 13.9 to 2.2). If that is not enough, ask the person whether the diagram can be split. Any id in crowdedNames has a name that did not fit its box and had nowhere free outside it, so it is drawn overlapping something. Make the box bigger or shorten technology. It is NOT dropped — a room losing its name is worse than an overlap. Any id in adriftNames is a wide box whose name did not fit and is drawn outside it — in a table that leaves the row looking empty. Any

Creates a new diagram. Fails if the file already exists (this is not an overwrite path). Nothing is written unless it conforms to the format. To change an existing diagram, use zumen_propose.

Applies a proposal to an existing diagram. The pins in your proposal are not read, so hand edits survive. Anything that disagrees with a hand edit is not applied and comes back as a conflict. Conflicts are decided by a person, not by you.

Exports to svg (to show), **png (to look at yourself)**, mermaid (readable tomorrow) or drawio (editable tomorrow). Each exporter states what it could not carry. **png comes back as the picture itself** — always look at one before calling a drawing done (the numeric checks only tell you whether it is readable). It needs Chrome, and says so when Chrome is missing.

Writes one animated SVG plus numbered SVGs (all padded to the same paper) from a list of steps. No screen recording, so it works remotely. **No encoder is bundled** — the returned recipe shows how to make an mp4 with the tools you already have.

Reports whether the desktop app is on the other end of the live link and what it is showing. **Check this before using any zumen_live_* tool.** If nothing is connected, use zumen_propose (which writes the file) instead. screens = 0 means no human is looking at this screen.

Takes no parameters.

**Reads the screen, not the disk.** Edits the person just made but has not saved live here; zumen_read would not see them. Read this before changing anything.

Takes no parameters.

Puts a proposal **on the screen only**. It does not enter the source of truth; nothing happens until the person presses "apply". **You have no way to press it.** With wait, this blocks until the person answers (applied = they took it / discarded = they rejected it / timeout = they have not looked yet / gone = the screen went away). **timeout does not mean rejected.** A proposal that fails validation is never shown.

Selects that element on screen. **Selecting only; the diagram does not change.** Use it instead of describing in words which thing you mean.