CADCraft

Audit basis. Refreshed 2026-11-07 against tag v0.18.0, commit 32238e83c2c8bf643994132883e94bc96961f649 — git rev-parse HEAD in the pinned checkout confirms it, and the installed 0.18.0 bundle (id ai.storyteller.cadcraft) prints cadcraft 0.18.0 (32238e83c2c8bf643994132883e94bc96961f649). The previous release this skill described was v0.17.0 (f389d6a72e3fc160ea125b4f264d68f64cbe2aba, "Release 0.17.0", 2026-11-02).

v0.17.0 → v0.18.0 delta (measured with git diff v0.17.0..HEAD: 308 files, +24,334/−1,327). Six command ids added, none removed — dview, image, imageattach, minsert, xclip, xclipframe. What changed in the surfaces this skill documents: XCLIP/XCLIPFRAME clip a block or xref reference to a rectangle, polygon or closed polyline (invert, on/off/delete/polyline; frames 0/1/2, default 2), per reference in block coordinates, extents cut, kept through DXF and DWG as the reference's SPATIAL_FILTER (crates/engine/src/cmd/blocks/xclip.rs, crates/io/src/dxf_clip.rs); raster images — IMAGEATTACH (iat, JSON only) reads PNG/JPEG/BMP/TIFF, ATTACH now delegates to it for image files (other underlays still refuse), and IMAGE (im) lists them, the picture draws on screen (tiled pyramid, sharp at any zoom) and in PNG output while its pixels stay cached with the open drawing, never in the file (crates/engine/src/cmd/image.rs, crates/io/src/raster.rs, crates/ui-egui/src/canvas/images.rs); SHX fonts — shape, big and unifont files are parsed and drawn for text, attributes, dimensions and tables, and linetype shapes draw (crates/fonts/src/shx/mod.rs); DVIEW twists the model view or the active layout viewport, and the twist survives DXF/DWG as group 51 (crates/engine/src/cmd/view/dview.rs); MINSERT repeats a block reference in rows and columns (crates/engine/src/cmd/blocks.rs); a round-trip harness — cadcraft-cli roundtrip and cargo xtask corpus open, save, reopen and diff every DXF/DWG of a folder (crates/io/src/roundtrip.rs); DWG read/write moved into a child process so a hostile file kills only that open or save, on the acadrust 0.6.6 bridge (crates/dwg/src/worker.rs); autosave holds a per-folder lock, writes owner-only files, shows failures and recovers at the next start, and a UI panic autosaves and reports (crates/engine/src/autosave.rs, crates/ui-egui/src/fault.rs); a Find and Replace window (Cmd+F, ui.dialog.find) over a FIND command that gained types/handles, plus an Edit Text window for TEXT/MTEXT/attdef/dimension text (crates/ui-egui/src/finddlg.rs, crates/ui-egui/src/textdlg.rs); PLOT takes its output format from the path extension (PNG/SVG hold one sheet; an unknown extension is refused) and render accepts background/plot_style in MCP and ui.render (crates/engine/src/cmd/plotters.rs, crates/mcp/src/tools.rs); a drawing now opens on the view it was saved at ($VIEWCTR/$VIEWSIZE; open reports saved_view) instead of always on the extents (crates/engine/src/session/files.rs, crates/doc/src/header.rs); Georgian as the 19th interface language (crates/ui-egui/src/i18n/ka.tsv); a web page-host mode (?host=parent, apps/cadcraft-web/src/host.rs); and a security policy (SECURITY.md). Smaller but agent-relevant: BREAK/TRIM keep the entity handle, EXPLODE of a reference with different X and Y scales makes ellipses, EXTEND runs a polyline's arc end round its circle, a solid HATCH keeps its angle/scale/double flag, properties.set skips locked layers and counts what it left out, OLE2FRAME frames draw and move, and DXF reading raises its group-code limit (100 million or a set limit) instead of failing silently.

