llms.txt git:20260712.8a7dd72A

Immutable. This exact content never changes and is served at /api/v1/blob/92bf5c30f36d8db8.

# ArchLang

> A small declarative language that compiles to professional SVG floor plans — like Typst/LaTeX, but for architecture.

This file follows the [llms.txt](https://llmstxt.org/) convention: a concise, machine-readable map
of the project for large language models and AI agents.

## About

- Repository: https://github.com/chanmeng666/archlang
- Primary stack: Node.js / JavaScript
- License: MIT

## Key documents

- [README](https://github.com/chanmeng666/archlang/blob/main/README.md): overview, features, installation, usage
- [spec.llm.md](https://github.com/chanmeng666/archlang/blob/main/spec.llm.md): the WHOLE language in one page (~2k tokens) — read this to author `.arch`
- [llms-full.txt](https://archlang-docs.vercel.app/llms-full.txt): the full agent context in one document — the spec, the workflow skill, the CLI reference, and every diagnostic code (also at `/llms-full.txt`)
- [SKILL.md](https://github.com/chanmeng666/archlang/blob/main/SKILL.md): the agent skill — how to drive ArchLang via the CLI
- [AGENTS.md](https://github.com/chanmeng666/archlang/blob/main/AGENTS.md): how AI agents should work in this repo
- [CONTRIBUTING](https://github.com/chanmeng666/archlang/blob/main/CONTRIBUTING.md): development setup and contribution workflow
- [CHANGELOG](https://github.com/chanmeng666/archlang/blob/main/CHANGELOG.md): version history

## Machine-native artifacts (served at the docs-site root)

- [/plan.schema.json](https://archlang-docs.vercel.app/plan.schema.json): JSON Schema (2020-12) for **Plan JSON** — the structured compile input (`arch compile --from-json`)
- [/intent.schema.json](https://archlang-docs.vercel.app/intent.schema.json): JSON Schema (2020-12) for an **Intent** — a brief's checkable expectations as data (`arch validate --intent` / `arch score --brief`)
- [/archlang.gbnf](https://archlang-docs.vercel.app/archlang.gbnf): **GBNF** constrained-decoding grammar — force a local model to emit only parseable ArchLang
- **Append `.md` to any generated doc route for raw markdown**: e.g. [/spec.md](https://archlang-docs.vercel.app/spec.md), `/reference.md`, `/errors.md`, `/analysis.md`, `/furniture.md`
- **MCP server** — [`@chanmeng666/archlang-mcp`](https://www.npmjs.com/package/@chanmeng666/archlang-mcp): an optional stdio MCP shim over the library (tools: compile/describe/lint/validate/repair/fix/suggest/complete; resources: spec/context/schema/grammar). The CLI stays the primary, token-cheaper interface — see the README's agent section
- **Dataset** — [`ChanMeng666/archlang-repair-trajectories`](https://huggingface.co/datasets/ChanMeng666/archlang-repair-trajectories): a fully synthetic, self-verifying corpus — `repair` trajectories (broken source + diagnostics → deterministically healed source) + `authoring` pairs (brief → golden + intent), CC0-1.0; generator + seed open source in `dataset/`

## To USE ArchLang (author floor plans)

ArchLang is agent-native via its CLI — no server required, nothing to configure (an optional MCP shim exists for MCP-native clients; the CLI stays primary):

```bash
npx @chanmeng666/archlang context              # cold start: the whole bundled agent context (spec + skill + CLI + errors) in one call
npx @chanmeng666/archlang spec                 # learn the whole language (read this first)
npx @chanmeng666/archlang manifest --json      # the whole CLI API as data: commands, flags, formats, lint rules, error codes
npx @chanmeng666/archlang compile plan.arch -o out.svg --json   # render; JSON: { ok, diagnostics, summary }
npx @chanmeng666/archlang preview plan.arch -o out.png --json   # render a PNG to SHOW the user (zero-install where resvg is present; --install fetches it)
npx @chanmeng666/archlang describe plan.arch --json             # verify: rooms, areas, adjacency, door connections, circulation
npx @chanmeng666/archlang lint plan.arch --json                 # architectural soundness warnings
npx @chanmeng666/archlang validate plan.arch --strict --json    # parse + lint, no render; --strict fails on warnings (the ship gate)
npx @chanmeng666/archlang fix plan.arch --dry-run --json        # preview the machine-applicable diagnostic fixes (drop --dry-run to apply)
npx @chanmeng666/archlang suggest plan.arch --json              # advisory door/window topology statements for unreachable rooms / windowless bedrooms
npx @chanmeng666/archlang score plan.arch --brief intent.json --json   # continuous intent-satisfaction meter against a brief (satisfied/total; exit 0)
npx @chanmeng666/archlang repair plan.arch -o fixed.arch        # explicit corrector: furniture out of walls/doorways/swings + change log
npx @chanmeng666/archlang compile plan.arch -o walk.svg --overlay circulation   # opt-in: draw the walkability routes on top
npx @chanmeng666/archlang batch a.arch b.arch -f svg --json     # render many plans/variants at once → results[]
npx @chanmeng666/archlang md notes.md -o out.md -f svg          # render fenced arch blocks in Markdown → image links
```

Loop: `spec` → write `.arch` → `compile --json` → if `ok:false` (exit 2) fix via each
`diagnostics[].fix` → `describe --json` to confirm intent → `preview` to show the user a raster →
`lint --json` to confirm soundness. `manifest --json` is the one-call API map; `batch`/`md` cover
variant exploration and embedding plans in Markdown. See
[SKILL.md](https://github.com/chanmeng666/archlang/blob/main/SKILL.md).

In CI, the in-repo composite Action `ChanMeng666/archlang/.github/actions/arch-render@<tag>` renders
every ```` ```arch ```` fence in a repo's Markdown to images in one step (see
[.github/actions/arch-render/README.md](https://github.com/chanmeng666/archlang/blob/main/.github/actions/arch-render/README.md)).

`lint` catches tacit architectural mistakes, not just syntax: a bathroom reached only through a
bedroom, a wet room that isn't fully walled in, a door swing hitting furniture, a bath/kitchen with
no fixtures, a windowless bedroom, an unenterable room, a too-narrow door, a room use only inferred
from an indirect label alias (`W_ALIAS_MATCH`, with a fix that pins the explicit `uses`), plus **human-circulation**
checks — a walk that squeezes below a passable width (`W_PATH_TOO_NARROW`) or wanders far from a
straight line (`W_CIRCUITOUS_PATH`), measured on a clearance-eroded nav grid and also readable as
facts from `describe().circulation` (per-room walk distance / bottleneck width / detour) or drawn with
`compile --overlay circulation`. Draw real fixtures with
`furniture wc|basin|shower|bathtub|kitchen_sink|counter|fridge|stove …` (or the `lib/fixtures.arch`
library), and let `dims auto` place dimension strings for you.

## To CONTRIBUTE (work on the repo)

Read the README and AGENTS.md first, then follow the commands and conventions they describe. Prefer
the project's own scripts over ad-hoc commands.