@chanmeng666/archlang-mcp 0.1.0

package/dist/llms-full.txt

@@ -0,0 +1,599 @@
+<!-- GENERATED by scripts/gen-llms-full.ts — do not edit by hand. Run `npm run gen:llms`. -->
+
+# ArchLang — full agent context (llms-full.txt)
+
+This is the complete context for driving **ArchLang**, a tiny declarative language that compiles a
+`.arch` floor-plan source file into a professional drawing (SVG/PNG/PDF/DXF). It follows the
+[llms.txt](https://llmstxt.org/) convention: `llms.txt` is the concise project map, and this
+`llms-full.txt` is the whole thing in one document — the language spec, the agent workflow, the CLI
+reference, and every diagnostic code — sized to drop into a system prompt.
+
+ArchLang is built for agents: **deterministic** (same source → byte-identical output), **pure** (no
+runtime, no IO in the compiler), and **self-correcting** (every error carries a machine code and a
+`fix`). Author, render, and verify entirely through the `arch` CLI — never hand-render SVG.
+
+Contents:
+
+1. Language spec — the whole language in one page.
+2. Agent workflow — the compile → fix → describe → gate loop, and how to repair plan topology.
+3. CLI reference — every command, flag, and exit code.
+4. Diagnostic catalog — every error and warning, each with a fix.
+
+---
+
+## 1. Language spec
+
+# ArchLang in one prompt
+
+ArchLang is a tiny declarative language that compiles a `.arch` source file into a professional
+floor-plan drawing (SVG/PNG/PDF/DXF). It is built for AI agents: deterministic (same source →
+identical output), pure (no runtime/IO), and self-correcting (every error carries a machine code and
+a `fix`). This page is everything you need to author it. Print it any time with `arch spec`.
+
+## The 7 rules that matter
+
+1. **Units are millimetres.** A 4-metre wall is `4000`, not `4`.
+2. **Origin is top-left; +x goes right, +y goes DOWN** (screen/SVG convention — *not* math y-up).
+3. **Coordinates are `(x, y)` tuples; sizes are `WxH`** (e.g. `4000x3000`) or `<expr> x <expr>` with spaces.
+4. **Doors and windows must lie ON a wall segment** (on its centerline), or you get a
+   `W_DOOR_OFF_WALL` / `W_WINDOW_OFF_WALL` warning.
+5. **String interpolation is `"{expr}"`** inside double quotes (e.g. `label "Unit {i}"`).
+6. **Ids must be unique.** Omit `id=` to auto-generate one; give an `id` only when you reference it.
+7. **Everything is expand-time and pure** — `let`/`for`/`if`/functions all evaluate during compile.
+
+## Structure
+
+```arch
+plan "Title" {
+  units mm            # required-ish settings come first
+  grid 50             # snap grid in mm
+  scale 1:50          # drawing scale (annotation only)
+  north up            # up | down | left | right
+  # … elements and scripting …
+  title { project "…" drawn_by "…" date "…" }
+}
+```
+
+## Elements
+
+```text
+wall <category> thickness <mm> [material <name>] { (x,y) (x,y) … [close] }   # category e.g. exterior/partition; `close` makes a loop
+room [id=<name>] at (x,y) size <W>x<H> [label "…"] [uses living|kitchen|dining|bedroom|bath|wc|hall|circulation|storage|utility|office|entry …]   # OR relational: room [id=…] (right-of|left-of|below|above) <roomId> [align top|middle|bottom|left|right] [gap <mm>] size <W>x<H> [label "…"]
+door [id=<name>] at (x,y) width <mm> [wall <id|category>] [hinge left|right] [swing in|out]   # must sit on a wall
+window [id=<name>] at (x,y) width <mm> [wall <id|category>]   # must sit on a wall
+opening [id=<name>] at (x,y) width <mm> [wall <id|category>]   # a leaf-less cased opening (gap in a wall) that still connects the two spaces
+furniture <category> (at (x,y) | against wall <id> [segment <n>] [offset <mm>] [side left|right]) [size <W>x<H>] [label "…"] [rotate 0|90|180|270] [in <roomId>]   # `at` size is plan W×H; `against` size is wall-relative along×depth and derives position+rotation, with `side` inferred from `in <roomId>` when omitted; a known fixture (wc/basin/shower/bathtub/kitchen_sink/counter/stove/fridge…) `against wall` may omit `size` to use its catalogued footprint
+dim (x,y)->(x,y) offset <mm> [text "…"]   # a dimension line
+column [id=<name>] at (x,y) size <W>x<H>
+```
+
+## Scripting (all expand-time, deterministic)
+
+- `let NAME = expr` — bind a constant. `NAME = expr` — reassign an existing binding.
+- `let f(a, b) = expr` — a pure value-function. Built-ins: `min max abs sqrt floor ceil round len str`.
+- `for i in lo..hi { … }` — loop over a half-open integer range (`0..3` → 0,1,2).
+- `if cond { … } else { … }` · `while cond { … }`.
+- `set <element>(attr: value)` — scoped default for following elements (e.g. `set door(swing: out)`).
+- Arrays: `[a, b, c]`, indexed `arr[i]`. Operators: `+ - * / %`, `== != < > <= >=`, `&& ||`. Comments: `# …`.
+- `import "lib/x.arch": name` and `component name(args) { … }` for reuse.
+
+## Keyword reference
+
+- **Settings / control:** `plan`, `component`, `let`, `theme`, `title`, `style`, `import`, `for`, `if`, `while`, `else`, `set`, `strip`
+- **Elements:** `wall`, `room`, `door`, `window`, `opening`, `furniture`, `dim`, `column`
+- **Attributes:** `units`, `grid`, `scale`, `north`, `dims`, `accTitle`, `accDescr`, `material`, `angle`, `at`, `size`, `width`, `thickness`, `label`, `hinge`, `swing`, `offset`, `text`, `close`, `id`, `project`, `drawn_by`, `date`, `from`, `as`, `right-of`, `left-of`, `below`, `above`, `align`, `gap`, `uses`, `rotate`, `against`, `segment`, `side`, `on`, `into`, `near`, `anchor`, `inset`, `height`
+- **Enums / values:** `up`, `down`, `left`, `right`, `in`, `out`, `mm`, `true`, `false`, `top`, `middle`, `bottom`, `center`, `centered`, `start`, `end`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `auto`, `living`, `kitchen`, `dining`, `bedroom`, `bath`, `wc`, `hall`, `circulation`, `storage`, `utility`, `office`, `entry`
+
+## CLI loop (how an agent drives it)
+
+```bash
+arch spec                              # print this spec
+arch manifest --json                   # the whole CLI API as data: commands, flags, formats, lint rules, error codes
+arch compile plan.arch -o out.svg --json   # render; JSON has { ok, diagnostics, summary }
+echo '<source>' | arch compile - --json    # compile from stdin (no temp file)
+arch preview plan.arch -o out.png --json   # render a PNG you can SHOW the user (zero-install where resvg is present; --install fetches it)
+arch compile plan.arch -o walk.svg --overlay circulation   # opt-in: draw the entrance→room walks + pinch markers on top (default output is unchanged)
+arch describe plan.arch --json         # semantic facts: rooms, areas, adjacency, what doors connect, + per-room circulation (walk distance, bottleneck width, detour)
+arch lint plan.arch --json             # architectural soundness warnings
+arch validate plan.arch --strict --json   # parse + lint, no render; --strict fails on warnings too
+arch explain E_ROOM_SIZE --json        # look up any error code
+arch repair plan.arch -o fixed.arch    # explicit corrector: new source w/ furniture out of walls/doorways/swings, overlaps separated, fixtures into their room + snapped to walls + change log
+arch batch a.arch b.arch -f svg --json # render many variants at once → results[]
+arch md notes.md -o out.md -f svg      # render every fenced arch block in a Markdown file → image links
+```
+
+**Self-correction loop:** compile/validate → if `ok` is false, read each `diagnostics[].fix` (and
+`line`/`col`/`span`), edit the source, recompile. Exit code `2` means a deterministic
+user-source error (fix it; don't blindly retry). Then `describe --json` to confirm the plan matches
+intent (right room count, areas, adjacency) without rendering an image. **Before shipping, gate with
+`arch validate --strict --json`** — it fails on advisory warnings too, so a plan that lint flags
+(furniture through a wall, a fixture blocking a doorway, a room you can't step into, an unreachable
+room, a walk that squeezes too narrow — `W_PATH_TOO_NARROW` — or wanders the long way round —
+`W_CIRCUITOUS_PATH`) cannot pass silently.
+
+**Place furniture so it's physically sound:** keep every piece inside its room and off the walls
+(don't cross a wall centerline); back plumbing/kitchen fixtures onto a wall with `against wall <id>`
+(+ `in <roomId>`) rather than guessing an `at`; give every room a `door`/`opening`; and leave
+the doorway approach and the door's swing clear.
+
+**Fix topology from facts, not guesses.** `arch repair` corrects furniture but never adds a door or
+window (that is a design choice). When lint reports an unreachable room / no entrance / windowless
+bedroom, read `describe --json` — `access.rooms[].reachable`, room `bbox`/`adjacent`, building
+extent = min/max of room boxes — and add a `door`/`opening`/`window` on the right wall yourself
+(an exterior entrance into a cut-off living space beats routing through a bedroom), then re-`repair`
+and `validate --strict`. See SKILL.md for the exact arithmetic.
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Using metres (`size 4x3`) | Use millimetres (`size 4000x3000`). |
+| Expecting +y to go up | +y goes **down**; a room below another has a larger y. |
+| Door/window floating in space | Put its `at` on a wall segment's centerline. |
+| `size 4000` (no height) | Sizes are `WxH`: `size 4000x3000` (or `W x H` with spaces). |
+| Reusing an `id` | Ids are unique; omit `id=` to auto-generate. |
+| String math without interpolation | Use `"{expr}"`, e.g. `label "{aream2(W,H)} m²"`. |
+
+## Worked examples
+
+### `examples/studio.arch`
+
+```arch
+# A compact studio apartment — the canonical ArchLang example.
+#
+# Architecturally sound (passes `arch lint`): every room opens off a central hall,
+# so the bath is never reached through the bedroom; the bath is fully enclosed and
+# fitted with real fixtures; and no door leaf sweeps onto furniture. Self-contained
+# (no imports) so it compiles from a single file.
+plan "Studio 1BR" {
+  units mm
+  grid 50
+  scale 1:50
+  north up
+
+  # Exterior shell + partitions. The x=4000 divider runs the FULL height so the bath
+  # is walled off from the living space; the right column splits into bedroom / hall / bath.
+  wall exterior  thickness 200 { (0,0) (7000,0) (7000,6000) (0,6000) close }
+  wall partition thickness 100 { (4000,0) (4000,6000) }
+  wall partition thickness 100 { (4000,3000) (7000,3000) }
+  wall partition thickness 100 { (4000,4400) (7000,4400) }
+
+  room id=r_living at (0,0)       size 4000x6000 label "Living / Kitchen" uses living kitchen
+  room id=r_bed    at (4000,0)    size 3000x3000 label "Bedroom"           uses bedroom
+  room id=r_hall   at (4000,3000) size 3000x1400 label "Hall"             uses hall
+  room id=r_bath   at (4000,4400) size 3000x1600 label "Bath"             uses bath
+
+  # Entrance into the living space; the hall links it to the bedroom and the bath.
+  # Living ↔ hall is a cased opening (circulation needs no door leaf); the bedroom
+  # and bath each get a real door off the hall.
+  door    id=d_main   at (3000,6000) width 1000 wall exterior  hinge left  swing in
+  opening id=o_living at (4000,3700) width 900  wall partition
+  door    id=d_bed    at (6400,3000) width 800  wall partition hinge right swing out
+  door    id=d_bath   at (4600,4400) width 800  wall partition hinge left  swing out
+
+  window at (0,2000)    width 1500 wall exterior
+  window at (7000,1500) width 1200 wall exterior
+  window at (7000,5200) width 700  wall exterior
+
+  # Kitchen run along the north wall: sink · counter · stove · fridge (drawn as symbols).
+  furniture kitchen_sink at (300,250)  size 800x600
+  furniture counter      at (1200,250) size 600x600
+  furniture stove        at (1950,250) size 600x600
+  furniture fridge       at (2700,250) size 600x650
+
+  # Living + bedroom furniture, kept clear of the door swings.
+  furniture sofa at (350,4300) size 2000x900  label "Sofa"
+  furniture bed  at (4300,300) size 1500x2000 label "Bed"
+
+  # Bathroom fixtures, kept clear of the door's entry path (the door swings out into
+  # the hall): shower in the far corner, basin against the partition, WC on the south
+  # wall — the left third of the room stays open so you can actually step inside.
+  furniture shower at (6000,5000) size 900x900   # against the E + S walls (corner)
+  furniture basin  at (5200,4450) size 600x450   # back to the hall partition
+  furniture wc     at (5200,5200) size 400x700   # back to the south wall
+
+  # Dimension strings: room widths above, overall extents around. The reference
+  # (witness) points sit on the building's OUTER faces (x=-100/7100, y=-100/6100 for
+  # the 200mm shell) so the extension lines start at the wall face and read outward,
+  # never poking back into the building — while the spans still measure centerline to
+  # centerline (4000 · 3000 · 7000 · 6000).
+  dim (4000,-100)->(0,-100)    offset 250 text "4000"
+  dim (7000,-100)->(4000,-100) offset 250 text "3000"
+  dim (0,6100)->(7000,6100)    offset 500 text "7000"
+  dim (7100,6000)->(7100,0)    offset 500 text "6000"
+
+  title {
+    project "Studio Apartment"
+    drawn_by "ArchCanvas"
+    date "2026-06-27"
+  }
+}
+```
+
+### `examples/parametric.arch`
+
+```arch
+# Parametric plan (v0.8 scripting): a row of studio units generated with a
+# `for` loop over a range, a value-function, an array indexed per unit, a scoped
+# `set` rule, an `if`, and string-interpolated labels. Everything is derived
+# from the constants — change COUNT and the whole row regenerates.
+plan "Parametric — Studio Row" {
+  units mm
+  grid 50
+  scale 1:100
+  north up
+
+  # Plan-level constants (visible everywhere below — plan scope is global).
+  let WALL  = 200
+  let W     = 4000          # unit width
+  let H     = 5000          # unit depth
+  let DOOR  = 900
+  let WIN   = 1600
+  let COUNT = 3             # number of units
+
+  # A value-function (pure closure) — area in square metres.
+  let aream2(w, h) = w * h / 1000000
+
+  # Per-unit names, indexed by the loop variable.
+  let names = ["Studio A", "Studio B", "Studio C"]
+
+  # Entrance doors swing outward throughout this plan (scoped default).
+  set door(swing: out)
+
+  for i in 0..COUNT {
+    let x = i * W
+    wall exterior thickness WALL { (x, 0) (x + W, 0) (x + W, H) (x, H) close }
+    room at (x, 0) size W x H label "{names[i]}"
+    furniture bed   at (x + 300, 300)      size 1500x2000 label "Bed"
+    furniture kitch at (x + W - 1900, 300) size 1600x600  label "Kitchen"
+    door   at (x + W / 2, H) width DOOR wall exterior hinge left
+    window at (x + W / 2, 0) width WIN  wall exterior
+
+    # The end unit carries a per-unit area dimension (computed by the function).
+    # Referenced to the outer face (y = H + WALL/2) so the extension lines start at
+    # the wall and read downward, away from the building.
+    if i == COUNT - 1 {
+      dim (x, H + WALL / 2)->(x + W, H + WALL / 2) offset 600 text "{aream2(W, H)} m² each"
+    }
+  }
+
+  # Overall run, dimensioned above the building: right-to-left so the offset lands
+  # ABOVE the row (outside), and referenced to the outer top face (y = -WALL/2).
+  dim (W * COUNT, 0 - WALL / 2)->(0, 0 - WALL / 2) offset 1300 text "{COUNT} units"
+}
+```
+
+---
+
+## 2. Agent workflow
+
+# ArchLang — author floor plans as code
+
+ArchLang turns a small `.arch` text file into a professional floor-plan drawing. It is built for
+agents: deterministic, self-correcting (errors carry a machine code, a prose `fix`, and often a
+**machine-applicable** fix `arch fix` can apply), and verifiable without ever looking at an image
+(`arch describe`).
+
+## Setup (zero-install)
+
+The CLI runs straight from npm — no clone, no build:
+
+```bash
+npx @chanmeng666/archlang help
+```
+
+(Or `npm i -g @chanmeng666/archlang` to get a persistent `arch` binary.)
+
+## The loop (always follow this)
+
+1. **Learn the language first.** Run `arch spec` and read it — the entire language in one page
+   (~2k tokens). (`arch context` prints *everything*: spec + this workflow + CLI reference + error
+   catalog.) Do this before writing any `.arch`.
+2. **Write the plan** to a `.arch` file (or pipe via stdin with `-`), preferring the **placement
+   sugar** below so you never hand-compute a coordinate.
+3. **Render it:** `arch compile plan.arch -o plan.svg --json`. The JSON is `{ ok, diagnostics,
+   summary }`.
+4. **Auto-fix the mechanical faults:** if `ok` is false, run `arch fix plan.arch --dry-run --json`
+   to preview the **machine-applicable** edits (off-wall opening → attachment form, out-of-range
+   position clamped, …), then re-run without `--dry-run` to apply. Anything `fix` can't resolve stays
+   in `diagnostics[].fix` for you to edit by hand. Exit code `2` means a deterministic user error —
+   fix it, don't blindly retry (`1` = IO/internal, `3` = bad usage).
+5. **See the plan without an image:** `arch compile plan.arch -f txt` (or `arch preview plan.arch
+   --ascii`) prints a zero-dependency ASCII floor plan you can read straight from stdout.
+6. **Verify intent:** `arch describe plan.arch --json` returns the rooms (areas, adjacency), what each
+   door connects, and totals. Confirm the room count, labels, and areas match what was asked.
+7. **Gate on soundness — don't ship a flagged plan.** `arch validate plan.arch --strict --json`
+   (parse + resolve + lint). `--strict` makes **every advisory warning fail** (exit `2`) — the gate a
+   generation pipeline runs before it ships. Add `--graph g.json` to also assert the intended
+   room-to-room adjacency (`{ "living": ["kitchen","hall"], … }`); a mismatch fails. Read each
+   `diagnostics[].fix`, edit, and re-run until it passes — or, if a warning is deliberate, say so.
+8. **Fix furniture geometry:** `arch repair plan.arch -o fixed.arch` pushes furniture out of
+   walls/doorways/swing arcs (the geometric corrector; distinct from `fix`).
+9. **Show the user:** `arch preview plan.arch -o plan.png` renders a PNG (`--install` fetches the
+   optional renderer if missing).
+
+## Write it right the first time (placement sugar — the preferred path)
+
+A geometry-blind generator that emits absolute coordinates produces plans that render but are
+physically wrong (openings off their wall, furniture through walls). Author by **attachment** instead
+— the compiler computes the coordinate, and fails loudly if the reference is ambiguous:
+
+- **Attach openings to a wall by position, not `at (x,y)`.** `door on <wall> at <pos> …` /
+  `window on <wall> at <pos> …` / `opening on <wall> at <pos> …`, where `<pos>` is millimetres along
+  the wall or a percentage (`50%`). `swing into <room>` picks the swing direction toward a named room;
+  `hinge near start|end` hinges at the segment end nearer a wall end. (Off-wall/ambiguous →
+  `E_ATTACH_WALL_REF`; past the wall → `E_ATTACH_POS_RANGE`.)
+- **Lay rooms with `strip`.** `strip right at (0,0) gap 0 height 4000 { room … room … }` places a row
+  (or column, with `down`/`up` + `width`) of rooms end to end — no per-room `at`.
+- **Place furniture by anchor.** `furniture <kind> in <room> anchor <corner|edge> [inset <mm>] …`
+  snaps a piece flush to a room corner/edge; `against wall <id>` backs plumbing/kitchen fixtures onto a
+  real wall face. Both are closed-form and never float or penetrate.
+- **Every room still needs a way in** — put a `door` or cased `opening` on a wall of *every* room
+  (an open-plan space still needs a modeled opening), and keep furniture out of the doorway approach
+  (≥300 mm) and the leaf's swing.
+- **Absolute `at (x,y)` is the fallback**, not the default — reach for it only when no attachment
+  expresses what you mean.
+
+See `examples/attached.arch` for a full one-bedroom authored this way, and `arch spec` for the grammar.
+
+## Self-correct with data, not guesswork
+
+`arch compile --json` returns every problem as a `Diagnostic` with a byte span, `line`/`col`, a
+catalogued `E_*`/`W_*` code, and a prose `fix`. Where the correction is a mechanical text edit, the
+diagnostic also carries **machine-applicable `fixes`**:
+
+- **`arch fix`** applies them in a bounded, self-checking fixpoint — **only `machine-applicable` by
+  default** (`--unsafe` also applies `maybe-incorrect`; `--dry-run` previews; `--force` keeps a pass
+  that would otherwise roll back). Use it to clear the syntactic faults before you touch anything by
+  hand.
+- **`arch fix` is syntactic; `arch repair` is geometric.** `fix` rewrites text where the right text is
+  known (e.g. an off-wall door → the attachment form); `repair` *moves furniture* to a position no
+  text edit could express. They compose — fix first, then repair.
+
+## Fix the topology: add doors & windows the room graph needs
+
+`fix`/`repair` never add a door or a window — *where* to put one is a design choice the compiler must
+not make. When lint reports `W_ROOM_UNREACHABLE`, `W_ROOM_DISCONNECTED`, `W_NO_ENTRANCE`,
+`W_BATH_VIA_BEDROOM`, or `W_BEDROOM_NO_WINDOW`, ask ArchLang for candidates:
+
+- **`arch suggest plan.arch --json`** returns ready-to-paste `door`/`window` statements (in the
+  **attachment form**) plus a rationale for each — for the unreachable room or windowless bedroom.
+  Choose one and insert it, then re-run the loop. This replaces hand-computing coordinates.
+- **Manual fallback** (if `suggest` offers nothing that fits): from `describe().access`, connect each
+  unreachable room in priority — (1) a new **exterior entrance** `door on <exterior wall> at <pos>`
+  into a living/kitchen/hall with an exterior edge (avoids routing through a bedroom); else (2) a
+  `door on <shared wall> at <pos>` to an adjacent reachable, non-bedroom room; and give a windowless
+  bedroom a `window on <its exterior wall> at <pos> width 1200`. Never make a bathroom reachable only
+  through a bedroom. Then `arch repair` (a new door may pinch furniture) and re-gate.
+
+> An *existing* opening `validate` reports **off its wall** (`W_DOOR_OFF_WALL` /
+> `W_WINDOW_OFF_WALL` / `W_OPENING_OFF_WALL`) is a mis-coordinate, not a missing connector — run
+> `arch fix` (it rewrites it to the attachment form) rather than adding a new one.
+
+## Structured authoring & constrained generation (optional)
+
+- **Plan JSON.** Author or ingest the machine-native shape and compile it: `arch compile plan.json
+  --from-json -o out.svg`. The schema is served at
+  [`/plan.schema.json`](https://archlang-docs.vercel.app/plan.schema.json).
+- **GBNF.** To force a local model to emit only parseable ArchLang, constrain decoding with
+  [`/archlang.gbnf`](https://archlang-docs.vercel.app/archlang.gbnf).
+
+## Commands
+
+```bash
+arch spec                              # the whole language in one page — READ THIS FIRST
+arch context                           # everything in one call: spec + this workflow + CLI reference + error catalog
+arch manifest --json                   # the whole CLI API as data: commands, flags, formats, lint rules, error codes
+arch compile plan.arch -o out.svg --json   # render (also -f dxf|txt|pdf|png)
+arch compile plan.arch -f txt          # zero-dependency ASCII text plan on stdout (also `preview --ascii`)
+arch compile plan.json --from-json -o out.svg   # compile structured Plan JSON (see /plan.schema.json)
+echo '<source>' | arch compile - -o - -f svg    # compile stdin → SVG on stdout
+arch fix plan.arch --dry-run --json    # preview the machine-applicable diagnostic fixes (drop --dry-run to apply)
+arch suggest plan.arch --json          # advisory door/window statements for unreachable rooms / windowless bedrooms
+arch describe plan.arch --json         # semantic facts: rooms, areas, adjacency, door connections, circulation
+arch lint plan.arch --json             # architectural soundness warnings
+arch validate plan.arch --strict --json           # parse + resolve + lint; --strict fails on warnings (the ship gate)
+arch validate plan.arch --graph g.json --json     # also check interior-door adjacency against an intended graph
+arch repair plan.arch -o fixed.arch    # geometric corrector: furniture out of walls/doorways/swings + change log
+arch fmt plan.arch --write             # canonical formatting
+arch batch a.arch b.arch -f svg --json # render many plans/variants at once → results[]
+arch preview plan.arch -o plan.png     # render a PNG to SHOW the user (--install fetches resvg if missing)
+arch new -o plan.arch                  # scaffold a starter plan
+arch explain E_ROOM_SIZE --json        # look up any diagnostic code
+```
+
+(An optional MCP server, `@chanmeng666/archlang-mcp`, wraps these same library functions for
+MCP-native hosts — prefer the CLI when you have a shell; it costs nothing in context until called.)
+
+## Key rules (full detail in `arch spec`)
+
+- **Units are millimetres** (a 4 m wall is `4000`); **origin top-left, +x right, +y DOWN**.
+- **Attach openings to walls** (`on <wall> at <pos>`) so they always sit on a segment; a raw `at`
+  that lands off any wall warns (and `arch fix` rewrites it).
+- **Fixtures draw real symbols:** `furniture wc|basin|shower|bathtub|kitchen_sink|counter|fridge|stove …`
+  renders a plan symbol; put fixtures in every bath and kitchen so lint stays quiet.
+- **`dims auto`** draws dimension strings for you (`overall`, `rooms`, `walls`, or `all`).
+- Edit is cheap: "make the bedroom 1 m wider" is a one-number change, then recompile.
+
+Treat the CLI as the source of truth — author, render, and verify through it rather than reasoning
+about SVG by hand.
+
+---
+
+## 3. CLI reference
+
+The `arch` CLI is the agent interface. ArchLang compiler — agent-native CLI. Compile .arch floor-plan source to SVG/PNG/PDF/DXF.
+
+Every command takes `--json` (structured result on stdout, messages on stderr) and reads source
+from a file or stdin (`-`). There is intentionally no MCP server — this CLI is the whole API.
+
+**Exit codes:** `0` ok · `1` internal / IO error · `2` user-source error (deterministic — fix it, don't blindly retry) · `3` bad usage
+
+**Global flags:** `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**Output formats (`-f`):** `svg` · `dxf` · `txt` · `pdf` (needs `pdfkit`) · `png` (needs `@resvg/resvg-js`)
+
+### Commands
+
+**`arch compile`** — render a plan to SVG/DXF/PDF/PNG
+  - input: <file.arch|-> (Plan JSON with --from-json) → output: file (or stdout with -o -)
+  - flags: `--out|-o <file|->` output destination ('-' = stdout) · `--format|-f <svg|dxf|txt|pdf|png>` output format (default svg) · `--width|-w <px>` page width hint in pixels · `--cols <n>` text renderer (-f txt / preview --ascii) grid width in characters (default 80) · `--charset <unicode|ascii>` text renderer glyph set (default unicode) · `--overlay <circulation>` draw an opt-in diagnostic overlay (circulation walks + bottleneck markers); default output is unchanged · `--error-svg` on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2) · `--accessible` emit <title>/<desc>/role/aria accessibility metadata (the describe() caption) into the SVG; default output is unchanged · `--from-json` read the input as Plan JSON (RPLAN shape) instead of .arch, convert it, then compile · `--install` auto-install the optional dep for the chosen format if missing (PNG/PDF) · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch batch`** — render many .arch files in one call, concurrently
+  - input: <a.arch> <b.arch> … → output: one file per input; --json gives a results[] array
+  - flags: `--out|-o <dir>` output directory (default: alongside each input) · `--format|-f <svg|dxf|txt|pdf|png>` output format (default svg) · `--jobs|-j <n>` max concurrent renders (default: CPU count) · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch md`** (aliases: `markdown`) — render every ```arch block in a Markdown file and rewrite to image links
+  - input: <doc.md> → output: out.md + one image per block
+  - flags: `--out|-o <out.md>` rewritten Markdown destination · `--format|-f <svg|dxf|txt|pdf|png>` output format (default svg) · `--error-svg` on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2) · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch preview`** — render a PNG you can look at (zero-install where the optional binary is present)
+  - input: <file.arch|-> → output: PNG file (or ASCII text on stdout with --ascii)
+  - flags: `--out|-o <out.png>` PNG destination (default: <name>.png) · `--scale|-s <n>` raster scale (default 2) · `--ascii` print a zero-dependency ASCII text plan to stdout instead of a PNG · `--cols <n>` text renderer (-f txt / preview --ascii) grid width in characters (default 80) · `--charset <unicode|ascii>` text renderer glyph set (default unicode) · `--error-svg` on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2) · `--install` auto-install @resvg/resvg-js if missing, then render · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch watch`** — recompile on save (interactive)
+  - input: <file.arch> → output: file, rewritten on each save
+  - flags: `--out|-o <file|->` output destination ('-' = stdout) · `--format|-f <svg|dxf|txt|pdf|png>` output format (default svg) · `--width|-w <px>` page width hint in pixels
+
+**`arch validate`** — parse + resolve + lint, no render (is it valid & sound?)
+  - input: <file.arch|-> → output: diagnostics (plus a graph{} report with --graph)
+  - flags: `--strict|--fail-on-warning` advisory warnings fail too (exit 2) · `--graph <graph.json>` also check the plan's interior-door adjacency against an intended graph (bare dict or {input_graph:{…}}); mismatch → exit 2 · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch describe`** — semantic facts: rooms, areas, adjacency, what doors connect
+  - input: <file.arch|-> → output: facts (JSON or a summary)
+  - flags: `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch lint`** — architectural soundness warnings
+  - input: <file.arch|-> → output: W_* warnings
+  - flags: `--profile <residential-basic|accessibility-advisory>` advisory ruleset · `--strict|--fail-on-warning` warnings fail (exit 2) · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch ast`** — parse only (no resolve/render) and print the span-bearing AST as JSON
+  - input: <file.arch|-> → output: AST JSON (scripting nodes unexpanded)
+  - flags: `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch complete`** — completion items in scope at a source byte offset (the LSP completion() core)
+  - input: <file.arch|-> → output: { items: [...] } completion items
+  - flags: `--at <byteOffset>` source byte offset to list completions at (required) · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch fmt`** — canonical formatting
+  - input: <file.arch|-> → output: formatted source (or in place with --write)
+  - flags: `--write` format the file in place · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch repair`** — explicit source-to-source corrector (furniture out of walls) + change log
+  - input: <file.arch|-> → output: corrected source + change log on stderr
+  - flags: `--out|-o <file|->` output destination ('-' = stdout) · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch fix`** — apply the machine-applicable fix suggestions on a plan's diagnostics (bounded fixpoint)
+  - input: <file.arch|-> → output: fixed source (to the input file or -o) + change log on stderr
+  - flags: `--out|-o <file|->` output destination ('-' = stdout) · `--unsafe` also apply `maybe-incorrect` fixes (default: machine-applicable only) · `--dry-run` compute the result but do not write it · `--force` keep a pass even if it raises the error count · `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch suggest`** — advisory topology suggestions as data (door/window statements that resolve reachability/window faults)
+  - input: <file.arch|-> → output: suggestions (JSON or a summary)
+  - flags: `--json` structured result on stdout, messages on stderr · `--quiet|-q` suppress human messages on stderr
+
+**`arch manifest`** (aliases: `capabilities`) — this document: the whole CLI API as structured data
+  - input: none → output: the manifest (JSON or a summary)
+  - flags: `--json` structured result on stdout, messages on stderr
+
+**`arch spec`** — print the one-prompt language spec (spec.llm.md)
+  - input: none → output: the spec
+  - flags: `--json` structured result on stdout, messages on stderr
+
+**`arch context`** — print the full bundled agent context (spec + workflow + CLI + errors)
+  - input: none → output: the full agent context (llms-full.txt)
+  - flags: `--json` structured result on stdout, messages on stderr
+
+**`arch new`** (aliases: `init`) — scaffold a starter .arch
+  - input: none → output: starter source
+  - flags: `--out|-o <file>` write the starter here · `--force` overwrite an existing file · `--json` structured result on stdout, messages on stderr
+
+**`arch explain`** — look up an error code (cause / fix / example)
+  - input: <CODE> → output: catalog entry
+  - flags: `--json` structured result on stdout, messages on stderr
+
+---
+
+## 4. Diagnostic catalog
+
+Every diagnostic carries a stable code and a `fix`. Look one up with `arch explain <CODE>`.
+**43 errors** (abort rendering) · **31 warnings** (advisory; `validate --strict` fails on them too).
+
+### Errors
+
+- `E_ACC_PLACEMENT` — `accTitle`/`accDescr` used outside the plan level. **Fix:** Move the `accTitle`/`accDescr` line up to the plan body, alongside `units`/`north`.
+- `E_ARGCOUNT` — Component called with the wrong number of arguments. **Fix:** Pass exactly one argument per declared parameter.
+- `E_ARITY` — Built-in function called with the wrong number of arguments. **Fix:** Check the function's arity; most built-ins take one argument.
+- `E_ASSIGN_UNDEF` — Assignment to an undeclared name. **Fix:** Declare it first with `let`, or fix a typo in the name.
+- `E_ATTACH_POS_RANGE` — Opening attachment position is out of range. **Fix:** Use a percentage in 0–100%, a millimetre distance within the wall's run, or `center`.
+- `E_ATTACH_WALL_REF` — Opening attached to an unknown or ambiguous wall. **Fix:** Reference an existing, unique wall id (add `id=` to the wall if needed).
+- `E_CALL_DEPTH` — Value-function call stack too deep. **Fix:** Make the recursion terminate, or rewrite it iteratively with a bounded `while`.
+- `E_COLUMN_SIZE` — Column must have a positive size. **Fix:** Give the column a positive `size W x H`.
+- `E_DIV_ZERO` — Division or modulo by zero. **Fix:** Guard the divisor, or use a non-zero value.
+- `E_DOMAIN` — Math domain error. **Fix:** Pass a value within the function's domain.
+- `E_DOOR_WIDTH` — Door must have a positive width. **Fix:** Give the door a positive `width`.
+- `E_DUP_ID` — Duplicate element id. **Fix:** Rename one of them, or drop the explicit id to auto-generate a unique one.
+- `E_FURN_AGAINST` — Invalid `against wall` fixture placement. **Fix:** Name an existing wall id, add `segment <n>` for multi-segment walls, give `side left|right`, keep the segment axis-aligned, and drop any explicit `rotate`.
+- `E_FURN_ROOM` — Furniture placed `in` an unknown room. **Fix:** Use the id of an existing `room id=…`, or drop the `in` clause.
+- `E_FURN_ROTATE` — Furniture rotation must be a quarter-turn. **Fix:** Use a quarter-turn: `rotate 0|90|180|270`.
+- `E_FURN_SIZE` — Furniture must have a positive size. **Fix:** Give the item a positive `size W x H`.
+- `E_IMPORT_BAD_SPEC` — Malformed import spec. **Fix:** Use a relative path ("lib/x.arch") or a namespaced spec ("@scope/name:1.0.0").
+- `E_IMPORT_CONFLICT` — Imported name conflicts with an existing component. **Fix:** Rename with `as`, or remove the duplicate.
+- `E_IMPORT_CYCLE` — Cyclic import. **Fix:** Break the cycle so module dependencies form a tree.
+- `E_IMPORT_NOT_EXPORTED` — Imported name is not exported by the module. **Fix:** Import a name the module actually defines (check its `component`s).
+- `E_IMPORT_NOT_FOUND` — Import path could not be resolved. **Fix:** Check the path (relative to the importing file) and that the file exists.
+- `E_IMPORT_PARSE` — Imported module has a parse error. **Fix:** Fix the syntax error in the imported module.
+- `E_INDEX` — Array index out of range. **Fix:** Clamp or check the index against `len(arr)`.
+- `E_JSON_KIND` — Unknown element kind in plan JSON. **Fix:** Use one of the supported kinds: opening `kind` must be `door` | `window` | `opening`.
+- `E_JSON_SCHEMA` — Plan JSON does not match the schema. **Fix:** Fix the value at the reported JSON path (the message names it, e.g. `/rooms/0/width`); express geometry as concrete numbers, and author scripting/imports in `.arch` source instead.
+- `E_LAYOUT_CYCLE` — Relational room placement forms a cycle. **Fix:** Break the cycle by giving one of the rooms absolute `at (x,y)` coordinates.
+- `E_LAYOUT_REF` — Relational placement references an unknown room. **Fix:** Reference an existing room id, or fix the typo.
+- `E_OPENING_WIDTH` — Opening must have a positive width. **Fix:** Give the opening a positive `width`.
+- `E_PLACE_REF` — Furniture placed in an unknown or non-absolute room. **Fix:** Reference an existing room given absolute `at (x,y)` coordinates.
+- `E_PNG_DEPENDENCY` — PNG/PDF export needs an optional dependency that is not installed. **Fix:** Install the optional dependency (`npm install @resvg/resvg-js`), or re-run with `--install` to fetch it automatically, or render to SVG/DXF (zero-dependency).
+- `E_RANGE_LIMIT` — Range too large. **Fix:** Use a smaller range, or restructure to avoid materializing it.
+- `E_RECURSION` — Component recursion too deep. **Fix:** Add a base case so the recursion terminates.
+- `E_REDEF` — Name already defined in this scope. **Fix:** Rename one binding, or use `NAME = …` to reassign instead of redeclaring.
+- `E_ROOM_SIZE` — Room must have a positive size. **Fix:** Give the room a positive `size W x H`.
+- `E_STRIP_NEST` — Illegal `strip` nesting. **Fix:** Move the `strip` to the plan body, alongside the other elements.
+- `E_STRIP_SIZE` — Room in a `strip` is missing a size. **Fix:** Give the room a `size <main>` (main-axis extent) plus either a strip `height`/`width` or its own `size <main>x<cross>`.
+- `E_TYPE` — Type mismatch. **Fix:** Convert or supply the expected type.
+- `E_UNKNOWN_COMPONENT` — Unknown component. **Fix:** Define the component, import it, or fix the name (see the suggestion hint).
+- `E_UNKNOWN_FN` — Unknown function. **Fix:** Define it with `let f(…) = …`, or fix the name.
+- `E_UNKNOWN_REF` — Unknown reference. **Fix:** Declare it with `let`, pass it as a parameter, or fix the typo.
+- `E_WALL_THICKNESS` — Wall must have a positive thickness. **Fix:** Give the wall a positive `thickness`.
+- `E_WHILE_LIMIT` — `while` exceeded its iteration cap. **Fix:** Ensure the loop body updates a binding so the condition eventually fails.
+- `E_WINDOW_WIDTH` — Window must have a positive width. **Fix:** Give the window a positive `width`.
+
+### Warnings
+
+- `W_BATH_VIA_BEDROOM` — Bathroom is reachable only through a bedroom. **Fix:** Add a door connecting the bathroom to a hall/living space, or route circulation so it is not reached only via a bedroom.
+- `W_BEDROOM_NO_WINDOW` — Bedroom has no window. **Fix:** Add a `window` on an exterior wall of the room.
+- `W_CIRCUITOUS_PATH` — A room is reached by a very roundabout path. **Fix:** Add a more direct connection — a door or a hall — so the room is not reached the long way round.
+- `W_DOOR_CLEARANCE` — Door is narrower than the minimum clear width. **Fix:** Widen the door to at least the minimum clear width.
+- `W_DOOR_OFF_WALL` — Door does not lie on any wall. **Fix:** Move the door onto a wall, or name its host with `wall <id|category>`. The diagnostic points at the nearest wall.
+- `W_DOORWAY_BLOCKED` — A doorway's landing is blocked. **Fix:** Clear the space directly in front of and behind the door, or move the door.
+- `W_DUP_ACC_METADATA` — Duplicate `accTitle`/`accDescr`. **Fix:** Keep a single `accTitle` and a single `accDescr`; delete the extra line(s).
+- `W_EMPTY_PLAN` — Empty plan. **Fix:** Add at least one element (wall, room, …).
+- `W_FIXTURE_FLOATING` — A plumbing/kitchen fixture is not against a wall. **Fix:** Move the fixture so one edge is against a wall (supply/waste/venting runs in the wall), or remove it.
+- `W_FIXTURE_WRONG_ROOM` — Fixture sits outside its declared room. **Fix:** Move the fixture inside the named room, or correct the `in <roomId>`.
+- `W_FURN_CLEARANCE` — A fixture's use-space is blocked. **Fix:** Leave the catalogued clearance clear in front of the fixture, or move the obstructing furniture.
+- `W_FURNITURE_OVERLAP` — Two pieces of furniture overlap. **Fix:** Move or resize one so they no longer intersect; leave a walkway between them.
+- `W_FURNITURE_WALL_COLLISION` — Furniture penetrates a wall. **Fix:** Move or resize the piece so it sits fully inside the room (against the wall face, not through it), or anchor it with `against wall <id>`.
+- `W_HATCH_SCALE` — Hatch scale must be positive; using 1. **Fix:** Use a positive `scale`.
+- `W_NO_ENTRANCE` — The plan has no exterior door. **Fix:** Add a `door` on an `exterior` wall.
+- `W_OPENING_OFF_WALL` — Opening does not lie on any wall. **Fix:** Move the opening onto a wall, or name its host with `wall <id|category>`. The diagnostic points at the nearest wall.
+- `W_PATH_TOO_NARROW` — The walk to a room squeezes below a passable width. **Fix:** Widen the tightest door/opening on the route, or move the furniture pinching it, so the whole path clears the minimum width.
+- `W_ROOM_DISCONNECTED` — Room has no door — it can't be entered. **Fix:** Add a `door` on one of the room's walls.
+- `W_ROOM_NO_CLEAR_PATH` — A room cannot be entered or crossed. **Fix:** Open up the layout: move or shrink the furniture nearest the door so there is a continuous walkable strip from each entrance into the room.
+- `W_ROOM_NO_FIXTURE` — Bathroom or kitchen has no fixtures. **Fix:** Place the expected fixtures — e.g. import `lib/fixtures.arch` and add a `wc`, `basin`, `shower`, or `kitchen_sink`.
+- `W_ROOM_NOT_ENCLOSED` — Bathroom is not fully enclosed. **Fix:** Extend the partition so the room's perimeter is walled on all sides (a door/window in the wall is fine — only a missing wall counts).
+- `W_ROOM_OVERLAP` — Rooms overlap. **Fix:** Adjust positions/sizes if the overlap is unintended (it is allowed).
+- `W_ROOM_TOO_SMALL` — Room is implausibly small. **Fix:** Increase its `size`, or merge it into an adjacent space.
+- `W_ROOM_UNREACHABLE` — Room cannot be reached from the entrance. **Fix:** Add a door or cased `opening` linking it (directly or through a hall) to a space that reaches the entrance.
+- `W_SANITIZED_CONFIG` — A disallowed config value was stripped. **Fix:** Use a plain colour/string value (no `<`, `>`, or `url(data:…)`).
+- `W_SWING_OBSTRUCTED` — Door swing is obstructed. **Fix:** Move the door or the obstruction, flip the `hinge`/`swing`, or use a sliding door so the leaf clears.
+- `W_SWING_ROOM_NOT_ADJACENT` — `swing into <room>` names a room the door does not border. **Fix:** Point `swing into` at a room the door actually opens onto, or use explicit `swing in|out`. The door falls back to its default swing.
+- `W_UNKNOWN_MATERIAL` — Unknown wall material; using the default hatch. **Fix:** Use a known material (e.g. brick, concrete, insulation, tile) or omit it.
+- `W_UNKNOWN_STYLE_KEY` — Unknown style key. **Fix:** Use a valid key (e.g. fill / stroke / label, depending on the kind).
+- `W_UNKNOWN_THEME_KEY` — Unknown theme key. **Fix:** Use a known theme key (see the language reference / hover).
+- `W_WINDOW_OFF_WALL` — Window does not lie on any wall. **Fix:** Move the window onto a wall, or name its host with `wall <id|category>`. The diagnostic points at the nearest wall.