v0.16.0 → v0.17.0 (previous release). -WBLOCK and OOPS joined the registry; command-line parity entries (-ATTDEF attribute modes, -INSERT ATTREQ/Preset/Verify, CHANGE, -ARRAY, -UNITS), Thai text and MTEXT word wrap, RECTANG/POLYGON vertices in AutoCAD's order, SCALE scaling text heights while OFFSET keeps them, DXF code-page and escape fixes, staged CLI writes, and a .bak kept when a DWG is overwritten. Older history (v0.15.x and earlier: CHPROP, SOLID, PEDIT Multiple, BEDIT block switching, Vietnamese, MCP/control buffer bounds) is folded into CHANGES.md.

Verify against your installed version — the ArtCraft Launcher auto-updates, so a newer build may differ; every count quoted here was re-measured at this tag, and code paths that moved were re-cited. The measurement method for each count is in evidence.md. There is no references/ directory: all detail is here with repo-relative evidence paths.

Overview

CADCraft is an open-source (MIT OR Apache-2.0) 2D CAD and drafting application written in Rust (egui/eframe 0.37, wgpu) for macOS, Windows, Linux, FreeBSD and the web (WebAssembly); 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 — ROADMAP.md (last updated 2026-10-21) still lists four of AutoCAD's five core workflows failing the alpha gate, but that snapshot predates this release, which narrowed two of its rows (XCLIP, SHX fonts) and added a raster-image path; do not quote the roadmap's row text as current.

The differentiator: every user-visible action is a command. The engine registry holds 457 commands at this tag — 439 unique literal CommandSpec::new("<id>") ids plus the 18 ids the gc!/dc! constraint macros expand to, with no duplicate ids; the same derivation re-measures 451 at v0.17.0. The desktop app's catalog adds 59 UI-only entries (crates/ui-egui/src/menus.rs), so the app-level catalog is 516. Re-derive before quoting: cadcraft-cli commands | jq length (the app bundle does not install the CLI).

