# 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 ` x ` 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 thickness [material ] { (x,y) (x,y) … [close] } # category e.g. exterior/partition; `close` makes a loop room [id=] at (x,y) size x [label "…"] [uses living|kitchen|dining|bedroom|bath|wc|hall|circulation|storage|utility|office|entry …] # OR relational: room [id=…] (right-of|left-of|below|above) [align top|middle|bottom|left|right] [gap ] size x [label "…"] door [id=] at (x,y) width [wall ] [hinge left|right] [swing in|out] # must sit on a wall window [id=] at (x,y) width [wall ] # must sit on a wall opening [id=] at (x,y) width [wall ] # a leaf-less cased opening (gap in a wall) that still connects the two spaces furniture (at (x,y) | against wall [segment ] [offset ] [side left|right]) [size x] [label "…"] [rotate 0|90|180|270] [in ] # `at` size is plan W×H; `against` size is wall-relative along×depth and derives position+rotation, with `side` inferred from `in ` 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 [text "…"] # a dimension line column [id=] at (x,y) size x ``` ## 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 (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 '' | 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 ` (+ `in `) 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 at …` / `window on at …` / `opening on at …`, where `` is millimetres along the wall or a percentage (`50%`). `swing into ` 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 in anchor [inset ] …` snaps a piece flush to a room corner/edge; `against wall ` 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 at ` into a living/kitchen/hall with an exterior edge (avoids routing through a bedroom); else (2) a `door on at ` to an adjacent reachable, non-bedroom room; and give a windowless bedroom a `window on at 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 '' | 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 at `) 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: (Plan JSON with --from-json) → output: file (or stdout with -o -) - flags: `--out|-o ` output destination ('-' = stdout) · `--format|-f ` output format (default svg) · `--width|-w ` page width hint in pixels · `--cols ` text renderer (-f txt / preview --ascii) grid width in characters (default 80) · `--charset ` text renderer glyph set (default unicode) · `--overlay ` 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