# DXF-CSV v1.0 — Spec Companion **Audience:** AI language models and human readers of the companion HTML **Purpose:** Everything true and useful about DXF-CSV v1.0 that isn't in `spec.md` — mostly Drawing Sync/`dwgsync.exe` operational behavior rather than the CSV format itself. Read this alongside `spec.md`, not instead of it. **Relationship to spec.md:** `spec.md` is the normative format specification. This document covers operational behavior, gotchas, and guidance originating in the companion HTML pages (`usage.html`, `ai-guide.html`, `reference.html`) that would distract from the format definition if placed in the spec. **Maintained by:** DrawingSync / Code Truck — https://drawingsync.com --- ## Install and compatibility Direct download: `https://drawingsync.com/downloads/DrawingSync-2027-x64-Plugin.msi` (and the non-plugin `DrawingSync-2027-x64.msi` variant). The installer and all binaries are code-signed. After installing, run `DSABOUT` in AutoCAD to verify installation. Works with AutoCAD 2013 and later, within Autodesk's supported product lifecycle. --- ## Invoking `dwgsync.exe` — what to expect `dwgsync.exe` is a **Windows GUI executable, not a console app**. On success with `-q` it exits silently — exit code 0, no stdout or stderr. On invalid, incomplete, or unexpected arguments it can show a blocking modal dialog instead of printing an error — a synchronous wait with no timeout will hang indefinitely. Running the exe with no arguments also shows a modal help dialog (not console text) listing available flags. **`-q` is quiet, not invisible.** It suppresses prompts and console output and exits automatically when done — but the Drawing Sync window itself still shows on screen during processing, displaying the extraction/merge progress and results. For a small drawing that's up for a couple of seconds at most; for a larger one it can stay up for the full duration and steal focus. If using `-q` and the window itself shouldn't show at all, add `-hide`. This is intended for AI-console use, not something a human user would typically ask for directly. **With `-hide`, errors are not visible to the user** — there's no window to show a dialog, so checking the exit code and verifying the output file are the only way to detect failure, not optional extras. **For automation/AI callers:** always run with an explicit timeout and known-good argument patterns; if a call hangs, kill the `dwgsync` process rather than waiting on it. **Timing, empirically (this is not a spec guarantee, just observed behavior):** exports and imports are fast even at real-world drawing sizes — a ~5MB DWG with thousands of entities completed a full `-dxs=TABLES,BLOCKS,ENTITIES` export in under 20 seconds. A 60-120 second timeout is generous for automation; anything that takes noticeably longer is a strong signal of a hung dialog, not genuine processing time. **Unicode paths:** `dwgsync.exe` accepts Unicode filenames and paths natively — Windows process arguments are wide-character, and non-Latin script filenames (Cyrillic, Arabic, etc.) work correctly. If a call unexpectedly hangs on a non-ASCII path, suspect your own argument-passing before the tool — some process-launch APIs mangle non-ASCII arguments before `dwgsync.exe` ever sees them, producing a hang indistinguishable from the invalid-arguments case above but caused by the caller, not the target file. --- ## `-dsm` merge behavior ### The `new.dxf` special case The positional source drawing argument must already exist, with exactly one exception: `new.dxf`. If the source argument is literally named `new.dxf` and no file exists at that path, Drawing Sync loads its built-in minimal DXF template (`sha1:781e2fb2654f`) into memory and merges against that instead — **`new.dxf` itself is never written to disk.** In most cases `new.dxf` should not already exist for this reason; if it does, it's used as an ordinary source file and the template substitution does not happen. Any other filename that doesn't exist is **not** substituted — the call fails (or hangs on a dialog, per the invocation note above) rather than falling back to a template. This makes `new.dxf` the right source for pure AI-generated content with no real drawing behind it — whatever sha1 the CSV declares (e.g. `sha1:396cb2c5a30e`, the empty-AutoCAD-2018 template) is just metadata; CSVIN doesn't check it against the template it loads (see "sha1 as a drawing selection aid" below — this holds for every case, not just `new.dxf`). ### Missing table/block dependencies For anything other than `new.dxf`, the `sha1:` clause is mainly about making sure the right tables and blocks already exist in the target drawing. **CSVIN is generally forgiving when they don't:** a table the CSV references but doesn't define gets created with defaults, a referenced block becomes empty, rather than failing the import. Matching sha1, or targeting an ancestor of it, is what makes that unnecessary — the drawing already carries the real definitions, so the CSV doesn't need to re-supply them. --- ## sha1 as a drawing selection aid, not a runtime check The `sha1:` clause tells the caller — human or AI — which physical drawing this CSV was authored against, so the right one can be opened or specified before running CSVIN or `-dsm`. **CSVIN does not verify the hash against the target drawing at import time and does not reject an import over a mismatch** — by the time CSVIN runs, drawing selection has already happened. This applies throughout: "Modify mode" (CSVIN updates changed entities in place in the open drawing — it does not itself verify the hash; opening the right one is on the caller) and the "Open library" model (callers who open or target the drawing a published sha1 identifies get the expectations encoded in that template, since CSVIN simply merges into whatever drawing it's given — there is no registry check). What getting the drawing selection right buys you: an AI generating content for `sha1:396cb2c5a30e` (empty AutoCAD 2018 template) makes no assumptions about pre-existing blocks, layers, or styles — it must define everything it uses. An AI generating content for a domain-specific template sha1 can reference blocks, layers, dimstyles, and text styles that already exist in that drawing without redefining them — provided the caller actually targets that drawing. --- ## The `_ai` layer convention `_ai` is a **plain layer name used by convention** for direct communication between a user and an AI in the drawing itself — not a reserved or specially-handled name. CSVIN and CSVOUT apply no special processing to it: a user can put geometry and/or a TEXT/MTEXT note on `_ai` to ask an AI something ("Can you improve this?"), and an AI can write back an in-drawing comment the same way. Content on `_ai` is not automatically excluded from the design — if it shouldn't remain, hiding, freezing, or purging the layer is up to the user. **Best practice:** freeze `_ai` and give it a standard color (ACI 30) — see `sample_csvout_reference.csv` line 9 (`LAYER,,_ai,,Continuous,...,30, ...,1,...` — color 30, frozen flag set). `_claude` follows the same convention but has never been observed in practice. It is not documented in spec.md. --- ## `-dxs` default behavior When no `-dxs` is specified, CSVOUT defaults to `TABLES(LAYER),ENTITIES` — **always, regardless of what the drawing contains.** `BLOCKS` is included only when explicitly requested. When `BLOCKS` is requested but the drawing has no block definitions to export, CSVOUT still emits an empty `BLOCKS` section (`SECTION`/`ENDSEC` with no `BLOCK` rows) rather than omitting it — this is how a reader distinguishes "blocks were requested and there were none" from "blocks were never requested."