cadcraft git:20261101.18741c7A

Immutable. This exact content never changes and is served at /api/v1/blob/294ab5939cff95d2.

---
name: cadcraft
description: >-
  CADCraft is an open-source, clean-room AutoCAD-style 2D CAD and drafting app (pure Rust, egui)
  for macOS, Windows, Linux, FreeBSD and the browser, with DXF/DWG file support and first-class
  agent control over MCP, a JSON control channel and a headless CLI. Trigger this skill whenever
  the user mentions CADCraft (or "the CAD app"), asks what it can or cannot do, which file formats
  it opens or writes, its keyboard shortcuts or commands, wants to draw, edit, dimension, hatch,
  block, xref, lay out, plot or export a drawing, convert/inspect/verify a DXF or DWG, script or
  automate drafting (AutoLISP, .scr scripts, .pgp aliases, MCP, control channel, cadcraft-cli),
  prepare assets for it, or troubleshoot it — and also when they describe the job without naming
  the app ("draw a floor plan", "edit this DXF", "convert this DWG to PDF/PNG", "put dimensions on
  this drawing", "check this drawing opens elsewhere").
---

# CADCraft

Audit basis: this checkout is tag `v0.15.1`, commit `660e15c9f494ce647e87de10adbb01a8786e0901` ("Release 0.15.1", 2026-10-31). The installed `/Applications/CADCraft.app` still reports version `0.14.0` (bundle id `ai.storyteller.cadcraft`) and prints `cadcraft 0.14.0 (fbd97d4…)` — **the installed bundle lags this tag.** **Verify against your installed version** — the ArtCraft Launcher auto-updates.

v0.15.0–0.15.1 adds **`chprop`** (change properties at the command line, as AutoCAD asks for them, #2497) and **`solid`** (2-D solids drawn and chained as AutoCAD chains them, #2489) — 442 → 444 engine commands — plus **`-UNITS`** with surveyor bearings (#2562), **PEDIT Multiple** (#2225), **BEDIT switching blocks** (#2219), MEASURE picking its start end by curve parameter (#2207), dimensions reporting their measurement as soon as one is created (#2421), DWG keeps the current layer through save/reopen (#2407) and block draw-order sort handles through the DXF bridge (#2439), **DXF saves pre-2007 text in the file's code page** instead of `\U+` escapes, extents count turned-off layers (#2485) and an MTEXT's wrap width only narrows its box (#2491), annotative text with Match-orientation-to-layout draws upright (#2504), **saving over a DWG asks before losing content and keeps a `.bak`** (#2518), backups of same-named drawings no longer overwrite each other (#2537), Ctrl/Cmd+W closes the drawing (#2057), Enter runs the highlighted command suggestion (#2135), LISP entity names answer object-picking prompts and angle variables are radians (#2477/#2482), and a hardening wave bounds the MCP client's reply read and the control server's buffer (#1925). There is no `references/` directory: all detail is here with repo-relative evidence paths, and `evidence.md` beside this file tiers each claim (implemented / partial / claimed-absent).

## Overview

CADCraft is an open-source (MIT OR Apache-2.0) 2D CAD and drafting application written in Rust (egui/eframe — migrated to egui 0.37 this release, wgpu) for macOS, Windows, Linux, FreeBSD and the web; source is GitHub `storytold/cadcraft`. It is a clean-room reimplementation of Autodesk AutoCAD targeting AutoCAD 2027, 2D drafting first (`AGENTS.md` clean-room rules, `docs/target-app-parity.md`). Stage: **pre-alpha** — four of AutoCAD's five core workflows fail the alpha gate (`ROADMAP.md`).

The differentiator: every user-visible action is a command. The engine registry holds **442** commands (`docs/parity-checklist.md` — repo-generated by `cargo xtask parity` from live `cadcraft-cli commands` output), the desktop app's catalog adds **57** UI-only entries for **499** total, and the same ids are reachable from the command line, the JSON control channel, the MCP server and `cadcraft-cli`.

**Release delta vs v0.13.0 (measured, not copied).** Registered commands **441 → 442** (+1; generated checklist); menu breadth **296/491 → 297/491 (60 %)**; static `CommandSpec::new(` sites **425 → 428**; the `gc!`/`dc!` constraint macros are unchanged (12 + 6); MCP tools 15 and control methods 27 app / 12 headless are **unchanged**; CLI verbs **7**, now **parsed with clap following RFC-0012** (same surface, standard clap usage errors); `acadrust` stays **0.6.5**. Landed this release: **Blocks ▸ Modify ▸ Object ▸ Block Description…** and the Block Editor saving a changed description (PR #2113); **View ▸ Viewports ▸ Named Viewports…** (lists, restores and deletes saved viewport configurations, PR #2175); **LAYOUT's SAveas saves a layout as a drawing template** (PR #2177); **AREA and DIST gained an Arc option** that measures arc segments (PR #2193) and AREA refuses values past f64's range (PR #2162); the DXF writer escapes literal `\U+`/`\M+` backslashes (PR #2050); the drawing's `WIPEOUTFRAME` is read from its `WIPEOUTVARIABLES` object (PR #908); dynamic-block element tags read from the entity's own xdata (PR #967); associative-array parameters survive an xref load (PR #966); table commands reject a malformed handle instead of using the selected table (PR #970); in-place text editing accepts IME composition and commit (PR #1905); the MCP bridge resends once when the app refuses a token read before `--launch` opened it (PR #2098); CLI `--save`, `convert` and `sample` write through a staged file so a failed write keeps the previous drawing (PR #982); PNG export runs hairline polyline strokes as one path (faster, PR #2331); side panels dock in left/right columns and macOS Edit-menu keys edit a focused text field; the startup update prompt with self-update landed (PR #2141); Windows installs per-user by default (PR #2230).

**Why 428 sites but 442 commands** — do not "correct" one number to the other: two `CommandSpec::new(` occurrences are the bodies of the `gc!`/`dc!` macros, and those macros are invoked 18 times (12 `gc!`, 6 `dc!`) in the constraints module. 428 − 2 + 18 = 444 ≠ 442 — the generated checklist (442) counts the *live* registry, which is the number to quote for capability claims; the site arithmetic brackets it.

## Capabilities (verified)

Everything below is implemented and wired to a command/CLI/MCP/control surface unless marked **partial** or **claimed**; `evidence.md` gives the per-claim tier.

### Drawing, editing and precision

- **Draw:** LINE, PLINE (arcs, widths), CIRCLE (center/radius/diameter, 2P, 3P), ARC, RECTANG (fillet/chamfer), POLYGON, ELLIPSE (+arcs), SPLINE, POINT, XLINE, RAY, DONUT, TEXT, MTEXT, plus MLINE, REGION and HELIX (`crates/engine/src/cmd/draw*.rs`).
- **Modify:** ERASE, MOVE, COPY, ROTATE, SCALE, MIRROR, STRETCH, OFFSET, TRIM, EXTEND, FILLET, CHAMFER, BREAK, JOIN, EXPLODE, rectangular/polar ARRAY (associative, ARRAYEDIT; ARRAYPATH exists but is not associative), draw order, OVERKILL, LENGTHEN, ALIGN, REVERSE, FLATTEN, CHSPACE; Express Tools NCOPY, BREAKLINE, TXT2MTXT, BURST, MOCORO.
- **Precision:** 14 object snaps with deferred tangent/perpendicular; object snap tracking; polar tracking; ortho; grid snap; direct distance entry; `@dx,dy`, `@d<a`, `#x,y`; point modifiers FROM/M2P/TK; typed snap overrides (`crates/engine/src/snap.rs`).
- **Command line and grips:** prompts with clickable keywords, history (F2), AutoComplete, aliases (`.pgp` + ALIASEDIT/REINIT), transparent commands, `.scr` scripts; hot grips cycle Stretch/Move/Rotate/Scale/Mirror. Hex handle and colour parsing rejects a leading `+`; `wcmatch` handles patterns with many `*` wildcards; `format_angle` no longer zeroes radians near a full turn at low precision; a Fix on a derived point holds its pre-edit position.
- **Layers and properties:** Layers palette and Layer Properties Manager, layer tools, saved layer states, Properties palette, linetypes, lineweights, ACI/true colour, transparency, OPTIONS dialog with persisted profiles.
- **Annotation:** the DIM* family (linear, aligned, angular, arc, diameter, radius, ordinate, jogged, continue, baseline, QDIM, DIMEDIT/DIMTEDIT, DIMBREAK, DIMINSPECT, DIMSTYLE, DIMREASSOCIATE, DIMTFILL/DIMTFILLCLR); MLEADER family; TABLE with formulas, cell styles, TABLEDIT/TABLEEXPORT, table breaking and CSV data links (tables now reject malformed handles); TOLERANCE; annotative scaling; on-canvas MTEXT editor; QuickCalc palette; COMPARE and COMPAREEXPORT. **GETVAR CECOLOR reads back as text, as in AutoCAD** (PR #2069).
- **Hatch, blocks, xrefs:** pick-point HATCH with islands, HATCHEDIT, 23 standard patterns, solid and gradient fills (HATCH spline edge degree capped at 10 like the SPLINE reader), user `.pat` files; BLOCK/INSERT/ATTDEF, BATTMAN, ATTSYNC, ATTEDIT, DATAEXTRACTION/EATTEXT, nested blocks, groups, WBLOCK, PURGE; xrefs (XATTACH, -XREF, XBIND, XOPEN, overlays, relative paths); Block Editor for static blocks (BEDIT/BSAVE/BSAVEAS/BCLOSE) — **now saving a changed block description, editable through Modify ▸ Object ▸ Block Description…**; REFEDIT/REFSET/REFCLOSE; dynamic blocks read from other files with visibility/lookup/custom-property edits and grips (element tags now read from the entity's own xdata).
- **Layouts and plotting:** paper-space layouts, polygonal/object/clipped viewports (VPCLIP, VPLAYER), MSPACE/PSPACE, page setups, PLOT dialog, Plot Preview, EXPORTPDF, PUBLISH, PDFBOOK, plot styles (CTB/STB) and plotter devices — **plus the Named Viewports dialog (lists/restores/deletes saved viewport configurations) and LAYOUT SAveas to a drawing template**. PLOTWINDOW picks both corners even with ORTHO on.
- **Inquiry:** **AREA and DIST measure arc segments with the Arc option; AREA refuses values past f64's range**; long engineering-unit distances fall back to decimal.
- **Parametric:** geometric and dimensional constraints, AUTOCONSTRAIN, CONSTRAINTBAR, DELCONSTRAINT, PARAMETERS with expressions, re-solve after edits, `constraints.inspect`/`constraints.dof`; an ellipse solution stored with its axes swapped or mirrored still meets every constraint (PR #2082). Region intersection tests very long segments against every segment (PR #975); circle intersection judges tangency against the smaller circle (PR #976).
- **AutoLISP:** `.lsp` via APPLOAD (with a `.lsp` file browser), `(load)`, drag-and-drop, or the `lisp`/`appload` commands; `(defun c:NAME)`; startup files; `command`, `entget/entmake/entmod`, `ssget` filters, `get…` input, `vl-*` functions, `tblsearch/tblnext`. No Visual LISP ActiveX, DCL dialogs, reactors or Startup Suite.
- **Grid stability:** the grid index no longer overflows its span with a very large view (PR #979); complex text shaping omits empty outlines (PR #1960).

### Files and formats (exact, from code)

- **Open/read:** DXF ASCII R12–2018 and binary R13+; pre-2007 files decode from `$DWGCODEPAGE`. DWG by content magic through the `acadrust` **0.6.5** bridge (MPL-2.0, unmodified; R13/R14 untested, pre-R13 not read). SVG and gzipped SVGZ (shapes, paths, groups, Inkscape layers; no CSS, `use`, fills/gradients/patterns, text, images).
- **Save/native:** DXF is the native path — ASCII or binary, versions 2000–2018; DWG write 2000–2018. `.dwt` templates save via SAVEAS; NEW/QNEW accept `.dwt`/`.dxf` templates; **LAYOUT SAveas writes a layout as a drawing template**. The DXF writer escapes literal `\U+`/`\M+` backslashes. **CLI `--save`, `convert` and `sample` write through a staged file so a failed write keeps the previous drawing.**
- **Unmodelled content:** DXF writes back unknown entities/objects, foreign xdata, extension dictionaries, reactors, layer states and colour books; through **DWG** the bridge drops custom-class entities/objects, xdata on table records and blocks, entity colour books and reactors. SAVE/SAVEAS report what the target cannot hold in a `notSaved` field.
- **Import:** another DXF/DWG's objects via `import`; user `.lin`, `.pat` and `.pgp` files. SVG/SVGZ is read by `open`. Stored xref/data-link paths resolve through `craft-docpath`.
- **Export:** SVG; PNG 2400×1600 (faster: hairline polyline stroke runs share one path); vector PDF with embedded TrueType text subsets, OCG layers, multi-sheet output, hyperlinks and plotted transparency. EXPORT, EXPORTPDF, PUBLISH, PDFBOOK, PLOT, PREVIEW and `cadcraft-cli convert`; they return base64 `data` when no path is given. CLI image/PDF export always renders **model space**.

### Automation surfaces (all over the same command registry)

- **Command catalog.** `engine.commands` / `cadcraft-cli commands` return id, label, menu path, shortcut, aliases, parameter docs and enabled state. Headless/CLI catalog = **442** engine commands; the desktop app's catalog adds **57** `UI_COMMANDS` (**499** entries). Ids are AutoCAD command names lower-cased.
- **MCP server (stdio).** `cadcraft-cli mcp` (headless) or `cadcraft-cli mcp --connect 127.0.0.1:PORT [--lazy] [--launch]`. **15 tools** — 12 headless, plus 3 only when connected: `command_line`, `script`, `execute`, `list_commands`, `inspect_drawing`, `query_entities`, `render`, `find_text`, `new_drawing`, `open`, `save`, `cancel`, and app-only `screenshot`, `ui_inspect`, `ui_click`. **New:** the bridge resends once when the app refuses a token read before `--launch` opened it (PR #2098). Resources: `cadcraft://drawing` and `cadcraft://commands`.
- **JSON control channel.** Desktop app with `--control PORT`; one JSON object per line over `127.0.0.1:PORT`. **Every request must carry `"token": "<session token>"`** (unchanged this release — the server starts with a fresh session token in an owner-only file, `cadcraft-control-<port>.token`, in `$XDG_RUNTIME_DIR` (else `~/.cache`; `%LOCALAPPDATA%` on Windows); its path is logged at startup; the MCP bridge reads it automatically). **27 top-level methods** in the app, **12** in headless mode: `cmdline.input/script/key/state`, `engine.execute` (alias `command`), `engine.commands`, `drawing.inspect`, `ui.inspect`, `ui.elements`, `ui.menu.list`/`invoke`, `ui.pointer`, `ui.click`, `ui.move`, `ui.drag`, `ui.key`, `ui.text`, `ui.set`, `ui.resize`, `ui.focus`, `ui.screenshot`, `ui.render`, `app.open`/`save`/`quit`, `control.methods`, `ping`. Limits: 16 connections, 64 queued requests, 256 MiB/line, 60 s reply timeout (`state: not-run` = safe to resend, `may-have-run` = inspect first), 10 min idle, 30 s blocked-write timeout.
- **CLI `cadcraft-cli`** (separate zip; **arguments now parsed with clap following RFC-0012**): **7 verbs** — `info`, `convert`, `run`, `commands`, `mcp`, `perf`, `sample` — plus `--version`/`--help`.

| Command | What it does |
|---|---|
| `info FILE` | Print `drawing.inspect` JSON. |
| `convert IN OUT.(dxf\|dwg\|svg\|png\|pdf) [--window … \| --view extents\|current]` | Conversion / image export; PNG 2400×1600; model space only. |
| `run [FILE \| --sample \| --metric] [--script TEXT] [--script-file F.scr] [--cmd 'id {json}']… [--save OUT] [--export OUT] [FRAMING]` | Headless edit session; staged writes. |
| `commands [FILTER]` | JSON command catalog. |
| `mcp [--connect HOST:PORT [--lazy] [--launch]]` | MCP server on stdio. |
| `perf [N \| FILE]` | Timing table. |
| `sample (bracket\|floorplan) OUT` | Built-in sample drawing in any writable format. |

  `--cmd` chaining: `"{last}"` becomes the last object handle an earlier `--cmd` returned.
- **Scripting and import automation:** `.scr` via SCRIPT or `run --script-file`; AutoLISP via `lisp` / `appload`; `.pgp` via `aliasedit`/`reinit`; `.lin`/`.pat` loading; `document.bytes {format, version, binary}` returns base64 without touching a file.
- **Read-back commands for agents:** `drawing.inspect` (+`skipped{count,sections}`), `entities`, `texts`, `shapes` (with `selfCheck`), `usage`, `loops`, `countlist`/`counttable`/`count`, `properties`, `list`, `dist`, `id`, `area`.

### Platform notes

- Native macOS universal app (signed, notarized DMG; CLI in a separate signed zip), Windows x64/arm64/x86 MSI (**per-user install by default now**), Linux x86_64/aarch64/riscv64, FreeBSD x86_64 tar.
- WebAssembly build runs the same UI (`?webgl`, `?cpu`, `?sample`, `?host=parent`). **No DWG**, no autosave, saves are browser downloads.
- **16 interface languages** (Swedish gained its 49 missing strings this release); live switching via `ui.language` and `CADCRAFT_LOCALE`. CJK/Arabic/Hangul need an installed matching font.
- Accessibility: system-cursor restore, animation-effects setting; **in-place text editing accepts IME composition and commit** (PR #1905).
- 3Dconnexion SpaceMouse motion is compiled for Windows/Linux only.

## Known limitations and not-implemented

Read `docs/gaps.md` before promising anything. The generated checklist says 297/491 (60 %) menu breadth, with 194 reference items uncovered. The high-impact limits for an agent:

- **Saving DWG is lossy.** The acadrust bridge drops custom-class entities/objects, xdata on table records and blocks, entity colour books and reactors; DXF keeps unmodelled content raw. Always check the `notSaved` report on every DWG save.
- **No real-file corpus and no AutoCAD verification.** All file tests are synthetic; no CADCraft output has been checked in AutoCAD black-box.
- **No 3D at all.** No UCS, 3D views, orbit, solids, surfaces, meshes, sections, visual styles, materials, lights or rendering. `3DORBIT`, `ATTACH` and `SHARE` are registered only to refuse. README's tagline says "2D and 3D"; the 3D half is not implemented.
- **Curve geometry is tessellated.** Ellipse/spline intersections, offsets, trims, closest points and snaps are approximations; polyline offsets ignore bulges; tolerances are absolute.
- **XCLIP is missing; xrefs cannot be edited in place.** REFEDIT edits block references only. No dynamic-block authoring (parameters/actions).
- **SHX fonts are not parsed.** SHX-style text draws with CADCraft's stroke font or `FONTALT`.
- **No PDF import/underlays, no raster image attach/display, no DWF/DGN/WMF/EPS/ACIS/STL exchange, no DWS standards, no system printers.**
- **Binary plot files are unread.** `.ctb`/`.stb`/`.pc3`/`.pmp` must be recreated in CADCraft's JSON formats.
- **MTEXT editing is partial.** TEXTEDIT replaces text by handle, but there is no in-place formatting editor for an existing MTEXT, no fields, no spell check, stacked fractions show as placeholders.
- **No autosave in the web build.** Desktop autosave writes DXF `.sv$` files; the web build has none. **Autosave no longer writes the old host as recovery when the Block Editor's changes can't be composed** (PR #980).
- **SETVAR covers ~150 of ~1,000 variables**; no Sheet Set Manager, eTransmit, Traces, Markup Import, CUI(x) or workspaces.
- **macOS Finder file association for `.dxf` is broken (#158)**; open positionally or via File > Open.
- **No plug-in API.** ObjectARX/.NET plug-ins cannot load. What an agent can extend today is AutoLISP, `.scr` scripts, `.pgp` aliases, `.lin` linetypes and `.pat` patterns.
- **Web PLOT may show raw PDF bytes (#134)**; Windows/Linux get little runtime testing.
- **Claimed but unverified here (static reading only):** README's interactive-feel claims (AutoComplete, right-click repeat), associative-dimension behaviour, MTEXT bidi/OpenType shaping for Arabic-script text, per-language font availability, and SpaceMouse behaviour on Windows/Linux.

## How to operate

**Launch (macOS).** GUI binary is inside `/Applications/CADCraft.app` (`Contents/MacOS/CADCraft`); launch with `open -a "CADCraft"`. Start flags: `--control <port>`, `--sample`, `--version`/`-V`, and positional drawing paths. CADCraft's own MCP `--launch` runs `open -a CADCraft --args --control PORT`. **The bundle contains no CLI binary** — install `cadcraft-cli` from `cadcraft-cli-<ver>-macos-universal.zip`. CADCraft does not have to be running for `cadcraft-cli` or headless MCP.

Environment variables that matter: `CADCRAFT_CONTROL_PORT`, `CADCRAFT_CONFIG_DIR`, `CADCRAFT_LOCALE`, `CADCRAFT_SYSTEM_CURSOR=1`, `CADCRAFT_FONTALT`/`CADCRAFT_FONTFALLBACK`, `CADCRAFT_VSYNC`, `CADCRAFT_NO_NATIVE_MENU`, `CADCRAFT_WAYLAND=1`, `WGPU_BACKEND`, `RUST_LOG`.

**Settings/state (macOS).** `~/Library/Application Support/CADCraft/` holds `logs/cadcraft.log`, `autosave/` (`.sv$` DXF drawings), `support/` (AutoLISP startup files), and `workspace.json`. The control token file lives outside it (see the control-channel bullet).

**Document model.** One window, many drawings: each open drawing is a document with its own file tab and model/paper spaces; `document.switch {index}` switches, `close {index}`/`closeall` close them. Tool Sets, Layers, Properties and External References dock (side panels in left/right dock columns now), float and persist; QuickCalc opens as a floating palette (Cmd+8); layout tabs stay stable when Tool Sets toggle.

**Keyboard shortcuts (from source — do not invent others).** Engine `.key()` values: Cmd+N new, Cmd+O open, Cmd+S save, Cmd+Shift+S save as, Cmd+W close, Cmd+P plot, Cmd+Z/Cmd+Shift+Z undo/redo, Cmd+C/V/X clipboard, Cmd+Shift+C copy with base point, Cmd+Shift+V paste as block, Cmd+A select all, Cmd+Shift+A PICKSTYLE, Delete clear selection, F3 osnap, F5 isoplane, F7 grid, F8 ortho, F9 snap, F10 polar, F11 object snap tracking, F12 dynamic input. UI-only: Cmd+1 Properties, Cmd+3 Tool Sets, Cmd+8 QuickCalc, Cmd+9 command line, F1 command reference, F2 command history, Cmd+Q quit.

**Open/save/export flow.** The Open dialog filters DWG/DXF/DWT and SVG/SVGZ; the Save dialog offers DXF, DWG, DWT, SVG, PNG, PDF. QSAVE/SAVE writes the drawing's own format/version; SAVEAS `{path, version?, binary?}`; the macOS save panel cannot pick a version per file. `document.bytes {format, version, binary}` returns base64 without touching a file. EXPORT writes dxf|dwg|svg|png|pdf; PLOT/EXPORTPDF write PDF through the plotter; PUBLISH one PDF per sheet; PDFBOOK builds ISO A-series books from frame polylines. In the web build, saves are downloads.

**Headless CLI (what an agent will use most).**
```sh
cadcraft-cli info drawing.dxf                       # JSON summary: counts, extents, layers, styles, skipped…
cadcraft-cli convert drawing.dxf out.svg            # dxf|dwg|svg|png|pdf; PNG is 2400×1600
cadcraft-cli convert drawing.dwg detail.png --window 0,0,20000,15000   # frame a rectangle
cadcraft-cli run --sample --script 'CIRCLE 22,3 1\n' --save out.dxf --export out.png
cadcraft-cli run drawing.dxf --script-file setup.scr --save out.dxf
cadcraft-cli run drawing.dxf --cmd 'circle {"center":[10,10],"radius":4}' --cmd 'zoom {"mode":"extents"}' --export sel.png
cadcraft-cli run drawing.dxf --cmd 'mview {"p1":[20,20],"p2":[200,150]}' --cmd 'viewport.set {"handle":"{last}","scale":1}'
cadcraft-cli commands dim                           # command catalog (JSON), filtered
cadcraft-cli sample floorplan out.dxf               # built-in sample drawings
cadcraft-cli mcp --connect 127.0.0.1:7979           # bridge MCP to the running app
```
Framing rules: `convert` fits model-space extents; `run --export` uses the current view only if a command changed it; `--window x0,y0,x1,y1` shows exactly that rectangle. CLI PNG/SVG/PDF always render **model space**.

**Command-first workflow.** Anything the UI can do is a command: `engine.execute {command, params}` runs the JSON form with no dialogs; typing (`cmdline.input`) drives the interactive prompt machines exactly like a user. A refused command-line line still replies `ok: true` — check the `error` field. Errors inside a command never take the app down (panic guard). UI commands exist only in the app catalog; headless returns "unknown command" for them.

## Working with an AI agent

Legitimate and reliable:

- **Prefer the headless surfaces**: `cadcraft-cli` for one-shot work and verification, MCP (headless or bridged) for interactive sessions, the control channel when a human is watching the same window. Do not drive the GUI blindly; `ui.screenshot` needs a presented frame.
- **Talk to the control port correctly.** Read `cadcraft-control-<port>.token` (`$XDG_RUNTIME_DIR`, else `~/.cache`; `%LOCALAPPDATA%` on Windows) and send `"token"` in every request line, or use the MCP bridge which does it for you (and now retries once across a `--launch` race). Never assume a local connection is authorized.
- **Author drawings programmatically**: `engine.execute` per entity, or a `.scr` script / `cadcraft-cli run --script-file`, is far more reliable than pointer simulation. Read back with `drawing.inspect`/`entities`, `texts`, `shapes` (areas/centroids — now with arc-segment measuring in AREA/DIST), `usage` before purging, `loops`, and eyeball with `render`.
- **Prepare/convert inputs**: `convert` turns DXF/DWG/SVG to DXF/DWG/SVG/PNG/PDF; SVG imports as paths/groups in millimetres, page top-left at the origin, Y up. Check `info`'s JSON before assuming contents.
- **Interpret and repair project files**: DXF is a documented text format; CADCraft-specific data travels under the `CADCRAFT` xdata app name and `CADCRAFT_*` dictionary entries. For damaged drawings use AUDIT/RECOVER; crash autosaves are `.sv$` DXF files listed by DRAWINGRECOVERY.
- **Verify exports before reporting success**: re-open the saved file, compare entity counts/extents/layers, check `open`'s `warnings`, `drawing.inspect.skipped.count`, and the `notSaved` report (CLI prints it on stderr for `.dwg`/`.dwt`). Render to PNG and look at it. CLI writes are staged, so a failed write keeps the previous drawing.
- **Report commands with their exact ids** from `engine.commands`/`cadcraft-cli commands`; ids are AutoCAD command names lower-cased. The app catalog's `ui.*` entries are not engine commands.
- **Counts to expect at v0.15.1**: 444 engine commands (+`chprop`, `solid` over v0.14.0's 442; `CommandSpec::new` id sets diffed between tags); 57 UI-only commands (499 in the app catalog); 15 MCP tools (12 headless + 3 app-only); 27 control methods app / 12 headless; 7 CLI verbs. Re-derive with `cadcraft-cli commands | jq length` rather than trusting any number, including the ones above.

What an agent must NOT do:

- Assume DWG saves round-trip losslessly, or that AutoCAD will open CADCraft output cleanly — nobody has verified that. Keep an untouched copy of every received file; prefer DXF when the user's tooling allows it.
- Assume 3D/UCS, PDF underlays, raster image display, SHX metrics, dynamic-block authoring, XCLIP, xref in-place editing, Visual LISP/DCL/reactors, fields, spell check, sheet sets, eTransmit, Traces or CUI exist. Check `docs/gaps.md` first.
- Invent shortcuts, menu paths, flags or format names: only what is in `CommandSpec`, `UI_COMMANDS` and the CLI usage string exists.
- Edit `.dwg` bytes or expect a CADCraft-proprietary project format — there is none; the drawing *is* the DXF/DWG.
- Send UI-only commands to a headless MCP/CLI session, or rely on `screenshot` without a presented frame.
- Call `app.quit` before saving: it quits without the unsaved-changes prompt.
- Trust it for production/concurrent work: pre-alpha, a synthetic-only file test suite, and open correctness issues.

## Verification protocol

1. Work throwaway-first: `cadcraft-cli sample bracket scratch/t.dxf` (or `run --metric`), draw, save to a scratch path, re-open, inspect, delete. Never test on the only copy of a real drawing.
2. After every save, assert on the result: the `notSaved` field / the stderr warning must be absent. After reading, `drawing.inspect.skipped.count` must be 0 for DXF, and `open`'s `warnings` must be empty for DWG/SVG. A silent export is not a verified export.
3. Round-trip discipline: new → edit → save → close → reopen → compare counts/extents/layers; then export to PNG/SVG/PDF and look at it. For CAD-interchange files, when the user has AutoCAD or another viewer, open the file there too.
4. Version and back up: keep each session's output under a new name or in version control; the desktop app has SAVETIME autosave, Drawing Recovery, AUDIT and RECOVER, but the web build has none, and DWG saves can drop unmodelled content.
5. Update CADCraft only between projects (launcher auto-updates), and re-check this skill's claims when the version moves — this skill describes v0.15.1.

## Sources & evidence

- Repo: https://github.com/storytold/cadcraft (clean-room, MIT OR Apache-2.0).
- Inspected at tag `v0.15.1`, commit `660e15c9f494ce647e87de10adbb01a8786e0901` ("Release 0.15.1", 2026-10-31), on 2026-11-01. The installed GUI binary still prints `cadcraft 0.14.0 (fbd97d4…)` (bundle lags the tag). The launcher auto-updates, so **verify against your installed version**.
- Key files read: `README.md`, `Cargo.toml`, `docs/{gaps,parity-checklist,file-format-parity,control-protocol,mcp,autolisp,customization,localization}.md`; `apps/cadcraft-cli/src/main.rs`, `apps/cadcraft/src/{main.rs,control_server.rs}`, `apps/cadcraft-web/src/main.rs`; `crates/io/src/lib.rs` and DXF/SVG/PDF readers/writers, `crates/dxf/src/`, `crates/dwg/src/lib.rs`, `crates/engine/src/cmd/` (registry + draw/modify/annotate/blocks/layout/exchange/inquiry/constraints/lisp/audit), `crates/engine/src/{snap.rs,autosave.rs,doc_path.rs,graphics.rs}`, `crates/ui-egui/src/{menus.rs,control.rs,i18n/}`, `crates/mcp/src/{tools.rs,server.rs,backend.rs,control_token.rs}`, `crates/doc/src/library.rs`, `xtask/src/parity.rs`.
- Shared libraries consulted: all `storytold/craft-libs` crates pinned at one revision, `92d392cf…` (`Cargo.toml`), chiefly `craft-docpath` (stored-path policy) and `craft-pdf`; not cloned.
- Read-only inspection: no build, no GUI launch, no drawing modified. The only execution was `/Applications/CADCraft.app/Contents/MacOS/CADCraft --version`. Cross-check `evidence.md` for claim-by-claim tiering.