The repo's generated checklist (docs/parity-checklist.md, dated 2026-11-01 and not regenerated for v0.18.0) still says 449 registered commands and menu breadth 298/491. Treat that as a pre-release snapshot, not this tag: it is two ids short of v0.17.0's 451 and eight short of 457. Do not "correct" one number to the other — the two gc!/dc! macro bodies carry no literal id, the 18 invocations expand to ids a literal scan cannot see, and the published checklist counts a built registry from the day it ran.

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, crates/engine/src/cmd/draw2.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. BREAK and TRIM keep the object's handle; EXPLODE of a reference with different X and Y scales gives ellipses, not circles; EXTEND runs a polyline's arc end segment round its circle (crates/engine/src/cmd/modify/trim.rs, crates/engine/src/cmd/modify/explode.rs).
• Precision: 14 object snaps with deferred tangent/perpendicular (crates/engine/src/snap.rs — ALL has 14 entries: endpoint, midpoint, center, geometric center, node, quadrant, intersection, extension, insertion, perpendicular, tangent, nearest, apparent intersection, parallel); object snap tracking; polar tracking; ortho; grid snap; direct distance entry; @dx,dy, @d<a, #x,y; point modifiers FROM/M2P/TK and point filters (crates/engine/src/pointmod.rs); typed snap overrides.
• 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.
• 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. properties.set leaves objects on locked layers alone and says how many (crates/engine/src/cmd/props.rs).
• 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; TOLERANCE; annotative scaling; on-canvas MTEXT editor and an Edit Text window (see How to operate); QuickCalc palette; COMPARE and COMPAREEXPORT. FIND now takes types and handles and returns match snippets (crates/engine/src/cmd/utility.rs).
• Hatch, blocks, xrefs: pick-point HATCH with islands, HATCHEDIT, 23 built-in patterns including SOLID (crates/doc/src/library.rs), solid and gradient fills, user .pat files; BLOCK/INSERT/MINSERT/ATTDEF, BATTMAN, ATTSYNC, ATTEDIT, DATAEXTRACTION/EATTEXT, nested blocks, groups, WBLOCK, PURGE; xrefs (XATTACH, -XREF, XBIND, XOPEN, overlays, relative paths); XCLIP/XCLIPFRAME clip block and xref references (rectangular, polygonal and closed-polyline boundaries, Invert clip, ON/OFF/Delete/generate Polyline, a frame mode per drawing), boundary stored per reference and kept through DXF/DWG; Block Editor for static blocks (BEDIT/BSAVE/BSAVEAS/BCLOSE); REFEDIT/REFSET/REFCLOSE; dynamic blocks read from other files with visibility/lookup/custom-property edits and grips.
• 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, Named Viewports dialog, LAYOUT SAveas to a drawing template. PLOT picks PNG/SVG/PDF from the path's extension and refuses a path whose extension names no format; PNG and SVG hold one sheet only (crates/engine/src/cmd/plotters.rs); a landscape media's size order and rotation survive DXF/DWG.
• 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; shapes (with selfCheck), usage, loops, countlist/counttable/count, properties, list, dist, id.
• Parametric: geometric and dimensional constraints, AUTOCONSTRAIN, CONSTRAINTBAR, DELCONSTRAINT, PARAMETERS with expressions, re-solve after edits, constraints.inspect/constraints.dof (crates/constraints/src/lib.rs).
• 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 (crates/engine/src/lisp.rs). No Visual LISP ActiveX, DCL dialogs, reactors or Startup Suite.
• Raster images (new this release): IMAGEATTACH (iat) with {path, data?, at?, scale?|width?, rotation?, name?} — a relative path is relative to the drawing's folder; IMAGE (im) lists every image with status Loaded / Not Found / Not loaded. At most 1,000 image files, 256 MiB per file and 2 GiB of decoded pixels per drawing; a missing file stays a crossed-out frame. Drawn on screen and in PNG output with rotation, fade and a clip boundary read from the file; brightness and contrast are kept but not applied (crates/engine/src/cmd/image.rs, crates/io/src/raster.rs).
• Fonts: TrueType/OpenType/collection fonts by family or file name, FONTALT/FONTFALLBACK, and now SHX shape fonts, big fonts and unifonts (searched beside the drawing, in CADCRAFT_SHXPATH, through a font map, or registered by the web app; never inside another CAD program's folder). Text widths and extents follow the SHX pen's own metrics (crates/fonts/src/shx/mod.rs).

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.6 bridge (MPL-2.0, unmodified; R13 untested, pre-R13 not read) in a child process. SVG and gzipped SVGZ (shapes, paths, groups, Inkscape layers; no CSS, use, fills/gradients/patterns, text, images). Raster image files PNG, JPEG, BMP and TIFF are decoded for IMAGE entities; the format comes from the content, not the name (crates/doc/src/format.rs, crates/io/src/raster.rs). The DXF reader and writer are hardened against hostile input (every count and offset bounded; a crafted file is refused or read only as far as it is valid) (crates/dxf/tests/hardening.rs).
• Save/native: DXF is the native path — ASCII or binary, versions 2000–2018; DWG write 2000–2018 (2018 by default; the file's own version when there is one). .dwt templates save via SAVEAS; NEW/QNEW accept .dwt/.dxf templates; LAYOUT SAveas writes a layout as a template. Oversized files now fail loudly instead of silently: a drawing opened directly is capped at 512 MiB, a DWG at 512 MiB with a 1 GiB DXF rendition, and the DXF reader reads up to 100 million group codes (raise it with CADCRAFT_MAX_DXF_TAGS) (crates/engine/src/cmd/file.rs, crates/dwg/src/lib.rs, crates/dxf/src/lib.rs).
• 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. An OLE2FRAME's data and frame corners survive a DWG save in this release; it moves and scales uniformly, and rotate, mirror or a non-uniform scale is refused.
• Import: another DXF/DWG's objects via import; user .lin, .pat and .pgp files. SVG/SVGZ is read by open. Raster images are attached by IMAGEATTACH, not imported as geometry. Stored xref/data-link paths resolve through craft-docpath.
• Export: SVG; PNG 2400×1600; 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. Raster images appear in PNG output; PDF and SVG output draw only the image frame.

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 = the engine registry (457 at this tag, see Overview); the desktop app adds 59 UI_COMMANDS entries (crates/ui-egui/src/menus.rs). 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 (unchanged at v0.18.0) — 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 (crates/mcp/src/tools.rs). render gained background (dark/white/paper/#rrggbb) and plot_style (a CTB/STB name, or none), so a PNG can match a plot (crates/engine/src/render_look.rs). Resources: cadcraft://drawing and cadcraft://commands (crates/mcp/src/server.rs).
• 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>" — 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), and logs its path at startup; the MCP bridge reads it automatically (crates/mcp/src/control_token.rs). 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 (now with window, background, plot_style), app.open/save/quit, control.methods, ping. Limits: 16 connections, 64 queued requests, 256 MiB per line, 512 MiB buffered across connections, 60 s reply timeout (state: not-run = safe to resend, may-have-run = inspect first), 10 min idle, 30 s blocked-write timeout (apps/cadcraft/src/control_server.rs).
• CLI cadcraft-cli (separate zip; arguments parsed with clap following RFC-0012): 8 verbs — info, convert, run, commands, mcp, perf, sample, roundtrip (new) — plus --version/--help.

--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, and image for attached rasters.

Platform notes

• Native macOS universal app (signed, notarized DMG; CLI in a separate signed zip, cadcraft-cli-<ver>-macos-universal.zip by default — packaging/macos/package.sh), Windows x64/arm64/x86 MSI (Scope="perUserOrMachine" in packaging/windows/cadcraft.wxs; a fresh install from the 2026-11 launcher is machine-wide, an existing per-user install stays under the user profile), Linux x86_64/aarch64/riscv64 (AppImage, deb, rpm and tar), FreeBSD tar (x86_64; the aarch64 build has no DWG bridge, crates/dwg/build.rs).
• WebAssembly build runs the same UI (?webgl, ?cpu, ?sample) and, new this release, a page-host mode (?host=parent in an iframe, or data-host="page" on the canvas) where the host page opens drawings and receives saves as postMessage/DOM CustomEvents instead of downloads (apps/cadcraft-web/src/host.rs). No DWG, no autosave, saves are browser downloads without a host.
• 19 interface languages (LANGUAGES in crates/ui-egui/src/i18n.rs: English plus 18 translations, Georgian new this release); live switching via ui.language and CADCRAFT_LOCALE. docs/localization.md still lists 18 interface languages and omits Vietnamese (vi), which the code registers. CJK/Arabic/Hangul need an installed matching font; Georgian needs the craft-fonts Noto Sans Georgian face.
• Accessibility: system-cursor restore, animation-effects setting; in-place text editing accepts IME composition and commit.
• 3Dconnexion SpaceMouse motion is compiled for Windows/Linux only (hidapi target dependencies in apps/cadcraft/Cargo.toml).

Known limitations and not-implemented

Read docs/gaps.md before promising anything; it is the maintained list and it is newer than ROADMAP.md. The checklist's menu breadth (298/491, 61 %) is the 2026-11-01 snapshot and was not regenerated at v0.18.0. The high-impact limits for an agent:

• Saving DWG is lossy. The acadrust bridge drops custom-class entities and 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. The DWG worker process (new) has no memory limit of its own, so a crafted file can use a lot of memory before that one open or save dies (SECURITY.md known limits).
• No shipped real-file corpus and no AutoCAD sign-off. The round-trip harness now exists (cadcraft-cli roundtrip, cargo xtask corpus), but the corpus lives in a separate repo; docs/gaps.md still lists a black-box AutoCAD check as a gap, and the only check recorded is one R2000 DXF bug (2026-10-29 in docs/file-format-parity.md). Do not tell a user their CADCraft file is AutoCAD-clean.
• No 3D at all. No UCS, 3D views, orbit, solids, surfaces, meshes, sections, visual styles, materials, lights or rendering. 3DORBIT and SHARE are registered only to refuse, and ATTACH refuses PDF/DWF/DGN underlays while attaching PNG/JPEG/BMP/TIFF; DVIEW's 3D options (CAmera, TArget, Distance, POints, CLip, Hide) print "not available yet" — TWist, PAn, Zoom, Off and Undo work on 2D views. 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.
• Xrefs cannot be edited in place (REFEDIT edits block references only) and there is no dynamic-block authoring (parameters/actions). XCLIP now exists, so do not repeat the old "no XCLIP" claim.
• SHX text is only as good as the font files present. No bundled SHX font; without the file the style falls back to FONTALT/the stroke font and widths differ. No Options entry for the search path or font map, no desktop drag-and-drop of .shx, the big-font code page is guessed from the file name, vertical text is not justified along its column, and extended big-font box scaling is unverified against real files (docs/gaps.md FF8).
• Raster images are display-and-PNG only. No PDF/SVG image output, no prompts/dialog/menu row, no -IMAGE options (detach, reload, unload, path), no IMAGECLIP, IMAGEADJUST or IMAGEFRAME, brightness/contrast not applied, images lie under all other objects on screen whatever their draw order, size is not taken from the file's resolution, and pixels are never stored in the drawing — move the drawing without its image files and the pictures are gone. No PDF import/underlays, 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. The new Edit Text window edits an object's plain text (TEXT, MTEXT, an attribute definition, a dimension's text), not formatting codes; there are no fields, no spell check, and stacked fractions show as placeholders.
• No autosave in the web build. Desktop autosave writes DXF .sv$ files, holds a lock per settings folder, shows a failure notice and offers recovery at the next start; a UI panic autosaves and writes a crash report. The web build has none of this, and a panic aborts there.
• SETVAR covers ~150 of ~1,000 variables; no Sheet Set Manager, eTransmit, Traces, Markup Import, CUI(x) or workspaces.
• find/textedit/xclip/imageattach are engine-level. The first three have UI entries (Cmd+F window, shortcut-menu Edit Text, Modify ▸ Clip ▸ Xref); IMAGEATTACH is JSON only (ATTACH takes the same JSON for an image path) — there is no attach dialog or menu row.
• 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.
• Docs that lag the code (code wins): README.md still says SHX fonts "aren't read yet"; ROADMAP.md (2026-10-21) still says "no XCLIP" and "no REFEDIT"; docs/file-format-parity.md mentions the old acadrust 0.6.3 in a historical note; docs/localization.md omits Vietnamese.
• 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). The GUI binary is the installed CADCraft.app's Contents/MacOS/CADCraft; launch with open -a "CADCraft". Start flags: --control <port> (also read from CADCRAFT_CONTROL_PORT), --sample, --version/-V/-h, and positional drawing paths; an unknown flag is a usage error (exit 2); --dwg-worker is internal (a copy of the binary started to read or write one DWG — never call it yourself). CADCraft's own MCP --launch runs open -a CADCraft --args --control PORT. The bundle contains no CLI binary — Contents/MacOS/ holds only CADCraft, so install cadcraft-cli from the CLI 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_SHXPATH (SHX search path, new this release), CADCRAFT_MAX_DXF_TAGS (raise the DXF group-code limit), CADCRAFT_VSYNC, CADCRAFT_NO_NATIVE_MENU, CADCRAFT_WAYLAND=1, WGPU_BACKEND, RUST_LOG. CLI-only: CADCRAFT_CORPUS_DIR and CADCRAFT_CORPUS_STRICT=1 for roundtrip.

Settings/state (macOS). ~/Library/Application Support/CADCraft/ holds logs/cadcraft.log (rotated, 16 MiB cap), autosave/ (.sv$ DXF copies plus a per-instance .lock), support/ (AutoLISP startup files), crash-reports/ (new: panic reports), 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 and float; 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, Cmd+F Find and Replace (new), 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 takes the format from the path extension and refuses an unknown one, and PNG/SVG hold a single sheet; EXPORTPDF always writes PDF; PUBLISH one PDF per sheet; PDFBOOK builds ISO A-series books from frame polylines. In the web build, saves are downloads unless a host page is attached.

Headless CLI (what an agent will use most).

cadcraft-cli info drawing.dxf                       # JSON summary: counts, extents, layers, styles, skipped…
cadcraft-cli convert drawing.dxf out.svg            # dxf|dwg|dwt|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 'imageattach {"path":"site.png","at":[0,0],"width":120}'
cadcraft-cli run drawing.dxf --cmd 'xclip {"handle":"2A","option":"new","rectangle":[[0,0],[100,80]]}'
cadcraft-cli commands dim                           # command catalog (JSON), filtered
cadcraft-cli sample floorplan out.dxf               # built-in sample drawings
cadcraft-cli roundtrip drawings/ --out reports/     # open → save → reopen loss report
cadcraft-cli roundtrip drawings/ --same-format --keep-saved --tolerance 1e-6
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. --view current follows the session view, and since this release an opened drawing's view is the one stored in the file (when it has a usable $VIEWCTR/$VIEWSIZE), not the extents — the CLI's own help text still says "extents plus a 10% margin", which is stale. CLI PNG/SVG/PDF always render model space. The CLI installs the same raster decoder as the app, so IMAGEATTACH works headlessly (apps/cadcraft-cli/src/lib.rs).

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); a panic in the interface itself now autosaves every unsaved drawing and reports it. 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. Never assume a local connection is authorized.
• Measure what a save loses before you promise a round trip. cadcraft-cli roundtrip FOLDER is the strongest tool in this release: it opens, saves as DXF and DWG, reopens and lists every lost/added/changed entity, table record, header variable and opaque record, with --same-format for a single format and --keep-saved to inspect the files. Compare the report before and after your edits.
• 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, image, shapes, usage before purging, loops, and eyeball with render (now with background/plot_style, so the PNG can look like the plot).
• Prepare/convert inputs: convert turns DXF/DWG/SVG to DXF/DWG/DWT/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.
• Attach images deliberately: IMAGEATTACH stores a path in the drawing and caches pixels in memory, so the image file must travel with the DXF; a relative path is relative to the drawing's folder. PNG output shows the picture, PDF/SVG do not.
• Keep fonts with the drawing: SHX text metrics depend on the named .shx being beside the drawing or on CADCRAFT_SHXPATH; without it the text falls back and widths/extents change.
• 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, and a left-behind .sv$ plus its .lock file is the recovery candidate after a crash.
• 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.18.0: 457 engine commands (439 literal ids + 18 gc!/dc! macro ids, zero removed; the generated checklist still reads 449 from its 2026-11-01 run); 59 UI-only commands; 15 MCP tools (12 headless + 3 app-only, unchanged); 27 control methods app / 12 headless; 8 CLI verbs; 19 interface languages; 23 built-in hatch patterns; 14 object snaps; 4 drawing formats read / 6 written plus 4 raster image formats. Re-derive with cadcraft-cli commands | jq length rather than trusting any number, including these.

What an agent must NOT do:

• Assume DWG saves round-trip losslessly, or that AutoCAD will open CADCraft output cleanly — only one R2000 DXF bug has been black-box checked, so a systematic check is outstanding. Keep an untouched copy of every received file; prefer DXF when the user's tooling allows it.
• Assume 3D/UCS, PDF underlays, dynamic-block authoring, xref in-place editing, Visual LISP/DCL/reactors, fields, spell check, sheet sets, eTransmit, Traces or CUI exist. Check docs/gaps.md first.
• Assume an attached raster image is inside the drawing, or that SHX text will look the same without its font file.
• Invent shortcuts, menu paths, flags or format names: only what is in CommandSpec, UI_COMMANDS and the CLI usage string exists. IMAGEATTACH has no dialog or menu row; it is a JSON command.
• 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, synthetic-only file tests in-repo, and open correctness gaps.

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 a folder of real files, run cadcraft-cli roundtrip FOLDER and read the report before and after your work. When the user has AutoCAD or another viewer, open the file there too — a systematic AutoCAD check is still outstanding (docs/gaps.md).
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. If autosave shows a failure notice, treat unsaved work as unprotected until you save.
5. Update CADCraft only between projects (launcher auto-updates), and re-check this skill's claims when the version moves — this skill describes v0.18.0.

Sources & evidence

• Repo: https://github.com/storytold/cadcraft (clean-room, MIT OR Apache-2.0).
• Inspected at tag v0.18.0, commit 32238e83c2c8bf643994132883e94bc96961f649 ("Release 0.18.0", 2026-11-06), on 2026-11-07; the v0.17.0 ref (f389d6a72e3fc160ea125b4f264d68f64cbe2aba) was used for the id-set and file diffs. The installed GUI bundle /Applications/CADCraft.app is version 0.18.0, bundle id ai.storyteller.cadcraft, and its binary printed cadcraft 0.18.0 (32238e83c2c8bf643994132883e94bc96961f649); Contents/MacOS/ holds no CLI, and no cadcraft-cli is installed on this machine, so every count was derived from source plus the repo's generated checklist. The launcher auto-updates, so verify against your installed version.
• Key files read: README.md, ROADMAP.md, SECURITY.md, Cargo.toml, docs/{gaps,parity-checklist,target-app-parity,file-format-parity,control-protocol,mcp,cli,autolisp,customization,localization}.md; apps/cadcraft/src/{main.rs,control_server.rs,env.rs,workspace.rs}, apps/cadcraft-cli/src/{args.rs,lib.rs,roundtrip.rs}, apps/cadcraft-web/src/{main.rs,host.rs}; crates/engine/src/cmd.rs and crates/engine/src/cmd/{blocks.rs,blocks/xclip.rs,image.rs,plotters.rs,utility.rs,props.rs,layout.rs,settings.rs,modify/trim.rs,modify/explode.rs,view/dview.rs,draw.rs,draw2.rs}, crates/engine/src/{snap.rs,pointmod.rs,autosave.rs,render_look.rs,lisp.rs,settings_dir.rs}; crates/io/src/{lib.rs,raster.rs,roundtrip.rs,dxf_clip.rs}, crates/dwg/src/{lib.rs,worker.rs}, crates/dxf/src/lib.rs, crates/doc/src/{format.rs,library.rs,entity/layout.rs,xclip.rs,raster.rs}, crates/fonts/src/shx/mod.rs, crates/render/src/raster.rs, crates/mcp/src/{tools.rs,server.rs,backend.rs,control_token.rs}, crates/ui-egui/src/{menus.rs,control.rs,i18n.rs,i18n/ka.tsv,finddlg.rs,textdlg.rs,fault.rs,autosave.rs,canvas/images.rs}, xtask/src/{main.rs,parity.rs}, packaging/macos/package.sh, packaging/windows/cadcraft.wxs.
• Shared libraries consulted: all storytold/craft-libs crates pinned at 92d392cff132eaf53e13afff77f38b5c11b73aa0 (chiefly craft-docpath, craft-pdf), plus craft-web-host at 2e2312ddaf21bc3d85cd3395d0955c7d239306f6 for the web host bridge (apps/cadcraft-web/Cargo.toml); the DWG bridge is acadrust 0.6.6 (MPL-2.0, unmodified). Not cloned.
• Read-only inspection: no build, no GUI launch, no drawing modified. The only execution was the installed binary's --version. Cross-check evidence.md for claim-by-claim tiering.