From 3d2660d418a2bef771b6e5ebea9229a507ffb4e1 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 12 Jun 2026 18:07:19 -0500
Subject: [PATCH 01/39] docs: add docs folder and align readme with univerlab
 system

---
 README.md                   |  28 +++++++++-
 docs/agents.md              |  70 +++++++++++++++++++++++++
 docs/building-and-export.md |  68 ++++++++++++++++++++++++
 docs/cf-format.md           | 100 ++++++++++++++++++++++++++++++++++++
 docs/cli-reference.md       |  66 ++++++++++++++++++++++++
 docs/index.md               |  65 +++++++++++++++++++++++
 docs/installation.md        |  49 ++++++++++++++++++
 docs/live-preview.md        |  45 ++++++++++++++++
 docs/quickstart.md          |  66 ++++++++++++++++++++++++
 9 files changed, 556 insertions(+), 1 deletion(-)
 create mode 100644 docs/agents.md
 create mode 100644 docs/building-and-export.md
 create mode 100644 docs/cf-format.md
 create mode 100644 docs/cli-reference.md
 create mode 100644 docs/index.md
 create mode 100644 docs/installation.md
 create mode 100644 docs/live-preview.md
 create mode 100644 docs/quickstart.md

diff --git a/README.md b/README.md
index ebe8a10..194897c 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,31 @@ Agents get first-class support:
 
 ---
 
+## Installation
+
+**Linux / macOS:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.sh | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
+```
+
+Or via cargo: `cargo install cadforge` — see [`docs/installation.md`](docs/installation.md) for all methods.
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/): installation, quick start, the
+`.cf` format, live preview, building & export, working with agents, and the
+complete CLI reference.
+
+---
+
+
 ## Features
 
 ### 🎯 Core Platform
@@ -294,4 +319,5 @@ MIT — see [LICENSE](LICENSE) for details.
 
 ---
 
-Made with ❤️ by [JheisonMB](https://github.com/JheisonMB) and [UniverLab](https://github.com/UniverLab)
\ No newline at end of file
+An experiment of [UniverLab](https://github.com/UniverLab) — an open computational laboratory.
+Made with ❤️ by [JheisonMB](https://github.com/JheisonMB)
diff --git a/docs/agents.md b/docs/agents.md
new file mode 100644
index 0000000..f267b01
--- /dev/null
+++ b/docs/agents.md
@@ -0,0 +1,70 @@
+---
+title: Working with Agents
+description: The agent-facing toolchain — schema discovery, JSON reports, visual previews with metadata.
+order: 7
+---
+
+# Working with Agents
+
+Cadforge is designed for **humans and AI agents working together** on the
+same project. Everything an agent needs is exposed through the CLI.
+
+## Self-discovery — `cadforge schema`
+
+```bash
+cadforge schema
+```
+
+Prints the complete `.cf` language reference as markdown. An agent with
+shell access can learn the entire format in one command — no prior
+training on cadforge required.
+
+## Machine-readable state
+
+```bash
+cadforge check --json    # validation report
+cadforge layers --json   # layers, entity counts, colors
+```
+
+## Visual grounding — `cadforge preview`
+
+```bash
+cadforge preview                          # PNG + preview.meta.json
+cadforge preview --format svg             # same render as vector SVG
+cadforge preview --width 1024 -H 768      # custom resolution
+cadforge preview --layer muros            # single layer
+```
+
+The PNG is a faithful render — real text, measured dimension labels,
+hatches, line styles — and `preview.meta.json` contains per-entity
+bounding boxes in **world and pixel coordinates**. A multimodal agent can
+look at the image and locate every entity in it.
+
+Rendering is deterministic on any machine (an embedded monospace font is
+used), including fontless containers.
+
+## Confirming edits — `--highlight`
+
+```bash
+cadforge preview --highlight ln-001,tx-002
+```
+
+Draws labeled amber markers around the listed entities, so an agent can
+visually confirm its edit landed exactly where intended.
+
+## Targeted edit prompts from the browser
+
+In [live preview](live-preview.md), clicking an entity and pressing
+**copy for agent** produces a ready-made prompt with the entity's id,
+source TOML and file — paste it into your agent and ask for the change.
+
+## A typical agent loop
+
+```bash
+cadforge schema                      # 1. learn the language
+cadforge layers --json               # 2. inspect the project
+# ... edit .cf files ...
+cadforge check --json                # 3. validate
+cadforge preview --highlight <ids>   # 4. visually confirm
+cadforge build                       # 5. emit the DXF
+```
diff --git a/docs/building-and-export.md b/docs/building-and-export.md
new file mode 100644
index 0000000..3f0f693
--- /dev/null
+++ b/docs/building-and-export.md
@@ -0,0 +1,68 @@
+---
+title: Building & Export
+description: Deterministic DXF compilation, watch mode, validation, and DXF import.
+order: 6
+---
+
+# Building & Export
+
+## Compile to DXF
+
+```bash
+cadforge build                       # default output.dxf
+cadforge build --output plano.dxf    # custom output path
+cadforge build --layer muros         # compile a single layer
+cadforge build --check               # validate only, no DXF
+```
+
+The output is deterministic: identical input produces a bit-identical
+DXF. Export uses proper AutoCAD-compatible entities — LWPOLYLINE for
+polylines, HATCH for solid fills, MTEXT for annotations — with full
+layer/color/lineweight mapping.
+
+## Validation
+
+```bash
+cadforge check          # geometry + constraints, human-readable
+cadforge check --json   # machine-readable report
+cadforge layers         # list layers with entity counts and colors
+cadforge layers --json  # machine-readable layer listing
+```
+
+## Watch mode
+
+```bash
+cadforge watch
+```
+
+Monitors `.cf` and `.toml` files and rebuilds the DXF on changes with a
+300 ms debounce.
+
+## Formatting
+
+```bash
+cadforge fmt           # normalize .cf files in place
+cadforge fmt --check   # CI-friendly check mode
+```
+
+## Importing existing drawings
+
+```bash
+cadforge import plano.dxf                 # all layers
+cadforge import plano.dxf --layer muros   # a single DXF layer
+```
+
+Import migrates an existing DXF into `.cf` layer files plus a
+`project.toml`, so legacy drawings can join the declarative workflow.
+
+## Pipeline
+
+```
+.cf file (TOML)
+    │
+    ▼
+ Parser ──▶ Resolver ──▶ Compiler ──▶ DXF Emit
+                │
+                ▼
+          Boundary Resolver ──▶ Preview PNG/SVG + JSON meta
+```
diff --git a/docs/cf-format.md b/docs/cf-format.md
new file mode 100644
index 0000000..65d0da8
--- /dev/null
+++ b/docs/cf-format.md
@@ -0,0 +1,100 @@
+---
+title: The .cf Format
+description: Layers, primitives, styled dimensions, construction tools and constraints.
+order: 4
+---
+
+# The .cf Format
+
+A cadforge project is a `project.toml` plus one `.cf` file per layer.
+`.cf` files are TOML: a `[layer]` header followed by arrays of entity
+tables.
+
+> The authoritative reference is always `cadforge schema` — it prints the
+> complete language specification (markdown) for the exact version you
+> have installed.
+
+## Layers
+
+```toml
+[layer]
+name = "muros"
+color = "#FFFFFF"
+```
+
+Layers organize geometry with custom names, colors and line weights. You
+can compile or preview single layers (`--layer muros`) or the whole
+project.
+
+## Primitives
+
+Supported primitives: `line`, `polyline`, `rect`, `circle`, `arc`,
+`text`, `point`, `dim`, `hatch`, `fill`, `group`.
+
+```toml
+[[line]]
+id = "ln-001"
+from = [0.0, 0.0]
+to = [8.5, 0.0]
+weight = 0.50
+
+[[rect]]
+id = "rc-001"
+origin = [1.0, 1.0]
+width = 3.5
+height = 4.0
+
+[[circle]]
+id = "ci-001"
+center = [4.0, 3.0]
+radius = 0.5
+
+[[arc]]
+id = "ac-001"
+center = [2.0, 2.0]
+radius = 0.9
+from_angle = 0.0
+to_angle = 90.0
+
+[[polyline]]
+id = "pl-001"
+points = [[0.0, 0.0], [5.0, 0.0], [5.0, 3.0], [0.0, 3.0]]
+closed = true
+
+[[text]]
+id = "tx-001"
+position = [4.0, 3.0]
+content = "SALA"
+size = 0.2
+```
+
+Every entity has a stable `id` — that is what makes plans diffable and
+lets agents target precise edits.
+
+## Styled dimensions
+
+`dim` entities are auto-measured — the label is computed from the
+geometry, never typed by hand:
+
+```toml
+[[dim]]
+id = "dm-001"
+from = [0, 0]
+to = [5, 0]
+offset = 0.5
+```
+
+Configurable per dimension: `text_size`, `precision`, `show_units`,
+`offset`.
+
+## Construction tools
+
+`[[array]]` (linear and polar — spiral staircases, gear teeth, repeated
+columns) and `[[mirror]]` expand into concrete primitives at build time.
+Copies get derived ids: `base@1`, `base@2`, … and `base@m` for mirrors.
+
+## Constraints
+
+Layers can declare relationships: `parent`, `belongs_to` and
+`spatial_dependency`. Violations are warnings by default and
+build-blocking with `strict = true` in `project.toml`.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
new file mode 100644
index 0000000..6b2f86f
--- /dev/null
+++ b/docs/cli-reference.md
@@ -0,0 +1,66 @@
+---
+title: CLI Reference
+description: Every cadforge command and flag.
+order: 8
+---
+
+# CLI Reference
+
+```
+cadforge <command> [options]
+```
+
+## Project lifecycle
+
+| Command | Description |
+|---------|-------------|
+| `cadforge new <name>` | Create a new project with multi-layer scaffold |
+| `cadforge init` | Initialize cadforge in the current directory |
+| `cadforge build` | Compile project to DXF |
+| `cadforge build --check` | Validate project and constraints without generating DXF |
+| `cadforge build --output <path>` | Compile to custom output path |
+| `cadforge build --layer <name>` | Compile a specific layer only |
+| `cadforge watch` | Auto-rebuild on file changes (300 ms debounce) |
+
+## Preview
+
+| Command | Description |
+|---------|-------------|
+| `cadforge serve` | Live preview server — browser auto-reloads on save |
+| `cadforge serve --open --port <p>` | Open browser automatically on a custom port |
+| `cadforge preview` | Faithful PNG render + `preview.meta.json` |
+| `cadforge preview --format svg` | Vector SVG preview (same renderer) |
+| `cadforge preview --highlight <ids>` | Amber markers around specific entities |
+| `cadforge preview --width <w> -H <h>` | Custom resolution |
+| `cadforge preview --layer <name>` | Preview a specific layer only |
+| `cadforge view` | Open the project in the configured viewer |
+| `cadforge view --layer <name>` | Open only one layer in the viewer |
+
+## Inspection & quality
+
+| Command | Description |
+|---------|-------------|
+| `cadforge check` | Validate with project metadata and layer colors |
+| `cadforge check --json` | Machine-readable validation report |
+| `cadforge layers` | List layers with entity counts and colors |
+| `cadforge layers --json` | Machine-readable layer listing |
+| `cadforge schema` | Print the full `.cf` language reference (markdown) |
+| `cadforge fmt` | Format `.cf` files (normalize whitespace) |
+| `cadforge fmt --check` | Check formatting without modifying (CI) |
+
+## Import & config
+
+| Command | Description |
+|---------|-------------|
+| `cadforge import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
+| `cadforge import <file.dxf> --layer <name>` | Import only one DXF layer |
+| `cadforge config set <key> <value>` | Set global defaults (`author`, `units`) |
+| `cadforge config show` | Show global defaults |
+
+## Output files
+
+| File | Description |
+|------|-------------|
+| `output.dxf` | Default build output |
+| `preview.png` / `preview.svg` | Preview renders |
+| `preview.meta.json` | Per-entity bounding boxes (world + pixel coordinates) |
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..886e64d
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,65 @@
+---
+title: Cadforge
+description: Architecture as Code — declarative 2D CAD in TOML, live browser preview, deterministic DXF output.
+order: 1
+---
+
+# Cadforge
+
+Cadforge is an **Architecture as Code** CLI tool and Rust library for
+declarative 2D CAD modeling. Write geometry as code in `.cf` TOML files,
+watch it live in the browser, and compile to AutoCAD-compatible DXF —
+built for humans and AI agents working together.
+
+## The plan is not drawn — it is declared
+
+Traditional CAD drawings are collections of lines without semantics:
+impossible to version, diff or automate. Cadforge treats an architectural
+plan like source code:
+
+- Same input → **bit-identical output**, every time.
+- `git diff` works on floor plans.
+- AI agents can generate and modify designs with surgical precision.
+
+## The core loop
+
+```bash
+cadforge new casa && cd casa
+cadforge serve --open        # live preview in the browser
+```
+
+Edit any `.cf` file — by hand or by asking an AI agent — and the browser
+updates on every save. Parse errors and constraint violations appear as an
+overlay instead of a crash. When the design is right, `cadforge build`
+emits a deterministic DXF.
+
+## Built for agents
+
+Agents get first-class support:
+
+- `cadforge schema` — the full `.cf` language reference in one command;
+  agents self-discover the format without prior training.
+- `cadforge check --json` / `cadforge layers --json` — machine-readable
+  reports.
+- `cadforge preview` — a faithful PNG render plus `preview.meta.json`
+  with per-entity bounding boxes, so multimodal agents can *look* at the
+  plan and locate every entity.
+- `cadforge preview --highlight ln-001,tx-002` — labeled markers to
+  visually confirm an edit landed where intended.
+
+## How the documentation is organized
+
+- [Installation](installation.md) — install, update and uninstall.
+- [Quick Start](quickstart.md) — from zero to DXF.
+- [The .cf Format](cf-format.md) — layers, primitives, construction tools.
+- [Live Preview](live-preview.md) — `cadforge serve` and its controls.
+- [Building & Export](building-and-export.md) — build, watch, DXF import/export.
+- [Working with Agents](agents.md) — the agent-facing toolchain.
+- [CLI Reference](cli-reference.md) — every command and flag.
+
+## Part of UniverLab
+
+Cadforge is an experiment of [UniverLab](https://github.com/UniverLab),
+an open computational laboratory. It follows the lab's engineering
+principles: one tool one job, reproducibility first, offline-friendly
+design.
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..21dfb5a
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,49 @@
+---
+title: Installation
+description: Install cadforge with the quick installer, cargo, or from source.
+order: 2
+---
+
+# Installation
+
+> Cadforge is currently in **beta** (`0.1.0-beta.x`). Interfaces may still
+> change before 1.0.
+
+## Quick install
+
+**Linux / macOS:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.sh | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
+```
+
+## Via cargo
+
+```bash
+cargo install cadforge
+```
+
+Available on [crates.io](https://crates.io/crates/cadforge).
+
+## From source
+
+```bash
+git clone https://github.com/UniverLab/cadforge.git
+cd cadforge
+cargo build --release
+# Binary at target/release/cadforge
+```
+
+## Uninstall
+
+```bash
+rm -f ~/.local/bin/cadforge
+```
+
+Projects are plain directories of TOML files — nothing else to clean up.
diff --git a/docs/live-preview.md b/docs/live-preview.md
new file mode 100644
index 0000000..9ff502d
--- /dev/null
+++ b/docs/live-preview.md
@@ -0,0 +1,45 @@
+---
+title: Live Preview
+description: The cadforge serve loop — pan/zoom, inspector, layer states, 3D view, error overlay.
+order: 5
+---
+
+# Live Preview
+
+```bash
+cadforge serve                       # start the local preview server
+cadforge serve --open --port 4377    # open browser, custom port
+```
+
+`cadforge serve` runs a zero-config local server with auto-reload on
+save (SSE). Edit a `.cf` file and the browser updates instantly.
+
+## Controls
+
+| Action | Effect |
+|---|---|
+| Scroll | Zoom (centered on cursor) |
+| Drag | Pan |
+| Double-click / `F` | Fit to content |
+| Click an entity | Inspector with its source TOML block |
+| Layer panel / keys `1`–`9` | Cycle each layer **on → ghost → off** |
+| `3D` button / key `3` | Stacked exploded view of the layers |
+
+## Inspector and "copy for agent"
+
+Clicking any entity opens an inspector showing its source TOML. The
+**copy for agent** button produces a ready-made targeted-edit prompt you
+can paste into an AI agent — the entity id, its current definition, and
+the file it lives in.
+
+## Ghost mode
+
+Cycling a layer to *ghost* renders it as a faint trace — useful for
+drawing one floor plan over another, or checking alignment between
+structural and furniture layers.
+
+## Error overlay
+
+Build errors (parse errors, constraint violations) render as an overlay
+with file and line detail instead of crashing the server. Fix the file,
+save, and the view recovers — the loop never breaks.
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..174506a
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,66 @@
+---
+title: Quick Start
+description: Scaffold a project, preview it live, and compile to DXF.
+order: 3
+---
+
+# Quick Start
+
+## 1. Create a project
+
+```bash
+cadforge new my-house
+cd my-house
+```
+
+`cadforge new` scaffolds a complete multi-layer project (walls, doors,
+furniture, dimensions) with meaningful architectural examples. To adopt
+cadforge in an existing directory use `cadforge init`.
+
+## 2. Preview it live
+
+```bash
+cadforge serve --open
+```
+
+A local server opens the plan in your browser. Edit any `.cf` file and
+the view refreshes on save; build errors render as an overlay with
+file/line detail, so the loop never breaks. See
+[Live Preview](live-preview.md) for the full controls.
+
+## 3. Edit geometry
+
+Geometry lives in `.cf` files — TOML with one table per entity:
+
+```toml
+[layer]
+name = "muros"
+color = "#FFFFFF"
+
+[[line]]
+id = "ln-001"
+from = [0.0, 0.0]
+to = [8.5, 0.0]
+weight = 0.50
+```
+
+Run `cadforge schema` for the complete language reference, or read
+[The .cf Format](cf-format.md).
+
+## 4. Validate and format
+
+```bash
+cadforge check     # validate geometry and constraints, no output files
+cadforge fmt       # normalize .cf files
+```
+
+## 5. Compile to DXF
+
+```bash
+cadforge build                       # default output.dxf
+cadforge build --output plano.dxf    # custom output path
+cadforge build --layer muros         # single layer
+```
+
+The output is deterministic and AutoCAD-compatible. `cadforge watch`
+rebuilds automatically while you edit.

From 7e3aad675c21d26770f313af114f7d0cb8c7c795 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 14 Jun 2026 16:30:08 -0500
Subject: [PATCH 02/39] feat: install the cadforge agent skill from the install
 scripts

---
 scripts/install.ps1 | 23 +++++++++++++++++++++++
 scripts/install.sh  | 24 +++++++++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 943467b..303eea4 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -76,6 +76,29 @@ if ($userPath -notlike "*$InstallDir*") {
 # --- cleanup ---
 Remove-Item $Tmp -Recurse -Force
 
+# --- install the cadforge agent skill (optional) ---
+# Teaches AI agents how to drive cadforge. Skipped when npx is unavailable or
+# $env:SKIP_SKILL is set; a failure here never fails the binary install above.
+$Skill      = "cadforge"
+$SkillsRepo = "https://github.com/UniverLab/skills"
+if ($env:SKIP_SKILL) {
+    Info "skill" "skipped (SKIP_SKILL set)"
+} elseif (Get-Command npx -ErrorAction SilentlyContinue) {
+    Info "skill" "adding '$Skill' (npx skills add)"
+    try {
+        & npx -y skills add $SkillsRepo --skill $Skill
+        if ($LASTEXITCODE -eq 0) {
+            Info "skill" "installed"
+        } else {
+            Info "skill" "skipped - add later with: npx skills add $SkillsRepo --skill $Skill"
+        }
+    } catch {
+        Info "skill" "skipped - add later with: npx skills add $SkillsRepo --skill $Skill"
+    }
+} else {
+    Info "skill" "npx not found - add later with: npx skills add $SkillsRepo --skill $Skill"
+}
+
 # --- verify ---
 $ver = & "$InstallDir\$Binary" --version 2>$null
 Info "done" $ver
diff --git a/scripts/install.sh b/scripts/install.sh
index 044488a..e75f7ce 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -97,7 +97,29 @@ if [ -n "$PATHS_TO_ADD" ]; then
 fi
 
 # ============================================================
-# 3. Verify
+# 3. Install the cadforge agent skill (optional)
+# ============================================================
+# Teaches AI agents how to drive cadforge. Skipped when npx is unavailable or
+# SKIP_SKILL is set; a failure here never fails the binary install above.
+
+SKILL="cadforge"
+SKILLS_REPO="https://github.com/UniverLab/skills"
+
+if [ -n "${SKIP_SKILL:-}" ]; then
+  info "skill" "skipped (SKIP_SKILL set)"
+elif command -v npx >/dev/null 2>&1; then
+  info "skill" "adding '$SKILL' (npx skills add)"
+  if npx -y skills add "$SKILLS_REPO" --skill "$SKILL" </dev/null; then
+    info "skill" "installed"
+  else
+    info "skill" "skipped — add later with: npx skills add $SKILLS_REPO --skill $SKILL"
+  fi
+else
+  info "skill" "npx not found — add later with: npx skills add $SKILLS_REPO --skill $SKILL"
+fi
+
+# ============================================================
+# 4. Verify
 # ============================================================
 
 info "done" "$($INSTALL_DIR/$BINARY --version 2>/dev/null || echo "$BINARY installed")"

From 7dca8da3430c51c1c981e439e9992952ecd44019 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 14 Jun 2026 16:30:08 -0500
Subject: [PATCH 03/39] docs: describe cadforge as CAD as code, not
 architecture as code

---
 Cargo.toml    | 2 +-
 README.md     | 2 +-
 docs/index.md | 6 +++---
 src/main.rs   | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 6ce5be2..a4ecf47 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2,7 +2,7 @@
 name = "cadforge"
 version = "0.1.0-beta.2"
 edition = "2021"
-description = "Architecture as Code — deterministic geometry engine for reproducible architectural design"
+description = "CAD as code — deterministic geometry engine for reproducible CAD drawings"
 license = "MIT"
 homepage = "https://github.com/UniverLab/cadforge"
 repository = "https://github.com/UniverLab/cadforge"
diff --git a/README.md b/README.md
index 194897c..34cd733 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2E8B57?style=for-the-badge" alt="License"/></a>
 </p>
 
-cadforge is an **Architecture as Code** CLI tool and Rust library for declarative 2D CAD modeling. Write geometry as code in `.cf` TOML format, watch it live in the browser, and compile to DXF — built for humans and AI agents working together.
+cadforge is a **CAD as code** CLI tool and Rust library for declarative CAD modeling. Write geometry as code in `.cf` TOML format, watch it live in the browser, and compile to DXF — built for humans and AI agents working together.
 
 ---
 
diff --git a/docs/index.md b/docs/index.md
index 886e64d..e14208d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,13 +1,13 @@
 ---
 title: Cadforge
-description: Architecture as Code — declarative 2D CAD in TOML, live browser preview, deterministic DXF output.
+description: CAD as code — declarative CAD in TOML, live browser preview, deterministic DXF output.
 order: 1
 ---
 
 # Cadforge
 
-Cadforge is an **Architecture as Code** CLI tool and Rust library for
-declarative 2D CAD modeling. Write geometry as code in `.cf` TOML files,
+Cadforge is a **CAD as code** CLI tool and Rust library for
+declarative CAD modeling. Write geometry as code in `.cf` TOML files,
 watch it live in the browser, and compile to AutoCAD-compatible DXF —
 built for humans and AI agents working together.
 
diff --git a/src/main.rs b/src/main.rs
index bd4e412..a46e58a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -16,7 +16,7 @@ use std::path::PathBuf;
 #[command(
     name = "cadforge",
     version,
-    about = "Architecture as Code — declarative geometry → DXF"
+    about = "CAD as code — declarative geometry → DXF"
 )]
 struct Cli {
     #[command(subcommand)]

From d103e5c6e4ad07987b64bf60d8040be25d82fd60 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Thu, 18 Jun 2026 22:49:10 -0500
Subject: [PATCH 04/39] docs: add a DemoStage demo score for the cadforge
 live-preview demo

---
 demo/README.md |  21 ++++++++++
 demo/demo.toml | 105 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 demo/README.md
 create mode 100644 demo/demo.toml

diff --git a/demo/README.md b/demo/README.md
new file mode 100644
index 0000000..db00daa
--- /dev/null
+++ b/demo/README.md
@@ -0,0 +1,21 @@
+# cadforge demo
+
+The cadforge demo as code, recorded with [DemoStage](https://github.com/UniverLab/demo-stage).
+It shows the terminal scaffolding a CAD project and starting the live preview, with
+the rendered drawing in a browser pane.
+
+## Regenerate
+
+```sh
+demo check  demo/demo.toml
+demo export demo/demo.toml --target gif   # → demo/dist/cadforge.gif
+# or --target mp4
+```
+
+- `gif`/`mp4` of a terminal + browser pane need a Chromium (auto-downloaded by
+  DemoStage on first use, or use a system install) and, for mp4, ffmpeg.
+- The browser pane is captured after the terminal run, so this score leaves the
+  `cadforge serve` server running; stop it afterwards with
+  `cd /tmp/cadforge-demo/bracket && cadforge serve --stop`.
+
+Edit `demo/demo.toml` to change the commands, captions, layout or timing.
diff --git a/demo/demo.toml b/demo/demo.toml
new file mode 100644
index 0000000..d4d2031
--- /dev/null
+++ b/demo/demo.toml
@@ -0,0 +1,105 @@
+# cadforge demo — terminal (CAD as code) + the live SVG preview in a browser pane.
+#
+# Generate the GIF with DemoStage (https://github.com/UniverLab/demo-stage):
+#   demo check demo/demo.toml
+#   demo export demo/demo.toml --target gif      # → demo/dist/cadforge.gif
+#
+# NOTE: browser panes are captured *after* the terminal run, so the
+# `cadforge serve` background server must still be up at capture time — this demo
+# deliberately does NOT stop it. Afterwards: `cd /tmp/cadforge-demo/bracket &&
+# cadforge serve --stop`. Adjust commands/url to your build if they drift.
+
+[demo]
+name = "cadforge"
+output_dir = "demo/dist"
+
+[typing]
+base_ms = 70
+salt_ms = 14
+seed = 7
+
+[env]
+isolated = true
+setup_script = "rm -rf /tmp/cadforge-demo && mkdir -p /tmp/cadforge-demo && cd /tmp/cadforge-demo"
+
+[layout]
+width = 1280
+height = 720
+fps = 12
+background = "#0b0f14"
+
+  [[layout.panes]]
+  id = "console"
+  type = "terminal"
+  x = 0
+  y = 0
+  width = 760
+  height = 720
+  font_size = 15
+
+  [[layout.panes]]
+  id = "preview"
+  type = "browser"
+  x = 760
+  y = 0
+  width = 520
+  height = 720
+  url = "http://127.0.0.1:4377"
+
+[[timeline]]
+action = "focus"
+pane = "console"
+
+[[timeline]]
+action = "caption"
+text = "1 — scaffold a CAD project"
+
+[[timeline]]
+action = "type"
+text = "cadforge new bracket && cd bracket"
+human_salt = true
+
+[[timeline]]
+action = "keypress"
+key = "enter"
+
+[[timeline]]
+action = "wait"
+duration_ms = 1500
+
+[[timeline]]
+action = "caption"
+text = "2 — start the live preview"
+
+[[timeline]]
+action = "type"
+text = "cadforge serve"
+human_salt = true
+
+[[timeline]]
+action = "keypress"
+key = "enter"
+
+[[timeline]]
+action = "wait_for_stdout"
+match = "127.0.0.1:4377"
+
+[[timeline]]
+action = "wait"
+duration_ms = 1500
+
+[[timeline]]
+action = "caption"
+text = "3 — the drawing renders in the browser"
+
+[[timeline]]
+action = "focus"
+pane = "preview"
+
+[[timeline]]
+action = "scroll"
+direction = "down"
+duration_ms = 2500
+
+[[timeline]]
+action = "terminate"

From 40d8f88d7eb69ad84ab7de6839425d95ba8291af Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 10:37:49 -0500
Subject: [PATCH 05/39] =?UTF-8?q?feat:=20add=20a=203D=20solid=20engine=20?=
 =?UTF-8?q?=E2=80=94=20mesh=20CSG=20(extrude=20+=20boolean),=20camera=20vi?=
 =?UTF-8?q?ews=20and=20derived=20plans=20wired=20into=20the=20live=20previ?=
 =?UTF-8?q?ew?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md            |   2 +-
 project.toml         |  20 ++
 src/lib.rs           |   3 +
 src/main.rs          |  56 +++-
 src/mesh.rs          | 484 +++++++++++++++++++++++++++++++++
 src/model.rs         |  44 +++
 src/parser.rs        |  31 +++
 src/planos.rs        | 289 ++++++++++++++++++++
 src/preview.rs       |  98 +++++++
 src/render3d.rs      | 620 +++++++++++++++++++++++++++++++++++++++++++
 src/scaffold.rs      | 206 +++++++-------
 src/schema.rs        |  59 +++-
 src/serve.rs         | 403 ++++++++++++++++++++++++----
 tests/integration.rs |   1 +
 14 files changed, 2144 insertions(+), 172 deletions(-)
 create mode 100644 project.toml
 create mode 100644 src/mesh.rs
 create mode 100644 src/planos.rs
 create mode 100644 src/render3d.rs

diff --git a/README.md b/README.md
index 34cd733..fc330e2 100644
--- a/README.md
+++ b/README.md
@@ -94,7 +94,7 @@ complete CLI reference.
 
 ### 🏗️ Project Management
 
-- **Project Scaffolding** — `cadforge new` creates a complete multi-layer project (muros, puertas, mobiliario, cotas) with meaningful architectural examples.
+- **Project Scaffolding** — `cadforge new` creates a multi-layer starter project (shapes, curves, annotations) that showcases the core `.cf` primitives.
 - **Multi-Layer Compilation** — Compile all layers or target specific layers with `--layer`. Custom output path with `--output`.
 - **Auto-Rebuild** — `cadforge watch` monitors `.cf` and `.toml` files and auto-rebuilds DXF on changes with 300ms debounce.
 - **Code Formatting** — `cadforge fmt` normalizes `.cf` files. `--check` mode for CI validation.
diff --git a/project.toml b/project.toml
new file mode 100644
index 0000000..4758097
--- /dev/null
+++ b/project.toml
@@ -0,0 +1,20 @@
+
+[[plano]]
+name = "P-01"
+view = "iso"
+size = [420.0, 297.0]
+scale = "1:50"
+title = "Vista isometrica"
+
+[[plano]]
+name = "P-02"
+view = "front"
+title = "Alzado frontal"
+
+[[plano]]
+name = "P-03"
+view = "section"
+cut_axis = "z"
+cut_at = 1.5
+keep = "min"
+title = "Corte horizontal z=1.5"
diff --git a/src/lib.rs b/src/lib.rs
index 022de0a..67cd553 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -8,9 +8,12 @@ pub mod config;
 pub mod dxf_writer;
 pub mod fmt;
 pub mod importer;
+pub mod mesh;
 pub mod model;
 pub mod parser;
+pub mod planos;
 pub mod preview;
+pub mod render3d;
 pub mod scaffold;
 pub mod schema;
 pub mod serve;
diff --git a/src/main.rs b/src/main.rs
index a46e58a..bf310d0 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3,10 +3,10 @@ use cadforge::compiler::{check_project, compile_project, list_layers, project_re
 use cadforge::config::{config_set, config_show};
 use cadforge::fmt::format_project;
 use cadforge::importer::import_dxf;
-use cadforge::preview::{generate_preview, PreviewOutputs};
+use cadforge::preview::{generate_plano, generate_preview, PreviewOutputs, PreviewView};
 use cadforge::scaffold::{create_project, init_project};
 use cadforge::schema::print_schema;
-use cadforge::serve::serve_project;
+use cadforge::serve::{serve_daemon, serve_project, serve_stop};
 use cadforge::viewer::view_project;
 use cadforge::watch::watch_project;
 use clap::{Parser, Subcommand, ValueEnum};
@@ -85,8 +85,15 @@ enum Commands {
         /// Highlight entities by id (comma-separated) with labeled markers
         #[arg(long, value_delimiter = ',')]
         highlight: Vec<String>,
+        /// Render the extruded 3D view instead of the flat plan
+        #[arg(long = "3d")]
+        three_d: bool,
+        /// Render a named plano (drawing sheet) defined in project.toml
+        #[arg(long)]
+        plano: Option<String>,
     },
-    /// Live preview server — browser auto-reloads when .cf files change
+    /// Live preview server — browser auto-reloads when .cf files change.
+    /// Runs detached in the background by default; use --foreground to stay attached.
     Serve {
         /// Project directory (defaults to current dir)
         #[arg(short, long)]
@@ -97,6 +104,12 @@ enum Commands {
         /// Open the browser automatically
         #[arg(long)]
         open: bool,
+        /// Stay in the foreground (stream logs, stop with Ctrl+C) instead of daemonizing
+        #[arg(short = 'f', long)]
+        foreground: bool,
+        /// Stop the background server running for this project
+        #[arg(long)]
+        stop: bool,
     },
     /// Print the .cf language reference (markdown, for humans and AI agents)
     Schema,
@@ -219,17 +232,48 @@ fn main() -> Result<()> {
             layer,
             format,
             highlight,
+            three_d,
+            plano,
         } => {
             let dir = resolve_project_dir(path)?;
             let outputs = PreviewOutputs {
                 png: matches!(format, PreviewFormat::Png | PreviewFormat::All),
                 svg: matches!(format, PreviewFormat::Svg | PreviewFormat::All),
             };
-            generate_preview(&dir, width, height, layer.as_deref(), &highlight, outputs)
+            if let Some(name) = plano {
+                generate_plano(&dir, &name, width, height, outputs)
+            } else {
+                let view = if three_d {
+                    PreviewView::ThreeD
+                } else {
+                    PreviewView::Plan
+                };
+                generate_preview(
+                    &dir,
+                    width,
+                    height,
+                    layer.as_deref(),
+                    &highlight,
+                    outputs,
+                    view,
+                )
+            }
         }
-        Commands::Serve { path, port, open } => {
+        Commands::Serve {
+            path,
+            port,
+            open,
+            foreground,
+            stop,
+        } => {
             let dir = resolve_project_dir(path)?;
-            serve_project(&dir, port, open)
+            if stop {
+                serve_stop(&dir, port)
+            } else if foreground {
+                serve_project(&dir, port, open)
+            } else {
+                serve_daemon(&dir, port, open)
+            }
         }
         Commands::Schema => {
             print_schema();
diff --git a/src/mesh.rs b/src/mesh.rs
new file mode 100644
index 0000000..b13c6e3
--- /dev/null
+++ b/src/mesh.rs
@@ -0,0 +1,484 @@
+//! Triangle meshes + CSG booleans for the solid 3D view.
+//!
+//! Solids are triangle meshes. Booleans (`union`/`difference`/`intersection`)
+//! use a BSP-tree algorithm (the classic csg.js approach) — no dependencies,
+//! deterministic. Primitives (`box`, `cylinder`, extruded `prism`) tessellate
+//! to meshes; [`render3d`](crate::render3d) projects and shades the result.
+
+/// A 3D point / vector.
+pub type V3 = [f64; 3];
+
+fn add(a: V3, b: V3) -> V3 {
+    [a[0] + b[0], a[1] + b[1], a[2] + b[2]]
+}
+fn sub(a: V3, b: V3) -> V3 {
+    [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+}
+fn scale(a: V3, s: f64) -> V3 {
+    [a[0] * s, a[1] * s, a[2] * s]
+}
+fn dot(a: V3, b: V3) -> f64 {
+    a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+}
+fn cross(a: V3, b: V3) -> V3 {
+    [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ]
+}
+fn normalize(a: V3) -> V3 {
+    let l = dot(a, a).sqrt();
+    if l < 1e-12 {
+        a
+    } else {
+        scale(a, 1.0 / l)
+    }
+}
+fn lerp(a: V3, b: V3, t: f64) -> V3 {
+    add(a, scale(sub(b, a), t))
+}
+
+/// A triangle mesh (the only solid representation we keep).
+#[derive(Clone, Default)]
+pub struct Mesh {
+    pub tris: Vec<[V3; 3]>,
+}
+
+impl Mesh {
+    fn from_polys(polys: &[Poly]) -> Mesh {
+        let mut tris = Vec::new();
+        for p in polys {
+            // Fan-triangulate (BSP output polygons are convex).
+            for i in 1..p.verts.len().saturating_sub(1) {
+                tris.push([p.verts[0], p.verts[i], p.verts[i + 1]]);
+            }
+        }
+        Mesh { tris }
+    }
+
+    fn to_polys(&self) -> Vec<Poly> {
+        self.tris.iter().map(|t| Poly::new(t.to_vec())).collect()
+    }
+
+    /// Boolean union (`self` ∪ `other`).
+    pub fn union(&self, other: &Mesh) -> Mesh {
+        Mesh::from_polys(&csg_union(self.to_polys(), other.to_polys()))
+    }
+
+    /// Boolean difference (`self` − `other`).
+    pub fn difference(&self, other: &Mesh) -> Mesh {
+        Mesh::from_polys(&csg_difference(self.to_polys(), other.to_polys()))
+    }
+
+    /// Boolean intersection (`self` ∩ `other`).
+    pub fn intersection(&self, other: &Mesh) -> Mesh {
+        Mesh::from_polys(&csg_intersection(self.to_polys(), other.to_polys()))
+    }
+}
+
+// ── Primitive builders ──────────────────────────────────────────────────
+
+/// Axis-aligned box with its minimum corner at `at` and the given `size`.
+pub fn box_solid(at: V3, size: V3) -> Mesh {
+    let [x, y, z] = at;
+    let [sx, sy, sz] = size;
+    let c = [
+        [x, y, z],                // 0
+        [x + sx, y, z],           // 1
+        [x + sx, y + sy, z],      // 2
+        [x, y + sy, z],           // 3
+        [x, y, z + sz],           // 4
+        [x + sx, y, z + sz],      // 5
+        [x + sx, y + sy, z + sz], // 6
+        [x, y + sy, z + sz],      // 7
+    ];
+    // Each face as two triangles, wound CCW as seen from outside (consistent
+    // outward normals — the CSG BSP relies on it).
+    let faces = [
+        ([0, 3, 2], [0, 2, 1]), // bottom -Z
+        ([4, 5, 6], [4, 6, 7]), // top +Z
+        ([0, 1, 5], [0, 5, 4]), // -Y
+        ([1, 2, 6], [1, 6, 5]), // +X
+        ([2, 3, 7], [2, 7, 6]), // +Y
+        ([3, 0, 4], [3, 4, 7]), // -X
+    ];
+    let mut tris = Vec::with_capacity(12);
+    for (t1, t2) in faces {
+        tris.push([c[t1[0]], c[t1[1]], c[t1[2]]]);
+        tris.push([c[t2[0]], c[t2[1]], c[t2[2]]]);
+    }
+    Mesh { tris }
+}
+
+/// Vertical cylinder: base circle centered at `at`, radius `r`, height `h`.
+pub fn cylinder_solid(at: V3, r: f64, h: f64, segments: usize) -> Mesh {
+    let segs = segments.max(3);
+    let [cx, cy, cz] = at;
+    let top_c = [cx, cy, cz + h];
+    let bot_c = [cx, cy, cz];
+    let ring = |z: f64| -> Vec<V3> {
+        (0..segs)
+            .map(|i| {
+                let a = (i as f64 / segs as f64) * std::f64::consts::TAU;
+                [cx + r * a.cos(), cy + r * a.sin(), z]
+            })
+            .collect()
+    };
+    let bot = ring(cz);
+    let top = ring(cz + h);
+    let mut tris = Vec::with_capacity(segs * 4);
+    for i in 0..segs {
+        let j = (i + 1) % segs;
+        // Side (two triangles), outward.
+        tris.push([bot[i], bot[j], top[j]]);
+        tris.push([bot[i], top[j], top[i]]);
+        // Bottom fan (facing -Z) and top fan (facing +Z).
+        tris.push([bot_c, bot[j], bot[i]]);
+        tris.push([top_c, top[i], top[j]]);
+    }
+    Mesh { tris }
+}
+
+/// Extrude a 2D footprint from `base` to `base + height`. `closed` adds caps
+/// (a solid prism); otherwise only side walls are produced (an open wall).
+pub fn prism(footprint: &[[f64; 2]], base: f64, height: f64, closed: bool) -> Mesh {
+    let n = footprint.len();
+    if n < 2 {
+        return Mesh::default();
+    }
+    let top = base + height;
+    let mut tris = Vec::new();
+    let edges = if closed { n } else { n - 1 };
+    for i in 0..edges {
+        let a = footprint[i];
+        let b = footprint[(i + 1) % n];
+        let (a0, a1) = ([a[0], a[1], base], [a[0], a[1], top]);
+        let (b0, b1) = ([b[0], b[1], base], [b[0], b[1], top]);
+        tris.push([a0, b0, b1]);
+        tris.push([a0, b1, a1]);
+    }
+    if closed && n >= 3 {
+        // Caps (fan). Bottom faces -Z, top faces +Z.
+        for i in 1..n - 1 {
+            let t0 = [footprint[0][0], footprint[0][1], top];
+            let ti = [footprint[i][0], footprint[i][1], top];
+            let tj = [footprint[i + 1][0], footprint[i + 1][1], top];
+            tris.push([t0, ti, tj]);
+            let b0 = [footprint[0][0], footprint[0][1], base];
+            let bi = [footprint[i][0], footprint[i][1], base];
+            let bj = [footprint[i + 1][0], footprint[i + 1][1], base];
+            tris.push([b0, bj, bi]);
+        }
+    }
+    Mesh { tris }
+}
+
+// ── BSP CSG (port of csg.js) ──────────────────────────────────────────────
+
+const EPS: f64 = 1e-5;
+
+#[derive(Clone)]
+struct Plane {
+    normal: V3,
+    w: f64,
+}
+
+impl Plane {
+    fn from_points(a: V3, b: V3, c: V3) -> Plane {
+        let normal = normalize(cross(sub(b, a), sub(c, a)));
+        Plane {
+            w: dot(normal, a),
+            normal,
+        }
+    }
+    fn flip(&mut self) {
+        self.normal = scale(self.normal, -1.0);
+        self.w = -self.w;
+    }
+}
+
+#[derive(Clone)]
+struct Poly {
+    verts: Vec<V3>,
+    plane: Plane,
+}
+
+impl Poly {
+    fn new(verts: Vec<V3>) -> Poly {
+        let plane = Plane::from_points(verts[0], verts[1], verts[2]);
+        Poly { verts, plane }
+    }
+    fn flip(&mut self) {
+        self.verts.reverse();
+        self.plane.flip();
+    }
+}
+
+const COPLANAR: u8 = 0;
+const FRONT: u8 = 1;
+const BACK: u8 = 2;
+const SPANNING: u8 = 3;
+
+/// Split `poly` by `plane`, appending the pieces to the appropriate buckets.
+fn split_polygon(
+    plane: &Plane,
+    poly: &Poly,
+    coplanar_front: &mut Vec<Poly>,
+    coplanar_back: &mut Vec<Poly>,
+    front: &mut Vec<Poly>,
+    back: &mut Vec<Poly>,
+) {
+    let mut poly_type = 0u8;
+    let mut types = Vec::with_capacity(poly.verts.len());
+    for v in &poly.verts {
+        let t = dot(plane.normal, *v) - plane.w;
+        let ty = if t < -EPS {
+            BACK
+        } else if t > EPS {
+            FRONT
+        } else {
+            COPLANAR
+        };
+        poly_type |= ty;
+        types.push(ty);
+    }
+    match poly_type {
+        COPLANAR => {
+            if dot(plane.normal, poly.plane.normal) > 0.0 {
+                coplanar_front.push(poly.clone());
+            } else {
+                coplanar_back.push(poly.clone());
+            }
+        }
+        FRONT => front.push(poly.clone()),
+        BACK => back.push(poly.clone()),
+        _ => {
+            let mut fv = Vec::new();
+            let mut bv = Vec::new();
+            let n = poly.verts.len();
+            for i in 0..n {
+                let j = (i + 1) % n;
+                let (ti, tj) = (types[i], types[j]);
+                let (vi, vj) = (poly.verts[i], poly.verts[j]);
+                if ti != BACK {
+                    fv.push(vi);
+                }
+                if ti != FRONT {
+                    bv.push(vi);
+                }
+                if (ti | tj) == SPANNING {
+                    let denom = dot(plane.normal, sub(vj, vi));
+                    let t = if denom.abs() < 1e-12 {
+                        0.0
+                    } else {
+                        (plane.w - dot(plane.normal, vi)) / denom
+                    };
+                    let v = lerp(vi, vj, t);
+                    fv.push(v);
+                    bv.push(v);
+                }
+            }
+            if fv.len() >= 3 {
+                front.push(Poly::new(fv));
+            }
+            if bv.len() >= 3 {
+                back.push(Poly::new(bv));
+            }
+        }
+    }
+}
+
+#[derive(Default)]
+struct Node {
+    plane: Option<Plane>,
+    front: Option<Box<Node>>,
+    back: Option<Box<Node>>,
+    polygons: Vec<Poly>,
+}
+
+impl Node {
+    fn build(&mut self, polygons: Vec<Poly>) {
+        if polygons.is_empty() {
+            return;
+        }
+        if self.plane.is_none() {
+            self.plane = Some(polygons[0].plane.clone());
+        }
+        let plane = self.plane.clone().unwrap();
+        let mut front = Vec::new();
+        let mut back = Vec::new();
+        let mut cf = Vec::new();
+        let mut cb = Vec::new();
+        for p in &polygons {
+            split_polygon(&plane, p, &mut cf, &mut cb, &mut front, &mut back);
+        }
+        // Both coplanar buckets stay on this node (csg.js Node.build).
+        self.polygons.extend(cf);
+        self.polygons.extend(cb);
+        if !front.is_empty() {
+            self.front.get_or_insert_with(Default::default).build(front);
+        }
+        if !back.is_empty() {
+            self.back.get_or_insert_with(Default::default).build(back);
+        }
+    }
+
+    fn invert(&mut self) {
+        for p in &mut self.polygons {
+            p.flip();
+        }
+        if let Some(pl) = &mut self.plane {
+            pl.flip();
+        }
+        if let Some(f) = &mut self.front {
+            f.invert();
+        }
+        if let Some(b) = &mut self.back {
+            b.invert();
+        }
+        std::mem::swap(&mut self.front, &mut self.back);
+    }
+
+    fn clip_polygons(&self, polygons: Vec<Poly>) -> Vec<Poly> {
+        let Some(plane) = &self.plane else {
+            return polygons;
+        };
+        let mut front = Vec::new();
+        let mut back = Vec::new();
+        let mut cf = Vec::new();
+        let mut cb = Vec::new();
+        for p in &polygons {
+            split_polygon(plane, p, &mut cf, &mut cb, &mut front, &mut back);
+        }
+        // Coplanar pieces follow csg.js: front-facing with front, back with back.
+        front.extend(cf);
+        back.extend(cb);
+        let mut front = match &self.front {
+            Some(n) => n.clip_polygons(front),
+            None => front,
+        };
+        if let Some(n) = &self.back {
+            front.extend(n.clip_polygons(back));
+        }
+        front
+    }
+
+    fn clip_to(&mut self, other: &Node) {
+        self.polygons = other.clip_polygons(std::mem::take(&mut self.polygons));
+        if let Some(f) = &mut self.front {
+            f.clip_to(other);
+        }
+        if let Some(b) = &mut self.back {
+            b.clip_to(other);
+        }
+    }
+
+    fn all_polygons(&self) -> Vec<Poly> {
+        let mut out = self.polygons.clone();
+        if let Some(f) = &self.front {
+            out.extend(f.all_polygons());
+        }
+        if let Some(b) = &self.back {
+            out.extend(b.all_polygons());
+        }
+        out
+    }
+}
+
+fn node_of(polys: Vec<Poly>) -> Node {
+    let mut n = Node::default();
+    n.build(polys);
+    n
+}
+
+fn csg_union(a: Vec<Poly>, b: Vec<Poly>) -> Vec<Poly> {
+    let mut a = node_of(a);
+    let mut b = node_of(b);
+    a.clip_to(&b);
+    b.clip_to(&a);
+    b.invert();
+    b.clip_to(&a);
+    b.invert();
+    a.build(b.all_polygons());
+    a.all_polygons()
+}
+
+fn csg_difference(a: Vec<Poly>, b: Vec<Poly>) -> Vec<Poly> {
+    let mut a = node_of(a);
+    let mut b = node_of(b);
+    a.invert();
+    a.clip_to(&b);
+    b.clip_to(&a);
+    b.invert();
+    b.clip_to(&a);
+    b.invert();
+    a.build(b.all_polygons());
+    a.invert();
+    a.all_polygons()
+}
+
+fn csg_intersection(a: Vec<Poly>, b: Vec<Poly>) -> Vec<Poly> {
+    let mut a = node_of(a);
+    let mut b = node_of(b);
+    a.invert();
+    b.clip_to(&a);
+    b.invert();
+    a.clip_to(&b);
+    b.clip_to(&a);
+    a.build(b.all_polygons());
+    a.invert();
+    a.all_polygons()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn signed_volume(m: &Mesh) -> f64 {
+        // Sum of signed tetrahedron volumes (origin apex) — |result| = volume.
+        m.tris
+            .iter()
+            .map(|t| dot(t[0], cross(t[1], t[2])) / 6.0)
+            .sum::<f64>()
+            .abs()
+    }
+
+    #[test]
+    fn box_volume_is_correct() {
+        let b = box_solid([0.0, 0.0, 0.0], [2.0, 3.0, 4.0]);
+        assert_eq!(b.tris.len(), 12);
+        assert!((signed_volume(&b) - 24.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn difference_removes_material() {
+        // 4×4×4 cube minus a 2×2 column straight through it: volume 64 - 16 = 48.
+        let cube = box_solid([0.0, 0.0, 0.0], [4.0, 4.0, 4.0]);
+        let bore = box_solid([1.0, 1.0, -1.0], [2.0, 2.0, 6.0]);
+        let holed = cube.difference(&bore);
+        assert!(!holed.tris.is_empty());
+        assert!(
+            (signed_volume(&holed) - 48.0).abs() < 1e-4,
+            "expected 48, got {}",
+            signed_volume(&holed)
+        );
+    }
+
+    #[test]
+    fn union_merges_volume() {
+        // Two disjoint unit cubes: total volume 2.
+        let a = box_solid([0.0, 0.0, 0.0], [1.0, 1.0, 1.0]);
+        let b = box_solid([5.0, 0.0, 0.0], [1.0, 1.0, 1.0]);
+        assert!((signed_volume(&a.union(&b)) - 2.0).abs() < 1e-4);
+    }
+
+    #[test]
+    fn cylinder_and_prism_build() {
+        assert!(!cylinder_solid([0.0, 0.0, 0.0], 1.0, 2.0, 24)
+            .tris
+            .is_empty());
+        let sq = [[0.0, 0.0], [2.0, 0.0], [2.0, 2.0], [0.0, 2.0]];
+        assert!((signed_volume(&prism(&sq, 0.0, 3.0, true)) - 12.0).abs() < 1e-6);
+    }
+}
diff --git a/src/model.rs b/src/model.rs
index 16eb5ef..a2490d9 100644
--- a/src/model.rs
+++ b/src/model.rs
@@ -15,6 +15,11 @@ pub struct CommonAttrs {
     pub visible: bool,
     #[serde(default)]
     pub locked: bool,
+    /// Extrusion height in world units for the 3D view. `None`/0 stays flat;
+    /// a closed shape becomes a solid, a line/open polyline becomes a wall.
+    pub extrude: Option<f64>,
+    /// Base elevation (Z) for the 3D view. Defaults to 0 (the ground plane).
+    pub elevation: Option<f64>,
 }
 
 fn default_true() -> bool {
@@ -220,6 +225,41 @@ pub struct CfFill {
     pub common: CommonAttrs,
 }
 
+// ── 3D solids (CSG) ────────────────────────────────────────────────────
+
+/// A named 3D primitive solid for the extruded/CSG view. Referenced by id from
+/// `[[boolean]]`. 3D-only — solids do not appear in the 2D plan or DXF.
+#[derive(Debug, Clone, Deserialize)]
+pub struct CfSolid {
+    pub id: String,
+    /// `box` | `cylinder`.
+    pub shape: String,
+    /// Placement: box minimum corner, or cylinder base-circle center. Default origin.
+    pub at: Option<[f64; 3]>,
+    /// Box dimensions [sx, sy, sz].
+    pub size: Option<[f64; 3]>,
+    /// Cylinder radius.
+    pub radius: Option<f64>,
+    /// Cylinder height.
+    pub height: Option<f64>,
+    /// Cylinder facet count (default 40).
+    pub segments: Option<usize>,
+    pub color: Option<String>,
+}
+
+/// A CSG operation combining named solids. The result is rendered; the solids
+/// it consumes (`base` + `tools`) are not drawn on their own.
+#[derive(Debug, Clone, Deserialize)]
+pub struct CfBoolean {
+    pub id: Option<String>,
+    /// `difference` | `union` | `intersection`.
+    pub op: String,
+    pub base: String,
+    #[serde(default)]
+    pub tools: Vec<String>,
+    pub color: Option<String>,
+}
+
 // ── Layer-level metadata ───────────────────────────────────────────────
 
 #[derive(Debug, Clone, Deserialize, Default)]
@@ -265,4 +305,8 @@ pub struct CfFile {
     pub arrays: Vec<CfArray>,
     #[serde(default, rename = "mirror")]
     pub mirrors: Vec<CfMirror>,
+    #[serde(default, rename = "solid")]
+    pub solids: Vec<CfSolid>,
+    #[serde(default, rename = "boolean")]
+    pub booleans: Vec<CfBoolean>,
 }
diff --git a/src/parser.rs b/src/parser.rs
index ac5fe2f..3557a97 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -14,6 +14,37 @@ pub struct ProjectFile {
     pub layers: IndexMap<String, LayerEntry>,
     #[serde(default)]
     pub constraints: Option<toml::Value>,
+    /// Drawing sheets ("planos"): named views of the model with a title block.
+    #[serde(default, rename = "plano")]
+    pub planos: Vec<Plano>,
+}
+
+/// A drawing sheet: a named view of the model at a paper size, with a title
+/// block (rótulo). Views: `plan` (top), `iso`, `front`/`back`/`left`/`right`
+/// elevations, or `section` (a cut).
+#[derive(Debug, Clone, Deserialize)]
+pub struct Plano {
+    pub name: String,
+    #[serde(default = "default_view")]
+    pub view: String,
+    /// Sheet size [width, height] in mm. Default A3 landscape.
+    pub size: Option<[f64; 2]>,
+    /// Drawing scale label for the title block (e.g. "1:50").
+    pub scale: Option<String>,
+    /// Title shown in the rótulo (defaults to the plano name).
+    pub title: Option<String>,
+    /// Path to a `.cf` file drawn as a custom title block instead of the default.
+    pub rotulo: Option<String>,
+    /// Section only: cut axis `x` | `y` | `z`.
+    pub cut_axis: Option<String>,
+    /// Section only: position of the cut plane along `cut_axis`.
+    pub cut_at: Option<f64>,
+    /// Section only: which side to keep, `min` (default) or `max`.
+    pub keep: Option<String>,
+}
+
+fn default_view() -> String {
+    "plan".to_string()
 }
 
 #[derive(Debug, Clone, Deserialize)]
diff --git a/src/planos.rs b/src/planos.rs
new file mode 100644
index 0000000..64589af
--- /dev/null
+++ b/src/planos.rs
@@ -0,0 +1,289 @@
+//! Planos (drawing sheets) — render a named view of the model onto a sheet
+//! with a title block (rótulo).
+//!
+//! A "plano" is the CAD notion of a sheet/viewport: it reuses the one model and
+//! presents it through a chosen view (plan, iso, the four elevations, or a
+//! section cut), framed at a paper size with a title block. The title block is
+//! either auto-generated from the project metadata or drawn by the user in a
+//! `.cf` file referenced via `rotulo` — same primitives as everything else.
+
+use crate::parser::{parse_cf, Plano};
+use crate::render3d::{render_view, Camera, Cut};
+use crate::svg::{load_project_layers, render_scene_from};
+use anyhow::Result;
+use std::fmt::Write as _;
+use std::path::Path;
+
+const INNER_W: u32 = 1400;
+const BG: &str = "#0d0d0d";
+const FRAME: &str = "#9a9a9a";
+const INK: &str = "#e0e0e0";
+const MUTED: &str = "#9a9a9a";
+
+/// A rendered sheet SVG plus its pixel size.
+pub struct Sheet {
+    pub svg: String,
+    pub width_px: f64,
+    pub height_px: f64,
+}
+
+/// Render a single plano to a framed sheet SVG.
+pub fn render_plano(project_dir: &Path, plano: &Plano, target_width: u32) -> Result<Sheet> {
+    let (project, layers) = load_project_layers(project_dir, None)?;
+
+    // 1. Render the model through the requested view.
+    let (inner_svg, iw, ih) = match plano.view.as_str() {
+        "plan" => {
+            let s = render_scene_from(
+                &project.project.name,
+                &project.project.units,
+                &layers,
+                INNER_W,
+                &[],
+            );
+            (s.svg, s.width_px, s.height_px)
+        }
+        "section" => {
+            let axis = match plano.cut_axis.as_deref() {
+                Some("x") => 0,
+                Some("y") => 1,
+                _ => 2, // default: horizontal cut (z)
+            };
+            let cam = match axis {
+                0 => Camera::right_side(),
+                1 => Camera::front(),
+                _ => Camera::top(),
+            };
+            let cut = Cut {
+                axis,
+                at: plano.cut_at.unwrap_or(0.0),
+                keep_max: plano.keep.as_deref() == Some("max"),
+            };
+            let r = render_view(&layers, INNER_W, &cam, Some(&cut));
+            (r.svg, r.width_px, r.height_px)
+        }
+        other => {
+            let cam = match other {
+                "front" => Camera::front(),
+                "back" => Camera::back(),
+                "left" => Camera::left_side(),
+                "right" => Camera::right_side(),
+                "top" => Camera::top(),
+                _ => Camera::iso(),
+            };
+            let r = render_view(&layers, INNER_W, &cam, None);
+            (r.svg, r.width_px, r.height_px)
+        }
+    };
+
+    // 2. Sheet geometry (paper size in mm → pixels).
+    let [mm_w, mm_h] = plano.size.unwrap_or([420.0, 297.0]); // A3 landscape
+    let sheet_w = target_width as f64;
+    let sheet_h = sheet_w * (mm_h / mm_w).max(0.1);
+    let margin = sheet_w * 0.02;
+
+    // Title block: bottom-right box.
+    let tb_w = (sheet_w * 0.34).min(sheet_w - 2.0 * margin);
+    let tb_h = (sheet_h * 0.16).min(sheet_h - 2.0 * margin);
+    let tb_x = sheet_w - margin - tb_w;
+    let tb_y = sheet_h - margin - tb_h;
+
+    // Drawing area: inside the frame, above the title block.
+    let draw_x = margin + margin;
+    let draw_y = margin + margin;
+    let draw_w = sheet_w - 2.0 * draw_x;
+    let draw_h = (tb_y - draw_y - margin).max(1.0);
+
+    // 3. Compose the sheet SVG.
+    let mut out = String::with_capacity(inner_svg.len() + 4096);
+    let _ = write!(
+        out,
+        r#"<svg xmlns="http://www.w3.org/2000/svg" width="{w:.0}" height="{h:.0}" viewBox="0 0 {w:.0} {h:.0}" data-view="plano">"#,
+        w = sheet_w,
+        h = sheet_h,
+    );
+    let _ = write!(out, r#"<rect width="100%" height="100%" fill="{BG}"/>"#);
+    // Outer frame border.
+    let _ = write!(
+        out,
+        r#"<rect x="{x:.1}" y="{x:.1}" width="{w:.1}" height="{h:.1}" fill="none" stroke="{FRAME}" stroke-width="2"/>"#,
+        x = margin,
+        w = sheet_w - 2.0 * margin,
+        h = sheet_h - 2.0 * margin,
+    );
+
+    // The model view, fitted into the drawing area (nested SVG keeps aspect).
+    let _ = write!(
+        out,
+        r#"<svg x="{dx:.1}" y="{dy:.1}" width="{dw:.1}" height="{dh:.1}" viewBox="0 0 {iw:.0} {ih:.0}" preserveAspectRatio="xMidYMid meet">{body}</svg>"#,
+        dx = draw_x,
+        dy = draw_y,
+        dw = draw_w,
+        dh = draw_h,
+        body = svg_inner(&inner_svg),
+    );
+
+    // 4. Title block (rótulo): custom .cf or generated default.
+    out.push_str(&title_block(
+        project_dir,
+        plano,
+        &project.project.name,
+        &project.project.units,
+        project.project.scale.as_str(),
+        tb_x,
+        tb_y,
+        tb_w,
+        tb_h,
+    ));
+
+    out.push_str("</svg>");
+    Ok(Sheet {
+        svg: out,
+        width_px: sheet_w,
+        height_px: sheet_h,
+    })
+}
+
+/// The content between an SVG's outer `<svg …>` and `</svg>` tags.
+fn svg_inner(svg: &str) -> &str {
+    let start = svg.find('>').map(|i| i + 1).unwrap_or(0);
+    let end = svg.rfind("</svg>").unwrap_or(svg.len());
+    if start <= end {
+        &svg[start..end]
+    } else {
+        ""
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn title_block(
+    project_dir: &Path,
+    plano: &Plano,
+    project_name: &str,
+    units: &str,
+    project_scale: &str,
+    x: f64,
+    y: f64,
+    w: f64,
+    h: f64,
+) -> String {
+    // Custom rótulo: render the referenced .cf, fitted into the title block.
+    if let Some(rotulo) = &plano.rotulo {
+        if let Ok(cf) = parse_cf(&project_dir.join(rotulo)) {
+            let scene = render_scene_from(
+                project_name,
+                units,
+                &[("rotulo".to_string(), cf)],
+                INNER_W,
+                &[],
+            );
+            return format!(
+                r#"<rect x="{x:.1}" y="{y:.1}" width="{w:.1}" height="{h:.1}" fill="{BG}" stroke="{FRAME}" stroke-width="2"/>"#,
+            ) + &format!(
+                r#"<svg x="{x:.1}" y="{y:.1}" width="{w:.1}" height="{h:.1}" viewBox="0 0 {iw:.0} {ih:.0}" preserveAspectRatio="xMidYMid meet">{body}</svg>"#,
+                iw = scene.width_px,
+                ih = scene.height_px,
+                body = svg_inner(&scene.svg),
+            );
+        }
+    }
+
+    // Default rótulo.
+    let title = plano.title.as_deref().unwrap_or(&plano.name);
+    let scale = plano.scale.as_deref().unwrap_or(project_scale);
+    let pad = w * 0.04;
+    let row = h / 4.0;
+    let mut s = String::new();
+    let _ = write!(
+        s,
+        r#"<rect x="{x:.1}" y="{y:.1}" width="{w:.1}" height="{h:.1}" fill="{BG}" stroke="{FRAME}" stroke-width="2"/>"#,
+    );
+    // Divider under the title.
+    let _ = write!(
+        s,
+        r#"<line x1="{x:.1}" y1="{ly:.1}" x2="{x2:.1}" y2="{ly:.1}" stroke="{FRAME}" stroke-width="1"/>"#,
+        ly = y + row * 1.6,
+        x2 = x + w,
+    );
+    let fs_title = (row * 0.62).max(8.0);
+    let fs = (row * 0.40).max(7.0);
+    let _ = write!(
+        s,
+        r#"<text x="{tx:.1}" y="{ty:.1}" font-family="monospace" font-size="{fs_title:.1}" fill="{INK}">{title}</text>"#,
+        tx = x + pad,
+        ty = y + row * 1.05,
+        title = xml_escape(title),
+    );
+    let _ = write!(
+        s,
+        r#"<text x="{tx:.1}" y="{ty:.1}" font-family="monospace" font-size="{fs:.1}" fill="{MUTED}">{n}</text>"#,
+        tx = x + pad,
+        ty = y + row * 2.35,
+        n = xml_escape(project_name),
+    );
+    let _ = write!(
+        s,
+        r#"<text x="{tx:.1}" y="{ty:.1}" font-family="monospace" font-size="{fs:.1}" fill="{MUTED}">Escala {scale} · {units} · {view}</text>"#,
+        tx = x + pad,
+        ty = y + row * 3.25,
+        view = xml_escape(&plano.view),
+        scale = xml_escape(scale),
+        units = xml_escape(units),
+    );
+    let _ = write!(
+        s,
+        r#"<text x="{tx:.1}" y="{ty:.1}" font-family="monospace" font-size="{fs:.1}" fill="{MUTED}" text-anchor="end">cadforge</text>"#,
+        tx = x + w - pad,
+        ty = y + h - row * 0.35,
+    );
+    s
+}
+
+fn xml_escape(s: &str) -> String {
+    s.replace('&', "&amp;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+        .replace('"', "&quot;")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::parser::Plano;
+
+    fn plano(view: &str) -> Plano {
+        Plano {
+            name: "P-01".into(),
+            view: view.into(),
+            size: Some([420.0, 297.0]),
+            scale: Some("1:50".into()),
+            title: Some("Planta baja".into()),
+            rotulo: None,
+            cut_axis: None,
+            cut_at: None,
+            keep: None,
+        }
+    }
+
+    #[test]
+    fn renders_plan_sheet_with_title_block() {
+        let dir = Path::new("examples/vivienda");
+        let s = render_plano(dir, &plano("plan"), 1200).unwrap();
+        assert!(s.svg.contains(r#"data-view="plano""#));
+        assert!(s.svg.contains("Planta baja"));
+        assert!(s.svg.contains("Escala 1:50"));
+        // The model view is nested inside the sheet.
+        assert!(s.svg.matches("<svg").count() >= 2);
+        assert!((s.width_px - 1200.0).abs() < 1.0 && s.height_px > 0.0);
+    }
+
+    #[test]
+    fn renders_section_sheet() {
+        let dir = Path::new("examples/vivienda");
+        let mut p = plano("section");
+        p.cut_axis = Some("z".into());
+        p.cut_at = Some(1.0);
+        let s = render_plano(dir, &p, 1000).unwrap();
+        assert!(s.svg.contains(r#"data-view="plano""#));
+    }
+}
diff --git a/src/preview.rs b/src/preview.rs
index da7f5ad..55c670d 100644
--- a/src/preview.rs
+++ b/src/preview.rs
@@ -7,6 +7,9 @@
 //! the image.
 
 use crate::model::CfFile;
+use crate::parser::parse_project;
+use crate::planos::render_plano;
+use crate::render3d::render_scene_3d;
 use crate::svg::{
     enumerate_entities, layer_display_color, load_project_layers, render_scene_from, Scene,
 };
@@ -70,6 +73,15 @@ pub struct PreviewOutputs {
     pub svg: bool,
 }
 
+/// Which projection to render.
+#[derive(Clone, Copy, PartialEq)]
+pub enum PreviewView {
+    /// Flat 2D plan (the default).
+    Plan,
+    /// Extruded axonometric 3D view.
+    ThreeD,
+}
+
 /// Generate preview artifacts (PNG + metadata JSON, and/or SVG) for the project.
 ///
 /// Everything is produced from a single parse + render pass.
@@ -82,7 +94,11 @@ pub fn generate_preview(
     layer_filter: Option<&str>,
     highlight: &[String],
     outputs: PreviewOutputs,
+    view: PreviewView,
 ) -> Result<()> {
+    if view == PreviewView::ThreeD {
+        return generate_preview_3d(project_dir, width, height, layer_filter, outputs);
+    }
     let (project, layers) = load_project_layers(project_dir, layer_filter)?;
     let scene = render_scene_from(
         &project.project.name,
@@ -134,6 +150,88 @@ pub fn generate_preview(
     Ok(())
 }
 
+/// Render the extruded 3D view. Geometry is projected axonometrically, so there
+/// is no world→pixel mapping to emit — we write the PNG (and optional SVG) only.
+fn generate_preview_3d(
+    project_dir: &Path,
+    width: u32,
+    height: u32,
+    layer_filter: Option<&str>,
+    outputs: PreviewOutputs,
+) -> Result<()> {
+    let (_project, layers) = load_project_layers(project_dir, layer_filter)?;
+    let scene = render_scene_3d(&layers, width);
+
+    if outputs.svg {
+        let svg_path = project_dir.join("preview.svg");
+        std::fs::write(&svg_path, &scene.svg)
+            .with_context(|| format!("Cannot write {}", svg_path.display()))?;
+        println!("✓ SVG (3D): {}", svg_path.display());
+    }
+
+    if !outputs.png {
+        return Ok(());
+    }
+
+    let fit = (height as f64 / scene.height_px).min(1.0);
+    let pixmap = rasterize(&scene.svg, fit as f32)?;
+    let png_path = project_dir.join("preview.png");
+    pixmap
+        .save_png(&png_path)
+        .map_err(|e| anyhow::anyhow!("Failed to save PNG: {}", e))?;
+    println!(
+        "✓ Preview (3D): {} ({}x{})",
+        png_path.display(),
+        pixmap.width(),
+        pixmap.height()
+    );
+    Ok(())
+}
+
+/// Render a named plano (drawing sheet) to `preview.png` (and/or `preview.svg`).
+pub fn generate_plano(
+    project_dir: &Path,
+    name: &str,
+    width: u32,
+    height: u32,
+    outputs: PreviewOutputs,
+) -> Result<()> {
+    let project = parse_project(&project_dir.join("project.toml"))?;
+    let plano = project
+        .planos
+        .iter()
+        .find(|p| p.name == name)
+        .ok_or_else(|| {
+            let names: Vec<&str> = project.planos.iter().map(|p| p.name.as_str()).collect();
+            anyhow::anyhow!("no plano named '{}' (have: {})", name, names.join(", "))
+        })?;
+    let sheet = render_plano(project_dir, plano, width)?;
+
+    if outputs.svg {
+        let svg_path = project_dir.join("preview.svg");
+        std::fs::write(&svg_path, &sheet.svg)
+            .with_context(|| format!("Cannot write {}", svg_path.display()))?;
+        println!("✓ SVG (plano '{}'): {}", name, svg_path.display());
+    }
+    if !outputs.png {
+        return Ok(());
+    }
+    let fit = (height as f64 / sheet.height_px).min(1.0);
+    let pixmap = rasterize(&sheet.svg, fit as f32)?;
+    let png_path = project_dir.join("preview.png");
+    pixmap
+        .save_png(&png_path)
+        .map_err(|e| anyhow::anyhow!("Failed to save PNG: {}", e))?;
+    println!(
+        "✓ Preview (plano '{}'): {} ({}x{})",
+        name,
+        png_path.display(),
+        pixmap.width(),
+        pixmap.height()
+    );
+    Ok(())
+}
+
 // ── Internal ────────────────────────────────────────────────────────────
 
 fn build_meta(
diff --git a/src/render3d.rs b/src/render3d.rs
new file mode 100644
index 0000000..1195585
--- /dev/null
+++ b/src/render3d.rs
@@ -0,0 +1,620 @@
+//! 3D view renderer — extrudes `.cf` geometry into solids and projects them.
+//!
+//! cadforge geometry is declared in 2D plan coordinates. Any primitive can
+//! carry an `extrude` height (and optional `elevation`): a closed shape becomes
+//! a solid prism, a line or open polyline becomes a vertical wall. This module
+//! projects that geometry with a fixed axonometric (isometric) camera, sorts
+//! the faces back-to-front (painter's algorithm) and shades them, producing a
+//! single self-contained SVG — the same backend story as the 2D renderer, so
+//! it rasterizes to PNG and streams to the live viewer identically.
+
+use crate::mesh;
+use crate::model::{CfFile, CommonAttrs};
+use crate::svg::layer_display_color;
+use std::fmt::Write as _;
+
+const BG_COLOR: &str = "#141414";
+const PADDING_PX: f64 = 48.0;
+const CIRCLE_SEGMENTS: usize = 40;
+
+/// A rendered 3D SVG plus its pixel size (for the PNG rasterizer).
+pub struct Render3d {
+    pub svg: String,
+    pub width_px: f64,
+    pub height_px: f64,
+}
+
+/// One projected, shaded polygon ready to emit, with its camera depth.
+struct Face {
+    /// Projected screen-space points (pre-fit): (horizontal, vertical-up).
+    proj: Vec<(f64, f64)>,
+    fill: Option<String>,
+    stroke: String,
+    stroke_w: f64,
+    /// Larger = closer to the camera (drawn later, on top).
+    depth: f64,
+    layer: String,
+    id: Option<String>,
+}
+
+/// An orthographic/axonometric camera: screen-horizontal (`right`), screen-up
+/// (`up`) and the viewing direction (`view`, pointing from the scene toward the
+/// camera — used for depth sorting and back-face culling). Project a world
+/// point by dotting it against `right`/`up`.
+#[derive(Clone, Copy)]
+pub struct Camera {
+    right: V3,
+    up: V3,
+    view: V3,
+}
+
+impl Camera {
+    /// Standard 2:1 isometric (the default 3D look).
+    pub fn iso() -> Camera {
+        const C: f64 = 0.866_025_403_784_438_6;
+        const S: f64 = 0.5;
+        Camera {
+            right: [C, -C, 0.0],
+            up: [-S, -S, 1.0],
+            view: [0.577_350_27, 0.577_350_27, 0.577_350_27],
+        }
+    }
+    /// Looking straight down (-Z): a plan / planta.
+    pub fn top() -> Camera {
+        Camera {
+            right: [1.0, 0.0, 0.0],
+            up: [0.0, 1.0, 0.0],
+            view: [0.0, 0.0, 1.0],
+        }
+    }
+    pub fn front() -> Camera {
+        Camera {
+            right: [1.0, 0.0, 0.0],
+            up: [0.0, 0.0, 1.0],
+            view: [0.0, -1.0, 0.0],
+        }
+    }
+    pub fn back() -> Camera {
+        Camera {
+            right: [-1.0, 0.0, 0.0],
+            up: [0.0, 0.0, 1.0],
+            view: [0.0, 1.0, 0.0],
+        }
+    }
+    pub fn right_side() -> Camera {
+        Camera {
+            right: [0.0, -1.0, 0.0],
+            up: [0.0, 0.0, 1.0],
+            view: [1.0, 0.0, 0.0],
+        }
+    }
+    pub fn left_side() -> Camera {
+        Camera {
+            right: [0.0, 1.0, 0.0],
+            up: [0.0, 0.0, 1.0],
+            view: [-1.0, 0.0, 0.0],
+        }
+    }
+    fn project(&self, p: V3) -> (f64, f64) {
+        (v_dot(p, self.right), v_dot(p, self.up))
+    }
+    fn depth(&self, p: V3) -> f64 {
+        v_dot(p, self.view)
+    }
+}
+
+/// A section cut: keep one half-space of the model, revealing the interior at
+/// the cut plane. `axis` is 0=x, 1=y, 2=z; `keep_max` keeps the side where the
+/// coordinate is ≥ `at` (otherwise ≤ `at`).
+#[derive(Clone, Copy)]
+pub struct Cut {
+    pub axis: usize,
+    pub at: f64,
+    pub keep_max: bool,
+}
+
+impl Cut {
+    /// A huge box covering the discarded half-space (to subtract from solids).
+    fn discard_box(&self) -> mesh::Mesh {
+        const BIG: f64 = 1.0e5;
+        let mut at = [-BIG, -BIG, -BIG];
+        let mut size = [2.0 * BIG, 2.0 * BIG, 2.0 * BIG];
+        if self.keep_max {
+            at[self.axis] = -BIG; // discard coord < at
+            size[self.axis] = self.at + BIG;
+        } else {
+            at[self.axis] = self.at; // discard coord > at
+            size[self.axis] = BIG;
+        }
+        mesh::box_solid(at, size)
+    }
+}
+
+/// Render already-parsed layers to an isometric 3D [`Render3d`].
+pub fn render_scene_3d(layers: &[(String, CfFile)], width: u32) -> Render3d {
+    render_view(layers, width, &Camera::iso(), None)
+}
+
+/// Render already-parsed layers through an arbitrary [`Camera`], optionally
+/// sectioned by `cut`.
+pub fn render_view(
+    layers: &[(String, CfFile)],
+    width: u32,
+    cam: &Camera,
+    cut: Option<&Cut>,
+) -> Render3d {
+    let mut faces: Vec<Face> = Vec::new();
+
+    for (idx, (layer_name, cf)) in layers.iter().enumerate() {
+        let visible = cf.layer_meta.as_ref().map(|m| m.visible).unwrap_or(true);
+        if !visible {
+            continue;
+        }
+        let layer_color = layer_display_color(cf, idx);
+        collect_layer_faces(&mut faces, layer_name, cf, &layer_color, cam, cut);
+    }
+
+    // Project bounds across every face to size the canvas.
+    let (mut min_h, mut min_v, mut max_h, mut max_v) = (f64::MAX, f64::MAX, f64::MIN, f64::MIN);
+    for f in &faces {
+        for &(h, v) in &f.proj {
+            min_h = min_h.min(h);
+            min_v = min_v.min(v);
+            max_h = max_h.max(h);
+            max_v = max_v.max(v);
+        }
+    }
+    if faces.is_empty() {
+        min_h = 0.0;
+        min_v = 0.0;
+        max_h = 10.0;
+        max_v = 10.0;
+    }
+
+    let span_h = (max_h - min_h).max(1e-6);
+    let span_v = (max_v - min_v).max(1e-6);
+    let width_px = width as f64;
+    let scale = (width_px - 2.0 * PADDING_PX).max(1.0) / span_h;
+    let height_px = span_v * scale + 2.0 * PADDING_PX;
+
+    // World→screen: flip vertical (SVG y grows down) so up is up.
+    let to_px = |(h, v): (f64, f64)| -> (f64, f64) {
+        (
+            (h - min_h) * scale + PADDING_PX,
+            (max_v - v) * scale + PADDING_PX,
+        )
+    };
+
+    // Painter's algorithm: farthest first.
+    faces.sort_by(|a, b| {
+        a.depth
+            .partial_cmp(&b.depth)
+            .unwrap_or(std::cmp::Ordering::Equal)
+    });
+
+    let mut out = String::with_capacity(16 * 1024 + faces.len() * 96);
+    let _ = write!(
+        out,
+        r#"<svg xmlns="http://www.w3.org/2000/svg" width="{w:.0}" height="{h:.0}" viewBox="0 0 {w:.0} {h:.0}" data-view="3d">"#,
+        w = width_px,
+        h = height_px,
+    );
+    let _ = write!(
+        out,
+        r#"<rect width="100%" height="100%" fill="{}"/>"#,
+        BG_COLOR
+    );
+
+    for f in &faces {
+        let pts: String = f
+            .proj
+            .iter()
+            .map(|&p| {
+                let (x, y) = to_px(p);
+                format!("{x:.2},{y:.2}")
+            })
+            .collect::<Vec<_>>()
+            .join(" ");
+        let layer_attr = format!(r#" data-layer="{}""#, xml_escape(&f.layer));
+        let id_attr = match &f.id {
+            Some(id) => format!(r#" data-id="{}""#, xml_escape(id)),
+            None => String::new(),
+        };
+        match &f.fill {
+            Some(fill) => {
+                let _ = write!(
+                    out,
+                    r#"<polygon points="{pts}" fill="{fill}" stroke="{stroke}" stroke-width="{sw:.2}" stroke-linejoin="round"{layer_attr}{id_attr}/>"#,
+                    stroke = f.stroke,
+                    sw = f.stroke_w,
+                );
+            }
+            None => {
+                let _ = write!(
+                    out,
+                    r#"<polyline points="{pts}" fill="none" stroke="{stroke}" stroke-width="{sw:.2}" stroke-linejoin="round"{layer_attr}{id_attr}/>"#,
+                    stroke = f.stroke,
+                    sw = f.stroke_w,
+                );
+            }
+        }
+    }
+
+    out.push_str("</svg>");
+    Render3d {
+        svg: out,
+        width_px,
+        height_px,
+    }
+}
+
+/// A 2D footprint extracted from a primitive, ready to extrude.
+struct Footprint<'a> {
+    points: Vec<[f64; 2]>,
+    closed: bool,
+    common: &'a CommonAttrs,
+}
+
+fn collect_layer_faces(
+    faces: &mut Vec<Face>,
+    layer_name: &str,
+    cf: &CfFile,
+    layer_color: &str,
+    cam: &Camera,
+    cut: Option<&Cut>,
+) {
+    let mut prints: Vec<Footprint> = Vec::new();
+
+    for e in &cf.rects {
+        let [ox, oy] = e.origin;
+        prints.push(Footprint {
+            points: vec![
+                [ox, oy],
+                [ox + e.width, oy],
+                [ox + e.width, oy + e.height],
+                [ox, oy + e.height],
+            ],
+            closed: true,
+            common: &e.common,
+        });
+    }
+    for e in &cf.polylines {
+        prints.push(Footprint {
+            points: e.points.clone(),
+            closed: e.closed,
+            common: &e.common,
+        });
+    }
+    for e in &cf.lines {
+        prints.push(Footprint {
+            points: vec![e.from, e.to],
+            closed: false,
+            common: &e.common,
+        });
+    }
+    for e in &cf.circles {
+        prints.push(Footprint {
+            points: polygonize_arc(e.center, e.radius, 0.0, 360.0, CIRCLE_SEGMENTS),
+            closed: true,
+            common: &e.common,
+        });
+    }
+    for e in &cf.arcs {
+        let segs = ((e.to_angle - e.from_angle).abs() / 360.0 * CIRCLE_SEGMENTS as f64)
+            .ceil()
+            .max(2.0) as usize;
+        prints.push(Footprint {
+            points: polygonize_arc(e.center, e.radius, e.from_angle, e.to_angle, segs),
+            closed: false,
+            common: &e.common,
+        });
+    }
+
+    for fp in prints {
+        if fp.points.len() < 2 {
+            continue;
+        }
+        let base = fp.common.elevation.unwrap_or(0.0);
+        let h = fp.common.extrude.unwrap_or(0.0);
+        let color = fp
+            .common
+            .color
+            .clone()
+            .unwrap_or_else(|| layer_color.to_string());
+        let id = fp.common.id.clone();
+
+        if h > 0.0 {
+            // Extruded footprint → a real prism/wall mesh.
+            let mesh = apply_cut(mesh::prism(&fp.points, base, h, fp.closed), cut);
+            emit_mesh(faces, &mesh, &color, layer_name, &id, cam);
+        } else if cut.is_none() {
+            // Flat footprint lying on the ground plane (the plan, projected).
+            // Skipped in section views (there is no solid to cut).
+            emit_outline(faces, &fp, base, &color, layer_name, &id, cam);
+        }
+    }
+
+    collect_solid_faces(faces, layer_name, cf, layer_color, cam, cut);
+}
+
+/// Subtract the cut's discarded half-space from `m`, if a cut is active.
+fn apply_cut(m: mesh::Mesh, cut: Option<&Cut>) -> mesh::Mesh {
+    match cut {
+        Some(c) => m.difference(&c.discard_box()),
+        None => m,
+    }
+}
+
+/// Build the named [`mesh`] solids, apply each `[[boolean]]`, and emit the
+/// results. Solids consumed by a boolean are not drawn on their own.
+fn collect_solid_faces(
+    faces: &mut Vec<Face>,
+    layer_name: &str,
+    cf: &CfFile,
+    layer_color: &str,
+    cam: &Camera,
+    cut: Option<&Cut>,
+) {
+    use std::collections::{HashMap, HashSet};
+
+    let mut meshes: HashMap<&str, mesh::Mesh> = HashMap::new();
+    let mut colors: HashMap<&str, String> = HashMap::new();
+    for s in &cf.solids {
+        meshes.insert(s.id.as_str(), build_solid(s));
+        colors.insert(
+            s.id.as_str(),
+            s.color.clone().unwrap_or_else(|| layer_color.to_string()),
+        );
+    }
+
+    let mut consumed: HashSet<&str> = HashSet::new();
+    for b in &cf.booleans {
+        consumed.insert(b.base.as_str());
+        for t in &b.tools {
+            consumed.insert(t.as_str());
+        }
+    }
+
+    for b in &cf.booleans {
+        let Some(base) = meshes.get(b.base.as_str()) else {
+            continue; // unknown base — skip rather than fail the whole render
+        };
+        let mut acc = base.clone();
+        for t in &b.tools {
+            if let Some(tool) = meshes.get(t.as_str()) {
+                acc = match b.op.as_str() {
+                    "union" => acc.union(tool),
+                    "intersection" => acc.intersection(tool),
+                    _ => acc.difference(tool), // default: difference (cut)
+                };
+            }
+        }
+        let color = b
+            .color
+            .clone()
+            .or_else(|| colors.get(b.base.as_str()).cloned())
+            .unwrap_or_else(|| layer_color.to_string());
+        emit_mesh(faces, &apply_cut(acc, cut), &color, layer_name, &b.id, cam);
+    }
+
+    for s in &cf.solids {
+        if consumed.contains(s.id.as_str()) {
+            continue;
+        }
+        let (Some(m), Some(c)) = (meshes.get(s.id.as_str()), colors.get(s.id.as_str())) else {
+            continue;
+        };
+        emit_mesh(
+            faces,
+            &apply_cut(m.clone(), cut),
+            c,
+            layer_name,
+            &Some(s.id.clone()),
+            cam,
+        );
+    }
+}
+
+fn build_solid(s: &crate::model::CfSolid) -> mesh::Mesh {
+    let at = s.at.unwrap_or([0.0, 0.0, 0.0]);
+    match s.shape.as_str() {
+        "cylinder" => mesh::cylinder_solid(
+            at,
+            s.radius.unwrap_or(1.0),
+            s.height.unwrap_or(1.0),
+            s.segments.unwrap_or(40),
+        ),
+        _ => mesh::box_solid(at, s.size.unwrap_or([1.0, 1.0, 1.0])),
+    }
+}
+
+// ── Mesh → shaded faces ────────────────────────────────────────────────
+
+/// Light direction (from the upper front).
+const LIGHT: V3 = [0.32, 0.24, 0.92];
+const AMBIENT: f64 = 0.40;
+const DIFFUSE: f64 = 0.60;
+
+type V3 = [f64; 3];
+
+fn v_sub(a: V3, b: V3) -> V3 {
+    [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+}
+fn v_cross(a: V3, b: V3) -> V3 {
+    [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ]
+}
+fn v_dot(a: V3, b: V3) -> f64 {
+    a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+}
+fn v_norm(a: V3) -> V3 {
+    let l = v_dot(a, a).sqrt();
+    if l < 1e-12 {
+        a
+    } else {
+        [a[0] / l, a[1] / l, a[2] / l]
+    }
+}
+
+/// Project a mesh: cull back faces, flat-shade by the surface normal, and push
+/// one [`Face`] per visible triangle.
+fn emit_mesh(
+    faces: &mut Vec<Face>,
+    m: &mesh::Mesh,
+    color: &str,
+    layer: &str,
+    id: &Option<String>,
+    cam: &Camera,
+) {
+    for t in &m.tris {
+        let normal = v_norm(v_cross(v_sub(t[1], t[0]), v_sub(t[2], t[0])));
+        if v_dot(normal, cam.view) <= 0.0 {
+            continue; // back face — hidden
+        }
+        let lit = AMBIENT + DIFFUSE * v_dot(normal, LIGHT).max(0.0);
+        let proj: Vec<(f64, f64)> = t.iter().map(|&p| cam.project(p)).collect();
+        let cx = (t[0][0] + t[1][0] + t[2][0]) / 3.0;
+        let cy = (t[0][1] + t[1][1] + t[2][1]) / 3.0;
+        let cz = (t[0][2] + t[1][2] + t[2][2]) / 3.0;
+        // Stroke == fill: coplanar triangles (same shade) merge seamlessly so
+        // the internal triangulation never shows; the small width closes the
+        // anti-alias cracks between adjacent triangles. Face-to-face contrast
+        // (different normals → different shade) still defines the real edges.
+        let fill = scale_color(color, lit.clamp(0.0, 1.0));
+        faces.push(Face {
+            proj,
+            stroke: fill.clone(),
+            fill: Some(fill),
+            stroke_w: 1.0,
+            depth: cam.depth([cx, cy, cz]),
+            layer: layer.to_string(),
+            id: id.clone(),
+        });
+    }
+}
+
+/// A flat (non-extruded) footprint, drawn as an outline on the ground plane.
+fn emit_outline(
+    faces: &mut Vec<Face>,
+    fp: &Footprint,
+    base: f64,
+    color: &str,
+    layer: &str,
+    id: &Option<String>,
+    cam: &Camera,
+) {
+    let mut ring: Vec<[f64; 3]> = fp.points.iter().map(|p| [p[0], p[1], base]).collect();
+    if fp.closed {
+        if let Some(&first) = ring.first() {
+            ring.push(first); // close the outline visually
+        }
+    }
+    let mut proj = Vec::with_capacity(ring.len());
+    let mut d = f64::MIN;
+    for &p in &ring {
+        proj.push(cam.project(p));
+        d = d.max(cam.depth(p));
+    }
+    faces.push(Face {
+        proj,
+        fill: None,
+        stroke: color.to_string(),
+        stroke_w: 1.4,
+        depth: d - 0.01, // ground outlines sit just behind solids at the same spot
+        layer: layer.to_string(),
+        id: id.clone(),
+    });
+}
+
+/// Sample points along an arc (degrees, counterclockwise). For a full circle
+/// pass 0→360; the duplicate end point is dropped for closed footprints.
+fn polygonize_arc(center: [f64; 2], radius: f64, from: f64, to: f64, segs: usize) -> Vec<[f64; 2]> {
+    let segs = segs.max(2);
+    let full = (to - from).abs() >= 359.999;
+    let count = if full { segs } else { segs + 1 };
+    let mut pts = Vec::with_capacity(count);
+    for i in 0..count {
+        let t = i as f64 / segs as f64;
+        let ang = (from + (to - from) * t).to_radians();
+        pts.push([
+            center[0] + radius * ang.cos(),
+            center[1] + radius * ang.sin(),
+        ]);
+    }
+    pts
+}
+
+/// Multiply each channel of `#RRGGBB` by `factor`, clamped to a valid color.
+fn scale_color(hex: &str, factor: f64) -> String {
+    let h = hex.trim_start_matches('#');
+    let parse = |s: &str| u8::from_str_radix(s, 16).unwrap_or(180);
+    let (r, g, b) = if h.len() == 6 {
+        (parse(&h[0..2]), parse(&h[2..4]), parse(&h[4..6]))
+    } else {
+        (180, 180, 180)
+    };
+    let scale = |c: u8| ((c as f64) * factor).round().clamp(0.0, 255.0) as u8;
+    format!("#{:02X}{:02X}{:02X}", scale(r), scale(g), scale(b))
+}
+
+fn xml_escape(s: &str) -> String {
+    s.replace('&', "&amp;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+        .replace('"', "&quot;")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::model::CfFile;
+
+    #[test]
+    fn extruded_rect_produces_solid_faces() {
+        let cf: CfFile = toml::from_str(
+            r#"
+[[rect]]
+id = "rc-1"
+origin = [0.0, 0.0]
+width = 4.0
+height = 3.0
+extrude = 2.5
+"#,
+        )
+        .unwrap();
+        let r = render_scene_3d(&[("l".to_string(), cf)], 800);
+        // A box is 12 triangles; back-face culling leaves the visible front
+        // faces (top + the sides facing the camera) — several shaded polygons.
+        let polys = r.svg.matches("<polygon").count();
+        assert!((3..=12).contains(&polys), "got {polys} polygons");
+        assert!(r.svg.contains(r#"data-id="rc-1""#));
+        assert!(r.svg.contains(r#"data-view="3d""#));
+        assert!(r.width_px > 0.0 && r.height_px > 0.0);
+    }
+
+    #[test]
+    fn flat_geometry_renders_as_ground_outline() {
+        let cf: CfFile = toml::from_str(
+            r#"
+[[rect]]
+origin = [0.0, 0.0]
+width = 4.0
+height = 3.0
+"#,
+        )
+        .unwrap();
+        let r = render_scene_3d(&[("l".to_string(), cf)], 800);
+        assert_eq!(r.svg.matches("<polygon").count(), 0);
+        assert_eq!(r.svg.matches("<polyline").count(), 1);
+    }
+
+    #[test]
+    fn color_scaling_clamps() {
+        assert_eq!(scale_color("#FFFFFF", 0.5), "#808080");
+        assert_eq!(scale_color("#808080", 2.0), "#FFFFFF");
+        assert_eq!(scale_color("#000000", 1.0), "#000000");
+    }
+}
diff --git a/src/scaffold.rs b/src/scaffold.rs
index 158c0a7..0a7d966 100644
--- a/src/scaffold.rs
+++ b/src/scaffold.rs
@@ -16,10 +16,9 @@ pub fn create_project(name: &str, parent: &Path) -> Result<()> {
 
     println!("✓ Project '{}' created at {}", name, project_dir.display());
     println!("  → project.toml");
-    println!("  → muros.cf");
-    println!("  → puertas.cf");
-    println!("  → mobiliario.cf");
-    println!("  → cotas.cf");
+    println!("  → shapes.cf");
+    println!("  → curves.cf");
+    println!("  → annotations.cf");
     println!("  → .gitignore");
     println!(
         "\n  Run `cadforge serve --path {}` for a live preview,",
@@ -44,10 +43,9 @@ pub fn init_project(dir: &Path) -> Result<()> {
 
     println!("✓ Initialized CADforge project in {}", dir.display());
     println!("  → project.toml");
-    println!("  → muros.cf");
-    println!("  → puertas.cf");
-    println!("  → mobiliario.cf");
-    println!("  → cotas.cf");
+    println!("  → shapes.cf");
+    println!("  → curves.cf");
+    println!("  → annotations.cf");
     println!("  → .gitignore");
     println!("\n  Run `cadforge serve` for a live preview.");
     println!("  `cadforge schema` prints the .cf language reference.");
@@ -62,127 +60,115 @@ scale = "1:100"
 units = "m"
 
 [layers]
-muros = {{ file = "muros.cf", locked = false }}
-puertas = {{ file = "puertas.cf", locked = false }}
-mobiliario = {{ file = "mobiliario.cf", locked = false }}
-cotas = {{ file = "cotas.cf", locked = false }}
+shapes = {{ file = "shapes.cf", locked = false }}
+curves = {{ file = "curves.cf", locked = false }}
+annotations = {{ file = "annotations.cf", locked = false }}
 "#
     );
     fs::write(project_dir.join("project.toml"), project_toml)?;
 
-    let gitignore = "# CADforge output\noutput.dxf\npreview.png\npreview.svg\npreview.meta.json\n\n# Rust build artifacts\ntarget/\n";
+    let gitignore = "# CADforge output\noutput.dxf\npreview.png\npreview.svg\npreview.meta.json\n\n# CADforge serve daemon (pid + logs)\n.cadforge/\n\n# Rust build artifacts\ntarget/\n";
     fs::write(project_dir.join(".gitignore"), gitignore)?;
 
-    let muros_cf = r##"[layer]
-name = "muros"
+    let shapes_cf = r##"[layer]
+name = "shapes"
 color = "#FFFFFF"
-line_weight = 0.50
+line_weight = 0.35
 
-# Perímetro exterior
+# Rectangle from its bottom-left origin.
+# `extrude` gives it height in the 3D view (the `3D` button) — here, a box.
+[[rect]]
+id = "rc-001"
+origin = [0.0, 0.0]
+width = 4.0
+height = 4.0
+extrude = 3.0
+
+# Closed polyline (a polygon) — also used as a hatch boundary
 [[polyline]]
-id = "pl-perimetro"
-points = [[0.0, 0.0], [8.0, 0.0], [8.0, 6.0], [0.0, 6.0]]
+id = "pl-001"
+points = [[6.0, 0.0], [10.0, 0.0], [11.0, 2.0], [8.0, 4.0], [6.0, 2.0]]
 closed = true
-weight = 0.50
-
-# Muro divisorio horizontal
-[[line]]
-id = "ln-div-h"
-from = [0.0, 3.5]
-to = [5.0, 3.5]
-weight = 0.35
-
-# Muro divisorio vertical
-[[line]]
-id = "ln-div-v"
-from = [5.0, 0.0]
-to = [5.0, 6.0]
-weight = 0.35
-"##;
-    fs::write(project_dir.join("muros.cf"), muros_cf)?;
-
-    let puertas_cf = r##"[layer]
-name = "puertas"
-color = "#00CC44"
-
-# Puerta principal
-[[arc]]
-id = "ar-puerta-principal"
-center = [0.0, 2.5]
-radius = 0.9
-from_angle = 0.0
-to_angle = 90.0
 
-# Puerta interior
-[[arc]]
-id = "ar-puerta-int"
-center = [5.0, 4.5]
-radius = 0.8
-from_angle = 90.0
-to_angle = 180.0
+# Reference marker (drawn as a cross)
+[[point]]
+id = "pt-001"
+position = [2.0, 2.0]
+
+# Pattern fill inside the polygon above
+[[hatch]]
+id = "ht-001"
+boundary = "pl-001"
+pattern = "ansi31"
+angle = 45.0
 "##;
-    fs::write(project_dir.join("puertas.cf"), puertas_cf)?;
+    fs::write(project_dir.join("shapes.cf"), shapes_cf)?;
 
-    let mobiliario_cf = r##"[layer]
-name = "mobiliario"
+    let curves_cf = r##"[layer]
+name = "curves"
 color = "#4488FF"
+line_weight = 0.25
 
-# Mesa sala
-[[rect]]
-id = "rc-mesa"
-origin = [1.5, 4.5]
-width = 2.0
-height = 1.0
-
-# Cama dormitorio
-[[rect]]
-id = "rc-cama"
-origin = [5.5, 4.0]
-width = 2.0
-height = 1.5
-
-# Etiquetas
-[[text]]
-id = "tx-sala"
-position = [2.0, 5.0]
-content = "SALA"
-size = 0.25
+# Full circle — extruded into a cylinder in the 3D view
+[[circle]]
+id = "ci-001"
+center = [2.0, 8.0]
+radius = 1.5
+extrude = 2.0
 
-[[text]]
-id = "tx-dorm"
-position = [6.0, 5.0]
-content = "DORMITORIO"
-size = 0.20
+# Half arc (angles in degrees, counterclockwise from +X)
+[[arc]]
+id = "ar-001"
+center = [6.0, 8.0]
+radius = 1.5
+from_angle = 0.0
+to_angle = 180.0
 
-[[text]]
-id = "tx-cocina"
-position = [2.0, 1.5]
-content = "COCINA"
-size = 0.20
+# A small circle repeated around a center (polar array).
+# The array expands at build time into ci-sat, ci-sat@1, ci-sat@2, …
+[[circle]]
+id = "ci-sat"
+center = [11.5, 8.0]
+radius = 0.4
+
+[[array]]
+target = "ci-sat"
+mode = "polar"
+count = 6
+center = [10.0, 8.0]
+step_angle = 60.0
 "##;
-    fs::write(project_dir.join("mobiliario.cf"), mobiliario_cf)?;
+    fs::write(project_dir.join("curves.cf"), curves_cf)?;
 
-    let cotas_cf = r##"[layer]
-name = "cotas"
+    let annotations_cf = r##"[layer]
+name = "annotations"
 color = "#FF4444"
+line_weight = 0.18
 
-# Cota horizontal total
+# Linear dimension — the measured distance is labeled automatically
 [[dim]]
-id = "dm-ancho"
+id = "dm-001"
 type = "linear"
 from = [0.0, 0.0]
-to = [8.0, 0.0]
+to = [4.0, 0.0]
 offset = -0.8
 
-# Cota vertical total
-[[dim]]
-id = "dm-alto"
-type = "linear"
-from = [0.0, 0.0]
-to = [0.0, 6.0]
-offset = -0.8
+# Text labels (size is in world units, not points)
+[[text]]
+id = "tx-shapes"
+position = [2.0, 4.4]
+content = "shapes"
+size = 0.4
+align = "center"
+
+[[text]]
+id = "tx-curves"
+position = [4.0, 10.2]
+content = "curves"
+size = 0.4
+align = "center"
 "##;
-    fs::write(project_dir.join("cotas.cf"), cotas_cf)?;
+    fs::write(project_dir.join("annotations.cf"), annotations_cf)?;
 
     Ok(())
 }
@@ -202,16 +188,15 @@ mod tests {
 
         let project_dir = tmp.join("mi-proyecto");
         assert!(project_dir.join("project.toml").exists());
-        assert!(project_dir.join("muros.cf").exists());
-        assert!(project_dir.join("puertas.cf").exists());
-        assert!(project_dir.join("mobiliario.cf").exists());
-        assert!(project_dir.join("cotas.cf").exists());
+        assert!(project_dir.join("shapes.cf").exists());
+        assert!(project_dir.join("curves.cf").exists());
+        assert!(project_dir.join("annotations.cf").exists());
         assert!(!project_dir.join("AGENTS.md").exists());
         assert!(project_dir.join(".gitignore").exists());
 
         let content = fs::read_to_string(project_dir.join("project.toml")).unwrap();
         assert!(content.contains("mi-proyecto"));
-        assert!(content.contains("muros.cf"));
+        assert!(content.contains("shapes.cf"));
 
         let gitignore = fs::read_to_string(project_dir.join(".gitignore")).unwrap();
         assert!(gitignore.contains("output.dxf"));
@@ -242,10 +227,9 @@ mod tests {
         init_project(&tmp).unwrap();
 
         assert!(tmp.join("project.toml").exists());
-        assert!(tmp.join("muros.cf").exists());
-        assert!(tmp.join("puertas.cf").exists());
-        assert!(tmp.join("mobiliario.cf").exists());
-        assert!(tmp.join("cotas.cf").exists());
+        assert!(tmp.join("shapes.cf").exists());
+        assert!(tmp.join("curves.cf").exists());
+        assert!(tmp.join("annotations.cf").exists());
         assert!(tmp.join(".gitignore").exists());
 
         let _ = fs::remove_dir_all(&tmp);
diff --git a/src/schema.rs b/src/schema.rs
index dc5e0a1..a50100a 100644
--- a/src/schema.rs
+++ b/src/schema.rs
@@ -28,6 +28,24 @@ puertas = { file = "puertas.cf", locked = false }
 puertas.parent = "muros"        # child bbox must fit inside parent bbox
 cotas.belongs_to = "muros"      # child primitives reference parent ids via belongs_to
 "muros → puertas" = "spatial_dependency"  # movement warning (informational)
+
+# Planos (drawing sheets): named views of the model with a title block.
+# Render with `cadforge preview --plano <name>`, or pick them in the viewer's
+# Planos panel (under Layers).
+[[plano]]
+name = "P-01"
+view = "plan"          # plan | iso | front | back | left | right | top | section
+size = [420.0, 297.0]  # sheet size in mm (default A3 landscape)
+scale = "1:50"         # label shown in the rótulo (defaults to project scale)
+title = "Planta baja"  # rótulo title (defaults to name)
+rotulo = "rotulo.cf"   # optional: a .cf drawn as a custom title block
+
+[[plano]]
+name = "C-01"
+view = "section"       # a cut, viewed along the cut axis
+cut_axis = "z"         # x | y | z
+cut_at = 1.5           # plane position along the axis
+keep = "min"           # min (default) keeps the ≤ side, max keeps the ≥ side
 ```
 
 ## Layer files (`.cf`)
@@ -53,8 +71,14 @@ style = "solid"        # solid | dashed | dotted | dashdot
 visible = true
 locked = false
 belongs_to = "id"      # reference to a primitive id in the parent layer
+extrude = 3.0          # 3D view: extrusion height (world units). closed shape → solid,
+                       #          line / open polyline → wall. 0/omitted = flat
+elevation = 0.0        # 3D view: base height (Z) the shape sits at (default 0)
 ```
 
+The 2D plan is unaffected by `extrude`/`elevation`; they only shape the
+extruded 3D view (`cadforge preview --3d`, or the viewer's `3D` button).
+
 ### Primitives
 
 ```toml
@@ -140,6 +164,37 @@ targets = ["pl-nave", "ar-puerta"]
 axis = [[2.5, 0.0], [2.5, 1.0]]
 ```
 
+### 3D solids (CSG)
+
+For the 3D view you can also declare true solids and combine them with boolean
+operations (constructive solid geometry). Solids and booleans are **3D-only** —
+they do not appear in the 2D plan or the DXF. (For simple extrusions, prefer
+`extrude`/`elevation` on a 2D primitive; use solids when you need booleans.)
+
+```toml
+[[solid]]              # a named 3D primitive (referenced by booleans via id)
+id = "cubo"
+shape = "box"          # box | cylinder
+at = [0.0, 0.0, 0.0]   # box: minimum corner; cylinder: base-circle center
+size = [4.0, 4.0, 4.0] # box dimensions [sx, sy, sz]
+
+[[solid]]
+id = "broca"
+shape = "cylinder"
+at = [2.0, 2.0, -0.5]
+radius = 1.2
+height = 5.0
+segments = 48          # facet count (default 40)
+
+[[boolean]]            # combine solids — the result is rendered, the inputs are not
+id = "cubo-perforado"
+op = "difference"      # difference (cut) | union | intersection
+base = "cubo"
+tools = ["broca"]      # subtracted from / merged with the base, in order
+```
+
+A cube with a hole = a `box` minus a `cylinder` via `op = "difference"`.
+
 ## Conventions
 
 - Coordinates are world units (see `units`), Y grows upward, origin at [0, 0].
@@ -170,8 +225,8 @@ where intended (highlighted entities get labeled amber markers).
 
 For humans, `cadforge serve` adds: click any entity to inspect its source
 TOML block (copyable as an agent prompt for targeted edits), a layer panel
-with on/ghost/off states (trace one floor over another), and a 3D stacked
-view of the layers.
+with on/ghost/off states (trace one floor over another), and a `3D` button
+that renders the extruded view (see `extrude`/`elevation` above).
 "##;
 
 /// Print the `.cf` language reference to stdout.
diff --git a/src/serve.rs b/src/serve.rs
index 27d86cf..e50cdb2 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -6,20 +6,23 @@
 //!
 //! Viewer features: pan/zoom, click-to-inspect any entity (shows its source
 //! TOML block, copyable for targeted agent edits), per-layer visibility with
-//! a ghost mode for tracing over other floors, and a 3D stacked-layers view.
+//! a ghost mode for tracing over other floors, and an extruded 3D view.
 //!
 //! Plain `std::net` HTTP — this is a localhost dev server, no framework needed.
 
 use crate::parser::parse_project;
+use crate::render3d::render_scene_3d;
 use crate::svg::{layer_display_color, load_project_layers, render_scene_from};
-use anyhow::{Context, Result};
+use anyhow::{bail, Context, Result};
 use notify::{Event, EventKind, RecommendedWatcher, RecursiveMode, Watcher};
+use std::fs::{self, File};
 use std::io::{BufRead, BufReader, Write};
-use std::net::{TcpListener, TcpStream};
+use std::net::{SocketAddr, TcpListener, TcpStream};
 use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
 use std::sync::mpsc;
 use std::sync::{Arc, Condvar, Mutex};
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 const SVG_WIDTH: u32 = 1600;
 const DEBOUNCE: Duration = Duration::from_millis(80);
@@ -28,11 +31,15 @@ const SSE_KEEPALIVE: Duration = Duration::from_secs(15);
 struct LiveState {
     /// Arc so request handlers serve the SVG without copying it.
     svg: Arc<String>,
+    /// Extruded axonometric 3D render of the same scene.
+    svg3d: Arc<String>,
     error: Option<String>,
     version: u64,
     project_name: String,
     /// (name, color) per layer, for the layer panel.
     layers: Vec<(String, String)>,
+    /// (name, view, title) per plano, for the planos panel.
+    planos: Vec<(String, String, String)>,
 }
 
 /// Shared state plus a condvar so SSE clients are woken the instant a rebuild
@@ -55,10 +62,12 @@ pub fn serve_project(project_dir: &Path, port: u16, open: bool) -> Result<()> {
     let state: Shared = Arc::new(Live {
         state: Mutex::new(LiveState {
             svg: Arc::new(String::new()),
+            svg3d: Arc::new(String::new()),
             error: None,
             version: 0,
             project_name: project.project.name.clone(),
             layers: Vec::new(),
+            planos: Vec::new(),
         }),
         changed: Condvar::new(),
         project_dir: project_dir.clone(),
@@ -94,8 +103,162 @@ pub fn serve_project(project_dir: &Path, port: u16, open: bool) -> Result<()> {
     Ok(())
 }
 
+// ── Background daemon ──────────────────────────────────────────────────────
+//
+// `serve` runs detached by default: a parent process validates the project and
+// the port, spawns the real (foreground) server in its own process group with
+// its output redirected to a log file, waits until the port actually accepts a
+// connection, then prints the URL and exits. Waiting for real readiness means
+// we never claim "running" for a server that failed to come up.
+
+fn runtime_dir(project_dir: &Path) -> PathBuf {
+    project_dir.join(".cadforge")
+}
+
+fn pid_path(project_dir: &Path) -> PathBuf {
+    runtime_dir(project_dir).join("serve.pid")
+}
+
+fn log_path(project_dir: &Path) -> PathBuf {
+    runtime_dir(project_dir).join("serve.log")
+}
+
+/// True if `pid` refers to a live process (`kill -0`).
+fn process_alive(pid: u32) -> bool {
+    Command::new("kill")
+        .arg("-0")
+        .arg(pid.to_string())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+/// The recorded daemon pid for this project, but only if it is still alive.
+fn running_pid(project_dir: &Path) -> Option<u32> {
+    let pid: u32 = fs::read_to_string(pid_path(project_dir))
+        .ok()?
+        .trim()
+        .parse()
+        .ok()?;
+    process_alive(pid).then_some(pid)
+}
+
+/// Block until the server accepts a connection on `port`, or `timeout` elapses.
+fn wait_until_ready(port: u16, timeout: Duration) -> bool {
+    let addr = SocketAddr::from(([127, 0, 0, 1], port));
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        if TcpStream::connect_timeout(&addr, Duration::from_millis(200)).is_ok() {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(100));
+    }
+    false
+}
+
+/// Start the live preview server detached in the background (the default).
+pub fn serve_daemon(project_dir: &Path, port: u16, open: bool) -> Result<()> {
+    // Validate the project up front so config errors surface here, not in a log.
+    parse_project(&project_dir.join("project.toml"))?;
+    let project_dir = project_dir
+        .canonicalize()
+        .unwrap_or_else(|_| project_dir.to_path_buf());
+    let url = format!("http://127.0.0.1:{}", port);
+
+    if let Some(pid) = running_pid(&project_dir) {
+        println!("◉ cadforge serve already running (pid {pid})");
+        println!("  Preview: {url}");
+        println!("  Stop with: cadforge serve --stop");
+        if open {
+            open_browser(&url);
+        }
+        return Ok(());
+    }
+
+    // Fail fast on a busy port instead of letting the detached child die quietly.
+    match TcpListener::bind(("127.0.0.1", port)) {
+        Ok(listener) => drop(listener),
+        Err(e) => bail!("Cannot bind 127.0.0.1:{port} (port in use?): {e}"),
+    }
+
+    fs::create_dir_all(runtime_dir(&project_dir))?;
+    let log = log_path(&project_dir);
+    let log_file = File::create(&log)?;
+
+    let exe = std::env::current_exe().context("cannot locate cadforge executable")?;
+    let mut cmd = Command::new(exe);
+    cmd.arg("serve")
+        .arg("--foreground")
+        .arg("--path")
+        .arg(&project_dir)
+        .arg("--port")
+        .arg(port.to_string())
+        .stdin(Stdio::null())
+        .stdout(Stdio::from(log_file.try_clone()?))
+        .stderr(Stdio::from(log_file));
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        // Own process group: survives the parent shell / agent command exiting.
+        cmd.process_group(0);
+    }
+    let child = cmd.spawn().context("failed to spawn background server")?;
+    let pid = child.id();
+    fs::write(pid_path(&project_dir), pid.to_string())?;
+
+    if wait_until_ready(port, Duration::from_secs(5)) {
+        println!("◉ cadforge serve — running in background (pid {pid})");
+        println!("  Preview: {url}");
+        println!("  Logs:    {}", log.display());
+        println!("  Stop with: cadforge serve --stop");
+        if open {
+            open_browser(&url);
+        }
+        Ok(())
+    } else {
+        let _ = fs::remove_file(pid_path(&project_dir));
+        let tail = fs::read_to_string(&log).unwrap_or_default();
+        bail!(
+            "server did not come up within 5s. Log:\n{}",
+            tail.trim_end()
+        );
+    }
+}
+
+/// Stop the background server running for this project.
+pub fn serve_stop(project_dir: &Path, _port: u16) -> Result<()> {
+    let project_dir = project_dir
+        .canonicalize()
+        .unwrap_or_else(|_| project_dir.to_path_buf());
+    let pid_file = pid_path(&project_dir);
+
+    let Some(pid) = running_pid(&project_dir) else {
+        let _ = fs::remove_file(&pid_file); // clean up any stale pidfile
+        println!("No cadforge serve daemon running for this project.");
+        return Ok(());
+    };
+
+    let stopped = Command::new("kill")
+        .arg(pid.to_string())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false);
+    let _ = fs::remove_file(&pid_file);
+
+    if stopped {
+        println!("✓ Stopped cadforge serve (pid {pid}).");
+        Ok(())
+    } else {
+        bail!("failed to stop process {pid}")
+    }
+}
+
 fn rebuild(project_dir: &Path, state: &Shared) {
-    let result = (|| -> Result<(String, Vec<(String, String)>)> {
+    type PlanoInfo = Vec<(String, String, String)>;
+    type Built = (String, String, Vec<(String, String)>, PlanoInfo);
+    let result = (|| -> Result<Built> {
         let (project, layers) = load_project_layers(project_dir, None)?;
         let scene = render_scene_from(
             &project.project.name,
@@ -104,19 +267,33 @@ fn rebuild(project_dir: &Path, state: &Shared) {
             SVG_WIDTH,
             &[],
         );
+        let scene3d = render_scene_3d(&layers, SVG_WIDTH);
         let layer_info = layers
             .iter()
             .enumerate()
             .map(|(i, (name, cf))| (name.clone(), layer_display_color(cf, i)))
             .collect();
-        Ok((scene.svg, layer_info))
+        let plano_info = project
+            .planos
+            .iter()
+            .map(|p| {
+                (
+                    p.name.clone(),
+                    p.view.clone(),
+                    p.title.clone().unwrap_or_else(|| p.name.clone()),
+                )
+            })
+            .collect();
+        Ok((scene.svg, scene3d.svg, layer_info, plano_info))
     })();
 
     let mut st = state.state.lock().unwrap();
     match result {
-        Ok((svg, layers)) => {
+        Ok((svg, svg3d, layers, planos)) => {
             st.svg = Arc::new(svg);
+            st.svg3d = Arc::new(svg3d);
             st.layers = layers;
+            st.planos = planos;
             st.error = None;
         }
         Err(e) => {
@@ -128,6 +305,17 @@ fn rebuild(project_dir: &Path, state: &Shared) {
     state.changed.notify_all();
 }
 
+/// Render a plano by name to SVG (on demand, for the `/plano.svg` endpoint).
+fn render_named_plano(project_dir: &Path, name: &str) -> Result<String> {
+    let project = parse_project(&project_dir.join("project.toml"))?;
+    let plano = project
+        .planos
+        .iter()
+        .find(|p| p.name == name)
+        .with_context(|| format!("no plano named '{name}'"))?;
+    Ok(crate::planos::render_plano(project_dir, plano, SVG_WIDTH)?.svg)
+}
+
 fn spawn_watcher(project_dir: PathBuf, state: Shared) -> Result<()> {
     let (tx, rx) = mpsc::channel();
     let mut watcher = RecommendedWatcher::new(
@@ -203,6 +391,22 @@ fn handle_connection(stream: TcpStream, state: &Shared) -> std::io::Result<()> {
             let svg = Arc::clone(&state.state.lock().unwrap().svg);
             respond(stream, "200 OK", "image/svg+xml", svg.as_bytes())
         }
+        "/preview3d.svg" => {
+            let svg = Arc::clone(&state.state.lock().unwrap().svg3d);
+            respond(stream, "200 OK", "image/svg+xml", svg.as_bytes())
+        }
+        "/plano.svg" => {
+            // Rendered on demand (sections run CSG, so we don't precompute all).
+            let name = query_param(query, "name").unwrap_or_default();
+            let dir = &state.project_dir;
+            let svg = render_named_plano(dir, &name).unwrap_or_else(|e| {
+                format!(
+                    r##"<svg xmlns="http://www.w3.org/2000/svg" width="800" height="200"><rect width="100%" height="100%" fill="#0d0d0d"/><text x="20" y="40" fill="#ff9f9a" font-family="monospace" font-size="14">plano error: {}</text></svg>"##,
+                    html_escape(&format!("{e:#}"))
+                )
+            });
+            respond(stream, "200 OK", "image/svg+xml", svg.as_bytes())
+        }
         "/state" => {
             let st = state.state.lock().unwrap();
             let layers: Vec<_> = st
@@ -210,11 +414,19 @@ fn handle_connection(stream: TcpStream, state: &Shared) -> std::io::Result<()> {
                 .iter()
                 .map(|(name, color)| serde_json::json!({"name": name, "color": color}))
                 .collect();
+            let planos: Vec<_> = st
+                .planos
+                .iter()
+                .map(|(name, view, title)| {
+                    serde_json::json!({"name": name, "view": view, "title": title})
+                })
+                .collect();
             let body = serde_json::json!({
                 "version": st.version,
                 "project": st.project_name,
                 "error": st.error,
                 "layers": layers,
+                "planos": planos,
             })
             .to_string();
             drop(st);
@@ -448,15 +660,27 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   button.active { color: #FFB300; border-color: #FFB300; }
   #hint { margin-left: auto; font-size: 11px; color: #666; }
   main { flex: 1; display: flex; overflow: hidden; }
-  /* layer panel */
-  #layers { width: 170px; flex: none; background: #121212; border-right: 1px solid #222; padding: 8px; overflow-y: auto; user-select: none; }
-  #layers h3 { font-size: 10px; color: #666; text-transform: uppercase; letter-spacing: 1px; margin: 2px 0 8px 4px; }
+  /* left sidebar: two stacked panes (Layers over Planos), IntelliJ-style */
+  #sidebar { width: 200px; min-width: 130px; max-width: 560px; flex: none; background: #121212; border-right: 1px solid #222; display: flex; flex-direction: column; overflow: hidden; user-select: none; }
+  #layers-pane { flex: 1 1 auto; overflow-y: auto; padding: 8px; min-height: 48px; }
+  #planos-pane { flex: none; height: 40%; overflow-y: auto; padding: 8px; min-height: 48px; }
+  /* horizontal divider between the two panes */
+  #pane-divider { height: 6px; flex: none; cursor: row-resize; background: #161616; border-top: 1px solid #222; border-bottom: 1px solid #222; transition: background .15s; }
+  #pane-divider:hover, #pane-divider.dragging { background: #FFB300; }
+  /* drag handle to resize the whole sidebar width */
+  #layers-resizer { width: 6px; flex: none; cursor: col-resize; background: transparent; transition: background .15s; }
+  #layers-resizer:hover, #layers-resizer.dragging { background: #FFB300; }
+  #sidebar h3 { font-size: 10px; color: #666; text-transform: uppercase; letter-spacing: 1px; margin: 2px 0 8px 4px; }
   .layer-row { display: flex; align-items: center; gap: 7px; padding: 5px 6px; border-radius: 4px; cursor: pointer; font-size: 12px; }
-  .layer-row:hover { background: #1c1c1c; }
+  .layer-row:hover, .plano-row:hover { background: #1c1c1c; }
   .layer-dot { width: 9px; height: 9px; border-radius: 50%; flex: none; }
   .layer-row .st { margin-left: auto; font-size: 10px; color: #666; }
   .layer-row.ghost { color: #777; }
   .layer-row.off { color: #4a4a4a; }
+  .plano-row { display: flex; align-items: baseline; gap: 7px; padding: 5px 6px; border-radius: 4px; cursor: pointer; font-size: 12px; }
+  .plano-row .pv { margin-left: auto; font-size: 9px; color: #666; text-transform: uppercase; }
+  .plano-row.active { background: #2a2410; color: #FFB300; }
+  #planos-pane .empty { font-size: 11px; color: #555; padding: 4px 6px; line-height: 1.5; }
   /* viewport */
   #viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; perspective: 2200px; background: #0d0d0d; }
   #viewport.panning { cursor: grabbing; }
@@ -488,12 +712,17 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   <span id="title">{{PROJECT_NAME}}</span>
   <span class="tag">cadforge live</span>
   <span class="tag" id="version">v0</span>
-  <button id="btn3d" title="stack layers in 3D (key: 3)">3D</button>
+  <button id="btn3d" title="extruded 3D view (key: 3)">3D</button>
   <button id="btnfit" title="fit to view (key: F)">fit</button>
   <span id="hint">edit .cf files — preview updates automatically</span>
 </header>
 <main>
-  <aside id="layers"><h3>Layers</h3><div id="layerlist"></div></aside>
+  <aside id="sidebar">
+    <div id="layers-pane"><h3>Layers</h3><div id="layerlist"></div></div>
+    <div id="pane-divider" title="drag to resize panes"></div>
+    <div id="planos-pane"><h3>Planos</h3><div id="planoslist"></div></div>
+  </aside>
+  <div id="layers-resizer" title="drag to resize · double-click to reset"></div>
   <div id="viewport">
     <div id="canvas"></div>
     <pre id="error"></pre>
@@ -520,6 +749,7 @@ const dot = document.getElementById('dot');
 const errBox = document.getElementById('error');
 const versionTag = document.getElementById('version');
 const layerList = document.getElementById('layerlist');
+const planosList = document.getElementById('planoslist');
 const inspector = document.getElementById('inspector');
 const toast = document.getElementById('toast');
 
@@ -527,14 +757,19 @@ let scale = 1, tx = 0, ty = 0;
 let fitted = false;
 let mode3d = false;
 let svgText = '';
+let svg3dText = '';
 let layersInfo = [];                 // [{name, color}]
+let planosInfo = [];                 // [{name, view, title}]
+let currentPlano = null;             // active plano name, or null for the model
+let planoSvg = '';
 const layerState = {};               // name → 'on' | 'ghost' | 'off'
 let selectedId = null;
 
 // ── transform / view ────────────────────────────────────────────────
 function applyTransform() {
-  const tilt = mode3d ? ' rotateX(55deg) rotateZ(-38deg)' : '';
-  canvas.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})${tilt}`;
+  // The 3D view is a real axonometric projection baked into the SVG, so the
+  // canvas only ever needs pan + zoom (no CSS tilt).
+  canvas.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`;
 }
 function svgSize() {
   const svg = canvas.querySelector('svg');
@@ -545,57 +780,29 @@ function fitToView() {
   const s = svgSize();
   if (!s) return;
   const vw = viewport.clientWidth, vh = viewport.clientHeight;
-  scale = Math.min(vw / s.w, vh / s.h) * (mode3d ? 0.7 : 0.96);
+  scale = Math.min(vw / s.w, vh / s.h) * 0.96;
   tx = (vw - s.w * scale) / 2;
-  ty = (vh - s.h * scale) / 2 + (mode3d ? vh * 0.08 : 0);
+  ty = (vh - s.h * scale) / 2;
   applyTransform();
   fitted = true;
 }
 
 // ── rendering ───────────────────────────────────────────────────────
 function renderCanvas() {
-  if (!svgText) return;
-  if (!mode3d) {
-    canvas.innerHTML = svgText;
-  } else {
-    canvas.innerHTML = '';
-    const tpl = document.createElement('div');
-    tpl.innerHTML = svgText;
-    const names = [...tpl.querySelectorAll('g[data-layer]')].map(g => g.dataset.layer);
-    names.forEach((name, i) => {
-      const div = document.createElement('div');
-      div.className = 'plane';
-      div.style.transform = `translateZ(${i * 70}px)`;
-      div.innerHTML = svgText;
-      const svg = div.querySelector('svg');
-      svg.querySelectorAll('g[data-layer]').forEach(g => { if (g.dataset.layer !== name) g.remove(); });
-      if (i > 0) {
-        svg.querySelector('g[data-grid]')?.remove();
-        svg.querySelector('rect')?.remove();        // background only on base plane
-      } else {
-        svg.querySelector('rect')?.setAttribute('fill-opacity', '0.85');
-      }
-      canvas.appendChild(div);
-    });
-  }
+  const content = currentPlano ? planoSvg : (mode3d ? svg3dText : svgText);
+  if (!content) return;
+  canvas.innerHTML = content;
   applyLayerStates();
   applySelection();
 }
 
 function applyLayerStates() {
-  canvas.querySelectorAll('g[data-layer]').forEach(g => {
+  // 2D tags layers on <g>; the 3D view tags each projected face — match both.
+  canvas.querySelectorAll('[data-layer]').forEach(g => {
     const st = layerState[g.dataset.layer] || 'on';
     g.style.opacity = st === 'on' ? '' : st === 'ghost' ? '0.16' : '0';
     g.style.pointerEvents = st === 'on' ? '' : 'none';
   });
-  if (mode3d) {
-    canvas.querySelectorAll('.plane').forEach(p => {
-      const g = p.querySelector('g[data-layer]');
-      if (!g) return;
-      const st = layerState[g.dataset.layer] || 'on';
-      p.style.display = st === 'off' ? 'none' : '';
-    });
-  }
 }
 
 function renderLayerPanel() {
@@ -617,6 +824,37 @@ function cycleLayer(name) {
   applyLayerStates();
 }
 
+// ── planos panel ────────────────────────────────────────────────────
+function renderPlanosPanel() {
+  planosList.innerHTML = '';
+  if (!planosInfo.length) {
+    planosList.innerHTML = '<div class="empty">no planos — add [[plano]] to project.toml</div>';
+    return;
+  }
+  planosInfo.forEach(p => {
+    const row = document.createElement('div');
+    row.className = 'plano-row' + (currentPlano === p.name ? ' active' : '');
+    row.innerHTML = `<span>${p.title || p.name}</span><span class="pv">${p.view}</span>`;
+    row.onclick = () => openPlano(p.name);
+    planosList.appendChild(row);
+  });
+}
+async function fetchPlano(name) {
+  return (await fetch('/plano.svg?name=' + encodeURIComponent(name) + '&t=' + Date.now())).text();
+}
+async function openPlano(name) {
+  if (currentPlano === name) {           // toggle off → back to the model
+    currentPlano = null; planoSvg = '';
+    renderPlanosPanel(); renderCanvas(); fitToView();
+    return;
+  }
+  currentPlano = name;
+  renderPlanosPanel();
+  planoSvg = await fetchPlano(name);
+  renderCanvas();
+  fitToView();
+}
+
 // ── selection / inspector ───────────────────────────────────────────
 function applySelection() {
   canvas.querySelectorAll('.sel').forEach(n => n.classList.remove('sel'));
@@ -666,13 +904,15 @@ document.getElementById('close-ins').onclick = deselect;
 
 // ── data refresh ────────────────────────────────────────────────────
 async function refresh() {
-  const [stateRes, svgRes] = await Promise.all([
-    fetch('/state'), fetch('/preview.svg?t=' + Date.now())
+  const [stateRes, svgRes, svg3dRes] = await Promise.all([
+    fetch('/state'), fetch('/preview.svg?t=' + Date.now()), fetch('/preview3d.svg?t=' + Date.now())
   ]);
   const state = await stateRes.json();
   versionTag.textContent = 'v' + state.version;
   layersInfo = state.layers || [];
+  planosInfo = state.planos || [];
   renderLayerPanel();
+  renderPlanosPanel();
   if (state.error) {
     dot.classList.add('err');
     errBox.textContent = state.error;
@@ -681,6 +921,12 @@ async function refresh() {
     dot.classList.remove('err');
     errBox.classList.remove('show');
     svgText = await svgRes.text();
+    svg3dText = await svg3dRes.text();
+    // The active plano may reference changed geometry — re-render it too.
+    if (currentPlano) {
+      if (planosInfo.some(p => p.name === currentPlano)) planoSvg = await fetchPlano(currentPlano);
+      else { currentPlano = null; planoSvg = ''; }  // plano was removed
+    }
     renderCanvas();
     if (!fitted) fitToView();
   }
@@ -743,6 +989,59 @@ window.addEventListener('keydown', e => {
   }
 });
 
+// ── resizable sidebar (width) ───────────────────────────────────────
+(function () {
+  const sidebar = document.getElementById('sidebar');
+  const rz = document.getElementById('layers-resizer');
+  const KEY = 'cadforge.layersWidth', MIN = 130, MAX = 560, DEF = 200;
+  const saved = parseInt(localStorage.getItem(KEY) || '', 10);
+  if (saved >= MIN && saved <= MAX) sidebar.style.width = saved + 'px';
+  let dragging = false;
+  rz.addEventListener('mousedown', e => {
+    dragging = true; rz.classList.add('dragging');
+    document.body.style.cursor = 'col-resize'; e.preventDefault();
+  });
+  window.addEventListener('mousemove', e => {
+    if (!dragging) return;
+    const w = Math.min(MAX, Math.max(MIN, e.clientX - sidebar.getBoundingClientRect().left));
+    sidebar.style.width = w + 'px';
+  });
+  window.addEventListener('mouseup', () => {
+    if (!dragging) return;
+    dragging = false; rz.classList.remove('dragging'); document.body.style.cursor = '';
+    localStorage.setItem(KEY, parseInt(sidebar.style.width, 10));
+  });
+  rz.addEventListener('dblclick', () => {
+    sidebar.style.width = DEF + 'px'; localStorage.removeItem(KEY);
+  });
+})();
+
+// ── stacked panes: drag the Layers/Planos divider (height) ──────────
+(function () {
+  const sidebar = document.getElementById('sidebar');
+  const pane = document.getElementById('planos-pane');
+  const div = document.getElementById('pane-divider');
+  const KEY = 'cadforge.planosHeight';
+  const saved = parseInt(localStorage.getItem(KEY) || '', 10);
+  if (saved >= 48) pane.style.height = saved + 'px';
+  let dragging = false;
+  div.addEventListener('mousedown', e => {
+    dragging = true; div.classList.add('dragging');
+    document.body.style.cursor = 'row-resize'; e.preventDefault();
+  });
+  window.addEventListener('mousemove', e => {
+    if (!dragging) return;
+    const r = sidebar.getBoundingClientRect();
+    const h = Math.min(r.height - 60, Math.max(48, r.bottom - e.clientY));
+    pane.style.height = h + 'px';
+  });
+  window.addEventListener('mouseup', () => {
+    if (!dragging) return;
+    dragging = false; div.classList.remove('dragging'); document.body.style.cursor = '';
+    localStorage.setItem(KEY, parseInt(pane.style.height, 10));
+  });
+})();
+
 const events = new EventSource('/events');
 events.onmessage = refresh;
 events.onerror = () => dot.classList.add('err');
diff --git a/tests/integration.rs b/tests/integration.rs
index cce4778..9ad1f2f 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -387,6 +387,7 @@ offset = -0.6
             png: true,
             svg: true,
         },
+        cadforge::preview::PreviewView::Plan,
     )
     .unwrap();
 

From 052693042de427a420406ba310f398e6d8e8df06 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 10:39:40 -0500
Subject: [PATCH 06/39] refactor: rename the crate, binary and CLI from
 cadforge to cadspec (GitHub repo URLs kept until the repo is renamed)

---
 .github/workflows/release.yml       |   2 +-
 CONTRIBUTING.md                     |   4 +-
 Cargo.toml                          |   2 +-
 README.md                           | 120 ++++++++++++++--------------
 cadforge-spec.md => cadspec-spec.md |  80 +++++++++----------
 demo/README.md                      |  10 +--
 demo/demo.toml                      |  18 ++---
 docs/agents.md                      |  34 ++++----
 docs/building-and-export.md         |  26 +++---
 docs/cf-format.md                   |   4 +-
 docs/cli-reference.md               |  58 +++++++-------
 docs/index.md                       |  26 +++---
 docs/installation.md                |  14 ++--
 docs/live-preview.md                |   8 +-
 docs/quickstart.md                  |  22 ++---
 scripts/install.ps1                 |  16 ++--
 scripts/install.sh                  |  16 ++--
 src/config.rs                       |   4 +-
 src/dxf_writer.rs                   |   4 +-
 src/fmt.rs                          |   2 +-
 src/importer.rs                     |   4 +-
 src/lib.rs                          |   2 +-
 src/main.rs                         |  32 ++++----
 src/planos.rs                       |   2 +-
 src/preview.rs                      |   2 +-
 src/render3d.rs                     |   2 +-
 src/scaffold.rs                     |  28 +++----
 src/schema.rs                       |  32 ++++----
 src/serve.rs                        |  28 +++----
 src/svg.rs                          |   2 +-
 src/viewer.rs                       |   6 +-
 tests/integration.rs                |  58 +++++++-------
 32 files changed, 334 insertions(+), 334 deletions(-)
 rename cadforge-spec.md => cadspec-spec.md (77%)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 00965b8..256a1be 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -15,5 +15,5 @@ jobs:
     if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'
     uses: UniverLab/workflows/.github/workflows/rust-release.yml@main
     with:
-      binary-name: "cadforge"
+      binary-name: "cadspec"
     secrets: inherit
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f40a8e7..e306226 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to cadforge
+# Contributing to cadspec
 
 Thank you for your interest in contributing!
 
@@ -6,7 +6,7 @@ Thank you for your interest in contributing!
 
 ```bash
 git clone https://github.com/UniverLab/cadforge.git
-cd cadforge
+cd cadspec
 cargo build
 cargo test
 ```
diff --git a/Cargo.toml b/Cargo.toml
index a4ecf47..193ae4b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "cadforge"
+name = "cadspec"
 version = "0.1.0-beta.2"
 edition = "2021"
 description = "CAD as code — deterministic geometry engine for reproducible CAD drawings"
diff --git a/README.md b/README.md
index fc330e2..e03c851 100644
--- a/README.md
+++ b/README.md
@@ -14,12 +14,12 @@
 
 <p align="center">
   <a href="https://github.com/UniverLab/cadforge/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/UniverLab/cadforge/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI"/></a>
-  <a href="https://crates.io/crates/cadforge"><img src="https://img.shields.io/crates/v/cadforge?style=for-the-badge&logo=rust&logoColor=white" alt="Crates.io"/></a>
+  <a href="https://crates.io/crates/cadspec"><img src="https://img.shields.io/crates/v/cadspec?style=for-the-badge&logo=rust&logoColor=white" alt="Crates.io"/></a>
   <img src="https://img.shields.io/badge/Status-Active-27AE60?style=for-the-badge" alt="Status"/>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2E8B57?style=for-the-badge" alt="License"/></a>
 </p>
 
-cadforge is a **CAD as code** CLI tool and Rust library for declarative CAD modeling. Write geometry as code in `.cf` TOML format, watch it live in the browser, and compile to DXF — built for humans and AI agents working together.
+cadspec is a **CAD as code** CLI tool and Rust library for declarative CAD modeling. Write geometry as code in `.cf` TOML format, watch it live in the browser, and compile to DXF — built for humans and AI agents working together.
 
 ---
 
@@ -28,29 +28,29 @@ cadforge is a **CAD as code** CLI tool and Rust library for declarative CAD mode
 The core loop: **describe geometry in TOML, see it instantly, iterate.**
 
 ```bash
-cadforge new casa && cd casa
-cadforge serve --open        # live preview in the browser
+cadspec new casa && cd casa
+cadspec serve --open        # live preview in the browser
 ```
 
 Now edit any `.cf` file — by hand or by asking an AI agent — and the browser
 updates on every save. Parse errors and constraint violations appear as an
-overlay instead of a crash. When the design is right, `cadforge build` emits
+overlay instead of a crash. When the design is right, `cadspec build` emits
 a deterministic, AutoCAD-compatible DXF.
 
 Agents get first-class support:
 
-- `cadforge schema` — full `.cf` language reference in one command; agents
+- `cadspec schema` — full `.cf` language reference in one command; agents
   self-discover the format without prior training.
-- `cadforge check --json` / `cadforge layers --json` — machine-readable
+- `cadspec check --json` / `cadspec layers --json` — machine-readable
   validation reports.
-- `cadforge preview` — a faithful PNG render (real text, measured dimension
+- `cadspec preview` — a faithful PNG render (real text, measured dimension
   labels, hatches, line styles) + `preview.meta.json` with per-entity bounding
   boxes in world and pixel coordinates, so multimodal agents can *look* at the
   plan and locate every entity in the image.
-- `cadforge preview --highlight ln-001,tx-002` — labeled amber markers around
+- `cadspec preview --highlight ln-001,tx-002` — labeled amber markers around
   specific entities, so an agent can visually confirm its edit landed where
   intended.
-- `cadforge preview --format svg` — same render as vector SVG.
+- `cadspec preview --format svg` — same render as vector SVG.
 
 ---
 
@@ -68,7 +68,7 @@ curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/ins
 irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
 ```
 
-Or via cargo: `cargo install cadforge` — see [`docs/installation.md`](docs/installation.md) for all methods.
+Or via cargo: `cargo install cadspec` — see [`docs/installation.md`](docs/installation.md) for all methods.
 
 ## Documentation
 
@@ -86,20 +86,20 @@ complete CLI reference.
 - **📐 Declarative Geometry** — Define architectural elements (lines, rects, circles, arcs, polylines, text, dimensions) in TOML `.cf` files. Deterministic, reproducible, version-controlled.
 - **🛠️ Construction Tools** — `[[array]]` (linear and polar: spiral staircases, gear teeth, repeated columns) and `[[mirror]]` expand into concrete primitives at build time; copies get derived ids (`base@1`, `base@m`).
 - **📏 Styled Dimensions** — Auto-measured labels with configurable `text_size`, `precision`, `show_units`, and `offset` per dimension.
-- **🔴 Live Preview** — `cadforge serve` runs a local server with pan/zoom, auto-reload on save (SSE), click-to-inspect any entity (copy its source TOML as an agent prompt), per-layer ghost/hide states, a 3D stacked-layers view, and a build-error overlay. Zero config.
+- **🔴 Live Preview** — `cadspec serve` runs a local server with pan/zoom, auto-reload on save (SSE), click-to-inspect any entity (copy its source TOML as an agent prompt), per-layer ghost/hide states, a 3D stacked-layers view, and a build-error overlay. Zero config.
 - **🔗 Layer System** — Organize geometry by layer with custom names, colors, and line weights. Compile single layers or full projects.
 - **📄 DXF Export** — Compile `.cf` → DXF (AutoCAD-compatible). Full layer support, LWPOLYLINE for polylines, HATCH for solid fills, MTEXT for annotations.
 - **🖼️ Previews for Agents** — Raster PNG + metadata JSON (entity bounding boxes) and full-fidelity SVG with real text, auto-measured dimensions, line styles, and clipped hatch patterns.
-- **✅ Validation Engine** — `cadforge check` validates geometry and constraints without generating output; `--json` for tooling.
+- **✅ Validation Engine** — `cadspec check` validates geometry and constraints without generating output; `--json` for tooling.
 
 ### 🏗️ Project Management
 
-- **Project Scaffolding** — `cadforge new` creates a multi-layer starter project (shapes, curves, annotations) that showcases the core `.cf` primitives.
+- **Project Scaffolding** — `cadspec new` creates a multi-layer starter project (shapes, curves, annotations) that showcases the core `.cf` primitives.
 - **Multi-Layer Compilation** — Compile all layers or target specific layers with `--layer`. Custom output path with `--output`.
-- **Auto-Rebuild** — `cadforge watch` monitors `.cf` and `.toml` files and auto-rebuilds DXF on changes with 300ms debounce.
-- **Code Formatting** — `cadforge fmt` normalizes `.cf` files. `--check` mode for CI validation.
+- **Auto-Rebuild** — `cadspec watch` monitors `.cf` and `.toml` files and auto-rebuilds DXF on changes with 300ms debounce.
+- **Code Formatting** — `cadspec fmt` normalizes `.cf` files. `--check` mode for CI validation.
 - **Constraints** — `parent`, `belongs_to`, and `spatial_dependency` rules between layers; warnings by default, build-blocking with `strict = true`.
-- **DXF Import** — `cadforge import plano.dxf` migrates existing drawings into `.cf` layers + `project.toml`.
+- **DXF Import** — `cadspec import plano.dxf` migrates existing drawings into `.cf` layers + `project.toml`.
 
 ### 🔧 Architecture
 
@@ -114,35 +114,35 @@ complete CLI reference.
 
 | Command | Description |
 |---------|-------------|
-| `cadforge new <name>` | Create a new project with multi-layer scaffold |
-| `cadforge init` | Initialize CADforge in current directory |
-| `cadforge build` | Compile project to DXF |
-| `cadforge build --check` | Validate project and constraints without generating DXF |
-| `cadforge build --output <path>` | Compile to custom output path |
-| `cadforge build --layer <name>` | Compile specific layer only |
-| `cadforge serve` | Live preview server — browser auto-reloads on save |
-| `cadforge serve --open --port 4377` | Open browser automatically on a custom port |
-| `cadforge check` | Validate with project metadata and layer colors |
-| `cadforge check --json` | Machine-readable validation report |
-| `cadforge layers` | List layers with entity counts and colors |
-| `cadforge layers --json` | Machine-readable layer listing |
-| `cadforge schema` | Print the full `.cf` language reference (markdown) |
-| `cadforge preview` | Faithful PNG render + metadata JSON |
-| `cadforge preview --format svg` | Vector SVG preview (same renderer) |
-| `cadforge preview --highlight <id1,id2>` | Amber markers around specific entities |
-| `cadforge preview --width 1024 -H 768` | Custom resolution preview |
-| `cadforge preview --layer <name>` | Preview specific layer only |
-| `cadforge fmt` | Format .cf files (normalize whitespace) |
-| `cadforge fmt --check` | Check formatting without modifying (CI) |
-| `cadforge watch` | Auto-rebuild on file changes |
-| `cadforge import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
-| `cadforge import <file.dxf> --layer <name>` | Import only one DXF layer |
-| `cadforge view` | Open the project in the configured viewer |
-| `cadforge view --layer <name>` | Open only one layer in the viewer |
-| `cadforge config set <key> <value>` | Set global defaults (`author`, `units`) |
-| `cadforge config show` | Show global defaults |
-
-### Live preview controls (`cadforge serve`)
+| `cadspec new <name>` | Create a new project with multi-layer scaffold |
+| `cadspec init` | Initialize CADspec in current directory |
+| `cadspec build` | Compile project to DXF |
+| `cadspec build --check` | Validate project and constraints without generating DXF |
+| `cadspec build --output <path>` | Compile to custom output path |
+| `cadspec build --layer <name>` | Compile specific layer only |
+| `cadspec serve` | Live preview server — browser auto-reloads on save |
+| `cadspec serve --open --port 4377` | Open browser automatically on a custom port |
+| `cadspec check` | Validate with project metadata and layer colors |
+| `cadspec check --json` | Machine-readable validation report |
+| `cadspec layers` | List layers with entity counts and colors |
+| `cadspec layers --json` | Machine-readable layer listing |
+| `cadspec schema` | Print the full `.cf` language reference (markdown) |
+| `cadspec preview` | Faithful PNG render + metadata JSON |
+| `cadspec preview --format svg` | Vector SVG preview (same renderer) |
+| `cadspec preview --highlight <id1,id2>` | Amber markers around specific entities |
+| `cadspec preview --width 1024 -H 768` | Custom resolution preview |
+| `cadspec preview --layer <name>` | Preview specific layer only |
+| `cadspec fmt` | Format .cf files (normalize whitespace) |
+| `cadspec fmt --check` | Check formatting without modifying (CI) |
+| `cadspec watch` | Auto-rebuild on file changes |
+| `cadspec import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
+| `cadspec import <file.dxf> --layer <name>` | Import only one DXF layer |
+| `cadspec view` | Open the project in the configured viewer |
+| `cadspec view --layer <name>` | Open only one layer in the viewer |
+| `cadspec config set <key> <value>` | Set global defaults (`author`, `units`) |
+| `cadspec config show` | Show global defaults |
+
+### Live preview controls (`cadspec serve`)
 
 - Scroll → zoom (centered on cursor) · drag → pan · double-click / `F` → fit
 - **Click an entity** → inspector with its source TOML block; `copy for agent` produces a ready-made targeted-edit prompt
@@ -206,7 +206,7 @@ offset = 0.5
 
 `line`, `polyline`, `rect`, `circle`, `arc`, `text`, `point`, `dim`, `hatch`, `fill`, `group`
 
-Run `cadforge schema` for the complete reference with all attributes.
+Run `cadspec schema` for the complete reference with all attributes.
 
 ---
 
@@ -261,7 +261,7 @@ Run `cadforge schema` for the complete reference with all attributes.
 | Build output | `./output.dxf` | DXF |
 | Preview output | `./preview.png`, `./preview.svg` | PNG / SVG |
 | Preview metadata | `./preview.meta.json` | JSON |
-| Language reference | `cadforge schema` (stdout) | Markdown |
+| Language reference | `cadspec schema` (stdout) | Markdown |
 
 ---
 
@@ -269,40 +269,40 @@ Run `cadforge schema` for the complete reference with all attributes.
 
 **Create a new project:**
 ```bash
-cadforge new mi-proyecto
+cadspec new mi-proyecto
 cd mi-proyecto
 ```
 
 **Live preview while you edit:**
 ```bash
-cadforge serve --open    # browser refreshes on every save
+cadspec serve --open    # browser refreshes on every save
 ```
 
-**Edit `.cf` files** (TOML format with your geometry — run `cadforge schema` for the reference)
+**Edit `.cf` files** (TOML format with your geometry — run `cadspec schema` for the reference)
 
 **Format and validate:**
 ```bash
-cadforge fmt           # normalize .cf files
-cadforge check         # validate without generating DXF
+cadspec fmt           # normalize .cf files
+cadspec check         # validate without generating DXF
 ```
 
 **Compile to DXF:**
 ```bash
-cadforge build                        # default output.dxf
-cadforge build --output plano.dxf     # custom output path
-cadforge build --layer muros          # compile single layer
+cadspec build                        # default output.dxf
+cadspec build --output plano.dxf     # custom output path
+cadspec build --layer muros          # compile single layer
 ```
 
 **Preview:**
 ```bash
-cadforge preview                          # default 1600x1200 (fits content aspect)
-cadforge preview --width 1024 --height 768  # custom resolution
-cadforge preview --layer muros            # single layer preview
+cadspec preview                          # default 1600x1200 (fits content aspect)
+cadspec preview --width 1024 --height 768  # custom resolution
+cadspec preview --layer muros            # single layer preview
 ```
 
 **Auto-rebuild on changes:**
 ```bash
-cadforge watch       # monitors .cf and .toml files
+cadspec watch       # monitors .cf and .toml files
 ```
 
 ---
diff --git a/cadforge-spec.md b/cadspec-spec.md
similarity index 77%
rename from cadforge-spec.md
rename to cadspec-spec.md
index 0abb8d8..75ed8d6 100644
--- a/cadforge-spec.md
+++ b/cadspec-spec.md
@@ -1,4 +1,4 @@
-# CADforge — Especificación y Roadmap v1.0
+# CADspec — Especificación y Roadmap v1.0
 
 > Arquitectura como Código — motor determinista de geometría descriptiva para diseño arquitectónico reproducible, versionable y potenciado por agentes de IA.
 
@@ -6,13 +6,13 @@
 
 ## 1. Visión
 
-El diseño arquitectónico actual sufre de **entropía gráfica**: los planos son colecciones de líneas sin semántica, imposibles de versionar, comparar o automatizar. CADforge propone un cambio de paradigma:
+El diseño arquitectónico actual sufre de **entropía gráfica**: los planos son colecciones de líneas sin semántica, imposibles de versionar, comparar o automatizar. CADspec propone un cambio de paradigma:
 
 **El plano no se dibuja, se declara.**
 
 Al igual que el código fuente de software, un espacio arquitectónico es el resultado de un lenguaje estructurado. Si el código no cambia, el plano es idéntico bit a bit cada vez que se compila. Esto elimina la ambigüedad del clic humano, habilita `git diff` sobre planos, y permite que los agentes de IA generen y modifiquen diseños con precisión quirúrgica.
 
-CADforge no es un programa de dibujo. Es la infraestructura para que la arquitectura sea una **ciencia de datos reproducible**.
+CADspec no es un programa de dibujo. Es la infraestructura para que la arquitectura sea una **ciencia de datos reproducible**.
 
 ---
 
@@ -21,26 +21,26 @@ CADforge no es un programa de dibujo. Es la infraestructura para que la arquitec
 La arquitectura se divide en tres proyectos independientes que se integran entre sí:
 
 ```
-cadforge          → motor de geometría (librería Rust, crates.io)
-cadforge-cli      → interfaz de línea de comandos (binario Rust, crates.io)
-cadforge-view     → visor gráfico vectorial con modo calco (binario Rust)
+cadspec          → motor de geometría (librería Rust, crates.io)
+cadspec-cli      → interfaz de línea de comandos (binario Rust, crates.io)
+cadspec-view     → visor gráfico vectorial con modo calco (binario Rust)
 ```
 
 ### Separación de responsabilidades
 
 | Proyecto | Tipo | Responsabilidad |
 |---|---|---|
-| `cadforge` | Librería | Parser `.cf`, compilador → DXF, motor de geometría, sistema de capas y constraints |
-| `cadforge-cli` | Binario | Comandos, wizard, build, watch, import/export, integración con agentes |
-| `cadforge-view` | Binario | Visor vectorial estilo consola, modo calco, edición bidireccional → `.cf` |
+| `cadspec` | Librería | Parser `.cf`, compilador → DXF, motor de geometría, sistema de capas y constraints |
+| `cadspec-cli` | Binario | Comandos, wizard, build, watch, import/export, integración con agentes |
+| `cadspec-view` | Binario | Visor vectorial estilo consola, modo calco, edición bidireccional → `.cf` |
 
-La librería `cadforge` es reutilizable por cualquier proyecto Rust — el CLI y el visor son consumidores de ella.
+La librería `cadspec` es reutilizable por cualquier proyecto Rust — el CLI y el visor son consumidores de ella.
 
 ---
 
 ## 3. Formato de Proyecto
 
-Un proyecto CADforge es un directorio con la siguiente estructura:
+Un proyecto CADspec es un directorio con la siguiente estructura:
 
 ```
 mi-proyecto/
@@ -50,7 +50,7 @@ mi-proyecto/
 └── capa-c.cf       ← capa de primitivos (ej: acabados y anotaciones)
 ```
 
-El nombre de cada `.cf` lo define el usuario — CADforge no impone nomenclatura ni semántica de capas. Una capa es simplemente un conjunto de primitivos geométricos agrupados.
+El nombre de cada `.cf` lo define el usuario — CADspec no impone nomenclatura ni semántica de capas. Una capa es simplemente un conjunto de primitivos geométricos agrupados.
 
 ### project.toml
 
@@ -84,7 +84,7 @@ capa-c.belongs_to = "capa-b"
 
 El formato `.cf` es TOML válido. Se eligió TOML sobre JSON por ser más legible para humanos y agentes — menos contexto, más señal. Los agentes de IA que ya conocen TOML pueden generar y modificar archivos `.cf` sin entrenamiento adicional.
 
-**Principio clave:** el lenguaje `.cf` trabaja exclusivamente con **primitivos geométricos**. No existe concepto de "muro", "puerta" o "habitación" en el motor base. Esa semántica es responsabilidad del usuario o de capas de abstracción futuras (`cadforge-arch` en v2+). El motor solo sabe de formas, posiciones, atributos visuales y relaciones espaciales.
+**Principio clave:** el lenguaje `.cf` trabaja exclusivamente con **primitivos geométricos**. No existe concepto de "muro", "puerta" o "habitación" en el motor base. Esa semántica es responsabilidad del usuario o de capas de abstracción futuras (`cadspec-arch` en v2+). El motor solo sabe de formas, posiciones, atributos visuales y relaciones espaciales.
 
 ### Primitivos soportados en v1
 
@@ -206,7 +206,7 @@ Cada archivo `.cf` es una capa independiente. Las capas se orquestan desde `proj
 
 ### Comportamiento al compilar
 
-Cuando `cadforge build` detecta una violación de constraints:
+Cuando `cadspec build` detecta una violación de constraints:
 
 ```
 ⚠ CONSTRAINT VIOLATION
@@ -221,42 +221,42 @@ Las constraints no bloquean el build por defecto — emiten warnings. Se puede c
 
 ---
 
-## 6. cadforge-cli — Comandos
+## 6. cadspec-cli — Comandos
 
 ```bash
 # Inicialización
-cadforge new mi-proyecto          # crea estructura de proyecto
-cadforge init                     # inicializa en directorio existente
+cadspec new mi-proyecto          # crea estructura de proyecto
+cadspec init                     # inicializa en directorio existente
 
 # Compilación
-cadforge build                    # compila todas las capas → DXF
-cadforge build --layer muros      # compila una capa específica
-cadforge build --check            # valida constraints sin generar output
+cadspec build                    # compila todas las capas → DXF
+cadspec build --layer muros      # compila una capa específica
+cadspec build --check            # valida constraints sin generar output
 
 # Desarrollo
-cadforge watch                    # modo watch: recompila al guardar cualquier .cf
+cadspec watch                    # modo watch: recompila al guardar cualquier .cf
 
 # Importación / Migración
-cadforge import archivo.dxf       # convierte DXF existente → .cf (por capas detectadas)
-cadforge import archivo.dxf --layer muros  # importa a capa específica
+cadspec import archivo.dxf       # convierte DXF existente → .cf (por capas detectadas)
+cadspec import archivo.dxf --layer muros  # importa a capa específica
 
 # Visualización
-cadforge view                     # abre cadforge-view con el proyecto actual
-cadforge view --layer muros       # abre solo una capa
+cadspec view                     # abre cadspec-view con el proyecto actual
+cadspec view --layer muros       # abre solo una capa
 
 # Información
-cadforge layers                   # lista capas del proyecto con estado
-cadforge check                    # valida constraints y reporta conflictos
+cadspec layers                   # lista capas del proyecto con estado
+cadspec check                    # valida constraints y reporta conflictos
 
 # Configuración global
-cadforge config set author "Arq. Nombre Apellido"
-cadforge config set units m
-cadforge config show
+cadspec config set author "Arq. Nombre Apellido"
+cadspec config set units m
+cadspec config show
 ```
 
 ---
 
-## 7. cadforge-view — Visor Vectorial
+## 7. cadspec-view — Visor Vectorial
 
 ### Filosofía de diseño
 
@@ -303,7 +303,7 @@ Q           → cerrar visor
 Una de las propuestas de valor más importantes: **migrar lo que ya existe**.
 
 ```bash
-cadforge import plano-existente.dxf
+cadspec import plano-existente.dxf
 ```
 
 El importador:
@@ -314,7 +314,7 @@ El importador:
 5. Genera un `project.toml` con las capas detectadas
 
 ```
-cadforge import plano.dxf
+cadspec import plano.dxf
 
 ✓ Detected 4 layers: MUROS, ESTRUCTURA, COTAS, TEXTO
 ✓ muros.cf        — 23 walls inferred, 4 openings
@@ -345,7 +345,7 @@ Los agentes pueden leer y escribir archivos `.cf` directamente — TOML es un fo
 Y modificar coordenadas y orientaciones en `muros.cf` de forma precisa y auditable.
 
 ### ghscaff
-Plantilla `cadforge` en `ghscaff` para inicializar nuevos proyectos CADforge con estructura de repo correcta desde el primer commit.
+Plantilla `cadspec` en `ghscaff` para inicializar nuevos proyectos CADspec con estructura de repo correcta desde el primer commit.
 
 ---
 
@@ -373,22 +373,22 @@ Plantilla `cadforge` en `ghscaff` para inicializar nuevos proyectos CADforge con
 - [ ] Compilador `.cf` → DXF (2D, planos de planta)
 - [ ] Sistema de capas con `project.toml`
 - [ ] Constraints básicas: `parent`, `belongs_to`
-- [ ] `cadforge build` y `cadforge watch`
+- [ ] `cadspec build` y `cadspec watch`
 - [ ] Live preview vía visor externo (LibreCAD, FreeCAD)
-- [ ] Publicación en crates.io: `cadforge` (librería) + `cadforge-cli`
+- [ ] Publicación en crates.io: `cadspec` (librería) + `cadspec-cli`
 
 ### v1
 - [ ] Importador DXF → `.cf` con detección automática de primitivos
-- [ ] `cadforge-view` — visor vectorial propio (fondo negro, líneas vectoriales)
+- [ ] `cadspec-view` — visor vectorial propio (fondo negro, líneas vectoriales)
   - Modo lectura con zoom/pan y toggle de capas
   - Modo edición básico con escritura bidireccional al guardar
   - Modo calco con ventana semi-transparente
 - [ ] Constraints con warnings en build: `spatial_dependency`
 - [ ] Achurados estándar: ansi31, ansi32, ansi33, ansi34, solid
-- [ ] Publicación `cadforge-view` en crates.io
+- [ ] Publicación `cadspec-view` en crates.io
 
 ### v2
-- [ ] `cadforge-arch` — capa de abstracción arquitectónica sobre primitivos
+- [ ] `cadspec-arch` — capa de abstracción arquitectónica sobre primitivos
   - Objetos semánticos: `wall`, `opening`, `room`, `column`, `slab`
   - Construidos sobre primitivos del motor base
   - Publicado como crate independiente
@@ -413,6 +413,6 @@ Plantilla `cadforge` en `ghscaff` para inicializar nuevos proyectos CADforge con
 
 ## 13. Contexto Académico
 
-`cadforge` es el proyecto de tesis de especialización en IA con enfoque en diseño arquitectónico. La hipótesis central es que tratar la arquitectura como código — con determinismo, versionado y agentes — representa un cambio de paradigma en el flujo de trabajo del diseño arquitectónico.
+`cadspec` es el proyecto de tesis de especialización en IA con enfoque en diseño arquitectónico. La hipótesis central es que tratar la arquitectura como código — con determinismo, versionado y agentes — representa un cambio de paradigma en el flujo de trabajo del diseño arquitectónico.
 
 El proyecto vive bajo [`univerlab`](https://github.com/univerlab) junto a `texforge`, `gitkit`, `ghscaff` y `agent-canopy`, siguiendo los mismos principios: binario standalone, offline first, sin scope creep.
diff --git a/demo/README.md b/demo/README.md
index db00daa..11b1ec7 100644
--- a/demo/README.md
+++ b/demo/README.md
@@ -1,6 +1,6 @@
-# cadforge demo
+# cadspec demo
 
-The cadforge demo as code, recorded with [DemoStage](https://github.com/UniverLab/demo-stage).
+The cadspec demo as code, recorded with [DemoStage](https://github.com/UniverLab/demo-stage).
 It shows the terminal scaffolding a CAD project and starting the live preview, with
 the rendered drawing in a browser pane.
 
@@ -8,14 +8,14 @@ the rendered drawing in a browser pane.
 
 ```sh
 demo check  demo/demo.toml
-demo export demo/demo.toml --target gif   # → demo/dist/cadforge.gif
+demo export demo/demo.toml --target gif   # → demo/dist/cadspec.gif
 # or --target mp4
 ```
 
 - `gif`/`mp4` of a terminal + browser pane need a Chromium (auto-downloaded by
   DemoStage on first use, or use a system install) and, for mp4, ffmpeg.
 - The browser pane is captured after the terminal run, so this score leaves the
-  `cadforge serve` server running; stop it afterwards with
-  `cd /tmp/cadforge-demo/bracket && cadforge serve --stop`.
+  `cadspec serve` server running; stop it afterwards with
+  `cd /tmp/cadspec-demo/bracket && cadspec serve --stop`.
 
 Edit `demo/demo.toml` to change the commands, captions, layout or timing.
diff --git a/demo/demo.toml b/demo/demo.toml
index d4d2031..1c33d2a 100644
--- a/demo/demo.toml
+++ b/demo/demo.toml
@@ -1,16 +1,16 @@
-# cadforge demo — terminal (CAD as code) + the live SVG preview in a browser pane.
+# cadspec demo — terminal (CAD as code) + the live SVG preview in a browser pane.
 #
 # Generate the GIF with DemoStage (https://github.com/UniverLab/demo-stage):
 #   demo check demo/demo.toml
-#   demo export demo/demo.toml --target gif      # → demo/dist/cadforge.gif
+#   demo export demo/demo.toml --target gif      # → demo/dist/cadspec.gif
 #
 # NOTE: browser panes are captured *after* the terminal run, so the
-# `cadforge serve` background server must still be up at capture time — this demo
-# deliberately does NOT stop it. Afterwards: `cd /tmp/cadforge-demo/bracket &&
-# cadforge serve --stop`. Adjust commands/url to your build if they drift.
+# `cadspec serve` background server must still be up at capture time — this demo
+# deliberately does NOT stop it. Afterwards: `cd /tmp/cadspec-demo/bracket &&
+# cadspec serve --stop`. Adjust commands/url to your build if they drift.
 
 [demo]
-name = "cadforge"
+name = "cadspec"
 output_dir = "demo/dist"
 
 [typing]
@@ -20,7 +20,7 @@ seed = 7
 
 [env]
 isolated = true
-setup_script = "rm -rf /tmp/cadforge-demo && mkdir -p /tmp/cadforge-demo && cd /tmp/cadforge-demo"
+setup_script = "rm -rf /tmp/cadspec-demo && mkdir -p /tmp/cadspec-demo && cd /tmp/cadspec-demo"
 
 [layout]
 width = 1280
@@ -56,7 +56,7 @@ text = "1 — scaffold a CAD project"
 
 [[timeline]]
 action = "type"
-text = "cadforge new bracket && cd bracket"
+text = "cadspec new bracket && cd bracket"
 human_salt = true
 
 [[timeline]]
@@ -73,7 +73,7 @@ text = "2 — start the live preview"
 
 [[timeline]]
 action = "type"
-text = "cadforge serve"
+text = "cadspec serve"
 human_salt = true
 
 [[timeline]]
diff --git a/docs/agents.md b/docs/agents.md
index f267b01..73cc637 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -6,33 +6,33 @@ order: 7
 
 # Working with Agents
 
-Cadforge is designed for **humans and AI agents working together** on the
+Cadspec is designed for **humans and AI agents working together** on the
 same project. Everything an agent needs is exposed through the CLI.
 
-## Self-discovery — `cadforge schema`
+## Self-discovery — `cadspec schema`
 
 ```bash
-cadforge schema
+cadspec schema
 ```
 
 Prints the complete `.cf` language reference as markdown. An agent with
 shell access can learn the entire format in one command — no prior
-training on cadforge required.
+training on cadspec required.
 
 ## Machine-readable state
 
 ```bash
-cadforge check --json    # validation report
-cadforge layers --json   # layers, entity counts, colors
+cadspec check --json    # validation report
+cadspec layers --json   # layers, entity counts, colors
 ```
 
-## Visual grounding — `cadforge preview`
+## Visual grounding — `cadspec preview`
 
 ```bash
-cadforge preview                          # PNG + preview.meta.json
-cadforge preview --format svg             # same render as vector SVG
-cadforge preview --width 1024 -H 768      # custom resolution
-cadforge preview --layer muros            # single layer
+cadspec preview                          # PNG + preview.meta.json
+cadspec preview --format svg             # same render as vector SVG
+cadspec preview --width 1024 -H 768      # custom resolution
+cadspec preview --layer muros            # single layer
 ```
 
 The PNG is a faithful render — real text, measured dimension labels,
@@ -46,7 +46,7 @@ used), including fontless containers.
 ## Confirming edits — `--highlight`
 
 ```bash
-cadforge preview --highlight ln-001,tx-002
+cadspec preview --highlight ln-001,tx-002
 ```
 
 Draws labeled amber markers around the listed entities, so an agent can
@@ -61,10 +61,10 @@ source TOML and file — paste it into your agent and ask for the change.
 ## A typical agent loop
 
 ```bash
-cadforge schema                      # 1. learn the language
-cadforge layers --json               # 2. inspect the project
+cadspec schema                      # 1. learn the language
+cadspec layers --json               # 2. inspect the project
 # ... edit .cf files ...
-cadforge check --json                # 3. validate
-cadforge preview --highlight <ids>   # 4. visually confirm
-cadforge build                       # 5. emit the DXF
+cadspec check --json                # 3. validate
+cadspec preview --highlight <ids>   # 4. visually confirm
+cadspec build                       # 5. emit the DXF
 ```
diff --git a/docs/building-and-export.md b/docs/building-and-export.md
index 3f0f693..1f2b42d 100644
--- a/docs/building-and-export.md
+++ b/docs/building-and-export.md
@@ -9,10 +9,10 @@ order: 6
 ## Compile to DXF
 
 ```bash
-cadforge build                       # default output.dxf
-cadforge build --output plano.dxf    # custom output path
-cadforge build --layer muros         # compile a single layer
-cadforge build --check               # validate only, no DXF
+cadspec build                       # default output.dxf
+cadspec build --output plano.dxf    # custom output path
+cadspec build --layer muros         # compile a single layer
+cadspec build --check               # validate only, no DXF
 ```
 
 The output is deterministic: identical input produces a bit-identical
@@ -23,16 +23,16 @@ layer/color/lineweight mapping.
 ## Validation
 
 ```bash
-cadforge check          # geometry + constraints, human-readable
-cadforge check --json   # machine-readable report
-cadforge layers         # list layers with entity counts and colors
-cadforge layers --json  # machine-readable layer listing
+cadspec check          # geometry + constraints, human-readable
+cadspec check --json   # machine-readable report
+cadspec layers         # list layers with entity counts and colors
+cadspec layers --json  # machine-readable layer listing
 ```
 
 ## Watch mode
 
 ```bash
-cadforge watch
+cadspec watch
 ```
 
 Monitors `.cf` and `.toml` files and rebuilds the DXF on changes with a
@@ -41,15 +41,15 @@ Monitors `.cf` and `.toml` files and rebuilds the DXF on changes with a
 ## Formatting
 
 ```bash
-cadforge fmt           # normalize .cf files in place
-cadforge fmt --check   # CI-friendly check mode
+cadspec fmt           # normalize .cf files in place
+cadspec fmt --check   # CI-friendly check mode
 ```
 
 ## Importing existing drawings
 
 ```bash
-cadforge import plano.dxf                 # all layers
-cadforge import plano.dxf --layer muros   # a single DXF layer
+cadspec import plano.dxf                 # all layers
+cadspec import plano.dxf --layer muros   # a single DXF layer
 ```
 
 Import migrates an existing DXF into `.cf` layer files plus a
diff --git a/docs/cf-format.md b/docs/cf-format.md
index 65d0da8..27c7502 100644
--- a/docs/cf-format.md
+++ b/docs/cf-format.md
@@ -6,11 +6,11 @@ order: 4
 
 # The .cf Format
 
-A cadforge project is a `project.toml` plus one `.cf` file per layer.
+A cadspec project is a `project.toml` plus one `.cf` file per layer.
 `.cf` files are TOML: a `[layer]` header followed by arrays of entity
 tables.
 
-> The authoritative reference is always `cadforge schema` — it prints the
+> The authoritative reference is always `cadspec schema` — it prints the
 > complete language specification (markdown) for the exact version you
 > have installed.
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 6b2f86f..325010c 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -1,61 +1,61 @@
 ---
 title: CLI Reference
-description: Every cadforge command and flag.
+description: Every cadspec command and flag.
 order: 8
 ---
 
 # CLI Reference
 
 ```
-cadforge <command> [options]
+cadspec <command> [options]
 ```
 
 ## Project lifecycle
 
 | Command | Description |
 |---------|-------------|
-| `cadforge new <name>` | Create a new project with multi-layer scaffold |
-| `cadforge init` | Initialize cadforge in the current directory |
-| `cadforge build` | Compile project to DXF |
-| `cadforge build --check` | Validate project and constraints without generating DXF |
-| `cadforge build --output <path>` | Compile to custom output path |
-| `cadforge build --layer <name>` | Compile a specific layer only |
-| `cadforge watch` | Auto-rebuild on file changes (300 ms debounce) |
+| `cadspec new <name>` | Create a new project with multi-layer scaffold |
+| `cadspec init` | Initialize cadspec in the current directory |
+| `cadspec build` | Compile project to DXF |
+| `cadspec build --check` | Validate project and constraints without generating DXF |
+| `cadspec build --output <path>` | Compile to custom output path |
+| `cadspec build --layer <name>` | Compile a specific layer only |
+| `cadspec watch` | Auto-rebuild on file changes (300 ms debounce) |
 
 ## Preview
 
 | Command | Description |
 |---------|-------------|
-| `cadforge serve` | Live preview server — browser auto-reloads on save |
-| `cadforge serve --open --port <p>` | Open browser automatically on a custom port |
-| `cadforge preview` | Faithful PNG render + `preview.meta.json` |
-| `cadforge preview --format svg` | Vector SVG preview (same renderer) |
-| `cadforge preview --highlight <ids>` | Amber markers around specific entities |
-| `cadforge preview --width <w> -H <h>` | Custom resolution |
-| `cadforge preview --layer <name>` | Preview a specific layer only |
-| `cadforge view` | Open the project in the configured viewer |
-| `cadforge view --layer <name>` | Open only one layer in the viewer |
+| `cadspec serve` | Live preview server — browser auto-reloads on save |
+| `cadspec serve --open --port <p>` | Open browser automatically on a custom port |
+| `cadspec preview` | Faithful PNG render + `preview.meta.json` |
+| `cadspec preview --format svg` | Vector SVG preview (same renderer) |
+| `cadspec preview --highlight <ids>` | Amber markers around specific entities |
+| `cadspec preview --width <w> -H <h>` | Custom resolution |
+| `cadspec preview --layer <name>` | Preview a specific layer only |
+| `cadspec view` | Open the project in the configured viewer |
+| `cadspec view --layer <name>` | Open only one layer in the viewer |
 
 ## Inspection & quality
 
 | Command | Description |
 |---------|-------------|
-| `cadforge check` | Validate with project metadata and layer colors |
-| `cadforge check --json` | Machine-readable validation report |
-| `cadforge layers` | List layers with entity counts and colors |
-| `cadforge layers --json` | Machine-readable layer listing |
-| `cadforge schema` | Print the full `.cf` language reference (markdown) |
-| `cadforge fmt` | Format `.cf` files (normalize whitespace) |
-| `cadforge fmt --check` | Check formatting without modifying (CI) |
+| `cadspec check` | Validate with project metadata and layer colors |
+| `cadspec check --json` | Machine-readable validation report |
+| `cadspec layers` | List layers with entity counts and colors |
+| `cadspec layers --json` | Machine-readable layer listing |
+| `cadspec schema` | Print the full `.cf` language reference (markdown) |
+| `cadspec fmt` | Format `.cf` files (normalize whitespace) |
+| `cadspec fmt --check` | Check formatting without modifying (CI) |
 
 ## Import & config
 
 | Command | Description |
 |---------|-------------|
-| `cadforge import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
-| `cadforge import <file.dxf> --layer <name>` | Import only one DXF layer |
-| `cadforge config set <key> <value>` | Set global defaults (`author`, `units`) |
-| `cadforge config show` | Show global defaults |
+| `cadspec import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
+| `cadspec import <file.dxf> --layer <name>` | Import only one DXF layer |
+| `cadspec config set <key> <value>` | Set global defaults (`author`, `units`) |
+| `cadspec config show` | Show global defaults |
 
 ## Output files
 
diff --git a/docs/index.md b/docs/index.md
index e14208d..549dc89 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,12 +1,12 @@
 ---
-title: Cadforge
+title: Cadspec
 description: CAD as code — declarative CAD in TOML, live browser preview, deterministic DXF output.
 order: 1
 ---
 
-# Cadforge
+# Cadspec
 
-Cadforge is a **CAD as code** CLI tool and Rust library for
+Cadspec is a **CAD as code** CLI tool and Rust library for
 declarative CAD modeling. Write geometry as code in `.cf` TOML files,
 watch it live in the browser, and compile to AutoCAD-compatible DXF —
 built for humans and AI agents working together.
@@ -14,7 +14,7 @@ built for humans and AI agents working together.
 ## The plan is not drawn — it is declared
 
 Traditional CAD drawings are collections of lines without semantics:
-impossible to version, diff or automate. Cadforge treats an architectural
+impossible to version, diff or automate. Cadspec treats an architectural
 plan like source code:
 
 - Same input → **bit-identical output**, every time.
@@ -24,27 +24,27 @@ plan like source code:
 ## The core loop
 
 ```bash
-cadforge new casa && cd casa
-cadforge serve --open        # live preview in the browser
+cadspec new casa && cd casa
+cadspec serve --open        # live preview in the browser
 ```
 
 Edit any `.cf` file — by hand or by asking an AI agent — and the browser
 updates on every save. Parse errors and constraint violations appear as an
-overlay instead of a crash. When the design is right, `cadforge build`
+overlay instead of a crash. When the design is right, `cadspec build`
 emits a deterministic DXF.
 
 ## Built for agents
 
 Agents get first-class support:
 
-- `cadforge schema` — the full `.cf` language reference in one command;
+- `cadspec schema` — the full `.cf` language reference in one command;
   agents self-discover the format without prior training.
-- `cadforge check --json` / `cadforge layers --json` — machine-readable
+- `cadspec check --json` / `cadspec layers --json` — machine-readable
   reports.
-- `cadforge preview` — a faithful PNG render plus `preview.meta.json`
+- `cadspec preview` — a faithful PNG render plus `preview.meta.json`
   with per-entity bounding boxes, so multimodal agents can *look* at the
   plan and locate every entity.
-- `cadforge preview --highlight ln-001,tx-002` — labeled markers to
+- `cadspec preview --highlight ln-001,tx-002` — labeled markers to
   visually confirm an edit landed where intended.
 
 ## How the documentation is organized
@@ -52,14 +52,14 @@ Agents get first-class support:
 - [Installation](installation.md) — install, update and uninstall.
 - [Quick Start](quickstart.md) — from zero to DXF.
 - [The .cf Format](cf-format.md) — layers, primitives, construction tools.
-- [Live Preview](live-preview.md) — `cadforge serve` and its controls.
+- [Live Preview](live-preview.md) — `cadspec serve` and its controls.
 - [Building & Export](building-and-export.md) — build, watch, DXF import/export.
 - [Working with Agents](agents.md) — the agent-facing toolchain.
 - [CLI Reference](cli-reference.md) — every command and flag.
 
 ## Part of UniverLab
 
-Cadforge is an experiment of [UniverLab](https://github.com/UniverLab),
+Cadspec is an experiment of [UniverLab](https://github.com/UniverLab),
 an open computational laboratory. It follows the lab's engineering
 principles: one tool one job, reproducibility first, offline-friendly
 design.
diff --git a/docs/installation.md b/docs/installation.md
index 21dfb5a..6581b62 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,12 +1,12 @@
 ---
 title: Installation
-description: Install cadforge with the quick installer, cargo, or from source.
+description: Install cadspec with the quick installer, cargo, or from source.
 order: 2
 ---
 
 # Installation
 
-> Cadforge is currently in **beta** (`0.1.0-beta.x`). Interfaces may still
+> Cadspec is currently in **beta** (`0.1.0-beta.x`). Interfaces may still
 > change before 1.0.
 
 ## Quick install
@@ -26,24 +26,24 @@ irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps
 ## Via cargo
 
 ```bash
-cargo install cadforge
+cargo install cadspec
 ```
 
-Available on [crates.io](https://crates.io/crates/cadforge).
+Available on [crates.io](https://crates.io/crates/cadspec).
 
 ## From source
 
 ```bash
 git clone https://github.com/UniverLab/cadforge.git
-cd cadforge
+cd cadspec
 cargo build --release
-# Binary at target/release/cadforge
+# Binary at target/release/cadspec
 ```
 
 ## Uninstall
 
 ```bash
-rm -f ~/.local/bin/cadforge
+rm -f ~/.local/bin/cadspec
 ```
 
 Projects are plain directories of TOML files — nothing else to clean up.
diff --git a/docs/live-preview.md b/docs/live-preview.md
index 9ff502d..56bf566 100644
--- a/docs/live-preview.md
+++ b/docs/live-preview.md
@@ -1,17 +1,17 @@
 ---
 title: Live Preview
-description: The cadforge serve loop — pan/zoom, inspector, layer states, 3D view, error overlay.
+description: The cadspec serve loop — pan/zoom, inspector, layer states, 3D view, error overlay.
 order: 5
 ---
 
 # Live Preview
 
 ```bash
-cadforge serve                       # start the local preview server
-cadforge serve --open --port 4377    # open browser, custom port
+cadspec serve                       # start the local preview server
+cadspec serve --open --port 4377    # open browser, custom port
 ```
 
-`cadforge serve` runs a zero-config local server with auto-reload on
+`cadspec serve` runs a zero-config local server with auto-reload on
 save (SSE). Edit a `.cf` file and the browser updates instantly.
 
 ## Controls
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 174506a..4b4c466 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -9,18 +9,18 @@ order: 3
 ## 1. Create a project
 
 ```bash
-cadforge new my-house
+cadspec new my-house
 cd my-house
 ```
 
-`cadforge new` scaffolds a complete multi-layer project (walls, doors,
+`cadspec new` scaffolds a complete multi-layer project (walls, doors,
 furniture, dimensions) with meaningful architectural examples. To adopt
-cadforge in an existing directory use `cadforge init`.
+cadspec in an existing directory use `cadspec init`.
 
 ## 2. Preview it live
 
 ```bash
-cadforge serve --open
+cadspec serve --open
 ```
 
 A local server opens the plan in your browser. Edit any `.cf` file and
@@ -44,23 +44,23 @@ to = [8.5, 0.0]
 weight = 0.50
 ```
 
-Run `cadforge schema` for the complete language reference, or read
+Run `cadspec schema` for the complete language reference, or read
 [The .cf Format](cf-format.md).
 
 ## 4. Validate and format
 
 ```bash
-cadforge check     # validate geometry and constraints, no output files
-cadforge fmt       # normalize .cf files
+cadspec check     # validate geometry and constraints, no output files
+cadspec fmt       # normalize .cf files
 ```
 
 ## 5. Compile to DXF
 
 ```bash
-cadforge build                       # default output.dxf
-cadforge build --output plano.dxf    # custom output path
-cadforge build --layer muros         # single layer
+cadspec build                       # default output.dxf
+cadspec build --output plano.dxf    # custom output path
+cadspec build --layer muros         # single layer
 ```
 
-The output is deterministic and AutoCAD-compatible. `cadforge watch`
+The output is deterministic and AutoCAD-compatible. `cadspec watch`
 rebuilds automatically while you edit.
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 303eea4..cb014f1 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -1,4 +1,4 @@
-# install.ps1 — download and install cadforge on Windows
+# install.ps1 — download and install cadspec on Windows
 # Usage: irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
 #
 # Options (set as env vars before running):
@@ -8,7 +8,7 @@
 $ErrorActionPreference = "Stop"
 
 $Repo       = "UniverLab/cadforge"
-$Binary     = "cadforge.exe"
+$Binary     = "cadspec.exe"
 $Target     = "x86_64-pc-windows-msvc"
 $InstallDir = if ($env:INSTALL_DIR) { $env:INSTALL_DIR } else { "$env:USERPROFILE\.local\bin" }
 
@@ -43,9 +43,9 @@ if ($env:VERSION) {
 }
 
 # --- download ---
-$Archive = "cadforge-$Tag-$Target.zip"
+$Archive = "cadspec-$Tag-$Target.zip"
 $Url     = "https://github.com/$Repo/releases/download/$Tag/$Archive"
-$Tmp     = Join-Path $env:TEMP "cadforge-install"
+$Tmp     = Join-Path $env:TEMP "cadspec-install"
 New-Item -ItemType Directory -Force -Path $Tmp | Out-Null
 
 Info "download" $Url
@@ -76,10 +76,10 @@ if ($userPath -notlike "*$InstallDir*") {
 # --- cleanup ---
 Remove-Item $Tmp -Recurse -Force
 
-# --- install the cadforge agent skill (optional) ---
-# Teaches AI agents how to drive cadforge. Skipped when npx is unavailable or
+# --- install the cadspec agent skill (optional) ---
+# Teaches AI agents how to drive cadspec. Skipped when npx is unavailable or
 # $env:SKIP_SKILL is set; a failure here never fails the binary install above.
-$Skill      = "cadforge"
+$Skill      = "cadspec"
 $SkillsRepo = "https://github.com/UniverLab/skills"
 if ($env:SKIP_SKILL) {
     Info "skill" "skipped (SKIP_SKILL set)"
@@ -103,4 +103,4 @@ if ($env:SKIP_SKILL) {
 $ver = & "$InstallDir\$Binary" --version 2>$null
 Info "done" $ver
 Write-Host ""
-Info "ready" "Run 'cadforge --help' to get started!"
+Info "ready" "Run 'cadspec --help' to get started!"
diff --git a/scripts/install.sh b/scripts/install.sh
index e75f7ce..d98cf33 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1,10 +1,10 @@
 #!/bin/sh
-# install.sh — download and install cadforge from GitHub Releases
+# install.sh — download and install cadspec from GitHub Releases
 # Usage: curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.sh | sh
 set -eu
 
 REPO="UniverLab/cadforge"
-BINARY="cadforge"
+BINARY="cadspec"
 INSTALL_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
 
 info() { printf '  \033[1;34m%s\033[0m %s\n' "$1" "$2"; }
@@ -33,7 +33,7 @@ TMPDIR="$(mktemp -d)"
 trap 'rm -rf "$TMPDIR"' EXIT
 
 # ============================================================
-# 1. Install cadforge
+# 1. Install cadspec
 # ============================================================
 
 # --- resolve version ---
@@ -88,7 +88,7 @@ if [ -n "$PATHS_TO_ADD" ]; then
     if [ -f "$profile" ]; then
       for dir in $PATHS_TO_ADD; do
         if ! grep -q "export PATH=\"$dir:\$PATH\"" "$profile" 2>/dev/null; then
-          printf '\n# Added by cadforge installer\nexport PATH="%s:$PATH"\n' "$dir" >> "$profile"
+          printf '\n# Added by cadspec installer\nexport PATH="%s:$PATH"\n' "$dir" >> "$profile"
           info "updated" "$profile"
         fi
       done
@@ -97,12 +97,12 @@ if [ -n "$PATHS_TO_ADD" ]; then
 fi
 
 # ============================================================
-# 3. Install the cadforge agent skill (optional)
+# 3. Install the cadspec agent skill (optional)
 # ============================================================
-# Teaches AI agents how to drive cadforge. Skipped when npx is unavailable or
+# Teaches AI agents how to drive cadspec. Skipped when npx is unavailable or
 # SKIP_SKILL is set; a failure here never fails the binary install above.
 
-SKILL="cadforge"
+SKILL="cadspec"
 SKILLS_REPO="https://github.com/UniverLab/skills"
 
 if [ -n "${SKIP_SKILL:-}" ]; then
@@ -124,4 +124,4 @@ fi
 
 info "done" "$($INSTALL_DIR/$BINARY --version 2>/dev/null || echo "$BINARY installed")"
 echo ""
-info "ready" "Run 'cadforge --help' to get started!"
+info "ready" "Run 'cadspec --help' to get started!"
diff --git a/src/config.rs b/src/config.rs
index dca785c..d1c296a 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,4 +1,4 @@
-//! Global configuration for cadforge CLI defaults.
+//! Global configuration for cadspec CLI defaults.
 
 use anyhow::{anyhow, Context, Result};
 use std::fs;
@@ -9,7 +9,7 @@ const SUPPORTED_KEYS: &[&str] = &["author", "units"];
 
 fn config_path() -> Result<PathBuf> {
     let home = std::env::var("HOME").context("HOME environment variable is not set")?;
-    Ok(PathBuf::from(home).join(".cadforge").join("config.toml"))
+    Ok(PathBuf::from(home).join(".cadspec").join("config.toml"))
 }
 
 fn load_document(path: &PathBuf) -> Result<DocumentMut> {
diff --git a/src/dxf_writer.rs b/src/dxf_writer.rs
index e3f4dd3..d20487f 100644
--- a/src/dxf_writer.rs
+++ b/src/dxf_writer.rs
@@ -418,7 +418,7 @@ mod tests {
         w.circle(5.0, 5.0, 2.0, "MUROS", &s);
         w.rect(1.0, 1.0, 3.0, 4.0, "MUROS", &s);
 
-        let path = PathBuf::from("/tmp/cadforge_test_basic.dxf");
+        let path = PathBuf::from("/tmp/cadspec_test_basic.dxf");
         w.save(&path).unwrap();
         assert!(path.exists());
     }
@@ -434,7 +434,7 @@ mod tests {
         };
         w.line(0.0, 0.0, 1.0, 1.0, "TEST", &style);
 
-        let path = PathBuf::from("/tmp/cadforge_test_styled.dxf");
+        let path = PathBuf::from("/tmp/cadspec_test_styled.dxf");
         w.save(&path).unwrap();
         assert!(path.exists());
     }
diff --git a/src/fmt.rs b/src/fmt.rs
index 8f5bb4d..14a333b 100644
--- a/src/fmt.rs
+++ b/src/fmt.rs
@@ -53,7 +53,7 @@ pub fn format_project(project_dir: &Path, check_only: bool) -> Result<()> {
     }
 
     if check_only && changed > 0 {
-        anyhow::bail!("{changed} file(s) need formatting. Run `cadforge fmt` to fix.");
+        anyhow::bail!("{changed} file(s) need formatting. Run `cadspec fmt` to fix.");
     }
     if !check_only {
         println!("✓ {changed} file(s) formatted");
diff --git a/src/importer.rs b/src/importer.rs
index 306b384..bc7037d 100644
--- a/src/importer.rs
+++ b/src/importer.rs
@@ -1,4 +1,4 @@
-//! DXF importer — converts DXF layers/entities into CADforge `.cf` + `project.toml`.
+//! DXF importer — converts DXF layers/entities into CADspec `.cf` + `project.toml`.
 
 use crate::color::aci_to_hex;
 use anyhow::{anyhow, Context, Result};
@@ -310,7 +310,7 @@ fn dim_offset(from: [f64; 2], to: [f64; 2], insertion: [f64; 2]) -> Option<f64>
     Some((insertion[0] - mid[0]) * nx + (insertion[1] - mid[1]) * ny)
 }
 
-/// Drop the extension/dimension lines and label text that `cadforge build`
+/// Drop the extension/dimension lines and label text that `cadspec build`
 /// emits alongside each DIMENSION entity for viewer compatibility; the
 /// re-created `[[dim]]` regenerates all of them. Foreign DXFs are unaffected
 /// (their dimension graphics live in blocks, not loose entities).
diff --git a/src/lib.rs b/src/lib.rs
index 67cd553..b902819 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,4 @@
-//! cadforge — deterministic geometry engine for reproducible architectural design.
+//! cadspec — deterministic geometry engine for reproducible architectural design.
 //!
 //! Pipeline: `.cf` (TOML) → intermediate model → DXF output.
 
diff --git a/src/main.rs b/src/main.rs
index bf310d0..0de9eaa 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,20 +1,20 @@
 use anyhow::{bail, Result};
-use cadforge::compiler::{check_project, compile_project, list_layers, project_report};
-use cadforge::config::{config_set, config_show};
-use cadforge::fmt::format_project;
-use cadforge::importer::import_dxf;
-use cadforge::preview::{generate_plano, generate_preview, PreviewOutputs, PreviewView};
-use cadforge::scaffold::{create_project, init_project};
-use cadforge::schema::print_schema;
-use cadforge::serve::{serve_daemon, serve_project, serve_stop};
-use cadforge::viewer::view_project;
-use cadforge::watch::watch_project;
+use cadspec::compiler::{check_project, compile_project, list_layers, project_report};
+use cadspec::config::{config_set, config_show};
+use cadspec::fmt::format_project;
+use cadspec::importer::import_dxf;
+use cadspec::preview::{generate_plano, generate_preview, PreviewOutputs, PreviewView};
+use cadspec::scaffold::{create_project, init_project};
+use cadspec::schema::print_schema;
+use cadspec::serve::{serve_daemon, serve_project, serve_stop};
+use cadspec::viewer::view_project;
+use cadspec::watch::watch_project;
 use clap::{Parser, Subcommand, ValueEnum};
 use std::path::PathBuf;
 
 #[derive(Parser)]
 #[command(
-    name = "cadforge",
+    name = "cadspec",
     version,
     about = "CAD as code — declarative geometry → DXF"
 )]
@@ -25,12 +25,12 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
-    /// Create a new CADforge project
+    /// Create a new CADspec project
     New {
         /// Project name (creates a directory with this name)
         name: String,
     },
-    /// Initialize CADforge in the current directory
+    /// Initialize CADspec in the current directory
     Init,
     /// Compile project (.cf files) → DXF output
     Build {
@@ -128,7 +128,7 @@ enum Commands {
         #[arg(short, long)]
         path: Option<PathBuf>,
     },
-    /// Import a DXF file into CADforge project files
+    /// Import a DXF file into CADspec project files
     Import {
         /// Input DXF file
         input: PathBuf,
@@ -148,7 +148,7 @@ enum Commands {
         #[arg(short, long)]
         layer: Option<String>,
     },
-    /// Global cadforge configuration
+    /// Global cadspec configuration
     Config {
         #[command(subcommand)]
         command: ConfigCommands,
@@ -310,7 +310,7 @@ fn resolve_project_dir(path: Option<PathBuf>) -> Result<PathBuf> {
     let dir = path.unwrap_or_else(|| PathBuf::from("."));
     if !dir.join("project.toml").exists() {
         bail!(
-            "No project.toml found in '{}'. Run `cadforge new` to create a project.",
+            "No project.toml found in '{}'. Run `cadspec new` to create a project.",
             dir.display()
         );
     }
diff --git a/src/planos.rs b/src/planos.rs
index 64589af..de3d801 100644
--- a/src/planos.rs
+++ b/src/planos.rs
@@ -232,7 +232,7 @@ fn title_block(
     );
     let _ = write!(
         s,
-        r#"<text x="{tx:.1}" y="{ty:.1}" font-family="monospace" font-size="{fs:.1}" fill="{MUTED}" text-anchor="end">cadforge</text>"#,
+        r#"<text x="{tx:.1}" y="{ty:.1}" font-family="monospace" font-size="{fs:.1}" fill="{MUTED}" text-anchor="end">cadspec</text>"#,
         tx = x + w - pad,
         ty = y + h - row * 0.35,
     );
diff --git a/src/preview.rs b/src/preview.rs
index 55c670d..57ab2c2 100644
--- a/src/preview.rs
+++ b/src/preview.rs
@@ -2,7 +2,7 @@
 //!
 //! The PNG is a faithful raster of the SVG renderer (real text, measured
 //! dimensions, hatches, line styles), so what an agent *sees* in the image is
-//! exactly what `cadforge serve` shows a human. The metadata JSON maps every
+//! exactly what `cadspec serve` shows a human. The metadata JSON maps every
 //! entity to world and pixel bounding boxes so agents can locate geometry in
 //! the image.
 
diff --git a/src/render3d.rs b/src/render3d.rs
index 1195585..57d5a13 100644
--- a/src/render3d.rs
+++ b/src/render3d.rs
@@ -1,6 +1,6 @@
 //! 3D view renderer — extrudes `.cf` geometry into solids and projects them.
 //!
-//! cadforge geometry is declared in 2D plan coordinates. Any primitive can
+//! cadspec geometry is declared in 2D plan coordinates. Any primitive can
 //! carry an `extrude` height (and optional `elevation`): a closed shape becomes
 //! a solid prism, a line or open polyline becomes a vertical wall. This module
 //! projects that geometry with a fixed axonometric (isometric) camera, sorts
diff --git a/src/scaffold.rs b/src/scaffold.rs
index 0a7d966..e595ce8 100644
--- a/src/scaffold.rs
+++ b/src/scaffold.rs
@@ -1,10 +1,10 @@
-//! Scaffold — generates a new CADforge project structure.
+//! Scaffold — generates a new CADspec project structure.
 
 use anyhow::{bail, Result};
 use std::fs;
 use std::path::Path;
 
-/// Create a new CADforge project in the given directory.
+/// Create a new CADspec project in the given directory.
 pub fn create_project(name: &str, parent: &Path) -> Result<()> {
     let project_dir = parent.join(name);
     if project_dir.exists() {
@@ -21,15 +21,15 @@ pub fn create_project(name: &str, parent: &Path) -> Result<()> {
     println!("  → annotations.cf");
     println!("  → .gitignore");
     println!(
-        "\n  Run `cadforge serve --path {}` for a live preview,",
+        "\n  Run `cadspec serve --path {}` for a live preview,",
         name
     );
-    println!("  or `cadforge build --path {}` to compile to DXF.", name);
-    println!("  `cadforge schema` prints the .cf language reference.");
+    println!("  or `cadspec build --path {}` to compile to DXF.", name);
+    println!("  `cadspec schema` prints the .cf language reference.");
     Ok(())
 }
 
-/// Initialize a CADforge project in the current directory.
+/// Initialize a CADspec project in the current directory.
 pub fn init_project(dir: &Path) -> Result<()> {
     if dir.join("project.toml").exists() {
         bail!("project.toml already exists in '{}'", dir.display());
@@ -41,14 +41,14 @@ pub fn init_project(dir: &Path) -> Result<()> {
         .unwrap_or("project");
     write_project_files(dir, name)?;
 
-    println!("✓ Initialized CADforge project in {}", dir.display());
+    println!("✓ Initialized CADspec project in {}", dir.display());
     println!("  → project.toml");
     println!("  → shapes.cf");
     println!("  → curves.cf");
     println!("  → annotations.cf");
     println!("  → .gitignore");
-    println!("\n  Run `cadforge serve` for a live preview.");
-    println!("  `cadforge schema` prints the .cf language reference.");
+    println!("\n  Run `cadspec serve` for a live preview.");
+    println!("  `cadspec schema` prints the .cf language reference.");
     Ok(())
 }
 
@@ -67,7 +67,7 @@ annotations = {{ file = "annotations.cf", locked = false }}
     );
     fs::write(project_dir.join("project.toml"), project_toml)?;
 
-    let gitignore = "# CADforge output\noutput.dxf\npreview.png\npreview.svg\npreview.meta.json\n\n# CADforge serve daemon (pid + logs)\n.cadforge/\n\n# Rust build artifacts\ntarget/\n";
+    let gitignore = "# CADspec output\noutput.dxf\npreview.png\npreview.svg\npreview.meta.json\n\n# CADspec serve daemon (pid + logs)\n.cadspec/\n\n# Rust build artifacts\ntarget/\n";
     fs::write(project_dir.join(".gitignore"), gitignore)?;
 
     let shapes_cf = r##"[layer]
@@ -180,7 +180,7 @@ mod tests {
 
     #[test]
     fn creates_project_structure() {
-        let tmp = PathBuf::from("/tmp/cadforge_test_new");
+        let tmp = PathBuf::from("/tmp/cadspec_test_new");
         let _ = fs::remove_dir_all(&tmp);
         fs::create_dir_all(&tmp).unwrap();
 
@@ -208,7 +208,7 @@ mod tests {
 
     #[test]
     fn fails_if_dir_exists() {
-        let tmp = PathBuf::from("/tmp/cadforge_test_exists");
+        let tmp = PathBuf::from("/tmp/cadspec_test_exists");
         let _ = fs::remove_dir_all(&tmp);
         fs::create_dir_all(tmp.join("existing")).unwrap();
 
@@ -220,7 +220,7 @@ mod tests {
 
     #[test]
     fn init_in_existing_dir() {
-        let tmp = PathBuf::from("/tmp/cadforge_test_init");
+        let tmp = PathBuf::from("/tmp/cadspec_test_init");
         let _ = fs::remove_dir_all(&tmp);
         fs::create_dir_all(&tmp).unwrap();
 
@@ -237,7 +237,7 @@ mod tests {
 
     #[test]
     fn init_fails_if_project_exists() {
-        let tmp = PathBuf::from("/tmp/cadforge_test_init_exists");
+        let tmp = PathBuf::from("/tmp/cadspec_test_init_exists");
         let _ = fs::remove_dir_all(&tmp);
         fs::create_dir_all(&tmp).unwrap();
         fs::write(tmp.join("project.toml"), "").unwrap();
diff --git a/src/schema.rs b/src/schema.rs
index a50100a..90d9590 100644
--- a/src/schema.rs
+++ b/src/schema.rs
@@ -1,13 +1,13 @@
-//! Schema — the `.cf` language reference, printable via `cadforge schema`.
+//! Schema — the `.cf` language reference, printable via `cadspec schema`.
 //!
 //! This is the self-discovery entry point for AI agents and humans alike: one
 //! command dumps the complete format so any agent can generate valid `.cf`
 //! files without prior training.
 
 /// Complete `.cf` + `project.toml` reference in markdown.
-pub const CF_REFERENCE: &str = r##"# CADforge `.cf` Language Reference
+pub const CF_REFERENCE: &str = r##"# CADspec `.cf` Language Reference
 
-CADforge projects are plain TOML. A project is a directory with a `project.toml`
+CADspec projects are plain TOML. A project is a directory with a `project.toml`
 plus one `.cf` file per layer. Geometry is declared, never drawn: the same files
 always compile to the same DXF.
 
@@ -30,7 +30,7 @@ cotas.belongs_to = "muros"      # child primitives reference parent ids via belo
 "muros → puertas" = "spatial_dependency"  # movement warning (informational)
 
 # Planos (drawing sheets): named views of the model with a title block.
-# Render with `cadforge preview --plano <name>`, or pick them in the viewer's
+# Render with `cadspec preview --plano <name>`, or pick them in the viewer's
 # Planos panel (under Layers).
 [[plano]]
 name = "P-01"
@@ -77,7 +77,7 @@ elevation = 0.0        # 3D view: base height (Z) the shape sits at (default 0)
 ```
 
 The 2D plan is unaffected by `extrude`/`elevation`; they only shape the
-extruded 3D view (`cadforge preview --3d`, or the viewer's `3D` button).
+extruded 3D view (`cadspec preview --3d`, or the viewer's `3D` button).
 
 ### Primitives
 
@@ -206,24 +206,24 @@ A cube with a hole = a `box` minus a `cylinder` via `op = "difference"`.
 ## Workflow
 
 ```bash
-cadforge serve            # live preview in the browser (auto-reloads on save)
-cadforge build            # compile to output.dxf
-cadforge check --json     # machine-readable validation report
-cadforge layers --json    # machine-readable layer listing
-cadforge preview          # PNG + metadata JSON (--format svg for vector)
-cadforge preview --highlight ln-001,tx-002   # amber markers around those ids
-cadforge fmt              # normalize .cf formatting
+cadspec serve            # live preview in the browser (auto-reloads on save)
+cadspec build            # compile to output.dxf
+cadspec check --json     # machine-readable validation report
+cadspec layers --json    # machine-readable layer listing
+cadspec preview          # PNG + metadata JSON (--format svg for vector)
+cadspec preview --highlight ln-001,tx-002   # amber markers around those ids
+cadspec fmt              # normalize .cf formatting
 ```
 
-The feedback loop for agents: edit `.cf` → run `cadforge check --json` to
-validate → run `cadforge preview` and **look at `preview.png`** — it is a
+The feedback loop for agents: edit `.cf` → run `cadspec check --json` to
+validate → run `cadspec preview` and **look at `preview.png`** — it is a
 faithful render (real text, measured dimension labels, hatches, line styles).
 `preview.meta.json` maps every entity id to world and pixel bounding boxes.
 After editing specific entities, re-render with
-`cadforge preview --highlight <ids>` to visually confirm the change landed
+`cadspec preview --highlight <ids>` to visually confirm the change landed
 where intended (highlighted entities get labeled amber markers).
 
-For humans, `cadforge serve` adds: click any entity to inspect its source
+For humans, `cadspec serve` adds: click any entity to inspect its source
 TOML block (copyable as an agent prompt for targeted edits), a layer panel
 with on/ghost/off states (trace one floor over another), and a `3D` button
 that renders the extruded view (see `extrude`/`elevation` above).
diff --git a/src/serve.rs b/src/serve.rs
index e50cdb2..8ba64ce 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -1,4 +1,4 @@
-//! Live preview server — `cadforge serve`.
+//! Live preview server — `cadspec serve`.
 //!
 //! Watches the project files and serves an auto-reloading SVG preview in the
 //! browser. The vibecoding loop: an agent (or human) edits `.cf` files, the
@@ -79,7 +79,7 @@ pub fn serve_project(project_dir: &Path, port: u16, open: bool) -> Result<()> {
         .with_context(|| format!("Cannot bind 127.0.0.1:{} (port in use?)", port))?;
     let url = format!("http://127.0.0.1:{}", port);
 
-    println!("◉ cadforge serve — {}", project.project.name);
+    println!("◉ cadspec serve — {}", project.project.name);
     println!("  Preview: {}", url);
     println!("  Watching: {}", project_dir.display());
     println!();
@@ -112,7 +112,7 @@ pub fn serve_project(project_dir: &Path, port: u16, open: bool) -> Result<()> {
 // we never claim "running" for a server that failed to come up.
 
 fn runtime_dir(project_dir: &Path) -> PathBuf {
-    project_dir.join(".cadforge")
+    project_dir.join(".cadspec")
 }
 
 fn pid_path(project_dir: &Path) -> PathBuf {
@@ -168,9 +168,9 @@ pub fn serve_daemon(project_dir: &Path, port: u16, open: bool) -> Result<()> {
     let url = format!("http://127.0.0.1:{}", port);
 
     if let Some(pid) = running_pid(&project_dir) {
-        println!("◉ cadforge serve already running (pid {pid})");
+        println!("◉ cadspec serve already running (pid {pid})");
         println!("  Preview: {url}");
-        println!("  Stop with: cadforge serve --stop");
+        println!("  Stop with: cadspec serve --stop");
         if open {
             open_browser(&url);
         }
@@ -187,7 +187,7 @@ pub fn serve_daemon(project_dir: &Path, port: u16, open: bool) -> Result<()> {
     let log = log_path(&project_dir);
     let log_file = File::create(&log)?;
 
-    let exe = std::env::current_exe().context("cannot locate cadforge executable")?;
+    let exe = std::env::current_exe().context("cannot locate cadspec executable")?;
     let mut cmd = Command::new(exe);
     cmd.arg("serve")
         .arg("--foreground")
@@ -209,10 +209,10 @@ pub fn serve_daemon(project_dir: &Path, port: u16, open: bool) -> Result<()> {
     fs::write(pid_path(&project_dir), pid.to_string())?;
 
     if wait_until_ready(port, Duration::from_secs(5)) {
-        println!("◉ cadforge serve — running in background (pid {pid})");
+        println!("◉ cadspec serve — running in background (pid {pid})");
         println!("  Preview: {url}");
         println!("  Logs:    {}", log.display());
-        println!("  Stop with: cadforge serve --stop");
+        println!("  Stop with: cadspec serve --stop");
         if open {
             open_browser(&url);
         }
@@ -236,7 +236,7 @@ pub fn serve_stop(project_dir: &Path, _port: u16) -> Result<()> {
 
     let Some(pid) = running_pid(&project_dir) else {
         let _ = fs::remove_file(&pid_file); // clean up any stale pidfile
-        println!("No cadforge serve daemon running for this project.");
+        println!("No cadspec serve daemon running for this project.");
         return Ok(());
     };
 
@@ -248,7 +248,7 @@ pub fn serve_stop(project_dir: &Path, _port: u16) -> Result<()> {
     let _ = fs::remove_file(&pid_file);
 
     if stopped {
-        println!("✓ Stopped cadforge serve (pid {pid}).");
+        println!("✓ Stopped cadspec serve (pid {pid}).");
         Ok(())
     } else {
         bail!("failed to stop process {pid}")
@@ -646,7 +646,7 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
-<title>{{PROJECT_NAME}} — cadforge live</title>
+<title>{{PROJECT_NAME}} — cadspec live</title>
 <style>
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body { background: #0d0d0d; color: #ddd; font-family: ui-monospace, 'Cascadia Code', 'Fira Code', monospace; height: 100vh; display: flex; flex-direction: column; overflow: hidden; }
@@ -710,7 +710,7 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
 <header>
   <span id="dot"></span>
   <span id="title">{{PROJECT_NAME}}</span>
-  <span class="tag">cadforge live</span>
+  <span class="tag">cadspec live</span>
   <span class="tag" id="version">v0</span>
   <button id="btn3d" title="extruded 3D view (key: 3)">3D</button>
   <button id="btnfit" title="fit to view (key: F)">fit</button>
@@ -993,7 +993,7 @@ window.addEventListener('keydown', e => {
 (function () {
   const sidebar = document.getElementById('sidebar');
   const rz = document.getElementById('layers-resizer');
-  const KEY = 'cadforge.layersWidth', MIN = 130, MAX = 560, DEF = 200;
+  const KEY = 'cadspec.layersWidth', MIN = 130, MAX = 560, DEF = 200;
   const saved = parseInt(localStorage.getItem(KEY) || '', 10);
   if (saved >= MIN && saved <= MAX) sidebar.style.width = saved + 'px';
   let dragging = false;
@@ -1021,7 +1021,7 @@ window.addEventListener('keydown', e => {
   const sidebar = document.getElementById('sidebar');
   const pane = document.getElementById('planos-pane');
   const div = document.getElementById('pane-divider');
-  const KEY = 'cadforge.planosHeight';
+  const KEY = 'cadspec.planosHeight';
   const saved = parseInt(localStorage.getItem(KEY) || '', 10);
   if (saved >= 48) pane.style.height = saved + 'px';
   let dragging = false;
diff --git a/src/svg.rs b/src/svg.rs
index 003b2ef..a6767d7 100644
--- a/src/svg.rs
+++ b/src/svg.rs
@@ -2,7 +2,7 @@
 //!
 //! Renders real text, dimension lines with measured values, hatch patterns
 //! clipped to their boundary, line styles, and optional highlight markers.
-//! It is the single rendering backend: `cadforge serve` displays the SVG
+//! It is the single rendering backend: `cadspec serve` displays the SVG
 //! directly and the PNG preview rasterizes it.
 
 use crate::compiler::resolve_boundary;
diff --git a/src/viewer.rs b/src/viewer.rs
index 40a1048..1262ecf 100644
--- a/src/viewer.rs
+++ b/src/viewer.rs
@@ -17,7 +17,7 @@ pub fn view_project(project_dir: &Path, layer_filter: Option<&str>) -> Result<()
                 }
             })
             .collect::<String>();
-        std::env::temp_dir().join(format!("cadforge-view-{}.dxf", sanitized))
+        std::env::temp_dir().join(format!("cadspec-view-{}.dxf", sanitized))
     } else {
         project_dir.join("output.dxf")
     };
@@ -29,11 +29,11 @@ pub fn view_project(project_dir: &Path, layer_filter: Option<&str>) -> Result<()
 }
 
 fn open_file(path: &Path) -> Result<()> {
-    if let Ok(custom) = std::env::var("CADFORGE_VIEWER_CMD") {
+    if let Ok(custom) = std::env::var("CADSPEC_VIEWER_CMD") {
         let status = Command::new(&custom)
             .arg(path)
             .status()
-            .with_context(|| format!("Failed to run CADFORGE_VIEWER_CMD='{}'", custom))?;
+            .with_context(|| format!("Failed to run CADSPEC_VIEWER_CMD='{}'", custom))?;
         if !status.success() {
             return Err(anyhow!(
                 "Custom viewer command failed for {} (exit code: {:?})",
diff --git a/tests/integration.rs b/tests/integration.rs
index 9ad1f2f..da3f780 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -1,14 +1,14 @@
 //! Integration tests — full pipeline from .cf files to DXF output.
 
-use cadforge::compiler::compile_project;
-use cadforge::importer::import_dxf;
+use cadspec::compiler::compile_project;
+use cadspec::importer::import_dxf;
 use std::fs;
 use std::path::Path;
 
 #[test]
 fn compile_example_project_produces_valid_dxf() {
     let project_dir = Path::new("examples/vivienda");
-    let output = Path::new("/tmp/cadforge_compile_test_output.dxf");
+    let output = Path::new("/tmp/cadspec_compile_test_output.dxf");
 
     // Remove previous output if exists
     let _ = fs::remove_file(output);
@@ -49,13 +49,13 @@ fn compile_example_project_produces_valid_dxf() {
 
 #[test]
 fn compile_project_fails_on_missing_project_toml() {
-    let result = compile_project(Path::new("/tmp/nonexistent_cadforge_dir"), None, None);
+    let result = compile_project(Path::new("/tmp/nonexistent_cadspec_dir"), None, None);
     assert!(result.is_err());
 }
 
 #[test]
 fn check_project_validates_without_generating_dxf() {
-    use cadforge::compiler::check_project;
+    use cadspec::compiler::check_project;
 
     let project_dir = Path::new("examples/vivienda");
     let output = project_dir.join("check_should_not_exist.dxf");
@@ -110,7 +110,7 @@ to = [8.5, 0.0]
 offset = 0.5
 "##;
 
-    let cf: cadforge::model::CfFile = toml::from_str(toml).unwrap();
+    let cf: cadspec::model::CfFile = toml::from_str(toml).unwrap();
     assert_eq!(cf.lines.len(), 1);
     assert_eq!(cf.polylines.len(), 1);
     assert!(cf.polylines[0].common.weight.is_some());
@@ -141,7 +141,7 @@ to = [10.0, 2.0]
 style = "dashdot"
 "##;
 
-    let cf: cadforge::model::CfFile = toml::from_str(toml).unwrap();
+    let cf: cadspec::model::CfFile = toml::from_str(toml).unwrap();
     assert_eq!(cf.lines.len(), 3);
     assert!(cf.lines[0].common.style.is_some());
 }
@@ -161,15 +161,15 @@ scale = 1.0
 angle = 45.0
 "##;
 
-    let cf: cadforge::model::CfFile = toml::from_str(toml).unwrap();
+    let cf: cadspec::model::CfFile = toml::from_str(toml).unwrap();
     assert_eq!(cf.hatches.len(), 1);
     assert_eq!(cf.hatches[0].boundary, "pl-room");
 
     // Compile it to verify no panic
-    use cadforge::dxf_writer::DxfWriter;
+    use cadspec::dxf_writer::DxfWriter;
     let mut writer = DxfWriter::new();
     writer.add_layer("test", 7);
-    cadforge::compiler::compile_cf_public(&mut writer, &cf, "test");
+    cadspec::compiler::compile_cf_public(&mut writer, &cf, "test");
 }
 
 #[test]
@@ -181,16 +181,16 @@ points = [[0.0, 0.0], [4.0, 0.0], [4.0, 3.0], [0.0, 3.0]]
 color = "#808080"
 "##;
 
-    let cf: cadforge::model::CfFile = toml::from_str(toml).unwrap();
+    let cf: cadspec::model::CfFile = toml::from_str(toml).unwrap();
     assert_eq!(cf.fills.len(), 1);
 
     // Compile and verify it produces a DXF with SOLID entities
-    use cadforge::dxf_writer::DxfWriter;
+    use cadspec::dxf_writer::DxfWriter;
     let mut writer = DxfWriter::new();
     writer.add_layer("test", 7);
-    cadforge::compiler::compile_cf_public(&mut writer, &cf, "test");
+    cadspec::compiler::compile_cf_public(&mut writer, &cf, "test");
 
-    let path = std::path::PathBuf::from("/tmp/cadforge_test_fill.dxf");
+    let path = std::path::PathBuf::from("/tmp/cadspec_test_fill.dxf");
     writer.save(&path).unwrap();
     let content = fs::read_to_string(&path).unwrap();
     assert!(content.contains("SOLID"));
@@ -251,7 +251,7 @@ belongs_to = "room-1"
 
 #[test]
 fn compile_allows_constraint_warnings_when_not_strict() {
-    let dir = Path::new("/tmp/cadforge_constraints_non_strict");
+    let dir = Path::new("/tmp/cadspec_constraints_non_strict");
     let _ = fs::remove_dir_all(dir);
     write_constraints_fixture(dir, false);
 
@@ -269,7 +269,7 @@ fn compile_allows_constraint_warnings_when_not_strict() {
 
 #[test]
 fn compile_fails_on_constraint_violation_when_strict() {
-    let dir = Path::new("/tmp/cadforge_constraints_strict");
+    let dir = Path::new("/tmp/cadspec_constraints_strict");
     let _ = fs::remove_dir_all(dir);
     write_constraints_fixture(dir, true);
 
@@ -284,7 +284,7 @@ fn compile_fails_on_constraint_violation_when_strict() {
 
 #[test]
 fn render_svg_on_example_project() {
-    let svg = cadforge::svg::render_svg(Path::new("examples/vivienda"), None, 1600).unwrap();
+    let svg = cadspec::svg::render_svg(Path::new("examples/vivienda"), None, 1600).unwrap();
     assert!(svg.starts_with("<svg"));
     assert!(svg.ends_with("</svg>"));
     // Layer groups for every project layer
@@ -301,7 +301,7 @@ fn render_svg_on_example_project() {
 
 #[test]
 fn project_report_is_serializable_and_complete() {
-    let report = cadforge::compiler::project_report(Path::new("examples/vivienda")).unwrap();
+    let report = cadspec::compiler::project_report(Path::new("examples/vivienda")).unwrap();
     assert!(report.total_entities > 0);
     assert_eq!(report.layers.len(), 5);
     assert!(report.layers.iter().all(|l| !l.missing));
@@ -316,10 +316,10 @@ fn taller_example_expands_arrays_and_mirrors() {
     let dir = Path::new("examples/taller");
 
     // Expanded entity counts: 16 treads + 16 teeth + mirrored geometry
-    let report = cadforge::compiler::project_report(dir).unwrap();
+    let report = cadspec::compiler::project_report(dir).unwrap();
     assert_eq!(report.total_entities, 49);
 
-    let svg = cadforge::svg::render_svg(dir, None, 1200).unwrap();
+    let svg = cadspec::svg::render_svg(dir, None, 1200).unwrap();
     // 15 generated tread copies with derived ids
     let tread_copies = svg.matches(r#"data-id="pl-huella@"#).count();
     assert_eq!(tread_copies, 15);
@@ -330,7 +330,7 @@ fn taller_example_expands_arrays_and_mirrors() {
     assert!(svg.contains(">2.900<"));
 
     // The DXF compiles with the expanded geometry
-    let out = Path::new("/tmp/cadforge_taller.dxf");
+    let out = Path::new("/tmp/cadspec_taller.dxf");
     let _ = fs::remove_file(out);
     compile_project(dir, None, Some(out)).unwrap();
     assert!(out.exists());
@@ -339,7 +339,7 @@ fn taller_example_expands_arrays_and_mirrors() {
 
 #[test]
 fn preview_renders_faithful_png_with_metadata_and_highlights() {
-    let dir = Path::new("/tmp/cadforge_preview_test");
+    let dir = Path::new("/tmp/cadspec_preview_test");
     let _ = fs::remove_dir_all(dir);
     fs::create_dir_all(dir).unwrap();
     fs::write(
@@ -377,17 +377,17 @@ offset = -0.6
     )
     .unwrap();
 
-    cadforge::preview::generate_preview(
+    cadspec::preview::generate_preview(
         dir,
         800,
         800,
         None,
         &["rc-room".to_string()],
-        cadforge::preview::PreviewOutputs {
+        cadspec::preview::PreviewOutputs {
             png: true,
             svg: true,
         },
-        cadforge::preview::PreviewView::Plan,
+        cadspec::preview::PreviewView::Plan,
     )
     .unwrap();
 
@@ -407,13 +407,13 @@ offset = -0.6
 }
 
 #[test]
-fn import_generated_dxf_creates_cadforge_project() {
+fn import_generated_dxf_creates_cadspec_project() {
     let source = Path::new("examples/vivienda");
     let source_output = source.join("output.dxf");
     let _ = fs::remove_file(&source_output);
     compile_project(source, None, Some(&source_output)).unwrap();
 
-    let imported = Path::new("/tmp/cadforge_import_test");
+    let imported = Path::new("/tmp/cadspec_import_test");
     let _ = fs::remove_dir_all(imported);
     import_dxf(&source_output, imported, None).unwrap();
 
@@ -430,7 +430,7 @@ fn import_generated_dxf_creates_cadforge_project() {
 
 #[test]
 fn import_roundtrip_recovers_dims_styles_and_colors() {
-    let dir = Path::new("/tmp/cadforge_roundtrip_fidelity");
+    let dir = Path::new("/tmp/cadspec_roundtrip_fidelity");
     let _ = fs::remove_dir_all(dir);
     fs::create_dir_all(dir).unwrap();
     fs::write(
@@ -476,7 +476,7 @@ offset = -1.2
     let dxf_path = dir.join("output.dxf");
     compile_project(dir, None, Some(&dxf_path)).unwrap();
 
-    let imported = Path::new("/tmp/cadforge_roundtrip_fidelity_out");
+    let imported = Path::new("/tmp/cadspec_roundtrip_fidelity_out");
     let _ = fs::remove_dir_all(imported);
     import_dxf(&dxf_path, imported, None).unwrap();
     let cf = fs::read_to_string(imported.join("plano.cf")).unwrap();

From 1bb9f36607e2d4034bc0089547dc2e994e47b6b0 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 10:57:58 -0500
Subject: [PATCH 07/39] feat: export the 3D scene to glTF via preview --format
 gltf, reusing the same mesh builders as the 3D view

---
 src/gltf.rs     | 224 ++++++++++++++++++++++++++++++++++++++++++++++++
 src/lib.rs      |   1 +
 src/main.rs     |  48 ++++++-----
 src/preview.rs  |  23 +++++
 src/render3d.rs | 107 ++++++++++++++++++++---
 5 files changed, 373 insertions(+), 30 deletions(-)
 create mode 100644 src/gltf.rs

diff --git a/src/gltf.rs b/src/gltf.rs
new file mode 100644
index 0000000..7d365cf
--- /dev/null
+++ b/src/gltf.rs
@@ -0,0 +1,224 @@
+//! Minimal glTF 2.0 exporter.
+//!
+//! Turns the scene's solid meshes (from [`crate::render3d::scene_meshes`]) into a
+//! single self-contained `.gltf`: JSON with the binary buffer base64-embedded as
+//! a data URI. Pure Rust, deterministic, no extra dependencies.
+//!
+//! cadspec is Z-up (height is +Z); glTF is Y-up and right-handed, so every
+//! position and normal is remapped `(x, y, z) → (x, z, -y)` (a proper rotation).
+//! Triangles are flat-shaded (a per-face normal on each of its three vertices)
+//! and materials are double-sided, since boolean output can have mixed winding.
+
+use crate::mesh::Mesh;
+
+type V3 = [f64; 3];
+
+fn sub(a: V3, b: V3) -> V3 {
+    [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+}
+fn cross(a: V3, b: V3) -> V3 {
+    [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ]
+}
+fn norm(a: V3) -> V3 {
+    let l = (a[0] * a[0] + a[1] * a[1] + a[2] * a[2]).sqrt();
+    if l < 1e-12 {
+        [0.0, 0.0, 1.0]
+    } else {
+        [a[0] / l, a[1] / l, a[2] / l]
+    }
+}
+/// Z-up (cadspec) → Y-up (glTF).
+fn to_gltf(p: V3) -> [f32; 3] {
+    [p[0] as f32, p[2] as f32, -p[1] as f32]
+}
+
+/// Parse `#rgb` / `#rrggbb` into linear-ish `[r, g, b, 1]` floats (0..1).
+fn color_rgba(hex: &str) -> [f32; 4] {
+    let h = hex.trim().trim_start_matches('#');
+    let parse = |s: &str| u8::from_str_radix(s, 16).unwrap_or(160) as f32 / 255.0;
+    match h.len() {
+        3 => {
+            let r = parse(&h[0..1].repeat(2));
+            let g = parse(&h[1..2].repeat(2));
+            let b = parse(&h[2..3].repeat(2));
+            [r, g, b, 1.0]
+        }
+        6 => [parse(&h[0..2]), parse(&h[2..4]), parse(&h[4..6]), 1.0],
+        _ => [0.63, 0.63, 0.63, 1.0],
+    }
+}
+
+const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+fn base64(data: &[u8]) -> String {
+    let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
+    for chunk in data.chunks(3) {
+        let b = [
+            chunk[0],
+            *chunk.get(1).unwrap_or(&0),
+            *chunk.get(2).unwrap_or(&0),
+        ];
+        let n = ((b[0] as u32) << 16) | ((b[1] as u32) << 8) | (b[2] as u32);
+        out.push(B64[((n >> 18) & 63) as usize] as char);
+        out.push(B64[((n >> 12) & 63) as usize] as char);
+        out.push(if chunk.len() > 1 {
+            B64[((n >> 6) & 63) as usize] as char
+        } else {
+            '='
+        });
+        out.push(if chunk.len() > 2 {
+            B64[(n & 63) as usize] as char
+        } else {
+            '='
+        });
+    }
+    out
+}
+
+/// Serialize the scene meshes to a self-contained glTF 2.0 document.
+pub fn scene_to_gltf(meshes: &[(Mesh, String)]) -> String {
+    // Binary buffer: per mesh, all vertex positions then all normals (FLOAT VEC3).
+    let mut buf: Vec<u8> = Vec::new();
+    // Per-mesh accessor metadata gathered while writing the buffer.
+    struct Acc {
+        pos_off: usize,
+        nrm_off: usize,
+        count: usize,
+        min: [f32; 3],
+        max: [f32; 3],
+        color: [f32; 4],
+    }
+    let mut accs: Vec<Acc> = Vec::new();
+
+    for (mesh, color) in meshes {
+        if mesh.tris.is_empty() {
+            continue;
+        }
+        let pos_off = buf.len();
+        let mut min = [f32::MAX; 3];
+        let mut max = [f32::MIN; 3];
+        // Positions.
+        for t in &mesh.tris {
+            for v in t {
+                let p = to_gltf(*v);
+                for k in 0..3 {
+                    min[k] = min[k].min(p[k]);
+                    max[k] = max[k].max(p[k]);
+                    buf.extend_from_slice(&p[k].to_le_bytes());
+                }
+            }
+        }
+        let nrm_off = buf.len();
+        // Flat normals (same for the three vertices of a triangle).
+        for t in &mesh.tris {
+            let n = norm(cross(sub(t[1], t[0]), sub(t[2], t[0])));
+            let ng = to_gltf(n);
+            for _ in 0..3 {
+                for c in ng {
+                    buf.extend_from_slice(&c.to_le_bytes());
+                }
+            }
+        }
+        accs.push(Acc {
+            pos_off,
+            nrm_off,
+            count: mesh.tris.len() * 3,
+            min,
+            max,
+            color: color_rgba(color),
+        });
+    }
+
+    // Assemble the JSON.
+    let mut buffer_views = String::new();
+    let mut accessors = String::new();
+    let mut materials = String::new();
+    let mut gltf_meshes = String::new();
+    let mut nodes = String::new();
+    let mut node_idx = String::new();
+
+    for (i, a) in accs.iter().enumerate() {
+        let bv_pos = i * 2;
+        let bv_nrm = i * 2 + 1;
+        let acc_pos = i * 2;
+        let acc_nrm = i * 2 + 1;
+        let bytes = a.count * 12;
+        if i > 0 {
+            buffer_views.push(',');
+            accessors.push(',');
+            materials.push(',');
+            gltf_meshes.push(',');
+            nodes.push(',');
+            node_idx.push(',');
+        }
+        buffer_views.push_str(&format!(
+            r#"{{"buffer":0,"byteOffset":{},"byteLength":{}}},{{"buffer":0,"byteOffset":{},"byteLength":{}}}"#,
+            a.pos_off, bytes, a.nrm_off, bytes
+        ));
+        accessors.push_str(&format!(
+            r#"{{"bufferView":{bv_pos},"componentType":5126,"count":{c},"type":"VEC3","min":[{mn0},{mn1},{mn2}],"max":[{mx0},{mx1},{mx2}]}},{{"bufferView":{bv_nrm},"componentType":5126,"count":{c},"type":"VEC3"}}"#,
+            c = a.count,
+            mn0 = a.min[0], mn1 = a.min[1], mn2 = a.min[2],
+            mx0 = a.max[0], mx1 = a.max[1], mx2 = a.max[2],
+        ));
+        materials.push_str(&format!(
+            r#"{{"pbrMetallicRoughness":{{"baseColorFactor":[{r},{g},{b},{al}],"metallicFactor":0.0,"roughnessFactor":0.85}},"doubleSided":true}}"#,
+            r = a.color[0], g = a.color[1], b = a.color[2], al = a.color[3],
+        ));
+        gltf_meshes.push_str(&format!(
+            r#"{{"primitives":[{{"attributes":{{"POSITION":{acc_pos},"NORMAL":{acc_nrm}}},"material":{i}}}]}}"#,
+        ));
+        nodes.push_str(&format!(r#"{{"mesh":{i}}}"#));
+        node_idx.push_str(&i.to_string());
+    }
+
+    let b64 = base64(&buf);
+    format!(
+        r#"{{"asset":{{"version":"2.0","generator":"cadspec"}},"scene":0,"scenes":[{{"nodes":[{node_idx}]}}],"nodes":[{nodes}],"meshes":[{gltf_meshes}],"materials":[{materials}],"accessors":[{accessors}],"bufferViews":[{buffer_views}],"buffers":[{{"byteLength":{len},"uri":"data:application/octet-stream;base64,{b64}"}}]}}"#,
+        len = buf.len(),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn base64_known_vectors() {
+        assert_eq!(base64(b"Man"), "TWFu");
+        assert_eq!(base64(b"Ma"), "TWE=");
+        assert_eq!(base64(b"M"), "TQ==");
+    }
+
+    #[test]
+    fn color_parses_hex() {
+        assert_eq!(color_rgba("#ff0000"), [1.0, 0.0, 0.0, 1.0]);
+        assert_eq!(color_rgba("#000"), [0.0, 0.0, 0.0, 1.0]);
+    }
+
+    #[test]
+    fn single_triangle_exports_valid_gltf() {
+        let mesh = Mesh {
+            tris: vec![[[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]]],
+        };
+        let doc = scene_to_gltf(&[(mesh, "#6ec6e6".to_string())]);
+        // One triangle = 3 vertices; positions + normals = 3 * 2 * 12 = 72 bytes.
+        assert!(doc.contains(r#""byteLength":72"#));
+        assert!(doc.contains(r#""version":"2.0""#));
+        assert!(doc.contains(r#""count":3"#));
+        assert!(doc.contains(r#""POSITION""#) && doc.contains(r#""NORMAL""#));
+        // Z-up→Y-up: cad y=1 becomes gltf z=-1, so the POSITION min z is -1.
+        assert!(doc.contains(r#""min":[0,0,-1]"#));
+    }
+
+    #[test]
+    fn empty_scene_is_still_valid_json() {
+        let doc = scene_to_gltf(&[]);
+        assert!(doc.contains(r#""byteLength":0"#));
+        assert!(doc.contains(r#""meshes":[]"#));
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index b902819..348194f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -7,6 +7,7 @@ pub mod compiler;
 pub mod config;
 pub mod dxf_writer;
 pub mod fmt;
+pub mod gltf;
 pub mod importer;
 pub mod mesh;
 pub mod model;
diff --git a/src/main.rs b/src/main.rs
index 0de9eaa..438302b 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3,7 +3,9 @@ use cadspec::compiler::{check_project, compile_project, list_layers, project_rep
 use cadspec::config::{config_set, config_show};
 use cadspec::fmt::format_project;
 use cadspec::importer::import_dxf;
-use cadspec::preview::{generate_plano, generate_preview, PreviewOutputs, PreviewView};
+use cadspec::preview::{
+    generate_gltf, generate_plano, generate_preview, PreviewOutputs, PreviewView,
+};
 use cadspec::scaffold::{create_project, init_project};
 use cadspec::schema::print_schema;
 use cadspec::serve::{serve_daemon, serve_project, serve_stop};
@@ -163,6 +165,8 @@ enum PreviewFormat {
     Svg,
     /// Both PNG and SVG
     All,
+    /// Self-contained glTF of the 3D solids (`scene.gltf`)
+    Gltf,
 }
 
 #[derive(Subcommand)]
@@ -236,27 +240,31 @@ fn main() -> Result<()> {
             plano,
         } => {
             let dir = resolve_project_dir(path)?;
-            let outputs = PreviewOutputs {
-                png: matches!(format, PreviewFormat::Png | PreviewFormat::All),
-                svg: matches!(format, PreviewFormat::Svg | PreviewFormat::All),
-            };
-            if let Some(name) = plano {
-                generate_plano(&dir, &name, width, height, outputs)
+            if matches!(format, PreviewFormat::Gltf) {
+                generate_gltf(&dir, layer.as_deref())
             } else {
-                let view = if three_d {
-                    PreviewView::ThreeD
-                } else {
-                    PreviewView::Plan
+                let outputs = PreviewOutputs {
+                    png: matches!(format, PreviewFormat::Png | PreviewFormat::All),
+                    svg: matches!(format, PreviewFormat::Svg | PreviewFormat::All),
                 };
-                generate_preview(
-                    &dir,
-                    width,
-                    height,
-                    layer.as_deref(),
-                    &highlight,
-                    outputs,
-                    view,
-                )
+                if let Some(name) = plano {
+                    generate_plano(&dir, &name, width, height, outputs)
+                } else {
+                    let view = if three_d {
+                        PreviewView::ThreeD
+                    } else {
+                        PreviewView::Plan
+                    };
+                    generate_preview(
+                        &dir,
+                        width,
+                        height,
+                        layer.as_deref(),
+                        &highlight,
+                        outputs,
+                        view,
+                    )
+                }
             }
         }
         Commands::Serve {
diff --git a/src/preview.rs b/src/preview.rs
index 57ab2c2..33720dc 100644
--- a/src/preview.rs
+++ b/src/preview.rs
@@ -188,6 +188,29 @@ fn generate_preview_3d(
     Ok(())
 }
 
+/// Export the scene's 3D solids to a self-contained glTF (`scene.gltf`) — the
+/// same meshes the 3D view renders, for an interactive viewer or interchange.
+pub fn generate_gltf(project_dir: &Path, layer_filter: Option<&str>) -> Result<()> {
+    let (_project, layers) = load_project_layers(project_dir, layer_filter)?;
+    let meshes = crate::render3d::scene_meshes(&layers);
+    if meshes.is_empty() {
+        anyhow::bail!(
+            "no 3D geometry to export — declare [[solid]]/[[boolean]] or set `extrude` on a primitive"
+        );
+    }
+    let tris: usize = meshes.iter().map(|(m, _)| m.tris.len()).sum();
+    let doc = crate::gltf::scene_to_gltf(&meshes);
+    let out = project_dir.join("scene.gltf");
+    std::fs::write(&out, &doc).with_context(|| format!("Cannot write {}", out.display()))?;
+    println!(
+        "✓ glTF: {} ({} meshes, {} triangles)",
+        out.display(),
+        meshes.len(),
+        tris
+    );
+    Ok(())
+}
+
 /// Render a named plano (drawing sheet) to `preview.png` (and/or `preview.svg`).
 pub fn generate_plano(
     project_dir: &Path,
diff --git a/src/render3d.rs b/src/render3d.rs
index 57d5a13..9d017d4 100644
--- a/src/render3d.rs
+++ b/src/render3d.rs
@@ -255,16 +255,10 @@ struct Footprint<'a> {
     common: &'a CommonAttrs,
 }
 
-fn collect_layer_faces(
-    faces: &mut Vec<Face>,
-    layer_name: &str,
-    cf: &CfFile,
-    layer_color: &str,
-    cam: &Camera,
-    cut: Option<&Cut>,
-) {
+/// Every primitive's 2D footprint in a layer (rects, polylines, lines, circles,
+/// arcs) — the input to extrusion and outlining.
+fn footprints(cf: &CfFile) -> Vec<Footprint<'_>> {
     let mut prints: Vec<Footprint> = Vec::new();
-
     for e in &cf.rects {
         let [ox, oy] = e.origin;
         prints.push(Footprint {
@@ -309,8 +303,101 @@ fn collect_layer_faces(
             common: &e.common,
         });
     }
+    prints
+}
 
-    for fp in prints {
+/// World-space solid meshes for the whole scene — extruded footprints plus
+/// resolved solids/booleans, each with its display colour. This is the same
+/// geometry the 3D view renders (same builders), but unprojected and unsectioned,
+/// so it can be exported to a mesh format like glTF.
+pub fn scene_meshes(layers: &[(String, CfFile)]) -> Vec<(mesh::Mesh, String)> {
+    use std::collections::{HashMap, HashSet};
+    let mut out: Vec<(mesh::Mesh, String)> = Vec::new();
+
+    for (idx, (_name, cf)) in layers.iter().enumerate() {
+        let visible = cf.layer_meta.as_ref().map(|m| m.visible).unwrap_or(true);
+        if !visible {
+            continue;
+        }
+        let layer_color = layer_display_color(cf, idx);
+
+        // Extruded footprints → prism/wall meshes.
+        for fp in footprints(cf) {
+            if fp.points.len() < 2 {
+                continue;
+            }
+            let h = fp.common.extrude.unwrap_or(0.0);
+            if h <= 0.0 {
+                continue;
+            }
+            let base = fp.common.elevation.unwrap_or(0.0);
+            let color = fp
+                .common
+                .color
+                .clone()
+                .unwrap_or_else(|| layer_color.clone());
+            out.push((mesh::prism(&fp.points, base, h, fp.closed), color));
+        }
+
+        // Solids + booleans (mirrors collect_solid_faces, without projection).
+        let mut meshes: HashMap<&str, mesh::Mesh> = HashMap::new();
+        let mut colors: HashMap<&str, String> = HashMap::new();
+        for s in &cf.solids {
+            meshes.insert(s.id.as_str(), build_solid(s));
+            colors.insert(
+                s.id.as_str(),
+                s.color.clone().unwrap_or_else(|| layer_color.clone()),
+            );
+        }
+        let mut consumed: HashSet<&str> = HashSet::new();
+        for b in &cf.booleans {
+            consumed.insert(b.base.as_str());
+            for t in &b.tools {
+                consumed.insert(t.as_str());
+            }
+        }
+        for b in &cf.booleans {
+            let Some(base) = meshes.get(b.base.as_str()) else {
+                continue;
+            };
+            let mut acc = base.clone();
+            for t in &b.tools {
+                if let Some(tool) = meshes.get(t.as_str()) {
+                    acc = match b.op.as_str() {
+                        "union" => acc.union(tool),
+                        "intersection" => acc.intersection(tool),
+                        _ => acc.difference(tool),
+                    };
+                }
+            }
+            let color = b
+                .color
+                .clone()
+                .or_else(|| colors.get(b.base.as_str()).cloned())
+                .unwrap_or_else(|| layer_color.clone());
+            out.push((acc, color));
+        }
+        for s in &cf.solids {
+            if consumed.contains(s.id.as_str()) {
+                continue;
+            }
+            if let (Some(m), Some(c)) = (meshes.get(s.id.as_str()), colors.get(s.id.as_str())) {
+                out.push((m.clone(), c.clone()));
+            }
+        }
+    }
+    out
+}
+
+fn collect_layer_faces(
+    faces: &mut Vec<Face>,
+    layer_name: &str,
+    cf: &CfFile,
+    layer_color: &str,
+    cam: &Camera,
+    cut: Option<&Cut>,
+) {
+    for fp in footprints(cf) {
         if fp.points.len() < 2 {
             continue;
         }

From 911d7cf516639c714e2b589de579a4f6f74c7992 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 10:58:38 -0500
Subject: [PATCH 08/39] docs: document the 3D view and glTF export in the CLI
 reference

---
 docs/cli-reference.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 325010c..61e387a 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -30,6 +30,8 @@ cadspec <command> [options]
 | `cadspec serve --open --port <p>` | Open browser automatically on a custom port |
 | `cadspec preview` | Faithful PNG render + `preview.meta.json` |
 | `cadspec preview --format svg` | Vector SVG preview (same renderer) |
+| `cadspec preview --3d` | Axonometric 3D view (extrusions + solids) |
+| `cadspec preview --format gltf` | Export the 3D solids to `scene.gltf` (interactive 3D / interchange) |
 | `cadspec preview --highlight <ids>` | Amber markers around specific entities |
 | `cadspec preview --width <w> -H <h>` | Custom resolution |
 | `cadspec preview --layer <name>` | Preview a specific layer only |
@@ -63,4 +65,5 @@ cadspec <command> [options]
 |------|-------------|
 | `output.dxf` | Default build output |
 | `preview.png` / `preview.svg` | Preview renders |
+| `scene.gltf` | 3D scene export (glTF 2.0, self-contained) |
 | `preview.meta.json` | Per-entity bounding boxes (world + pixel coordinates) |

From 3c39c754196cb29e8005a38e8e4e5a87372fb888 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 11:33:33 -0500
Subject: [PATCH 09/39] feat(serve): add editor endpoints to list, read and
 save .cf files (save recompiles and live-reloads)

---
 src/serve.rs | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/src/serve.rs b/src/serve.rs
index 8ba64ce..268e4f4 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -437,11 +437,97 @@ fn handle_connection(stream: TcpStream, state: &Shared) -> std::io::Result<()> {
             let body = entity_block_json(&state.project_dir, &id);
             respond(stream, "200 OK", "application/json", body.as_bytes())
         }
+        // ── Built-in .cf editor ────────────────────────────────────────────
+        "/files" => {
+            let mut names: Vec<String> = std::fs::read_dir(&state.project_dir)
+                .map(|rd| {
+                    rd.filter_map(|e| e.ok())
+                        .map(|e| e.file_name().to_string_lossy().into_owned())
+                        .filter(|n| n.ends_with(".cf"))
+                        .collect()
+                })
+                .unwrap_or_default();
+            names.sort();
+            let body = serde_json::json!({ "files": names }).to_string();
+            respond(stream, "200 OK", "application/json", body.as_bytes())
+        }
+        "/file" => {
+            let name = query_param(query, "name").unwrap_or_default();
+            match safe_cf_name(&name) {
+                Some(n) => match std::fs::read_to_string(state.project_dir.join(&n)) {
+                    Ok(s) => respond(stream, "200 OK", "text/plain; charset=utf-8", s.as_bytes()),
+                    Err(_) => respond(stream, "404 Not Found", "text/plain", b"not found"),
+                },
+                None => respond(stream, "400 Bad Request", "text/plain", b"bad name"),
+            }
+        }
+        "/save" => {
+            let name = query_param(query, "name").unwrap_or_default();
+            let body = read_request_body(&mut reader);
+            match safe_cf_name(&name) {
+                Some(n) => match std::fs::write(state.project_dir.join(&n), &body) {
+                    Ok(()) => {
+                        rebuild(&state.project_dir, state);
+                        let st = state.state.lock().unwrap();
+                        let resp = serde_json::json!({
+                            "ok": st.error.is_none(),
+                            "version": st.version,
+                            "error": st.error,
+                        })
+                        .to_string();
+                        drop(st);
+                        respond(stream, "200 OK", "application/json", resp.as_bytes())
+                    }
+                    Err(e) => respond(
+                        stream,
+                        "500 Internal Server Error",
+                        "text/plain",
+                        format!("write error: {e}").as_bytes(),
+                    ),
+                },
+                None => respond(stream, "400 Bad Request", "text/plain", b"bad name"),
+            }
+        }
         "/events" => serve_events(stream, state),
         _ => respond(stream, "404 Not Found", "text/plain", b"not found"),
     }
 }
 
+/// Accept only a bare `*.cf` filename (no path traversal) for the editor.
+fn safe_cf_name(name: &str) -> Option<String> {
+    if name.is_empty()
+        || name.contains('/')
+        || name.contains('\\')
+        || name.contains("..")
+        || !name.ends_with(".cf")
+    {
+        return None;
+    }
+    Some(name.to_string())
+}
+
+/// Read the remaining request headers, then the body of `Content-Length` bytes.
+fn read_request_body(reader: &mut BufReader<TcpStream>) -> Vec<u8> {
+    let mut len = 0usize;
+    let mut line = String::new();
+    loop {
+        line.clear();
+        if reader.read_line(&mut line).unwrap_or(0) == 0 {
+            break;
+        }
+        let t = line.trim_end();
+        if t.is_empty() {
+            break;
+        }
+        if let Some(v) = t.to_ascii_lowercase().strip_prefix("content-length:") {
+            len = v.trim().parse().unwrap_or(0);
+        }
+    }
+    let mut body = vec![0u8; len];
+    let _ = std::io::Read::read_exact(reader, &mut body);
+    body
+}
+
 fn query_param(query: &str, key: &str) -> Option<String> {
     query.split('&').find_map(|pair| {
         let (k, v) = pair.split_once('=')?;

From e8c188aeeb97ba49bcf5bf6311b2d3eb9721a74d Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 11:44:52 -0500
Subject: [PATCH 10/39] feat(serve): style the live viewer like the landing
 with a system-following light/dark theme and a built-in .cf editor

---
 src/serve.rs | 238 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 206 insertions(+), 32 deletions(-)

diff --git a/src/serve.rs b/src/serve.rs
index 268e4f4..bef8b0a 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -733,42 +733,97 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
 <head>
 <meta charset="utf-8">
 <title>{{PROJECT_NAME}} — cadspec live</title>
+<script>
+  // Theme: follow the OS unless the user toggled an explicit choice. Pre-paint
+  // so there is no flash.
+  (function () {
+    try {
+      var t = localStorage.getItem('cadspec-theme');
+      if (t === 'light' || t === 'dark') document.documentElement.dataset.theme = t;
+    } catch (e) {}
+  })();
+</script>
 <style>
+  @import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&display=swap');
+  /* Dark is the default (the lab). System light, or the toggle, flips to the
+     plan-white. `[data-theme]` (set by the toggle) overrides the system. */
+  :root {
+    --bg: #0d0e11; --panel: #14161a; --panel-2: #181b20;
+    --ink: #d6dadf; --ink-strong: #ffffff; --ink-dim: #aab0b8;
+    --ink-mute: #7c828b; --ink-faint: #565b63;
+    --line: #23262c; --line-2: #2e323a;
+    --accent: #6ec6e6; --accent-soft: rgba(110,198,230,0.16);
+    --ok: #5dd39e; --err: #e0746e; --err-soft: #2a1212; --err-ink: #ff9f9a;
+    --code-bg: #0a0b0d; --code-ink: #cdd6df;
+  }
+  :root[data-theme="light"], :root[data-theme="light"] :root {
+    --bg: #f6f8fa; --panel: #ffffff; --panel-2: #eef2f5;
+    --ink: #1b2630; --ink-strong: #0a1218; --ink-dim: #41505b;
+    --ink-mute: #6b7882; --ink-faint: #97a2ab;
+    --line: #dde5ea; --line-2: #cdd7de;
+    --accent: #156c80; --accent-soft: rgba(21,108,128,0.12);
+    --ok: #1f8f5a; --err: #b23b34; --err-soft: #fbeae9; --err-ink: #9a3027;
+    --code-bg: #f0f3f5; --code-ink: #1b2630;
+  }
+  @media (prefers-color-scheme: light) {
+    :root:not([data-theme]) {
+      --bg: #f6f8fa; --panel: #ffffff; --panel-2: #eef2f5;
+      --ink: #1b2630; --ink-strong: #0a1218; --ink-dim: #41505b;
+      --ink-mute: #6b7882; --ink-faint: #97a2ab;
+      --line: #dde5ea; --line-2: #cdd7de;
+      --accent: #156c80; --accent-soft: rgba(21,108,128,0.12);
+      --ok: #1f8f5a; --err: #b23b34; --err-soft: #fbeae9; --err-ink: #9a3027;
+      --code-bg: #f0f3f5; --code-ink: #1b2630;
+    }
+  }
   * { margin: 0; padding: 0; box-sizing: border-box; }
-  body { background: #0d0d0d; color: #ddd; font-family: ui-monospace, 'Cascadia Code', 'Fira Code', monospace; height: 100vh; display: flex; flex-direction: column; overflow: hidden; }
-  header { display: flex; align-items: center; gap: 12px; padding: 9px 14px; background: #161616; border-bottom: 1px solid #2a2a2a; user-select: none; }
-  #dot { width: 10px; height: 10px; border-radius: 50%; background: #27ae60; flex: none; transition: background .2s; }
-  #dot.err { background: #e74c3c; }
-  #title { font-weight: 600; color: #fff; white-space: nowrap; }
-  .tag { font-size: 11px; color: #777; border: 1px solid #333; border-radius: 4px; padding: 2px 7px; white-space: nowrap; }
-  button { background: #1e1e1e; color: #bbb; border: 1px solid #383838; border-radius: 4px; padding: 3px 10px; font: inherit; font-size: 11px; cursor: pointer; }
-  button:hover { color: #fff; border-color: #555; }
-  button.active { color: #FFB300; border-color: #FFB300; }
-  #hint { margin-left: auto; font-size: 11px; color: #666; }
+  body { background: var(--bg); color: var(--ink); font-family: 'IBM Plex Mono', ui-monospace, 'Cascadia Code', monospace; height: 100vh; display: flex; flex-direction: column; overflow: hidden; }
+  header { display: flex; align-items: center; gap: 12px; padding: 9px 14px; background: var(--panel-2); border-bottom: 1px solid var(--line-2); user-select: none; }
+  #dot { width: 10px; height: 10px; border-radius: 50%; background: var(--ok); flex: none; transition: background .2s; }
+  #dot.err { background: var(--err); }
+  #title { font-weight: 600; color: var(--ink-strong); white-space: nowrap; }
+  .tag { font-size: 11px; color: var(--ink-mute); border: 1px solid var(--line-2); border-radius: 4px; padding: 2px 7px; white-space: nowrap; }
+  button { background: var(--panel); color: var(--ink-dim); border: 1px solid var(--line-2); border-radius: 4px; padding: 3px 10px; font: inherit; font-size: 11px; cursor: pointer; }
+  button:hover { color: var(--ink-strong); border-color: var(--ink-faint); }
+  button.active { color: var(--accent); border-color: var(--accent); }
+  #hint { margin-left: auto; font-size: 11px; color: var(--ink-faint); }
   main { flex: 1; display: flex; overflow: hidden; }
+  /* built-in .cf editor */
+  #editor { width: 340px; min-width: 200px; max-width: 720px; flex: none; background: var(--panel); border-right: 1px solid var(--line); display: flex; flex-direction: column; overflow: hidden; }
+  #editor.hidden { display: none; }
+  .ed-head { display: flex; gap: 6px; padding: 7px 8px; border-bottom: 1px solid var(--line); }
+  #ed-file { flex: 1; min-width: 0; background: var(--panel-2); color: var(--ink); border: 1px solid var(--line-2); border-radius: 4px; font: inherit; font-size: 11px; padding: 3px 6px; }
+  #ed-text { flex: 1; resize: none; background: var(--code-bg); color: var(--code-ink); border: 0; padding: 10px 12px; font: inherit; font-size: 12px; line-height: 1.55; tab-size: 2; outline: none; white-space: pre; overflow: auto; }
+  #ed-status { padding: 5px 10px; font-size: 10px; color: var(--ink-faint); border-top: 1px solid var(--line); white-space: nowrap; overflow: hidden; }
+  #ed-status.ok { color: var(--ok); }
+  #ed-status.err { color: var(--err); }
+  #ed-status.dirty { color: var(--accent); }
+  #editor-resizer { width: 6px; flex: none; cursor: col-resize; background: transparent; transition: background .15s; }
+  #editor-resizer.hidden { display: none; }
+  #editor-resizer:hover, #editor-resizer.dragging { background: var(--accent); }
   /* left sidebar: two stacked panes (Layers over Planos), IntelliJ-style */
-  #sidebar { width: 200px; min-width: 130px; max-width: 560px; flex: none; background: #121212; border-right: 1px solid #222; display: flex; flex-direction: column; overflow: hidden; user-select: none; }
+  #sidebar { width: 200px; min-width: 130px; max-width: 560px; flex: none; background: var(--panel); border-right: 1px solid var(--line); display: flex; flex-direction: column; overflow: hidden; user-select: none; }
   #layers-pane { flex: 1 1 auto; overflow-y: auto; padding: 8px; min-height: 48px; }
   #planos-pane { flex: none; height: 40%; overflow-y: auto; padding: 8px; min-height: 48px; }
   /* horizontal divider between the two panes */
-  #pane-divider { height: 6px; flex: none; cursor: row-resize; background: #161616; border-top: 1px solid #222; border-bottom: 1px solid #222; transition: background .15s; }
-  #pane-divider:hover, #pane-divider.dragging { background: #FFB300; }
+  #pane-divider { height: 6px; flex: none; cursor: row-resize; background: var(--panel-2); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); transition: background .15s; }
+  #pane-divider:hover, #pane-divider.dragging { background: var(--accent); }
   /* drag handle to resize the whole sidebar width */
   #layers-resizer { width: 6px; flex: none; cursor: col-resize; background: transparent; transition: background .15s; }
-  #layers-resizer:hover, #layers-resizer.dragging { background: #FFB300; }
-  #sidebar h3 { font-size: 10px; color: #666; text-transform: uppercase; letter-spacing: 1px; margin: 2px 0 8px 4px; }
+  #layers-resizer:hover, #layers-resizer.dragging { background: var(--accent); }
+  #sidebar h3 { font-size: 10px; color: var(--ink-faint); text-transform: uppercase; letter-spacing: 1px; margin: 2px 0 8px 4px; }
   .layer-row { display: flex; align-items: center; gap: 7px; padding: 5px 6px; border-radius: 4px; cursor: pointer; font-size: 12px; }
-  .layer-row:hover, .plano-row:hover { background: #1c1c1c; }
+  .layer-row:hover, .plano-row:hover { background: var(--panel-2); }
   .layer-dot { width: 9px; height: 9px; border-radius: 50%; flex: none; }
-  .layer-row .st { margin-left: auto; font-size: 10px; color: #666; }
-  .layer-row.ghost { color: #777; }
-  .layer-row.off { color: #4a4a4a; }
+  .layer-row .st { margin-left: auto; font-size: 10px; color: var(--ink-faint); }
+  .layer-row.ghost { color: var(--ink-mute); }
+  .layer-row.off { color: var(--ink-faint); }
   .plano-row { display: flex; align-items: baseline; gap: 7px; padding: 5px 6px; border-radius: 4px; cursor: pointer; font-size: 12px; }
-  .plano-row .pv { margin-left: auto; font-size: 9px; color: #666; text-transform: uppercase; }
-  .plano-row.active { background: #2a2410; color: #FFB300; }
-  #planos-pane .empty { font-size: 11px; color: #555; padding: 4px 6px; line-height: 1.5; }
+  .plano-row .pv { margin-left: auto; font-size: 9px; color: var(--ink-faint); text-transform: uppercase; }
+  .plano-row.active { background: var(--accent-soft); color: var(--accent); }
+  #planos-pane .empty { font-size: 11px; color: var(--ink-faint); padding: 4px 6px; line-height: 1.5; }
   /* viewport */
-  #viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; perspective: 2200px; background: #0d0d0d; }
+  #viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; perspective: 2200px; background: var(--bg); }
   #viewport.panning { cursor: grabbing; }
   #canvas { position: absolute; transform-origin: 0 0; will-change: transform; transform-style: preserve-3d; }
   #canvas svg { display: block; }
@@ -776,20 +831,20 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   /* entity interaction */
   #canvas [data-id] { cursor: pointer; }
   #canvas [data-id]:hover { filter: brightness(1.8); }
-  #canvas .sel { filter: drop-shadow(0 0 5px #FFB300) brightness(1.6); }
+  #canvas .sel { filter: drop-shadow(0 0 5px var(--accent)) brightness(1.6); }
   /* inspector */
-  #inspector { width: 300px; flex: none; background: #121212; border-left: 1px solid #222; padding: 12px; overflow-y: auto; display: none; }
+  #inspector { width: 300px; flex: none; background: var(--panel); border-left: 1px solid var(--line); padding: 12px; overflow-y: auto; display: none; }
   #inspector.show { display: block; }
-  #inspector h2 { font-size: 13px; color: #FFB300; word-break: break-all; }
-  #inspector .meta { font-size: 11px; color: #888; margin: 6px 0 10px; line-height: 1.6; }
-  #inspector pre { background: #0a0a0a; border: 1px solid #262626; border-radius: 5px; padding: 9px; font-size: 11px; line-height: 1.45; white-space: pre-wrap; word-break: break-all; color: #c8e0c8; }
+  #inspector h2 { font-size: 13px; color: var(--accent); word-break: break-all; }
+  #inspector .meta { font-size: 11px; color: var(--ink-mute); margin: 6px 0 10px; line-height: 1.6; }
+  #inspector pre { background: var(--code-bg); border: 1px solid var(--line-2); border-radius: 5px; padding: 9px; font-size: 11px; line-height: 1.45; white-space: pre-wrap; word-break: break-all; color: var(--code-ink); }
   #inspector .btns { display: flex; gap: 6px; margin-top: 10px; flex-wrap: wrap; }
-  #inspector .note { font-size: 10px; color: #8a6d1a; margin-top: 8px; }
-  #error { display: none; position: absolute; left: 16px; right: 16px; bottom: 16px; background: #2a1212; border: 1px solid #e74c3c; border-radius: 6px; padding: 12px 16px; color: #ff9f9a; font-size: 13px; white-space: pre-wrap; max-height: 40%; overflow: auto; z-index: 10; }
+  #inspector .note { font-size: 10px; color: var(--ink-faint); margin-top: 8px; }
+  #error { display: none; position: absolute; left: 16px; right: 16px; bottom: 16px; background: var(--err-soft); border: 1px solid var(--err); border-radius: 6px; padding: 12px 16px; color: var(--err-ink); font-size: 13px; white-space: pre-wrap; max-height: 40%; overflow: auto; z-index: 10; }
   #error.show { display: block; }
-  #toast { position: fixed; bottom: 44px; left: 50%; transform: translateX(-50%); background: #1e1e1e; border: 1px solid #FFB300; color: #FFB300; font-size: 11px; padding: 5px 14px; border-radius: 4px; opacity: 0; transition: opacity .2s; pointer-events: none; z-index: 20; }
+  #toast { position: fixed; bottom: 44px; left: 50%; transform: translateX(-50%); background: var(--panel-2); border: 1px solid var(--accent); color: var(--accent); font-size: 11px; padding: 5px 14px; border-radius: 4px; opacity: 0; transition: opacity .2s; pointer-events: none; z-index: 20; }
   #toast.show { opacity: 1; }
-  footer { padding: 5px 14px; background: #121212; border-top: 1px solid #222; font-size: 11px; color: #555; user-select: none; }
+  footer { padding: 5px 14px; background: var(--panel); border-top: 1px solid var(--line); font-size: 11px; color: var(--ink-faint); user-select: none; }
 </style>
 </head>
 <body>
@@ -800,9 +855,20 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   <span class="tag" id="version">v0</span>
   <button id="btn3d" title="extruded 3D view (key: 3)">3D</button>
   <button id="btnfit" title="fit to view (key: F)">fit</button>
+  <button id="btneditor" class="active" title="toggle editor (key: E)">editor</button>
+  <button id="btntheme" title="theme — follow system / light / dark">◐</button>
   <span id="hint">edit .cf files — preview updates automatically</span>
 </header>
 <main>
+  <aside id="editor">
+    <div class="ed-head">
+      <select id="ed-file" title="project .cf files"></select>
+      <button id="ed-save" title="save (Ctrl+S)">save</button>
+    </div>
+    <textarea id="ed-text" spellcheck="false" placeholder="select a .cf file…"></textarea>
+    <div id="ed-status">ready</div>
+  </aside>
+  <div id="editor-resizer" title="drag to resize the editor"></div>
   <aside id="sidebar">
     <div id="layers-pane"><h3>Layers</h3><div id="layerlist"></div></div>
     <div id="pane-divider" title="drag to resize panes"></div>
@@ -1134,6 +1200,114 @@ events.onerror = () => dot.classList.add('err');
 
 refresh();
 </script>
+<script>
+  // ── Theme toggle: auto (follow system) → light → dark → auto ───────────────
+  (function () {
+    var root = document.documentElement;
+    var btn = document.getElementById('btntheme');
+    var mq = matchMedia('(prefers-color-scheme: light)');
+    function mode() {
+      var t = root.dataset.theme;
+      return t === 'light' || t === 'dark' ? t : 'auto';
+    }
+    function apply(m) {
+      if (m === 'auto') {
+        delete root.dataset.theme;
+        try { localStorage.removeItem('cadspec-theme'); } catch (e) {}
+      } else {
+        root.dataset.theme = m;
+        try { localStorage.setItem('cadspec-theme', m); } catch (e) {}
+      }
+      var eff = m === 'auto' ? (mq.matches ? 'light' : 'dark') : m;
+      btn.textContent = m === 'auto' ? '◐' : m === 'light' ? '☀' : '☾';
+      btn.title = 'theme: ' + m + (m === 'auto' ? ' (' + eff + ')' : '') + ' — click to change';
+    }
+    btn.addEventListener('click', function () {
+      apply({ auto: 'light', light: 'dark', dark: 'auto' }[mode()]);
+    });
+    mq.addEventListener('change', function () { if (mode() === 'auto') apply('auto'); });
+    apply(mode());
+  })();
+
+  // ── Built-in .cf editor ────────────────────────────────────────────────────
+  (function () {
+    var editor = document.getElementById('editor');
+    var resizer = document.getElementById('editor-resizer');
+    var sel = document.getElementById('ed-file');
+    var text = document.getElementById('ed-text');
+    var saveBtn = document.getElementById('ed-save');
+    var status = document.getElementById('ed-status');
+    var toggle = document.getElementById('btneditor');
+    var dirty = false;
+
+    function setStatus(msg, cls) { status.textContent = msg; status.className = cls || ''; }
+
+    function loadFile(name) {
+      fetch('/file?name=' + encodeURIComponent(name))
+        .then(function (r) { return r.text(); })
+        .then(function (t) { text.value = t; dirty = false; setStatus(name); })
+        .catch(function () { setStatus('cannot load ' + name, 'err'); });
+    }
+    function loadFiles() {
+      fetch('/files').then(function (r) { return r.json(); }).then(function (j) {
+        sel.innerHTML = '';
+        (j.files || []).forEach(function (f) {
+          var o = document.createElement('option');
+          o.value = f; o.textContent = f; sel.appendChild(o);
+        });
+        if (sel.options.length) { loadFile(sel.value); }
+        else { text.value = ''; setStatus('no .cf files'); }
+      }).catch(function () { setStatus('cannot list files', 'err'); });
+    }
+    function save() {
+      var name = sel.value;
+      if (!name) return;
+      setStatus('saving…');
+      fetch('/save?name=' + encodeURIComponent(name), { method: 'POST', body: text.value })
+        .then(function (r) { return r.json(); })
+        .then(function (j) {
+          if (j.ok) { dirty = false; setStatus('saved · ' + name, 'ok'); }
+          else { dirty = false; setStatus('saved · build error (see viewer)', 'err'); }
+        })
+        .catch(function () { setStatus('save failed', 'err'); });
+    }
+
+    sel.addEventListener('change', function () {
+      if (!dirty || confirm('Discard unsaved changes?')) loadFile(sel.value);
+    });
+    text.addEventListener('input', function () {
+      if (!dirty) { dirty = true; setStatus('● ' + sel.value + ' (unsaved)', 'dirty'); }
+    });
+    saveBtn.addEventListener('click', save);
+    // Keep editor keystrokes out of the viewer's shortcuts (3 / f / 1-9 / esc).
+    text.addEventListener('keydown', function (e) {
+      e.stopPropagation();
+      if ((e.ctrlKey || e.metaKey) && (e.key === 's' || e.key === 'S')) { e.preventDefault(); save(); }
+    });
+    sel.addEventListener('keydown', function (e) { e.stopPropagation(); });
+
+    toggle.addEventListener('click', function () {
+      var hidden = editor.classList.toggle('hidden');
+      resizer.classList.toggle('hidden', hidden);
+      toggle.classList.toggle('active', !hidden);
+    });
+    window.addEventListener('keydown', function (e) {
+      var tag = (e.target && e.target.tagName) || '';
+      if ((e.key === 'e' || e.key === 'E') && !/INPUT|TEXTAREA|SELECT/.test(tag)) toggle.click();
+    });
+
+    // Drag to resize the editor pane.
+    var drag = false;
+    resizer.addEventListener('mousedown', function (e) { drag = true; resizer.classList.add('dragging'); e.preventDefault(); });
+    window.addEventListener('mousemove', function (e) {
+      if (!drag) return;
+      editor.style.width = Math.max(200, Math.min(720, e.clientX)) + 'px';
+    });
+    window.addEventListener('mouseup', function () { drag = false; resizer.classList.remove('dragging'); });
+
+    loadFiles();
+  })();
+</script>
 </body>
 </html>
 "##;

From 19b41863f95c30d87da38a20d4cf61eaeb5124ab Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 12:05:21 -0500
Subject: [PATCH 11/39] feat(serve): syntax-highlight the .cf editor and
 auto-save edits with a debounce

---
 src/serve.rs | 91 +++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 69 insertions(+), 22 deletions(-)

diff --git a/src/serve.rs b/src/serve.rs
index bef8b0a..948fd5b 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -755,6 +755,7 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
     --accent: #6ec6e6; --accent-soft: rgba(110,198,230,0.16);
     --ok: #5dd39e; --err: #e0746e; --err-soft: #2a1212; --err-ink: #ff9f9a;
     --code-bg: #0a0b0d; --code-ink: #cdd6df;
+    --t-num: #d9a35f; --t-hdr: #c79be0;
   }
   :root[data-theme="light"], :root[data-theme="light"] :root {
     --bg: #f6f8fa; --panel: #ffffff; --panel-2: #eef2f5;
@@ -764,6 +765,7 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
     --accent: #156c80; --accent-soft: rgba(21,108,128,0.12);
     --ok: #1f8f5a; --err: #b23b34; --err-soft: #fbeae9; --err-ink: #9a3027;
     --code-bg: #f0f3f5; --code-ink: #1b2630;
+    --t-num: #9a6516; --t-hdr: #7a3fa0;
   }
   @media (prefers-color-scheme: light) {
     :root:not([data-theme]) {
@@ -774,6 +776,7 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
       --accent: #156c80; --accent-soft: rgba(21,108,128,0.12);
       --ok: #1f8f5a; --err: #b23b34; --err-soft: #fbeae9; --err-ink: #9a3027;
       --code-bg: #f0f3f5; --code-ink: #1b2630;
+      --t-num: #9a6516; --t-hdr: #7a3fa0;
     }
   }
   * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -793,7 +796,19 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   #editor.hidden { display: none; }
   .ed-head { display: flex; gap: 6px; padding: 7px 8px; border-bottom: 1px solid var(--line); }
   #ed-file { flex: 1; min-width: 0; background: var(--panel-2); color: var(--ink); border: 1px solid var(--line-2); border-radius: 4px; font: inherit; font-size: 11px; padding: 3px 6px; }
-  #ed-text { flex: 1; resize: none; background: var(--code-bg); color: var(--code-ink); border: 0; padding: 10px 12px; font: inherit; font-size: 12px; line-height: 1.55; tab-size: 2; outline: none; white-space: pre; overflow: auto; }
+  /* highlighted-overlay editor: a coloured <pre> behind a transparent textarea */
+  #ed-wrap { flex: 1; position: relative; overflow: hidden; background: var(--code-bg); }
+  #ed-hl, #ed-text { position: absolute; inset: 0; margin: 0; border: 0; padding: 10px 12px; font: inherit; font-size: 12px; line-height: 1.55; tab-size: 2; white-space: pre; overflow: auto; }
+  #ed-hl { color: var(--code-ink); pointer-events: none; z-index: 0; }
+  #ed-hl code { font: inherit; }
+  #ed-text { resize: none; background: transparent; color: transparent; caret-color: var(--ink-strong); outline: none; z-index: 1; }
+  #ed-text::selection { background: var(--accent-soft); }
+  .t-key { color: var(--accent); }
+  .t-str { color: var(--ok); }
+  .t-num { color: var(--t-num); }
+  .t-hdr { color: var(--t-hdr); font-weight: 500; }
+  .t-com { color: var(--ink-faint); font-style: italic; }
+  .t-bool { color: var(--err); }
   #ed-status { padding: 5px 10px; font-size: 10px; color: var(--ink-faint); border-top: 1px solid var(--line); white-space: nowrap; overflow: hidden; }
   #ed-status.ok { color: var(--ok); }
   #ed-status.err { color: var(--err); }
@@ -865,7 +880,10 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
       <select id="ed-file" title="project .cf files"></select>
       <button id="ed-save" title="save (Ctrl+S)">save</button>
     </div>
-    <textarea id="ed-text" spellcheck="false" placeholder="select a .cf file…"></textarea>
+    <div id="ed-wrap">
+      <pre id="ed-hl" aria-hidden="true"><code></code></pre>
+      <textarea id="ed-text" spellcheck="false" autocapitalize="off" autocomplete="off" placeholder="select a .cf file…"></textarea>
+    </div>
     <div id="ed-status">ready</div>
   </aside>
   <div id="editor-resizer" title="drag to resize the editor"></div>
@@ -1229,23 +1247,64 @@ refresh();
     apply(mode());
   })();
 
-  // ── Built-in .cf editor ────────────────────────────────────────────────────
+  // ── Built-in .cf editor: syntax highlight + debounced auto-save ─────────────
   (function () {
     var editor = document.getElementById('editor');
     var resizer = document.getElementById('editor-resizer');
     var sel = document.getElementById('ed-file');
     var text = document.getElementById('ed-text');
+    var hl = document.querySelector('#ed-hl code');
     var saveBtn = document.getElementById('ed-save');
     var status = document.getElementById('ed-status');
     var toggle = document.getElementById('btneditor');
-    var dirty = false;
+    var current = null; // the file currently loaded in the textarea
+    var timer = null;
+    var SAVE_DELAY = 600;
 
     function setStatus(msg, cls) { status.textContent = msg; status.className = cls || ''; }
+    function escHtml(s) { return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+
+    // Lightweight .cf (TOML-ish) tokenizer → coloured spans.
+    function highlight(code) {
+      return code.split('\n').map(function (line) {
+        var out = '', rest = escHtml(line);
+        var km = rest.match(/^(\s*)([A-Za-z0-9_.\-]+)(\s*=)/);
+        if (km) { out += km[1] + '<span class="t-key">' + km[2] + '</span>' + km[3]; rest = rest.slice(km[0].length); }
+        out += rest.replace(/(#.*$)|("(?:[^"\\]|\\.)*")|(\[\[?[^\]]*\]\]?)|(-?\b\d+\.?\d*\b)|(\btrue\b|\bfalse\b)/g,
+          function (m, c, s, h, n, b) {
+            if (c) return '<span class="t-com">' + c + '</span>';
+            if (s) return '<span class="t-str">' + s + '</span>';
+            if (h) return '<span class="t-hdr">' + h + '</span>';
+            if (n) return '<span class="t-num">' + n + '</span>';
+            if (b) return '<span class="t-bool">' + b + '</span>';
+            return m;
+          });
+        return out;
+      }).join('\n');
+    }
+    function paint() { hl.innerHTML = highlight(text.value) + '\n'; }
+    function syncScroll() { var p = hl.parentNode; p.scrollTop = text.scrollTop; p.scrollLeft = text.scrollLeft; }
 
+    function save() {
+      var name = current; // captured: stays correct even if the file switches
+      if (!name) return;
+      clearTimeout(timer); timer = null;
+      setStatus('saving…');
+      fetch('/save?name=' + encodeURIComponent(name), { method: 'POST', body: text.value })
+        .then(function (r) { return r.json(); })
+        .then(function (j) { setStatus(j.ok ? 'saved · ' + name : 'saved · build error (see viewer)', j.ok ? 'ok' : 'err'); })
+        .catch(function () { setStatus('save failed', 'err'); });
+    }
+    function scheduleSave() {
+      clearTimeout(timer);
+      setStatus('● ' + current, 'dirty');
+      timer = setTimeout(save, SAVE_DELAY);
+    }
     function loadFile(name) {
+      clearTimeout(timer); timer = null;
       fetch('/file?name=' + encodeURIComponent(name))
         .then(function (r) { return r.text(); })
-        .then(function (t) { text.value = t; dirty = false; setStatus(name); })
+        .then(function (t) { current = name; text.value = t; paint(); syncScroll(); setStatus(name); })
         .catch(function () { setStatus('cannot load ' + name, 'err'); });
     }
     function loadFiles() {
@@ -1256,28 +1315,16 @@ refresh();
           o.value = f; o.textContent = f; sel.appendChild(o);
         });
         if (sel.options.length) { loadFile(sel.value); }
-        else { text.value = ''; setStatus('no .cf files'); }
+        else { current = null; text.value = ''; paint(); setStatus('no .cf files'); }
       }).catch(function () { setStatus('cannot list files', 'err'); });
     }
-    function save() {
-      var name = sel.value;
-      if (!name) return;
-      setStatus('saving…');
-      fetch('/save?name=' + encodeURIComponent(name), { method: 'POST', body: text.value })
-        .then(function (r) { return r.json(); })
-        .then(function (j) {
-          if (j.ok) { dirty = false; setStatus('saved · ' + name, 'ok'); }
-          else { dirty = false; setStatus('saved · build error (see viewer)', 'err'); }
-        })
-        .catch(function () { setStatus('save failed', 'err'); });
-    }
 
     sel.addEventListener('change', function () {
-      if (!dirty || confirm('Discard unsaved changes?')) loadFile(sel.value);
-    });
-    text.addEventListener('input', function () {
-      if (!dirty) { dirty = true; setStatus('● ' + sel.value + ' (unsaved)', 'dirty'); }
+      if (timer) save();          // flush the pending edit to the old file first
+      loadFile(sel.value);
     });
+    text.addEventListener('input', function () { paint(); scheduleSave(); });
+    text.addEventListener('scroll', syncScroll);
     saveBtn.addEventListener('click', save);
     // Keep editor keystrokes out of the viewer's shortcuts (3 / f / 1-9 / esc).
     text.addEventListener('keydown', function (e) {

From c78dc7126bb9dc0a3ebb164df82e421e8ff6bb6e Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 21 Jun 2026 12:29:34 -0500
Subject: [PATCH 12/39] feat(serve): render the 3D view interactively with
 three.js and glTF (orbit, theme-aware, live-reload)

---
 src/serve.rs | 115 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 110 insertions(+), 5 deletions(-)

diff --git a/src/serve.rs b/src/serve.rs
index 948fd5b..19b3432 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -305,6 +305,13 @@ fn rebuild(project_dir: &Path, state: &Shared) {
     state.changed.notify_all();
 }
 
+/// Build the scene's 3D solids as a glTF document (for the WebGL viewer).
+fn scene_gltf(project_dir: &Path) -> Result<String> {
+    let (_project, layers) = load_project_layers(project_dir, None)?;
+    let meshes = crate::render3d::scene_meshes(&layers);
+    Ok(crate::gltf::scene_to_gltf(&meshes))
+}
+
 /// Render a plano by name to SVG (on demand, for the `/plano.svg` endpoint).
 fn render_named_plano(project_dir: &Path, name: &str) -> Result<String> {
     let project = parse_project(&project_dir.join("project.toml"))?;
@@ -395,6 +402,11 @@ fn handle_connection(stream: TcpStream, state: &Shared) -> std::io::Result<()> {
             let svg = Arc::clone(&state.state.lock().unwrap().svg3d);
             respond(stream, "200 OK", "image/svg+xml", svg.as_bytes())
         }
+        "/scene.gltf" => {
+            let body =
+                scene_gltf(&state.project_dir).unwrap_or_else(|_| crate::gltf::scene_to_gltf(&[]));
+            respond(stream, "200 OK", "model/gltf+json", body.as_bytes())
+        }
         "/plano.svg" => {
             // Rendered on demand (sections run CSG, so we don't precompute all).
             let name = query_param(query, "name").unwrap_or_default();
@@ -840,6 +852,10 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   /* viewport */
   #viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; perspective: 2200px; background: var(--bg); }
   #viewport.panning { cursor: grabbing; }
+  #viewport.is3d { cursor: default; }
+  /* interactive WebGL (glTF) layer, shown in 3D mode */
+  #gl { position: absolute; inset: 0; width: 100%; height: 100%; display: none; }
+  #gl.show { display: block; }
   #canvas { position: absolute; transform-origin: 0 0; will-change: transform; transform-style: preserve-3d; }
   #canvas svg { display: block; }
   .plane { position: absolute; left: 0; top: 0; }
@@ -895,6 +911,7 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   <div id="layers-resizer" title="drag to resize · double-click to reset"></div>
   <div id="viewport">
     <div id="canvas"></div>
+    <canvas id="gl"></canvas>
     <pre id="error"></pre>
   </div>
   <aside id="inspector">
@@ -947,6 +964,7 @@ function svgSize() {
   return { w: parseFloat(svg.getAttribute('width')), h: parseFloat(svg.getAttribute('height')) };
 }
 function fitToView() {
+  if (mode3d) { if (window.gl3d) window.gl3d.frame(); return; }
   const s = svgSize();
   if (!s) return;
   const vw = viewport.clientWidth, vh = viewport.clientHeight;
@@ -959,7 +977,8 @@ function fitToView() {
 
 // ── rendering ───────────────────────────────────────────────────────
 function renderCanvas() {
-  const content = currentPlano ? planoSvg : (mode3d ? svg3dText : svgText);
+  if (mode3d) return;                 // 3D is the WebGL (glTF) layer, not the SVG
+  const content = currentPlano ? planoSvg : svgText;
   if (!content) return;
   canvas.innerHTML = content;
   applyLayerStates();
@@ -1099,11 +1118,13 @@ async function refresh() {
     }
     renderCanvas();
     if (!fitted) fitToView();
+    if (mode3d && window.gl3d) window.gl3d.reload();
   }
 }
 
 // ── input ───────────────────────────────────────────────────────────
 viewport.addEventListener('wheel', e => {
+  if (mode3d) return;                 // OrbitControls handles zoom in 3D
   e.preventDefault();
   const factor = Math.exp(-e.deltaY * 0.0012);
   const next = Math.min(Math.max(scale * factor, 0.05), 50);
@@ -1117,6 +1138,7 @@ viewport.addEventListener('wheel', e => {
 
 let panning = false, moved = 0, px = 0, py = 0;
 viewport.addEventListener('mousedown', e => {
+  if (mode3d) return;                 // OrbitControls handles rotate/pan in 3D
   panning = true; moved = 0; px = e.clientX; py = e.clientY;
   viewport.classList.add('panning');
 });
@@ -1132,18 +1154,27 @@ window.addEventListener('mouseup', () => {
   viewport.classList.remove('panning');
 });
 viewport.addEventListener('click', e => {
+  if (mode3d) return;                          // no entity-picking in 3D
   if (moved > 5) return;                       // it was a pan, not a click
   const el = e.target.closest('[data-id]');
-  if (el && !mode3d) select(el.getAttribute('data-id'));
-  else if (!el) deselect();
+  if (el) select(el.getAttribute('data-id'));
+  else deselect();
 });
 viewport.addEventListener('dblclick', fitToView);
 
 function toggle3d() {
   mode3d = !mode3d;
   document.getElementById('btn3d').classList.toggle('active', mode3d);
-  renderCanvas();
-  fitToView();
+  viewport.classList.toggle('is3d', mode3d);
+  if (mode3d) {
+    canvas.style.display = 'none';
+    if (window.gl3d) window.gl3d.mount();
+  } else {
+    canvas.style.display = '';
+    if (window.gl3d) window.gl3d.unmount();
+    renderCanvas();
+    fitToView();
+  }
 }
 document.getElementById('btn3d').onclick = toggle3d;
 document.getElementById('btnfit').onclick = fitToView;
@@ -1355,6 +1386,80 @@ refresh();
     loadFiles();
   })();
 </script>
+<script type="importmap">
+{
+  "imports": {
+    "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
+    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/"
+  }
+}
+</script>
+<script type="module">
+  // Interactive 3D: load the scene as glTF and orbit it. The flat axonometric
+  // SVG is no longer used for 3D — this is the real model.
+  import * as THREE from 'three';
+  import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+  import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+  var glCanvas = document.getElementById('gl');
+  var renderer, scene, camera, controls, model, raf = null, inited = false;
+  var loader = new GLTFLoader();
+
+  function bgColor() {
+    var c = getComputedStyle(document.documentElement).getPropertyValue('--bg').trim();
+    return new THREE.Color(c || '#0d0e11');
+  }
+  function resize() {
+    if (!renderer) return;
+    var w = glCanvas.clientWidth, h = glCanvas.clientHeight;
+    if (!w || !h) return;
+    renderer.setSize(w, h, false);
+    camera.aspect = w / h; camera.updateProjectionMatrix();
+  }
+  function init() {
+    if (inited) return; inited = true;
+    renderer = new THREE.WebGLRenderer({ canvas: glCanvas, antialias: true });
+    renderer.setPixelRatio(window.devicePixelRatio || 1);
+    scene = new THREE.Scene();
+    camera = new THREE.PerspectiveCamera(45, 1, 0.01, 1e6);
+    controls = new OrbitControls(camera, renderer.domElement);
+    controls.enableDamping = true; controls.dampingFactor = 0.08;
+    scene.add(new THREE.AmbientLight(0xffffff, 0.6));
+    var d1 = new THREE.DirectionalLight(0xffffff, 0.85); d1.position.set(1, 2, 1.5); scene.add(d1);
+    var d2 = new THREE.DirectionalLight(0xffffff, 0.3); d2.position.set(-1.2, -0.4, -1); scene.add(d2);
+    window.addEventListener('resize', resize);
+  }
+  function frame() {
+    if (!model) return;
+    var box = new THREE.Box3().setFromObject(model);
+    var size = box.getSize(new THREE.Vector3());
+    var center = box.getCenter(new THREE.Vector3());
+    var r = Math.max(size.x, size.y, size.z, 1) * 0.5;
+    controls.target.copy(center);
+    var dist = r / Math.tan((camera.fov * Math.PI / 180) / 2) * 1.7;
+    camera.position.set(center.x + dist * 0.8, center.y + dist * 0.7, center.z + dist * 0.9);
+    camera.near = Math.max(r / 200, 0.001); camera.far = r * 200; camera.updateProjectionMatrix();
+    controls.update();
+  }
+  function load() {
+    loader.load('/scene.gltf?t=' + Date.now(), function (g) {
+      if (model) scene.remove(model);
+      model = g.scene; scene.add(model); frame();
+    }, undefined, function () {});
+  }
+  function loop() {
+    raf = requestAnimationFrame(loop);
+    controls.update();
+    renderer.setClearColor(bgColor(), 1);
+    renderer.render(scene, camera);
+  }
+  window.gl3d = {
+    mount: function () { init(); glCanvas.classList.add('show'); resize(); load(); if (!raf) loop(); },
+    unmount: function () { glCanvas.classList.remove('show'); if (raf) { cancelAnimationFrame(raf); raf = null; } },
+    reload: function () { if (glCanvas.classList.contains('show')) load(); },
+    frame: function () { frame(); }
+  };
+</script>
 </body>
 </html>
 "##;

From 94f147abeeee092275251c97aaf9441feec03af0 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Thu, 25 Jun 2026 18:03:26 -0500
Subject: [PATCH 13/39] docs: update README banner to cadSpec wordmark and
 remove stale root docs

---
 CONTRIBUTING.md |  53 ------
 LICENSE         |   3 -
 README.md       |  22 +--
 cadspec-spec.md | 418 ------------------------------------------------
 4 files changed, 11 insertions(+), 485 deletions(-)
 delete mode 100644 CONTRIBUTING.md
 delete mode 100644 LICENSE
 delete mode 100644 cadspec-spec.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index e306226..0000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Contributing to cadspec
-
-Thank you for your interest in contributing!
-
-## Development workflow
-
-```bash
-git clone https://github.com/UniverLab/cadforge.git
-cd cadspec
-cargo build
-cargo test
-```
-
-Branch off `develop` for all changes. PRs go to `develop`, not `main`.
-
-## CI/CD and required secrets
-
-This project uses GitHub Actions for CI (`.github/workflows/ci.yml`) and automated releases (`.github/workflows/release.yml`).
-
-### Required repository secrets
-
-| Secret | Description | Where to get it |
-|---|---|---|
-| `CARGO_REGISTRY_TOKEN` | API token to publish crates to [crates.io](https://crates.io) | [crates.io/me](https://crates.io/me) → API Tokens → New Token |
-
-Configure secrets at:  
-`https://github.com/UniverLab/cadforge/settings/secrets/actions`
-
-> **Tip:** If you use [ghscaff](https://github.com/UniverLab/ghscaff), you can run `ghscaff apply` to configure missing secrets interactively, or set the env var before running:
-> ```bash
-> export CARGO_REGISTRY_TOKEN=<your_token>
-> ghscaff apply
-> ```
-
-## Release process
-
-Releases are automated via the `release.yml` workflow. To cut a release:
-
-1. Bump the version in `Cargo.toml`
-2. Commit: `chore: release vX.Y.Z`
-3. Tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
-
-The workflow builds binaries for Linux, macOS, and Windows, publishes to crates.io, and creates a GitHub Release.
-
-## Code style
-
-```bash
-cargo fmt        # format
-cargo clippy -- -D warnings   # lint
-cargo test       # test
-```
-
-All three must pass before merging.
diff --git a/LICENSE b/LICENSE
deleted file mode 100644
index 19e48cf..0000000
--- a/LICENSE
+++ /dev/null
@@ -1,3 +0,0 @@
-# MIT License
-
-See https://opensource.org/licenses/MIT for the full license text.
diff --git a/README.md b/README.md
index e03c851..00e96b5 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
 ```text
-                        █████ ███████████
-                       ░░███ ░░███░░░░░░█
-  ██████   ██████    ███████  ░███   █ ░   ██████  ████████   ███████  ██████
- ███░░███ ░░░░░███  ███░░███  ░███████    ███░░███░░███░░███ ███░░███ ███░░███
-░███ ░░░   ███████ ░███ ░███  ░███░░░█   ░███ ░███ ░███ ░░░ ░███ ░███░███████
-░███  ███ ███░░███ ░███ ░███  ░███  ░    ░███ ░███ ░███     ░███ ░███░███░░░
-░░██████ ░░████████░░████████ █████      ░░██████  █████    ░░███████░░██████
- ░░░░░░   ░░░░░░░░  ░░░░░░░░ ░░░░░        ░░░░░░  ░░░░░      ░░░░░███ ░░░░░░
-                                                             ███ ░███
-                                                            ░░██████
-                                                             ░░░░░░
+                        █████  █████████                             
+                       ░░███  ███░░░░░███                            
+  ██████   ██████    ███████ ░███    ░░░  ████████   ██████   ██████ 
+ ███░░███ ░░░░░███  ███░░███ ░░█████████ ░░███░░███ ███░░███ ███░░███
+░███ ░░░   ███████ ░███ ░███  ░░░░░░░░███ ░███ ░███░███████ ░███ ░░░ 
+░███  ███ ███░░███ ░███ ░███  ███    ░███ ░███ ░███░███░░░  ░███  ███
+░░██████ ░░████████░░████████░░█████████  ░███████ ░░██████ ░░██████ 
+ ░░░░░░   ░░░░░░░░  ░░░░░░░░  ░░░░░░░░░   ░███░░░   ░░░░░░   ░░░░░░  
+                                          ░███                       
+                                          █████                      
+                                         ░░░░░                       
 ```
 
 <p align="center">
diff --git a/cadspec-spec.md b/cadspec-spec.md
deleted file mode 100644
index 75ed8d6..0000000
--- a/cadspec-spec.md
+++ /dev/null
@@ -1,418 +0,0 @@
-# CADspec — Especificación y Roadmap v1.0
-
-> Arquitectura como Código — motor determinista de geometría descriptiva para diseño arquitectónico reproducible, versionable y potenciado por agentes de IA.
-
----
-
-## 1. Visión
-
-El diseño arquitectónico actual sufre de **entropía gráfica**: los planos son colecciones de líneas sin semántica, imposibles de versionar, comparar o automatizar. CADspec propone un cambio de paradigma:
-
-**El plano no se dibuja, se declara.**
-
-Al igual que el código fuente de software, un espacio arquitectónico es el resultado de un lenguaje estructurado. Si el código no cambia, el plano es idéntico bit a bit cada vez que se compila. Esto elimina la ambigüedad del clic humano, habilita `git diff` sobre planos, y permite que los agentes de IA generen y modifiquen diseños con precisión quirúrgica.
-
-CADspec no es un programa de dibujo. Es la infraestructura para que la arquitectura sea una **ciencia de datos reproducible**.
-
----
-
-## 2. Ecosistema — Tres Proyectos Separados
-
-La arquitectura se divide en tres proyectos independientes que se integran entre sí:
-
-```
-cadspec          → motor de geometría (librería Rust, crates.io)
-cadspec-cli      → interfaz de línea de comandos (binario Rust, crates.io)
-cadspec-view     → visor gráfico vectorial con modo calco (binario Rust)
-```
-
-### Separación de responsabilidades
-
-| Proyecto | Tipo | Responsabilidad |
-|---|---|---|
-| `cadspec` | Librería | Parser `.cf`, compilador → DXF, motor de geometría, sistema de capas y constraints |
-| `cadspec-cli` | Binario | Comandos, wizard, build, watch, import/export, integración con agentes |
-| `cadspec-view` | Binario | Visor vectorial estilo consola, modo calco, edición bidireccional → `.cf` |
-
-La librería `cadspec` es reutilizable por cualquier proyecto Rust — el CLI y el visor son consumidores de ella.
-
----
-
-## 3. Formato de Proyecto
-
-Un proyecto CADspec es un directorio con la siguiente estructura:
-
-```
-mi-proyecto/
-├── project.toml    ← archivo raíz: metadatos, capas, constraints
-├── capa-a.cf       ← capa de primitivos (ej: planta estructural)
-├── capa-b.cf       ← capa de primitivos (ej: instalaciones)
-└── capa-c.cf       ← capa de primitivos (ej: acabados y anotaciones)
-```
-
-El nombre de cada `.cf` lo define el usuario — CADspec no impone nomenclatura ni semántica de capas. Una capa es simplemente un conjunto de primitivos geométricos agrupados.
-
-### project.toml
-
-```toml
-[project]
-name = "Vivienda Unifamiliar Lote 12"
-scale = "1:100"
-units = "m"
-author = "Arq. Nombre Apellido"
-version = "0.3.0"
-
-[layers]
-capa-a = { file = "capa-a.cf", locked = false }
-capa-b = { file = "capa-b.cf", locked = false }
-capa-c = { file = "capa-c.cf", locked = false }
-
-[constraints]
-# Si un primitivo de capa-a se mueve, notificar a capa-b
-capa-a → capa-b = "spatial_dependency"
-
-# Los primitivos de capa-b deben vivir dentro del bbox de capa-a
-capa-b.parent = "capa-a"
-
-# Los primitivos de capa-c referencian explícitamente elementos de capa-b
-capa-c.belongs_to = "capa-b"
-```
-
----
-
-## 4. Lenguaje `.cf` (TOML)
-
-El formato `.cf` es TOML válido. Se eligió TOML sobre JSON por ser más legible para humanos y agentes — menos contexto, más señal. Los agentes de IA que ya conocen TOML pueden generar y modificar archivos `.cf` sin entrenamiento adicional.
-
-**Principio clave:** el lenguaje `.cf` trabaja exclusivamente con **primitivos geométricos**. No existe concepto de "muro", "puerta" o "habitación" en el motor base. Esa semántica es responsabilidad del usuario o de capas de abstracción futuras (`cadspec-arch` en v2+). El motor solo sabe de formas, posiciones, atributos visuales y relaciones espaciales.
-
-### Primitivos soportados en v1
-
-| Primitivo | Descripción |
-|---|---|
-| `[[line]]` | Línea entre dos puntos |
-| `[[polyline]]` | Polilínea de múltiples vértices, abierta o cerrada |
-| `[[rect]]` | Rectángulo por origen, ancho y alto |
-| `[[circle]]` | Círculo por centro y radio |
-| `[[arc]]` | Arco por centro, radio y ángulos |
-| `[[hatch]]` | Achurado sobre un contorno cerrado |
-| `[[text]]` | Texto con posición, tamaño y alineación |
-| `[[dim]]` | Cota lineal o angular |
-| `[[point]]` | Punto de referencia |
-| `[[group]]` | Agrupación de primitivos con id propio |
-
-### Atributos comunes
-
-Todos los primitivos comparten atributos visuales opcionales:
-
-```toml
-id          = "string"       # identificador único en la capa
-color       = "#FFFFFF"      # color en hex
-weight      = 0.35           # grosor de línea en mm
-style       = "solid"        # solid | dashed | dotted | dashdot
-layer       = "capa-a"       # capa a la que pertenece
-visible     = true
-locked      = false
-```
-
-### Ejemplos
-
-```toml
-# capa-a.cf
-
-[[line]]
-id = "ln-001"
-from = [0.0, 0.0]
-to   = [8.5, 0.0]
-weight = 0.50
-
-[[polyline]]
-id = "pl-001"
-points = [[0.0, 0.0], [8.5, 0.0], [8.5, 6.0], [0.0, 6.0]]
-closed = true
-weight = 0.35
-
-[[rect]]
-id = "rc-001"
-origin = [1.0, 1.0]
-width  = 3.5
-height = 4.0
-weight = 0.25
-
-[[circle]]
-id = "ci-001"
-center = [4.0, 3.0]
-radius = 0.5
-
-[[arc]]
-id = "ar-001"
-center     = [2.0, 2.0]
-radius     = 0.90
-from_angle = 0
-to_angle   = 90
-
-[[hatch]]
-id       = "ht-001"
-boundary = "pl-001"      # referencia al id del contorno cerrado
-pattern  = "ansi31"      # ansi31 | ansi32 | ansi33 | ansi34 | solid | none
-scale    = 1.0
-angle    = 45
-
-[[text]]
-id        = "tx-001"
-position  = [4.0, 3.0]
-content   = "SALA"
-size      = 14
-align     = "center"     # left | center | right
-
-[[dim]]
-id    = "dm-001"
-type  = "linear"         # linear | angular | radial
-from  = [0.0, 0.0]
-to    = [8.5, 0.0]
-offset = 0.5             # distancia de la cota al elemento
-
-[[group]]
-id      = "gr-001"
-members = ["ln-001", "rc-001", "tx-001"]
-```
-
-### Atributos globales de capa
-
-```toml
-[layer]
-name       = "capa-a"
-color      = "#FFFFFF"
-line_weight = 0.35
-visible    = true
-locked     = false
-```
-
----
-
-## 5. Sistema de Capas y Constraints
-
-### Concepto
-
-Cada archivo `.cf` es una capa independiente. Las capas se orquestan desde `project.toml`. Las **constraints** son reglas declarativas que definen relaciones espaciales y de pertenencia entre capas.
-
-### Tipos de constraints
-
-| Constraint | Descripción |
-|---|---|
-| `spatial_dependency` | Si un objeto de la capa A se mueve, la capa B recibe notificación de conflicto |
-| `parent` | Los objetos de la capa hija deben vivir dentro del bbox de la capa padre |
-| `belongs_to` | Un objeto de la capa hija referencia explícitamente un objeto de la capa padre |
-
-### Comportamiento al compilar
-
-Cuando `cadspec build` detecta una violación de constraints:
-
-```
-⚠ CONSTRAINT VIOLATION
-  Layer:      capa-b
-  Object:     ln-042
-  Constraint: spatial_dependency → capa-a
-  Detail:     pl-001 in capa-a moved 0.30m east — ln-042 in capa-b now outside its bbox
-  Action:     build continues with warning — update capa-b.cf to resolve
-```
-
-Las constraints no bloquean el build por defecto — emiten warnings. Se puede configurar `strict = true` en `project.toml` para bloquear.
-
----
-
-## 6. cadspec-cli — Comandos
-
-```bash
-# Inicialización
-cadspec new mi-proyecto          # crea estructura de proyecto
-cadspec init                     # inicializa en directorio existente
-
-# Compilación
-cadspec build                    # compila todas las capas → DXF
-cadspec build --layer muros      # compila una capa específica
-cadspec build --check            # valida constraints sin generar output
-
-# Desarrollo
-cadspec watch                    # modo watch: recompila al guardar cualquier .cf
-
-# Importación / Migración
-cadspec import archivo.dxf       # convierte DXF existente → .cf (por capas detectadas)
-cadspec import archivo.dxf --layer muros  # importa a capa específica
-
-# Visualización
-cadspec view                     # abre cadspec-view con el proyecto actual
-cadspec view --layer muros       # abre solo una capa
-
-# Información
-cadspec layers                   # lista capas del proyecto con estado
-cadspec check                    # valida constraints y reporta conflictos
-
-# Configuración global
-cadspec config set author "Arq. Nombre Apellido"
-cadspec config set units m
-cadspec config show
-```
-
----
-
-## 7. cadspec-view — Visor Vectorial
-
-### Filosofía de diseño
-
-El visor evoca la consola: **fondo negro, líneas vectoriales blancas/grises, tipografía monoespaciada**. No es un editor gráfico pesado — es una ventana de precisión sobre el archivo `.cf`.
-
-El rendering es **vectorial puro** — las líneas mantienen su calidad a cualquier zoom, sin pérdida de fidelidad como ocurriría en una TUI basada en caracteres. Se construye sobre una librería gráfica de bajo nivel (candidatos: `wgpu`, `femtovg`, `tiny-skia`).
-
-### Modos de operación
-
-**Modo lectura:**
-- Renderiza el proyecto completo o por capas
-- Zoom, pan, toggle de capas
-- Muestra constraints activas
-
-**Modo edición (bidireccional):**
-- Herramientas básicas: mover objeto, ajustar dimensión, agregar anotación
-- Los cambios se traducen al `.cf` correspondiente **al guardar** (no en tiempo real)
-- El archivo `.cf` es siempre la fuente de verdad
-
-**Modo calco:**
-- La ventana del visor se vuelve semi-transparente (alpha configurable)
-- Se puede posicionar sobre otra ventana (imagen, plano escaneado, referencia)
-- El usuario traza sobre la referencia y los objetos se capturan como `.cf`
-- **Auto-calco**: comando que analiza lo que está debajo de la ventana y propone objetos `.cf` detectados (experimental, v2)
-
-### Atajos de teclado
-
-```
-Z / X       → zoom in / out
-Flechas     → pan
-L           → toggle lista de capas
-1-9         → toggle visibilidad de capa por número
-E           → entrar a modo edición
-C           → entrar a modo calco
-S           → guardar cambios al .cf (en modo edición)
-Esc         → salir del modo actual
-Q           → cerrar visor
-```
-
----
-
-## 8. Importación DXF → `.cf`
-
-Una de las propuestas de valor más importantes: **migrar lo que ya existe**.
-
-```bash
-cadspec import plano-existente.dxf
-```
-
-El importador:
-1. Lee las capas del DXF original
-2. Mapea cada capa DXF a un archivo `.cf` nuevo
-3. Convierte geometría a objetos declarativos cuando es posible (líneas paralelas → `wall`, bloques → `column`, etc.)
-4. Lo que no puede inferir lo convierte a `[[line]]` genéricas — siempre importable, siempre editable
-5. Genera un `project.toml` con las capas detectadas
-
-```
-cadspec import plano.dxf
-
-✓ Detected 4 layers: MUROS, ESTRUCTURA, COTAS, TEXTO
-✓ muros.cf        — 23 walls inferred, 4 openings
-✓ estructura.cf   — 8 columns, 1 slab
-✓ cotas.cf        — 31 annotations (as [[annotation]])
-✓ texto.cf        — 12 text objects (as [[annotation]])
-✓ project.toml    — generated
-
-Import complete. Review .cf files and adjust inferred objects.
-```
-
----
-
-## 9. Integración con el Ecosistema Univerlab
-
-### gitkit
-Los archivos `.cf` y `project.toml` son texto plano — `git diff` muestra exactamente qué cambió:
-```diff
-- thickness = 0.15
-+ thickness = 0.20
-```
-No hay comparación de binarios, no hay "Plano_Final_v3_ESTE_SI.dwg".
-
-### agent-canopy
-Los agentes pueden leer y escribir archivos `.cf` directamente — TOML es un formato que los LLMs manejan bien. Un agente puede recibir instrucción:
-> "Optimiza la distribución de luz natural del salón"
-
-Y modificar coordenadas y orientaciones en `muros.cf` de forma precisa y auditable.
-
-### ghscaff
-Plantilla `cadspec` en `ghscaff` para inicializar nuevos proyectos CADspec con estructura de repo correcta desde el primer commit.
-
----
-
-## 10. Stack Técnico
-
-| Componente | Tecnología |
-|---|---|
-| Motor de geometría | `truck` (B-rep Rust), `nalgebra` |
-| Output DXF | crate `dxf` |
-| Parser TOML | `toml` crate |
-| CLI | `clap` con derive macros |
-| File watcher | `notify` crate |
-| Rendering visor | `femtovg` / `tiny-skia` (vectorial, ligero) |
-| Ventana visor | `winit` (cross-platform) |
-| Transparencia/calco | APIs nativas de ventana por OS |
-
----
-
-## 11. Roadmap
-
-### MVP
-- [ ] Parser TOML para archivos `.cf`
-- [ ] Primitivos base: `line`, `polyline`, `rect`, `circle`, `arc`, `hatch`, `text`, `dim`, `point`, `group`
-- [ ] Atributos comunes: color, weight, style, visible, locked
-- [ ] Compilador `.cf` → DXF (2D, planos de planta)
-- [ ] Sistema de capas con `project.toml`
-- [ ] Constraints básicas: `parent`, `belongs_to`
-- [ ] `cadspec build` y `cadspec watch`
-- [ ] Live preview vía visor externo (LibreCAD, FreeCAD)
-- [ ] Publicación en crates.io: `cadspec` (librería) + `cadspec-cli`
-
-### v1
-- [ ] Importador DXF → `.cf` con detección automática de primitivos
-- [ ] `cadspec-view` — visor vectorial propio (fondo negro, líneas vectoriales)
-  - Modo lectura con zoom/pan y toggle de capas
-  - Modo edición básico con escritura bidireccional al guardar
-  - Modo calco con ventana semi-transparente
-- [ ] Constraints con warnings en build: `spatial_dependency`
-- [ ] Achurados estándar: ansi31, ansi32, ansi33, ansi34, solid
-- [ ] Publicación `cadspec-view` en crates.io
-
-### v2
-- [ ] `cadspec-arch` — capa de abstracción arquitectónica sobre primitivos
-  - Objetos semánticos: `wall`, `opening`, `room`, `column`, `slab`
-  - Construidos sobre primitivos del motor base
-  - Publicado como crate independiente
-- [ ] Arch-Linter — validación de normativas arquitectónicas
-  - Áreas mínimas por tipo de espacio
-  - Normativas locales configurables por país/región
-- [ ] Auto-calco experimental — detección de geometría desde imagen de referencia
-- [ ] Output adicional: STL (volumétrico), STEP (intercambio industrial)
-- [ ] Constraints `strict = true` que bloquean el build
-
----
-
-## 12. No-Goals (v1)
-
-- No es un reemplazo de Revit o AutoCAD para flujos complejos de BIM
-- No genera renders fotorrealistas
-- No maneja modelos 3D complejos (solo extrusión simple de planta en v1)
-- No requiere conexión a internet ni licencias propietarias
-- No depende del MCP de Autodesk
-
----
-
-## 13. Contexto Académico
-
-`cadspec` es el proyecto de tesis de especialización en IA con enfoque en diseño arquitectónico. La hipótesis central es que tratar la arquitectura como código — con determinismo, versionado y agentes — representa un cambio de paradigma en el flujo de trabajo del diseño arquitectónico.
-
-El proyecto vive bajo [`univerlab`](https://github.com/univerlab) junto a `texforge`, `gitkit`, `ghscaff` y `agent-canopy`, siguiendo los mismos principios: binario standalone, offline first, sin scope creep.

From b28226bd8c75db924f92ddb316044d0bc67fe720 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 28 Jun 2026 13:43:02 -0500
Subject: [PATCH 14/39] refactor: extract resolve_booleans shared helper, split
 remove_dim_companions

---
 src/importer.rs | 49 +++++++++++++++++-------
 src/render3d.rs | 99 ++++++++++++++-----------------------------------
 2 files changed, 63 insertions(+), 85 deletions(-)

diff --git a/src/importer.rs b/src/importer.rs
index bc7037d..7c2ba44 100644
--- a/src/importer.rs
+++ b/src/importer.rs
@@ -340,27 +340,48 @@ fn remove_dim_companions(entities: &mut Vec<Imported>) {
         let mid = [(a[0] + b[0]) / 2.0, (a[1] + b[1]) / 2.0];
 
         for (cf, ct) in [(from, a), (to, b), (a, b)] {
-            if let Some(i) = (0..entities.len()).find(|&i| {
-                keep[i]
-                    && matches!(entities[i].shape, Shape::Line { from: lf, to: lt }
-                        if (close(lf, cf) && close(lt, ct)) || (close(lf, ct) && close(lt, cf)))
-            }) {
-                keep[i] = false;
-            }
-        }
-        if let Some(i) = (0..entities.len()).find(|&i| {
-            keep[i]
-                && matches!(entities[i].shape, Shape::Text { position, size, .. }
-                    if close(position, [mid[0] + nx * size * 0.5, mid[1] + ny * size * 0.5]))
-        }) {
-            keep[i] = false;
+            mark_line_companion(entities, &mut keep, cf, ct, close);
         }
+        mark_text_companion(entities, &mut keep, mid, nx, ny, close);
     }
 
     let mut it = keep.into_iter();
     entities.retain(|_| it.next().unwrap_or(true));
 }
 
+fn mark_line_companion(
+    entities: &[Imported],
+    keep: &mut [bool],
+    from: [f64; 2],
+    to: [f64; 2],
+    close: impl Fn([f64; 2], [f64; 2]) -> bool,
+) {
+    if let Some(i) = (0..entities.len()).find(|&i| {
+        keep[i]
+            && matches!(entities[i].shape, Shape::Line { from: lf, to: lt }
+                if (close(lf, from) && close(lt, to)) || (close(lf, to) && close(lt, from)))
+    }) {
+        keep[i] = false;
+    }
+}
+
+fn mark_text_companion(
+    entities: &[Imported],
+    keep: &mut [bool],
+    mid: [f64; 2],
+    nx: f64,
+    ny: f64,
+    close: impl Fn([f64; 2], [f64; 2]) -> bool,
+) {
+    if let Some(i) = (0..entities.len()).find(|&i| {
+        keep[i]
+            && matches!(entities[i].shape, Shape::Text { position, size, .. }
+                if close(position, [mid[0] + nx * size * 0.5, mid[1] + ny * size * 0.5]))
+    }) {
+        keep[i] = false;
+    }
+}
+
 /// Render a shape body (without `[[header]]`/`id`); returns (id prefix, body).
 fn emit_shape(shape: &Shape) -> (&'static str, String) {
     match shape {
diff --git a/src/render3d.rs b/src/render3d.rs
index 9d017d4..8003d93 100644
--- a/src/render3d.rs
+++ b/src/render3d.rs
@@ -311,7 +311,6 @@ fn footprints(cf: &CfFile) -> Vec<Footprint<'_>> {
 /// geometry the 3D view renders (same builders), but unprojected and unsectioned,
 /// so it can be exported to a mesh format like glTF.
 pub fn scene_meshes(layers: &[(String, CfFile)]) -> Vec<(mesh::Mesh, String)> {
-    use std::collections::{HashMap, HashSet};
     let mut out: Vec<(mesh::Mesh, String)> = Vec::new();
 
     for (idx, (_name, cf)) in layers.iter().enumerate() {
@@ -340,51 +339,8 @@ pub fn scene_meshes(layers: &[(String, CfFile)]) -> Vec<(mesh::Mesh, String)> {
         }
 
         // Solids + booleans (mirrors collect_solid_faces, without projection).
-        let mut meshes: HashMap<&str, mesh::Mesh> = HashMap::new();
-        let mut colors: HashMap<&str, String> = HashMap::new();
-        for s in &cf.solids {
-            meshes.insert(s.id.as_str(), build_solid(s));
-            colors.insert(
-                s.id.as_str(),
-                s.color.clone().unwrap_or_else(|| layer_color.clone()),
-            );
-        }
-        let mut consumed: HashSet<&str> = HashSet::new();
-        for b in &cf.booleans {
-            consumed.insert(b.base.as_str());
-            for t in &b.tools {
-                consumed.insert(t.as_str());
-            }
-        }
-        for b in &cf.booleans {
-            let Some(base) = meshes.get(b.base.as_str()) else {
-                continue;
-            };
-            let mut acc = base.clone();
-            for t in &b.tools {
-                if let Some(tool) = meshes.get(t.as_str()) {
-                    acc = match b.op.as_str() {
-                        "union" => acc.union(tool),
-                        "intersection" => acc.intersection(tool),
-                        _ => acc.difference(tool),
-                    };
-                }
-            }
-            let color = b
-                .color
-                .clone()
-                .or_else(|| colors.get(b.base.as_str()).cloned())
-                .unwrap_or_else(|| layer_color.clone());
-            out.push((acc, color));
-        }
-        for s in &cf.solids {
-            if consumed.contains(s.id.as_str()) {
-                continue;
-            }
-            if let (Some(m), Some(c)) = (meshes.get(s.id.as_str()), colors.get(s.id.as_str())) {
-                out.push((m.clone(), c.clone()));
-            }
-        }
+        let resolved = resolve_booleans(cf, &layer_color);
+        out.extend(resolved.into_iter().map(|(m, c, _id)| (m, c)));
     }
     out
 }
@@ -432,16 +388,9 @@ fn apply_cut(m: mesh::Mesh, cut: Option<&Cut>) -> mesh::Mesh {
     }
 }
 
-/// Build the named [`mesh`] solids, apply each `[[boolean]]`, and emit the
-/// results. Solids consumed by a boolean are not drawn on their own.
-fn collect_solid_faces(
-    faces: &mut Vec<Face>,
-    layer_name: &str,
-    cf: &CfFile,
-    layer_color: &str,
-    cam: &Camera,
-    cut: Option<&Cut>,
-) {
+/// Build named solids, apply boolean operations, return resolved meshes with colors and IDs.
+/// Used by both `scene_meshes` (glTF export) and `collect_solid_faces` (SVG render).
+fn resolve_booleans(cf: &CfFile, layer_color: &str) -> Vec<(mesh::Mesh, String, Option<String>)> {
     use std::collections::{HashMap, HashSet};
 
     let mut meshes: HashMap<&str, mesh::Mesh> = HashMap::new();
@@ -462,9 +411,10 @@ fn collect_solid_faces(
         }
     }
 
+    let mut out = Vec::new();
     for b in &cf.booleans {
         let Some(base) = meshes.get(b.base.as_str()) else {
-            continue; // unknown base — skip rather than fail the whole render
+            continue;
         };
         let mut acc = base.clone();
         for t in &b.tools {
@@ -472,7 +422,7 @@ fn collect_solid_faces(
                 acc = match b.op.as_str() {
                     "union" => acc.union(tool),
                     "intersection" => acc.intersection(tool),
-                    _ => acc.difference(tool), // default: difference (cut)
+                    _ => acc.difference(tool),
                 };
             }
         }
@@ -481,24 +431,31 @@ fn collect_solid_faces(
             .clone()
             .or_else(|| colors.get(b.base.as_str()).cloned())
             .unwrap_or_else(|| layer_color.to_string());
-        emit_mesh(faces, &apply_cut(acc, cut), &color, layer_name, &b.id, cam);
+        out.push((acc, color, b.id.clone()));
     }
-
     for s in &cf.solids {
         if consumed.contains(s.id.as_str()) {
             continue;
         }
-        let (Some(m), Some(c)) = (meshes.get(s.id.as_str()), colors.get(s.id.as_str())) else {
-            continue;
-        };
-        emit_mesh(
-            faces,
-            &apply_cut(m.clone(), cut),
-            c,
-            layer_name,
-            &Some(s.id.clone()),
-            cam,
-        );
+        if let (Some(m), Some(c)) = (meshes.get(s.id.as_str()), colors.get(s.id.as_str())) {
+            out.push((m.clone(), c.clone(), Some(s.id.clone())));
+        }
+    }
+    out
+}
+
+/// Build the named [`mesh`] solids, apply each `[[boolean]]`, and emit the
+/// results. Solids consumed by a boolean are not drawn on their own.
+fn collect_solid_faces(
+    faces: &mut Vec<Face>,
+    layer_name: &str,
+    cf: &CfFile,
+    layer_color: &str,
+    cam: &Camera,
+    cut: Option<&Cut>,
+) {
+    for (mesh, color, id) in resolve_booleans(cf, layer_color) {
+        emit_mesh(faces, &apply_cut(mesh, cut), &color, layer_name, &id, cam);
     }
 }
 

From d64763995ae8169389ae06929f6b379a120faaf4 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 28 Jun 2026 14:15:19 -0500
Subject: [PATCH 15/39] docs: align README with standard structure, fix CI
 badge URL, add features/installation sections

---
 README.md | 189 +++++++++++++++++++-----------------------------------
 1 file changed, 66 insertions(+), 123 deletions(-)

diff --git a/README.md b/README.md
index 00e96b5..8e91978 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
 ```
 
 <p align="center">
-  <a href="https://github.com/UniverLab/cadforge/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/UniverLab/cadforge/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI"/></a>
+  <a href="https://github.com/UniverLab/cadspec/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/UniverLab/cadspec/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI"/></a>
   <a href="https://crates.io/crates/cadspec"><img src="https://img.shields.io/crates/v/cadspec?style=for-the-badge&logo=rust&logoColor=white" alt="Crates.io"/></a>
   <img src="https://img.shields.io/badge/Status-Active-27AE60?style=for-the-badge" alt="Status"/>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2E8B57?style=for-the-badge" alt="License"/></a>
@@ -23,90 +23,86 @@ cadspec is a **CAD as code** CLI tool and Rust library for declarative CAD model
 
 ---
 
-## Vibecoding CAD
-
-The core loop: **describe geometry in TOML, see it instantly, iterate.**
-
-```bash
-cadspec new casa && cd casa
-cadspec serve --open        # live preview in the browser
-```
+## Features
 
-Now edit any `.cf` file — by hand or by asking an AI agent — and the browser
-updates on every save. Parse errors and constraint violations appear as an
-overlay instead of a crash. When the design is right, `cadspec build` emits
-a deterministic, AutoCAD-compatible DXF.
-
-Agents get first-class support:
-
-- `cadspec schema` — full `.cf` language reference in one command; agents
-  self-discover the format without prior training.
-- `cadspec check --json` / `cadspec layers --json` — machine-readable
-  validation reports.
-- `cadspec preview` — a faithful PNG render (real text, measured dimension
-  labels, hatches, line styles) + `preview.meta.json` with per-entity bounding
-  boxes in world and pixel coordinates, so multimodal agents can *look* at the
-  plan and locate every entity in the image.
-- `cadspec preview --highlight ln-001,tx-002` — labeled amber markers around
-  specific entities, so an agent can visually confirm its edit landed where
-  intended.
-- `cadspec preview --format svg` — same render as vector SVG.
+- **📐 Declarative Geometry** — Define architectural elements (lines, rects, circles, arcs, polylines, text, dimensions) in TOML `.cf` files. Deterministic, reproducible, version-controlled.
+- **🛠️ Construction Tools** — `[[array]]` (linear and polar) and `[[mirror]]` expand into concrete primitives at build time; copies get derived ids.
+- **📏 Styled Dimensions** — Auto-measured labels with configurable `text_size`, `precision`, `show_units`, and `offset`.
+- **🔴 Live Preview** — `cadspec serve` runs a local server with pan/zoom, auto-reload on save (SSE), click-to-inspect, per-layer ghost/hide, 3D view, and build-error overlay.
+- **🔗 Layer System** — Organize geometry by layer with custom names, colors, and line weights.
+- **📄 DXF Export** — Compile `.cf` → DXF (AutoCAD-compatible). Full layer support, LWPOLYLINE, HATCH, MTEXT.
+- **🖼️ Previews for Agents** — Raster PNG + metadata JSON (entity bounding boxes) and full-fidelity SVG with real text, dimensions, line styles, and highlights.
+- **✅ Validation Engine** — `cadspec check` validates geometry and constraints; `--json` for tooling.
+- **🔄 Formatting** — `cadspec fmt` normalizes `.cf` files. `--check` mode for CI.
+- **🔍 DXF Import** — `cadspec import drawing.dxf` migrates existing drawings into `.cf` layers.
 
 ---
 
 ## Installation
 
+### Quick install (recommended)
+
 **Linux / macOS:**
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/UniverLab/cadspec/main/scripts/install.sh | sh
 ```
 
 **Windows (PowerShell):**
 
 ```powershell
-irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
+irm https://raw.githubusercontent.com/UniverLab/cadspec/main/scripts/install.ps1 | iex
 ```
 
-Or via cargo: `cargo install cadspec` — see [`docs/installation.md`](docs/installation.md) for all methods.
+### Via cargo
 
-## Documentation
+```bash
+cargo install cadspec
+```
 
-Full documentation lives in [`docs/`](docs/): installation, quick start, the
-`.cf` format, live preview, building & export, working with agents, and the
-complete CLI reference.
+Available on [crates.io](https://crates.io/crates/cadspec).
+
+### From source
+
+```bash
+git clone https://github.com/UniverLab/cadspec.git
+cd cadspec
+cargo build --release
+# Binary at target/release/cadspec
+```
+
+### GitHub Releases
+
+Check the [Releases](https://github.com/UniverLab/cadspec/releases) page for precompiled binaries (Linux x86_64, macOS x86_64/ARM64, Windows x86_64).
+
+### Uninstall
+
+```bash
+rm -f ~/.local/bin/cadspec
+```
 
 ---
 
+## Quick Start
 
-## Features
+```bash
+cadspec new casa && cd casa
+cadspec serve --open        # live preview in the browser
+```
 
-### 🎯 Core Platform
+Edit any `.cf` file — the browser updates on every save. When the design is right:
 
-- **📐 Declarative Geometry** — Define architectural elements (lines, rects, circles, arcs, polylines, text, dimensions) in TOML `.cf` files. Deterministic, reproducible, version-controlled.
-- **🛠️ Construction Tools** — `[[array]]` (linear and polar: spiral staircases, gear teeth, repeated columns) and `[[mirror]]` expand into concrete primitives at build time; copies get derived ids (`base@1`, `base@m`).
-- **📏 Styled Dimensions** — Auto-measured labels with configurable `text_size`, `precision`, `show_units`, and `offset` per dimension.
-- **🔴 Live Preview** — `cadspec serve` runs a local server with pan/zoom, auto-reload on save (SSE), click-to-inspect any entity (copy its source TOML as an agent prompt), per-layer ghost/hide states, a 3D stacked-layers view, and a build-error overlay. Zero config.
-- **🔗 Layer System** — Organize geometry by layer with custom names, colors, and line weights. Compile single layers or full projects.
-- **📄 DXF Export** — Compile `.cf` → DXF (AutoCAD-compatible). Full layer support, LWPOLYLINE for polylines, HATCH for solid fills, MTEXT for annotations.
-- **🖼️ Previews for Agents** — Raster PNG + metadata JSON (entity bounding boxes) and full-fidelity SVG with real text, auto-measured dimensions, line styles, and clipped hatch patterns.
-- **✅ Validation Engine** — `cadspec check` validates geometry and constraints without generating output; `--json` for tooling.
-
-### 🏗️ Project Management
-
-- **Project Scaffolding** — `cadspec new` creates a multi-layer starter project (shapes, curves, annotations) that showcases the core `.cf` primitives.
-- **Multi-Layer Compilation** — Compile all layers or target specific layers with `--layer`. Custom output path with `--output`.
-- **Auto-Rebuild** — `cadspec watch` monitors `.cf` and `.toml` files and auto-rebuilds DXF on changes with 300ms debounce.
-- **Code Formatting** — `cadspec fmt` normalizes `.cf` files. `--check` mode for CI validation.
-- **Constraints** — `parent`, `belongs_to`, and `spatial_dependency` rules between layers; warnings by default, build-blocking with `strict = true`.
-- **DXF Import** — `cadspec import plano.dxf` migrates existing drawings into `.cf` layers + `project.toml`.
-
-### 🔧 Architecture
-
-- **Compiler Pipeline** — Parse → Resolve → Compile → Emit. Modular design for easy extension.
-- **DXF Writer** — Direct DXF entity writing with proper AutoCAD compatibility. Layer/color/lineweight mapping.
-- **Renderer** — One handwritten SVG backend; the PNG preview rasterizes it via resvg with an embedded monospace font (deterministic text on any machine, including fontless containers).
-- **Error Reporting** — Structured errors with file, line, and context. Fast-fail on validation errors.
+```bash
+cadspec build                        # default output.dxf
+cadspec build --output plano.dxf     # custom output path
+cadspec build --layer muros          # compile single layer
+```
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/): installation, quick start, the
+`.cf` format, live preview, building & export, working with agents, and the
+complete CLI reference.
 
 ---
 
@@ -115,7 +111,7 @@ complete CLI reference.
 | Command | Description |
 |---------|-------------|
 | `cadspec new <name>` | Create a new project with multi-layer scaffold |
-| `cadspec init` | Initialize CADspec in current directory |
+| `cadspec init` | Initialize cadspec in current directory |
 | `cadspec build` | Compile project to DXF |
 | `cadspec build --check` | Validate project and constraints without generating DXF |
 | `cadspec build --output <path>` | Compile to custom output path |
@@ -235,24 +231,6 @@ Run `cadspec schema` for the complete reference with all attributes.
 
 ---
 
-## Main Modules
-
-- `compiler/` — Project compilation pipeline, layer targeting, validation, JSON reports
-- `dxf_writer/` — DXF entity writing, LWPOLYLINE, HATCH, MTEXT generation
-- `preview/` — PNG rendering with configurable resolution, layer filtering, metadata JSON
-- `svg/` — Vector SVG rendering: real text, measured dimensions, hatch clipping, grid
-- `serve/` — Live preview server: file watcher + SSE auto-reload + error overlay
-- `schema/` — Embedded `.cf` language reference for humans and agents
-- `parser/` — TOML parsing, primitive extraction, array-of-tables handling
-- `model/` — Data structures: Layer, Primitive, Project
-- `scaffold/` — Multi-layer project creation with architectural examples
-- `fmt/` — .cf file formatting and normalization
-- `watch/` — File system watcher with auto-rebuild and debounce
-- `importer/` — DXF → `.cf` migration
-- `color/` — Color parsing and DXF color mapping
-
----
-
 ## Data Storage
 
 | Data | Location | Format |
@@ -265,51 +243,16 @@ Run `cadspec schema` for the complete reference with all attributes.
 
 ---
 
-## Usage
-
-**Create a new project:**
-```bash
-cadspec new mi-proyecto
-cd mi-proyecto
-```
-
-**Live preview while you edit:**
-```bash
-cadspec serve --open    # browser refreshes on every save
-```
-
-**Edit `.cf` files** (TOML format with your geometry — run `cadspec schema` for the reference)
-
-**Format and validate:**
-```bash
-cadspec fmt           # normalize .cf files
-cadspec check         # validate without generating DXF
-```
-
-**Compile to DXF:**
-```bash
-cadspec build                        # default output.dxf
-cadspec build --output plano.dxf     # custom output path
-cadspec build --layer muros          # compile single layer
-```
-
-**Preview:**
-```bash
-cadspec preview                          # default 1600x1200 (fits content aspect)
-cadspec preview --width 1024 --height 768  # custom resolution
-cadspec preview --layer muros            # single layer preview
-```
-
-**Auto-rebuild on changes:**
-```bash
-cadspec watch       # monitors .cf and .toml files
-```
-
----
-
 ## Tech Stack
 
-| Rust 2021 | clap | toml | toml_edit | resvg | dxf | notify | anyhow | serde |
+| Concern | Crate |
+|---|---|
+| CLI parsing | `clap` (derive) |
+| Error handling | `anyhow` |
+| Serialization | `serde` + `toml` + `toml_edit` |
+| DXF output | `dxf` |
+| File watching | `notify` |
+| PNG rasterization | `resvg` |
 
 ---
 

From d7fa7a1c8805dc774c8e19b4d7b9296fbda97ce8 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Tue, 30 Jun 2026 18:42:57 -0500
Subject: [PATCH 16/39] ci: drop redundant push trigger, rely on PR checks
 (branches protected)

---
 .github/workflows/ci.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 070f1a6..3f91eeb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,8 +3,6 @@ name: CI
 on:
   pull_request:
   workflow_dispatch:
-  push:
-    branches: [main]
 
 jobs:
   rust-ci:

From c8cb6205258c27805f52e6332550e17bbccef30a Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Tue, 30 Jun 2026 19:02:33 -0500
Subject: [PATCH 17/39] fix: replace remaining cadforge URLs with cadspec and
 add MIT LICENSE file

---
 Cargo.toml           |  4 ++--
 LICENSE              | 21 +++++++++++++++++++++
 docs/installation.md |  6 +++---
 scripts/install.ps1  |  4 ++--
 scripts/install.sh   |  4 ++--
 5 files changed, 30 insertions(+), 9 deletions(-)
 create mode 100644 LICENSE

diff --git a/Cargo.toml b/Cargo.toml
index 193ae4b..eb61594 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,8 +4,8 @@ version = "0.1.0-beta.2"
 edition = "2021"
 description = "CAD as code — deterministic geometry engine for reproducible CAD drawings"
 license = "MIT"
-homepage = "https://github.com/UniverLab/cadforge"
-repository = "https://github.com/UniverLab/cadforge"
+homepage = "https://github.com/UniverLab/cadspec"
+repository = "https://github.com/UniverLab/cadspec"
 publish = true
 exclude = ["crates/**"]
 
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f50fef1
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jheison Morales
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/installation.md b/docs/installation.md
index 6581b62..25e9df6 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -14,13 +14,13 @@ order: 2
 **Linux / macOS:**
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/UniverLab/cadspec/main/scripts/install.sh | sh
 ```
 
 **Windows (PowerShell):**
 
 ```powershell
-irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
+irm https://raw.githubusercontent.com/UniverLab/cadspec/main/scripts/install.ps1 | iex
 ```
 
 ## Via cargo
@@ -34,7 +34,7 @@ Available on [crates.io](https://crates.io/crates/cadspec).
 ## From source
 
 ```bash
-git clone https://github.com/UniverLab/cadforge.git
+git clone https://github.com/UniverLab/cadspec.git
 cd cadspec
 cargo build --release
 # Binary at target/release/cadspec
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index cb014f1..8d1d357 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -1,5 +1,5 @@
 # install.ps1 — download and install cadspec on Windows
-# Usage: irm https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.ps1 | iex
+# Usage: irm https://raw.githubusercontent.com/UniverLab/cadspec/main/scripts/install.ps1 | iex
 #
 # Options (set as env vars before running):
 #   $env:VERSION    = "0.1.0"           # pin a specific version
@@ -7,7 +7,7 @@
 
 $ErrorActionPreference = "Stop"
 
-$Repo       = "UniverLab/cadforge"
+$Repo       = "UniverLab/cadspec"
 $Binary     = "cadspec.exe"
 $Target     = "x86_64-pc-windows-msvc"
 $InstallDir = if ($env:INSTALL_DIR) { $env:INSTALL_DIR } else { "$env:USERPROFILE\.local\bin" }
diff --git a/scripts/install.sh b/scripts/install.sh
index d98cf33..2edebc2 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1,9 +1,9 @@
 #!/bin/sh
 # install.sh — download and install cadspec from GitHub Releases
-# Usage: curl -fsSL https://raw.githubusercontent.com/UniverLab/cadforge/main/scripts/install.sh | sh
+# Usage: curl -fsSL https://raw.githubusercontent.com/UniverLab/cadspec/main/scripts/install.sh | sh
 set -eu
 
-REPO="UniverLab/cadforge"
+REPO="UniverLab/cadspec"
 BINARY="cadspec"
 INSTALL_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
 

From d84808a0d89c0a49cc8dc42b8a092cce3e587a59 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Tue, 30 Jun 2026 19:06:28 -0500
Subject: [PATCH 18/39] feat(install): verify SHA256 checksum of downloaded
 archive

---
 scripts/install.ps1 | 20 ++++++++++++++++++++
 scripts/install.sh  | 23 +++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 8d1d357..fae492a 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -55,6 +55,26 @@ try {
     Fail "Download failed: $_`nURL: $Url"
 }
 
+# --- verify checksum ---
+# Match against SHA256SUMS.txt from the same release. Missing sums file (older
+# releases) -> skip; a present-but-mismatched checksum is fatal.
+$SumsUrl = "https://github.com/$Repo/releases/download/$Tag/SHA256SUMS.txt"
+$SumsOk  = $false
+try {
+    Invoke-WebRequest -Uri $SumsUrl -OutFile "$Tmp\SHA256SUMS.txt" -UseBasicParsing
+    $SumsOk = $true
+} catch {
+    Info "checksum" "SHA256SUMS.txt not found for $Tag - skipping verification"
+}
+if ($SumsOk) {
+    $line = Select-String -Path "$Tmp\SHA256SUMS.txt" -Pattern ([regex]::Escape($Archive)) | Select-Object -First 1
+    if (-not $line) { Fail "No checksum listed for $Archive in SHA256SUMS.txt" }
+    $expected = ($line.Line -split '\s+')[0].ToLower()
+    $actual   = (Get-FileHash "$Tmp\$Archive" -Algorithm SHA256).Hash.ToLower()
+    if ($actual -ne $expected) { Fail "Checksum mismatch for $Archive (expected $expected, got $actual)" }
+    Info "checksum" "verified"
+}
+
 # --- extract ---
 Expand-Archive -Path "$Tmp\$Archive" -DestinationPath $Tmp -Force
 $extracted = Join-Path $Tmp $Binary
diff --git a/scripts/install.sh b/scripts/install.sh
index 2edebc2..dc63bea 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -59,6 +59,29 @@ info "download" "$URL"
 HTTP_CODE=$(curl -fSL -w '%{http_code}' -o "$TMPDIR/$ARCHIVE" "$URL" 2>/dev/null) || true
 [ "$HTTP_CODE" = "200" ] || error "Download failed (HTTP $HTTP_CODE). Check that $TAG exists for $TARGET at:\n  $URL"
 
+# --- verify checksum ---
+# Match against SHA256SUMS.txt from the same release. Missing sums file (older
+# releases) or no sha256 tool → skip; a present-but-mismatched checksum is fatal.
+SUMS_URL="https://github.com/$REPO/releases/download/${TAG}/SHA256SUMS.txt"
+if curl -fsSL -o "$TMPDIR/SHA256SUMS.txt" "$SUMS_URL" 2>/dev/null; then
+  EXPECTED=$(awk -v f="$ARCHIVE" '$2 == f { print $1 }' "$TMPDIR/SHA256SUMS.txt" | head -1)
+  [ -n "$EXPECTED" ] || error "No checksum listed for $ARCHIVE in SHA256SUMS.txt"
+  if command -v sha256sum >/dev/null 2>&1; then
+    ACTUAL=$(sha256sum "$TMPDIR/$ARCHIVE" | awk '{ print $1 }')
+  elif command -v shasum >/dev/null 2>&1; then
+    ACTUAL=$(shasum -a 256 "$TMPDIR/$ARCHIVE" | awk '{ print $1 }')
+  else
+    ACTUAL=""
+    info "checksum" "no sha256 tool found — skipping verification"
+  fi
+  if [ -n "$ACTUAL" ]; then
+    [ "$ACTUAL" = "$EXPECTED" ] || error "Checksum mismatch for $ARCHIVE (expected $EXPECTED, got $ACTUAL)"
+    info "checksum" "verified"
+  fi
+else
+  info "checksum" "SHA256SUMS.txt not found for $TAG — skipping verification"
+fi
+
 # --- extract ---
 tar xzf "$TMPDIR/$ARCHIVE" -C "$TMPDIR"
 [ -f "$TMPDIR/$BINARY" ] || error "Binary not found in archive"

From 79223694b701c9d4c0cfcb4c0f51ee6e879fa57d Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 06:08:09 -0500
Subject: [PATCH 19/39] fix(dxf): write real layer colors to DXF layer table
 without duplicate records

compile_project registered every layer with ACI 7 (white) and compile_cf
re-added it with the actual color; the dxf crate appends layer records, so
the output contained two LAYER table entries per layer and external CAD
readers picked the white one. Layers are now registered once, after loading
the .cf files, using each layer's [layer].color.

DxfWriter::add_layer is now an upsert: re-adding an existing layer updates
its color instead of duplicating the table record.

hex_to_aci previously matched only 9 exact hex strings and silently mapped
everything else to white, so common colors like #FF4444 or #00CC44 lost all
color in the exported DXF and on import roundtrip. It now maps any parseable
color to the nearest entry of the standard ACI palette.

The roundtrip integration test now uses a non-palette layer color and
asserts the layer table has no duplicate records.
---
 src/color.rs         | 57 ++++++++++++++++++++++++++++++++++----------
 src/compiler.rs      | 10 +++++---
 src/dxf_writer.rs    |  6 +++++
 tests/integration.rs | 14 +++++++++--
 4 files changed, 69 insertions(+), 18 deletions(-)

diff --git a/src/color.rs b/src/color.rs
index ba1da47..ac38766 100644
--- a/src/color.rs
+++ b/src/color.rs
@@ -1,19 +1,41 @@
 //! Color and weight conversion utilities for DXF output.
 
-/// ACI color index from hex string (best-effort mapping to standard palette).
+/// Standard ACI palette (indices 1-9) as RGB triples.
+const ACI_PALETTE: [(u8, (u8, u8, u8)); 9] = [
+    (1, (0xFF, 0x00, 0x00)), // red
+    (2, (0xFF, 0xFF, 0x00)), // yellow
+    (3, (0x00, 0xFF, 0x00)), // green
+    (4, (0x00, 0xFF, 0xFF)), // cyan
+    (5, (0x00, 0x00, 0xFF)), // blue
+    (6, (0xFF, 0x00, 0xFF)), // magenta
+    (7, (0xFF, 0xFF, 0xFF)), // white
+    (8, (0x80, 0x80, 0x80)), // dark grey
+    (9, (0xC0, 0xC0, 0xC0)), // light grey
+];
+
+/// ACI color index from hex string: nearest color in the standard palette
+/// (unparseable input falls back to 7, white).
 pub fn hex_to_aci(hex: &str) -> u8 {
-    match hex.to_uppercase().trim_start_matches('#') {
-        "FF0000" => 1, // red
-        "FFFF00" => 2, // yellow
-        "00FF00" => 3, // green
-        "00FFFF" => 4, // cyan
-        "0000FF" => 5, // blue
-        "FF00FF" => 6, // magenta
-        "FFFFFF" => 7, // white
-        "808080" => 8, // dark grey
-        "C0C0C0" => 9, // light grey
-        _ => 7,        // default white
+    let hex = hex.trim_start_matches('#');
+    let Ok(rgb) = u32::from_str_radix(hex, 16) else {
+        return 7;
+    };
+    if hex.len() != 6 {
+        return 7;
     }
+    let (r, g, b) = (
+        (rgb >> 16) as i32,
+        ((rgb >> 8) & 0xFF) as i32,
+        (rgb & 0xFF) as i32,
+    );
+    ACI_PALETTE
+        .iter()
+        .min_by_key(|(_, (pr, pg, pb))| {
+            let (dr, dg, db) = (r - *pr as i32, g - *pg as i32, b - *pb as i32);
+            dr * dr + dg * dg + db * db
+        })
+        .map(|(index, _)| *index)
+        .unwrap_or(7)
 }
 
 /// Hex color from an ACI color index (inverse of `hex_to_aci`).
@@ -52,7 +74,16 @@ mod tests {
         assert_eq!(hex_to_aci("#FF0000"), 1);
         assert_eq!(hex_to_aci("#00FF00"), 3);
         assert_eq!(hex_to_aci("#FFFFFF"), 7);
-        assert_eq!(hex_to_aci("#123456"), 7); // unknown → white
+    }
+
+    #[test]
+    fn hex_to_aci_maps_arbitrary_colors_to_nearest() {
+        assert_eq!(hex_to_aci("#FF4444"), 1); // reddish → red
+        assert_eq!(hex_to_aci("#00CC44"), 3); // greenish → green
+        assert_eq!(hex_to_aci("#2244CC"), 5); // bluish → blue
+        assert_eq!(hex_to_aci("#123456"), 8); // dark muted → dark grey
+        assert_eq!(hex_to_aci("#invalid"), 7); // unparseable → white
+        assert_eq!(hex_to_aci("#FFF"), 7); // wrong length → white
     }
 
     #[test]
diff --git a/src/compiler.rs b/src/compiler.rs
index 48f9518..5d73fda 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -333,11 +333,15 @@ pub fn compile_project(
     let project = parse_project(&project_dir.join("project.toml"))?;
     let mut writer = DxfWriter::new();
 
+    let loaded_layers = load_layers(project_dir, &project.layers)?;
     for name in project.layers.keys() {
-        writer.add_layer(name, 7);
+        let color = loaded_layers
+            .get(name)
+            .and_then(|cf| cf.layer_meta.as_ref())
+            .and_then(|meta| meta.color.as_deref())
+            .unwrap_or("#FFFFFF");
+        writer.add_layer(name, hex_to_aci(color));
     }
-
-    let loaded_layers = load_layers(project_dir, &project.layers)?;
     let issues = validate_constraints(&project, &loaded_layers);
     let strict = is_strict(&project);
     if !issues.is_empty() {
diff --git a/src/dxf_writer.rs b/src/dxf_writer.rs
index d20487f..f4fc7ca 100644
--- a/src/dxf_writer.rs
+++ b/src/dxf_writer.rs
@@ -51,7 +51,13 @@ impl DxfWriter {
     }
 
     /// Add a named layer with an ACI color index (1-255).
+    /// Re-adding an existing layer updates its color instead of duplicating
+    /// the LAYER table record.
     pub fn add_layer(&mut self, name: &str, color_index: u8) {
+        if let Some(existing) = self.drawing.layers_mut().find(|l| l.name == name) {
+            existing.color = Color::from_index(color_index);
+            return;
+        }
         let layer = Layer {
             name: name.to_string(),
             color: Color::from_index(color_index),
diff --git a/tests/integration.rs b/tests/integration.rs
index da3f780..f108efe 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -442,7 +442,7 @@ fn import_roundtrip_recovers_dims_styles_and_colors() {
         dir.join("plano.cf"),
         r##"[layer]
 name = "plano"
-color = "#FF0000"
+color = "#FF4444"
 
 [[line]]
 id = "ln-base"
@@ -476,12 +476,22 @@ offset = -1.2
     let dxf_path = dir.join("output.dxf");
     compile_project(dir, None, Some(&dxf_path)).unwrap();
 
+    // Each layer appears exactly once in the DXF LAYER table ('0' + 'plano'),
+    // and 'plano' carries its ACI color instead of the default white.
+    let dxf_text = fs::read_to_string(&dxf_path).unwrap();
+    assert_eq!(
+        dxf_text.matches("AcDbLayerTableRecord").count(),
+        2,
+        "duplicate LAYER table records"
+    );
+
     let imported = Path::new("/tmp/cadspec_roundtrip_fidelity_out");
     let _ = fs::remove_dir_all(imported);
     import_dxf(&dxf_path, imported, None).unwrap();
     let cf = fs::read_to_string(imported.join("plano.cf")).unwrap();
 
-    // Layer color survives via the DXF layer table (ACI)
+    // Layer color survives via the DXF layer table (ACI): #FF4444 is not in
+    // the standard palette, so it comes back as the nearest ACI color (red).
     assert!(
         cf.contains("color = \"#FF0000\""),
         "layer color lost:\n{cf}"

From c37145a1ef282ed31857bdb96e58c0ac1b688f15 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 06:08:43 -0500
Subject: [PATCH 20/39] fix(cli): translate build success output to English

The build summary ("DXF generado", "entidades en capas") was the only
Spanish output left in an otherwise English CLI. Align it with the rest of
the command surface and the docs.
---
 src/compiler.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/compiler.rs b/src/compiler.rs
index 5d73fda..c612a02 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -373,14 +373,14 @@ pub fn compile_project(
         .unwrap_or_else(|| project_dir.join("output.dxf"));
     writer.save(&output_path)?;
 
-    println!("✓ DXF generado: {}", output_path.display());
+    println!("✓ DXF generated: {}", output_path.display());
     println!(
-        "  {} entidades en {} capas",
+        "  {} entities in {} layers",
         total_entities,
         layer_stats.len()
     );
     for (name, count) in &layer_stats {
-        println!("    {}: {} entidades", name, count);
+        println!("    {}: {} entities", name, count);
     }
     Ok(())
 }

From dcf2dd0429c4ff79703dff0cb9e91d55edd88ea5 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 06:10:22 -0500
Subject: [PATCH 21/39] docs: document serve daemon flags, preview
 --plano/--format all, import --output

The CLI reference and guides were missing flags that exist on the real
surface: serve's background/daemon behavior (--foreground, --stop),
preview --format all and --plano (drawing sheets declared as [[plano]] in
project.toml), and import --output.
---
 docs/building-and-export.md | 1 +
 docs/cli-reference.md       | 7 ++++++-
 docs/live-preview.md        | 8 ++++++--
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/docs/building-and-export.md b/docs/building-and-export.md
index 1f2b42d..59b6f4a 100644
--- a/docs/building-and-export.md
+++ b/docs/building-and-export.md
@@ -50,6 +50,7 @@ cadspec fmt --check   # CI-friendly check mode
 ```bash
 cadspec import plano.dxf                 # all layers
 cadspec import plano.dxf --layer muros   # a single DXF layer
+cadspec import plano.dxf --output casa   # into a specific directory
 ```
 
 Import migrates an existing DXF into `.cf` layer files plus a
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 61e387a..e51dafb 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -26,15 +26,19 @@ cadspec <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `cadspec serve` | Live preview server — browser auto-reloads on save |
+| `cadspec serve` | Live preview server (background) — browser auto-reloads on save |
 | `cadspec serve --open --port <p>` | Open browser automatically on a custom port |
+| `cadspec serve --foreground` | Stay attached: stream logs, stop with Ctrl+C |
+| `cadspec serve --stop` | Stop the background server running for this project |
 | `cadspec preview` | Faithful PNG render + `preview.meta.json` |
 | `cadspec preview --format svg` | Vector SVG preview (same renderer) |
+| `cadspec preview --format all` | Both PNG and SVG in one pass |
 | `cadspec preview --3d` | Axonometric 3D view (extrusions + solids) |
 | `cadspec preview --format gltf` | Export the 3D solids to `scene.gltf` (interactive 3D / interchange) |
 | `cadspec preview --highlight <ids>` | Amber markers around specific entities |
 | `cadspec preview --width <w> -H <h>` | Custom resolution |
 | `cadspec preview --layer <name>` | Preview a specific layer only |
+| `cadspec preview --plano <name>` | Render a named drawing sheet (`[[plano]]` in `project.toml`) |
 | `cadspec view` | Open the project in the configured viewer |
 | `cadspec view --layer <name>` | Open only one layer in the viewer |
 
@@ -56,6 +60,7 @@ cadspec <command> [options]
 |---------|-------------|
 | `cadspec import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
 | `cadspec import <file.dxf> --layer <name>` | Import only one DXF layer |
+| `cadspec import <file.dxf> --output <dir>` | Import into a specific directory |
 | `cadspec config set <key> <value>` | Set global defaults (`author`, `units`) |
 | `cadspec config show` | Show global defaults |
 
diff --git a/docs/live-preview.md b/docs/live-preview.md
index 56bf566..6fa2694 100644
--- a/docs/live-preview.md
+++ b/docs/live-preview.md
@@ -7,12 +7,16 @@ order: 5
 # Live Preview
 
 ```bash
-cadspec serve                       # start the local preview server
+cadspec serve                       # start the local preview server (background)
 cadspec serve --open --port 4377    # open browser, custom port
+cadspec serve --foreground          # stay attached, stream logs, Ctrl+C to stop
+cadspec serve --stop                # stop the background server for this project
 ```
 
 `cadspec serve` runs a zero-config local server with auto-reload on
-save (SSE). Edit a `.cf` file and the browser updates instantly.
+save (SSE). Edit a `.cf` file and the browser updates instantly. By
+default it detaches into the background and keeps the terminal free;
+use `--foreground` to stay attached or `--stop` to shut it down.
 
 ## Controls
 

From 1a7695aceaf1d5fddcad38e5bcc3e045d4024741 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 06:11:26 -0500
Subject: [PATCH 22/39] docs: add drawing sheets (planos) section to
 building-and-export guide

The [[plano]] project.toml feature (named views on paper-sized sheets with
title blocks, including section cuts) had no user documentation beyond the
new CLI reference row. Document the declaration keys, the available views,
and the preview --plano workflow, all verified against the real CLI.
---
 docs/building-and-export.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/building-and-export.md b/docs/building-and-export.md
index 59b6f4a..9e881f8 100644
--- a/docs/building-and-export.md
+++ b/docs/building-and-export.md
@@ -20,6 +20,38 @@ DXF. Export uses proper AutoCAD-compatible entities — LWPOLYLINE for
 polylines, HATCH for solid fills, MTEXT for annotations — with full
 layer/color/lineweight mapping.
 
+## Drawing sheets (planos)
+
+A *plano* is a named view of the model rendered onto a paper-sized sheet
+with a frame and a title block (rótulo). Declare sheets in `project.toml`
+and render them with `cadspec preview --plano <name>`:
+
+```toml
+[[plano]]
+name = "general"
+view = "plan"            # plan | iso | front | back | left | right | top | section
+scale = "1:100"          # label shown in the title block
+size = [420.0, 297.0]    # paper size in mm (default A3 landscape)
+title = "Planta general" # defaults to the plano name
+
+[[plano]]
+name = "corte-a"
+view = "section"
+cut_axis = "x"           # section only: x | y | z
+cut_at = 4.0             # position of the cut plane along cut_axis
+keep = "min"             # which side to keep: min (default) | max
+```
+
+```bash
+cadspec preview --plano general              # render one sheet
+cadspec preview --plano corte-a --format svg
+```
+
+The title block is generated from the project metadata; set `rotulo =
+"titleblock.cf"` on a plano to draw a custom one with the same `.cf`
+primitives as the rest of the drawing. The live preview (`cadspec
+serve`) lists all declared planos in a panel.
+
 ## Validation
 
 ```bash

From 1adf706ef5055e485b23bfa656533401624da6ae Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 18:35:51 -0500
Subject: [PATCH 23/39] docs: correct DXF entity claims (no native HATCH/MTEXT)

The build pipeline never emitted HATCH or MTEXT entities: filled regions
compile to fan-triangulated SOLID entities, hatch patterns to clipped
LINE segments (the dxf crate has no native HATCH), and annotations to
TEXT. Update README and the building-and-export guide to describe the
entities actually written.
---
 README.md                   | 2 +-
 docs/building-and-export.md | 5 ++++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8e91978..a46b719 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ cadspec is a **CAD as code** CLI tool and Rust library for declarative CAD model
 - **📏 Styled Dimensions** — Auto-measured labels with configurable `text_size`, `precision`, `show_units`, and `offset`.
 - **🔴 Live Preview** — `cadspec serve` runs a local server with pan/zoom, auto-reload on save (SSE), click-to-inspect, per-layer ghost/hide, 3D view, and build-error overlay.
 - **🔗 Layer System** — Organize geometry by layer with custom names, colors, and line weights.
-- **📄 DXF Export** — Compile `.cf` → DXF (AutoCAD-compatible). Full layer support, LWPOLYLINE, HATCH, MTEXT.
+- **📄 DXF Export** — Compile `.cf` → DXF (AutoCAD-compatible). Full layer support, LWPOLYLINE polygons, LINE/CIRCLE/ARC geometry, TEXT annotations, DIMENSION entities, and SOLID-filled regions.
 - **🖼️ Previews for Agents** — Raster PNG + metadata JSON (entity bounding boxes) and full-fidelity SVG with real text, dimensions, line styles, and highlights.
 - **✅ Validation Engine** — `cadspec check` validates geometry and constraints; `--json` for tooling.
 - **🔄 Formatting** — `cadspec fmt` normalizes `.cf` files. `--check` mode for CI.
diff --git a/docs/building-and-export.md b/docs/building-and-export.md
index 9e881f8..15f4e0c 100644
--- a/docs/building-and-export.md
+++ b/docs/building-and-export.md
@@ -17,7 +17,10 @@ cadspec build --check               # validate only, no DXF
 
 The output is deterministic: identical input produces a bit-identical
 DXF. Export uses proper AutoCAD-compatible entities — LWPOLYLINE for
-polylines, HATCH for solid fills, MTEXT for annotations — with full
+polylines and rectangles, LINE/CIRCLE/ARC for open geometry, TEXT for
+annotations, DIMENSION for measured dims, and SOLID (fan-triangulated)
+for filled regions. Hatch patterns are emitted as clipped LINE segments
+(the `dxf` crate has no native HATCH entity). All entities carry full
 layer/color/lineweight mapping.
 
 ## Drawing sheets (planos)

From 209d3456e5a69a502ad8ce4617b319112f069862 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 18:36:37 -0500
Subject: [PATCH 24/39] fix(compiler): warn instead of silently dropping
 unresolved hatch/fill boundaries

A hatch or fill whose `boundary` id did not match a closed polyline or
rect in the same layer file was skipped with no diagnostic, so a filled
region could silently vanish from the DXF. Emit a stderr warning naming
the entity, its layer, and the missing boundary id; the build still
succeeds. Boundaries remain resolved per layer file.
---
 src/compiler.rs | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/src/compiler.rs b/src/compiler.rs
index c612a02..a74e1a8 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -679,6 +679,8 @@ fn compile_cf(writer: &mut DxfWriter, cf: &CfFile, default_layer: &str) {
 
         if let Some(boundary) = resolve_boundary(&e.boundary, cf) {
             writer.hatch(&boundary, e.angle, spacing, layer, &style);
+        } else {
+            warn_unresolved_boundary("hatch", e.common.id.as_deref(), &e.boundary, default_layer);
         }
     }
 
@@ -688,7 +690,16 @@ fn compile_cf(writer: &mut DxfWriter, cf: &CfFile, default_layer: &str) {
         let style = resolve_style(&e.common);
 
         let pts = if let Some(ref boundary_id) = e.boundary {
-            resolve_boundary(boundary_id, cf)
+            let resolved = resolve_boundary(boundary_id, cf);
+            if resolved.is_none() {
+                warn_unresolved_boundary(
+                    "fill",
+                    e.common.id.as_deref(),
+                    boundary_id,
+                    default_layer,
+                );
+            }
+            resolved
         } else {
             e.points
                 .as_ref()
@@ -701,6 +712,20 @@ fn compile_cf(writer: &mut DxfWriter, cf: &CfFile, default_layer: &str) {
     }
 }
 
+/// Warn (without failing the build) when a hatch/fill references a boundary id
+/// that does not resolve to any closed polyline or rect in the same layer file.
+/// Boundaries are resolved per layer file; a reference to an id defined in a
+/// different layer will not resolve and the region is skipped.
+fn warn_unresolved_boundary(kind: &str, entity_id: Option<&str>, boundary: &str, layer: &str) {
+    let who = entity_id
+        .map(|id| format!("'{}'", id))
+        .unwrap_or_else(|| "<unnamed>".to_string());
+    eprintln!(
+        "warning: {kind} {who} in layer '{layer}' references boundary '{boundary}', \
+         which is not a closed polyline or rect in this layer — region skipped"
+    );
+}
+
 /// Resolve a boundary id to a list of (x,y) points from polylines or rects in the file.
 pub fn resolve_boundary(id: &str, cf: &CfFile) -> Option<Vec<(f64, f64)>> {
     // Search polylines

From ddb0102ead9d86a700c1afb5f33a487dca4e7b9a Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 18:37:20 -0500
Subject: [PATCH 25/39] fix(examples): make vivienda closet fill resolve to a
 real region

The fl-closet-d1 fill referenced boundary rc-closet-d1, which is defined
in muros.cf; since boundaries resolve per layer file the reference never
matched and the fill was skipped (no SOLID in the DXF, no fill in the
preview). Use inline points matching that rect so the closet renders as a
filled region in both DXF and preview.
---
 examples/vivienda/achurados.cf | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/examples/vivienda/achurados.cf b/examples/vivienda/achurados.cf
index b8b2dc8..9f49727 100644
--- a/examples/vivienda/achurados.cf
+++ b/examples/vivienda/achurados.cf
@@ -17,9 +17,11 @@ scale = 2.0
 angle = 45.0
 
 # ── Relleno solido del closet dormitorio 1 ─────────────────
+# Coincide con el rect rc-closet-d1 de muros.cf (origen [0,7], 1.2 x 2.0).
+# Se usan puntos en linea porque los boundary se resuelven por archivo de capa.
 [[fill]]
 id = "fl-closet-d1"
-boundary = "rc-closet-d1"
+points = [[0.0, 7.0], [1.2, 7.0], [1.2, 9.0], [0.0, 9.0]]
 color = "#E0E0E0"
 
 # ── Achurado de la cocina ───────────────────────────────────

From ba52f41dc4ed056ab360e0051fe94fe6d8df7401 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 18:41:59 -0500
Subject: [PATCH 26/39] feat(import): recover SOLID fills instead of dropping
 them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The importer skipped SOLID entities as unsupported, so a build → import
round-trip lost every filled region. Import SOLIDs as fill polygons and
fuse edge-adjacent ones per layer back into a single `[[fill]]`: the
fan-triangulated triangles `cadspec build` emits are stitched into their
original boundary by dropping shared interior edges and chaining the
remaining boundary edges into one ring. Disjoint fills stay separate, and
a ring that can't be stitched cleanly falls back to per-triangle fills.
Recovers fill color/lineweight and keeps the entity count stable across
round-trips.
---
 docs/building-and-export.md |   6 +
 src/importer.rs             | 299 +++++++++++++++++++++++++++++++++++-
 2 files changed, 304 insertions(+), 1 deletion(-)

diff --git a/docs/building-and-export.md b/docs/building-and-export.md
index 15f4e0c..6f9f855 100644
--- a/docs/building-and-export.md
+++ b/docs/building-and-export.md
@@ -90,6 +90,12 @@ cadspec import plano.dxf --output casa   # into a specific directory
 
 Import migrates an existing DXF into `.cf` layer files plus a
 `project.toml`, so legacy drawings can join the declarative workflow.
+Lines, polylines, circles, arcs, text, points and dimensions map back to
+their `.cf` primitives. Filled regions are reconstructed too: adjacent
+SOLID entities on a layer (such as the fan-triangulated fills that
+`cadspec build` emits) are fused back into a single `[[fill]]` with its
+original boundary, so an export/import round-trip does not inflate the
+entity count.
 
 ## Pipeline
 
diff --git a/src/importer.rs b/src/importer.rs
index 7c2ba44..68dcfa6 100644
--- a/src/importer.rs
+++ b/src/importer.rs
@@ -9,7 +9,7 @@ use std::fs;
 use std::path::{Path, PathBuf};
 
 /// Per-entity style recovered from DXF (true color, lineweight, line type).
-#[derive(Default)]
+#[derive(Default, Clone)]
 struct StyleAttrs {
     color: Option<String>,
     weight: Option<f64>,
@@ -87,6 +87,11 @@ enum Shape {
         to: [f64; 2],
         offset: f64,
     },
+    /// A filled region. Imported from one or more SOLID entities; adjacent
+    /// SOLID triangles/quads on the same layer are fused into a single fill.
+    Fill {
+        points: Vec<[f64; 2]>,
+    },
 }
 
 struct Imported {
@@ -168,6 +173,10 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
                         dim_offset(from, to, [e.insertion_point.x, e.insertion_point.y])
                             .map(|offset| Shape::Dim { from, to, offset })
                     }
+                    EntityType::Solid(e) => {
+                        let ring = solid_ring(e);
+                        (ring.len() >= 3).then_some(Shape::Fill { points: ring })
+                    }
                     _ => {
                         unsupported += 1;
                         None
@@ -184,6 +193,7 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
 
             for layer in layers.values_mut() {
                 remove_dim_companions(&mut layer.entities);
+                fuse_solids(&mut layer.entities);
             }
         }
         Err(_) => {
@@ -382,6 +392,221 @@ fn mark_text_companion(
     }
 }
 
+/// Recover the polygon ring of a DXF SOLID entity. SOLID vertices render in
+/// the order first → second → fourth → third; adjacent duplicates (the writer
+/// sets the fourth corner equal to the third for triangles) are collapsed.
+fn solid_ring(e: &dxf::entities::Solid) -> Vec<[f64; 2]> {
+    let raw = [
+        [e.first_corner.x, e.first_corner.y],
+        [e.second_corner.x, e.second_corner.y],
+        [e.fourth_corner.x, e.fourth_corner.y],
+        [e.third_corner.x, e.third_corner.y],
+    ];
+    let mut ring: Vec<[f64; 2]> = Vec::with_capacity(4);
+    for p in raw {
+        if ring.last().is_none_or(|q| !pts_eq(*q, p)) {
+            ring.push(p);
+        }
+    }
+    // Drop a closing duplicate if the last equals the first.
+    if ring.len() > 1 && pts_eq(ring[0], ring[ring.len() - 1]) {
+        ring.pop();
+    }
+    ring
+}
+
+/// Quantized key for a point so that geometrically equal vertices from
+/// different SOLID entities hash together despite float round-trip noise.
+type PtKey = (i64, i64);
+
+fn pt_key(p: [f64; 2]) -> PtKey {
+    ((p[0] * 1e6).round() as i64, (p[1] * 1e6).round() as i64)
+}
+
+fn pts_eq(a: [f64; 2], b: [f64; 2]) -> bool {
+    (a[0] - b[0]).abs() < 1e-6 && (a[1] - b[1]).abs() < 1e-6
+}
+
+/// Undirected edge key with a canonical (min, max) endpoint order.
+fn edge_key(a: PtKey, b: PtKey) -> (PtKey, PtKey) {
+    if a <= b {
+        (a, b)
+    } else {
+        (b, a)
+    }
+}
+
+/// Fuse adjacent SOLID-derived fills into single `[[fill]]` regions.
+///
+/// `cadspec build` fan-triangulates a solid fill into several SOLID entities;
+/// importing each one separately would inflate the entity count and lose the
+/// `[[fill]]` semantics. Fills that share an edge belong to the same region:
+/// group them, drop the shared (internal) edges, and stitch the remaining
+/// boundary edges back into one polygon. Foreign SOLIDs that don't tile a
+/// region are left as individual fills.
+fn fuse_solids(entities: &mut Vec<Imported>) {
+    let fill_positions: Vec<usize> = entities
+        .iter()
+        .enumerate()
+        .filter(|(_, e)| matches!(e.shape, Shape::Fill { .. }))
+        .map(|(i, _)| i)
+        .collect();
+    if fill_positions.len() < 2 {
+        return; // nothing to merge
+    }
+
+    let ring_of = |pos: usize| -> &[[f64; 2]] {
+        match &entities[pos].shape {
+            Shape::Fill { points } => points,
+            _ => unreachable!("filtered to fills"),
+        }
+    };
+
+    // Union-find over fills, joined when they share an edge.
+    let mut parent: Vec<usize> = (0..fill_positions.len()).collect();
+    fn find(parent: &mut [usize], mut x: usize) -> usize {
+        while parent[x] != x {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+        }
+        x
+    }
+
+    let mut edge_owner: std::collections::HashMap<(PtKey, PtKey), usize> =
+        std::collections::HashMap::new();
+    for (idx, &pos) in fill_positions.iter().enumerate() {
+        for (a, b) in ring_edges(ring_of(pos)) {
+            let key = edge_key(pt_key(a), pt_key(b));
+            if let Some(&other) = edge_owner.get(&key) {
+                let (ra, rb) = (find(&mut parent, idx), find(&mut parent, other));
+                parent[ra] = rb;
+            } else {
+                edge_owner.insert(key, idx);
+            }
+        }
+    }
+
+    // Group fill indices by component root.
+    let mut components: BTreeMap<usize, Vec<usize>> = BTreeMap::new();
+    for idx in 0..fill_positions.len() {
+        let root = find(&mut parent, idx);
+        components.entry(root).or_default().push(idx);
+    }
+
+    // Build replacement fills and track which original positions to drop.
+    let mut fused: Vec<Imported> = Vec::new();
+    let mut drop: Vec<bool> = vec![false; entities.len()];
+    for members in components.values() {
+        for &idx in members {
+            drop[fill_positions[idx]] = true;
+        }
+        let style_pos = fill_positions[members[0]];
+        let style = entities[style_pos].style.clone();
+
+        if members.len() == 1 {
+            // A lone fill: keep its own ring.
+            let points = ring_of(fill_positions[members[0]]).to_vec();
+            fused.push(Imported {
+                shape: Shape::Fill { points },
+                style,
+            });
+            continue;
+        }
+
+        let rings: Vec<&[[f64; 2]]> = members
+            .iter()
+            .map(|&idx| ring_of(fill_positions[idx]))
+            .collect();
+        match merge_rings(&rings) {
+            Some(points) => fused.push(Imported {
+                shape: Shape::Fill { points },
+                style,
+            }),
+            None => {
+                // Couldn't stitch a clean boundary: keep each fill as-is.
+                for &idx in members {
+                    fused.push(Imported {
+                        shape: Shape::Fill {
+                            points: ring_of(fill_positions[idx]).to_vec(),
+                        },
+                        style: entities[fill_positions[idx]].style.clone(),
+                    });
+                }
+            }
+        }
+    }
+
+    let mut it = drop.into_iter();
+    entities.retain(|_| !it.next().unwrap_or(false));
+    entities.extend(fused);
+}
+
+/// Iterate the closed ring's undirected edges as consecutive point pairs.
+fn ring_edges(ring: &[[f64; 2]]) -> Vec<([f64; 2], [f64; 2])> {
+    let n = ring.len();
+    (0..n).map(|i| (ring[i], ring[(i + 1) % n])).collect()
+}
+
+/// Merge a set of triangle/quad rings that tile one region into a single
+/// boundary polygon: edges shared by two rings are interior and dropped; the
+/// remaining boundary edges are chained into one ring. Returns `None` if the
+/// boundary is not a single simple loop.
+fn merge_rings(rings: &[&[[f64; 2]]]) -> Option<Vec<[f64; 2]>> {
+    let mut edge_count: std::collections::HashMap<(PtKey, PtKey), usize> =
+        std::collections::HashMap::new();
+    let mut coord: std::collections::HashMap<PtKey, [f64; 2]> = std::collections::HashMap::new();
+    for ring in rings {
+        for (a, b) in ring_edges(ring) {
+            coord.entry(pt_key(a)).or_insert(a);
+            coord.entry(pt_key(b)).or_insert(b);
+            *edge_count
+                .entry(edge_key(pt_key(a), pt_key(b)))
+                .or_insert(0) += 1;
+        }
+    }
+
+    // Boundary edges appear exactly once.
+    let boundary: Vec<(PtKey, PtKey)> = edge_count
+        .iter()
+        .filter(|(_, &c)| c == 1)
+        .map(|(&e, _)| e)
+        .collect();
+    if boundary.len() < 3 {
+        return None;
+    }
+
+    // Adjacency; a clean loop has every vertex at degree 2.
+    let mut adj: std::collections::HashMap<PtKey, Vec<PtKey>> = std::collections::HashMap::new();
+    for (a, b) in &boundary {
+        adj.entry(*a).or_default().push(*b);
+        adj.entry(*b).or_default().push(*a);
+    }
+    if adj.values().any(|v| v.len() != 2) {
+        return None;
+    }
+
+    // Walk the loop from a deterministic start.
+    let start = *adj.keys().min()?;
+    let mut ring_keys = vec![start];
+    let mut prev = start;
+    let mut cur = adj[&start][0];
+    while cur != start {
+        ring_keys.push(cur);
+        let nbrs = &adj[&cur];
+        let next = if nbrs[0] == prev { nbrs[1] } else { nbrs[0] };
+        prev = cur;
+        cur = next;
+        if ring_keys.len() > boundary.len() {
+            return None; // did not close cleanly
+        }
+    }
+    if ring_keys.len() != boundary.len() {
+        return None; // disconnected boundary (e.g. a hole)
+    }
+
+    Some(ring_keys.iter().map(|k| coord[k]).collect())
+}
+
 /// Render a shape body (without `[[header]]`/`id`); returns (id prefix, body).
 fn emit_shape(shape: &Shape) -> (&'static str, String) {
     match shape {
@@ -457,6 +682,14 @@ fn emit_shape(shape: &Shape) -> (&'static str, String) {
                 n(*offset)
             ),
         ),
+        Shape::Fill { points } => {
+            let pts = points
+                .iter()
+                .map(|p| format!("[{}, {}]", n(p[0]), n(p[1])))
+                .collect::<Vec<_>>()
+                .join(", ");
+            ("fl", format!("points = [{}]\n", pts))
+        }
     }
 }
 
@@ -469,6 +702,7 @@ fn header_for(prefix: &str) -> &'static str {
         "tx" => "text",
         "pt" => "point",
         "dm" => "dim",
+        "fl" => "fill",
         _ => "line",
     }
 }
@@ -547,3 +781,66 @@ fn collect_layer_names_from_layer_table(content: &str) -> Vec<String> {
     }
     names
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fill(points: Vec<[f64; 2]>) -> Imported {
+        Imported {
+            shape: Shape::Fill { points },
+            style: StyleAttrs::default(),
+        }
+    }
+
+    fn ring_of(e: &Imported) -> &[[f64; 2]] {
+        match &e.shape {
+            Shape::Fill { points } => points,
+            _ => panic!("expected fill"),
+        }
+    }
+
+    #[test]
+    fn merge_rings_stitches_fan_triangles_into_rectangle() {
+        // Fan triangulation of rect [0,0]-[2,2] from vertex [0,0].
+        let t1: &[[f64; 2]] = &[[0.0, 0.0], [2.0, 0.0], [2.0, 2.0]];
+        let t2: &[[f64; 2]] = &[[0.0, 0.0], [2.0, 2.0], [0.0, 2.0]];
+        let ring = merge_rings(&[t1, t2]).expect("should stitch a clean loop");
+        assert_eq!(ring.len(), 4, "shared diagonal edge is dropped");
+        // All four rectangle corners present regardless of winding/start.
+        for corner in [[0.0, 0.0], [2.0, 0.0], [2.0, 2.0], [0.0, 2.0]] {
+            assert!(
+                ring.iter().any(|p| pts_eq(*p, corner)),
+                "missing corner {corner:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn fuse_solids_merges_adjacent_and_keeps_disjoint_separate() {
+        let mut entities = vec![
+            // Region A: two triangles tiling rect [0,0]-[2,2].
+            fill(vec![[0.0, 0.0], [2.0, 0.0], [2.0, 2.0]]),
+            fill(vec![[0.0, 0.0], [2.0, 2.0], [0.0, 2.0]]),
+            // Region B: a lone triangle far away.
+            fill(vec![[10.0, 10.0], [11.0, 10.0], [10.5, 11.0]]),
+        ];
+        fuse_solids(&mut entities);
+        let fills: Vec<&Imported> = entities
+            .iter()
+            .filter(|e| matches!(e.shape, Shape::Fill { .. }))
+            .collect();
+        assert_eq!(fills.len(), 2, "adjacent pair fuses, disjoint stays");
+        let mut lens: Vec<usize> = fills.iter().map(|e| ring_of(e).len()).collect();
+        lens.sort_unstable();
+        assert_eq!(lens, vec![3, 4], "one rectangle (4) and one triangle (3)");
+    }
+
+    #[test]
+    fn fuse_solids_leaves_single_fill_untouched() {
+        let mut entities = vec![fill(vec![[0.0, 0.0], [1.0, 0.0], [0.5, 1.0]])];
+        fuse_solids(&mut entities);
+        assert_eq!(entities.len(), 1);
+        assert_eq!(ring_of(&entities[0]).len(), 3);
+    }
+}

From 25c216b838f16e9fe3f1617957e9a16670fd7c32 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Fri, 3 Jul 2026 22:42:20 -0500
Subject: [PATCH 27/39] feat(import): re-fuse hatch pattern lines instead of
 inflating them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `[[hatch]]` expands into many clipped DXF LINE entities (the DXF format
this tool targets has no native HATCH entity). A build→import round-trip
used to bring every one of those back as a separate `[[line]]`, inflating
one source hatch into dozens of stray lines.

Stamp each generated pattern line with `CADSPEC_HATCH` XDATA carrying a
group id plus the source region, pattern, angle and scale. On import,
lines sharing a group id collapse back into a single `[[hatch]]` (using
inline points), while untagged lines stay `[[line]]` — so a foreign DXF's
ordinary lines are never mistaken for hatch pattern (no false positives).

`[[hatch]]` now accepts inline `points` as an alternative to a `boundary`
id, mirroring `[[fill]]`; the compiler and SVG renderer resolve a hatch
region from either source. Verified stable across build→import→build on
the vivienda example (2 hatches + 4 real lines round-trip unchanged).
---
 docs/building-and-export.md |  13 ++--
 docs/cf-format.md           |  31 ++++++++++
 src/compiler.rs             |  23 ++++++-
 src/dxf_writer.rs           |  59 ++++++++++++++++--
 src/importer.rs             | 116 +++++++++++++++++++++++++++++++++++-
 src/model.rs                |   7 ++-
 src/svg.rs                  |  18 +++++-
 src/transform.rs            |  13 +++-
 tests/integration.rs        |  86 +++++++++++++++++++++++++-
 9 files changed, 344 insertions(+), 22 deletions(-)

diff --git a/docs/building-and-export.md b/docs/building-and-export.md
index 6f9f855..9bebda5 100644
--- a/docs/building-and-export.md
+++ b/docs/building-and-export.md
@@ -91,11 +91,14 @@ cadspec import plano.dxf --output casa   # into a specific directory
 Import migrates an existing DXF into `.cf` layer files plus a
 `project.toml`, so legacy drawings can join the declarative workflow.
 Lines, polylines, circles, arcs, text, points and dimensions map back to
-their `.cf` primitives. Filled regions are reconstructed too: adjacent
-SOLID entities on a layer (such as the fan-triangulated fills that
-`cadspec build` emits) are fused back into a single `[[fill]]` with its
-original boundary, so an export/import round-trip does not inflate the
-entity count.
+their `.cf` primitives. Filled and hatched regions are reconstructed too:
+adjacent SOLID entities on a layer (such as the fan-triangulated fills that
+`cadspec build` emits) are fused back into a single `[[fill]]`, and the
+clipped LINE segments a hatch expands into — marked with `CADSPEC_HATCH`
+XDATA on export — are re-fused into a single `[[hatch]]` carrying its region
+and pattern/angle/scale. So an export/import round-trip does not inflate the
+entity count, and only lines this tool emitted are ever folded back into a
+hatch (a foreign DXF's ordinary lines are left untouched).
 
 ## Pipeline
 
diff --git a/docs/cf-format.md b/docs/cf-format.md
index 27c7502..14135c2 100644
--- a/docs/cf-format.md
+++ b/docs/cf-format.md
@@ -71,6 +71,37 @@ size = 0.2
 Every entity has a stable `id` — that is what makes plans diffable and
 lets agents target precise edits.
 
+## Filled and hatched regions
+
+`fill` (solid color) and `hatch` (parallel pattern lines) mark an area. The
+region can come from either a reference to a closed `polyline`/`rect` `id` in
+the **same layer file** (`boundary`) or inline `points`:
+
+```toml
+[[fill]]
+id = "fl-closet"
+points = [[0.0, 7.0], [1.2, 7.0], [1.2, 9.0], [0.0, 9.0]]
+color = "#E0E0E0"
+
+[[hatch]]
+id = "ht-bano"
+boundary = "pl-bano"        # id of a closed polyline/rect in this file
+pattern = "ansi31"
+scale = 2.0
+angle = 45.0
+```
+
+Boundaries resolve per layer file: a `boundary` id defined in another layer
+will not resolve (the build warns and skips the region); use inline `points`
+to cross that boundary.
+
+At build time a `hatch` expands into DXF `LINE`s (there is no native HATCH
+entity in the DXF format this tool targets). Those pattern lines carry a
+`CADSPEC_HATCH` marker so `cadspec import` re-fuses them back into a single
+`[[hatch]]` — with inline `points` — instead of dozens of stray `[[line]]`s.
+Only lines this tool emits carry the marker, so importing a foreign DXF never
+mistakes ordinary lines for a hatch.
+
 ## Styled dimensions
 
 `dim` entities are auto-measured — the label is computed from the
diff --git a/src/compiler.rs b/src/compiler.rs
index a74e1a8..31b0d2d 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -677,10 +677,27 @@ fn compile_cf(writer: &mut DxfWriter, cf: &CfFile, default_layer: &str) {
         let style = resolve_style(&e.common);
         let spacing = 0.1 * e.scale; // base spacing scaled
 
-        if let Some(boundary) = resolve_boundary(&e.boundary, cf) {
-            writer.hatch(&boundary, e.angle, spacing, layer, &style);
+        let boundary = if let Some(ref boundary_id) = e.boundary {
+            let resolved = resolve_boundary(boundary_id, cf);
+            if resolved.is_none() {
+                warn_unresolved_boundary(
+                    "hatch",
+                    e.common.id.as_deref(),
+                    boundary_id,
+                    default_layer,
+                );
+            }
+            resolved
         } else {
-            warn_unresolved_boundary("hatch", e.common.id.as_deref(), &e.boundary, default_layer);
+            e.points
+                .as_ref()
+                .map(|p| p.iter().map(|v| (v[0], v[1])).collect())
+        };
+
+        if let Some(boundary) = boundary {
+            writer.hatch(
+                &boundary, e.angle, spacing, e.scale, &e.pattern, layer, &style,
+            );
         }
     }
 
diff --git a/src/dxf_writer.rs b/src/dxf_writer.rs
index f4fc7ca..7291dc2 100644
--- a/src/dxf_writer.rs
+++ b/src/dxf_writer.rs
@@ -4,9 +4,15 @@ use anyhow::Result;
 use dxf::entities::{Entity, EntityType, LwPolyline};
 use dxf::enums::AcadVersion;
 use dxf::tables::Layer;
-use dxf::{Color, Drawing, LwPolylineVertex, Point};
+use dxf::{Color, Drawing, LwPolylineVertex, Point, XData, XDataItem};
 use std::path::Path;
 
+/// XDATA application name stamped on the pattern lines a hatch expands into, so
+/// the DXF importer can recognize and re-fuse them back into a single `[[hatch]]`
+/// (instead of dozens of stray `[[line]]`s). Only lines this tool emits carry
+/// the tag, so import never mistakes a foreign DXF's lines for a hatch.
+pub const HATCH_XDATA_APP: &str = "CADSPEC_HATCH";
+
 /// Optional visual attributes applied to any entity.
 #[derive(Default, Clone)]
 pub struct EntityStyle {
@@ -24,6 +30,9 @@ impl EntityStyle {
 /// Builder for constructing a DXF drawing from primitives.
 pub struct DxfWriter {
     drawing: Drawing,
+    /// Monotonic id assigned to each hatch so its expanded pattern lines can be
+    /// grouped back together on import.
+    hatch_group_seq: i32,
 }
 
 impl DxfWriter {
@@ -36,7 +45,10 @@ impl DxfWriter {
         drawing.add_line_type(Self::make_line_type("DOTTED", &[0.0, -0.25]));
         drawing.add_line_type(Self::make_line_type("DASHDOT", &[0.5, -0.25, 0.0, -0.25]));
 
-        Self { drawing }
+        Self {
+            drawing,
+            hatch_group_seq: 0,
+        }
     }
 
     fn make_line_type(name: &str, pattern: &[f64]) -> dxf::tables::LineType {
@@ -68,7 +80,8 @@ impl DxfWriter {
 
     // ── Single entry point for adding entities ─────────────────────────
 
-    fn add_entity(&mut self, entity_type: EntityType, layer: &str, style: &EntityStyle) {
+    /// Build a styled entity (layer + color/weight/line-type) without adding it.
+    fn styled_entity(entity_type: EntityType, layer: &str, style: &EntityStyle) -> Entity {
         let mut entity = Entity::new(entity_type);
         entity.common.layer = layer.to_string();
         if let Some(c) = style.color_24bit {
@@ -80,7 +93,12 @@ impl DxfWriter {
         if let Some(lt) = &style.line_type {
             entity.common.line_type_name = lt.clone();
         }
-        self.drawing.add_entity(entity);
+        entity
+    }
+
+    fn add_entity(&mut self, entity_type: EntityType, layer: &str, style: &EntityStyle) {
+        self.drawing
+            .add_entity(Self::styled_entity(entity_type, layer, style));
     }
 
     // ── Public primitive methods ───────────────────────────────────────
@@ -264,14 +282,21 @@ impl DxfWriter {
         }
     }
 
-    /// Generate hatch pattern lines within a rectangular boundary.
+    /// Generate hatch pattern lines within a boundary polygon.
     /// `boundary` is a list of (x,y) points forming a closed polygon.
     /// `angle` is in degrees, `spacing` is distance between lines.
+    ///
+    /// `scale` and `pattern` are the source `[[hatch]]` values, carried on each
+    /// generated line as XDATA (alongside the boundary and a group id) so the
+    /// importer can re-fuse the lines into one `[[hatch]]` on a DXF round-trip.
+    #[allow(clippy::too_many_arguments)]
     pub fn hatch(
         &mut self,
         boundary: &[(f64, f64)],
         angle: f64,
         spacing: f64,
+        scale: f64,
+        pattern: &str,
         layer: &str,
         style: &EntityStyle,
     ) {
@@ -279,6 +304,24 @@ impl DxfWriter {
             return;
         }
 
+        // XDATA stamped on every pattern line of this hatch: group id, source
+        // angle/scale/pattern, then the boundary polygon vertices. All lines of
+        // one hatch share the same payload, so any of them can rebuild it.
+        self.hatch_group_seq += 1;
+        let mut items = vec![
+            XDataItem::Long(self.hatch_group_seq),
+            XDataItem::Real(angle),
+            XDataItem::Real(scale),
+            XDataItem::Str(pattern.to_string()),
+        ];
+        for &(x, y) in boundary {
+            items.push(XDataItem::WorldSpacePosition(Point::new(x, y, 0.0)));
+        }
+        let xdata = XData {
+            application_name: HATCH_XDATA_APP.to_string(),
+            items,
+        };
+
         // Compute bounding box
         let (min_x, max_x, min_y, max_y) = bounding_box(boundary);
 
@@ -307,7 +350,11 @@ impl DxfWriter {
 
             // Clip line to boundary polygon
             if let Some((cx1, cy1, cx2, cy2)) = clip_line_to_polygon(x1, y1, x2, y2, boundary) {
-                self.line(cx1, cy1, cx2, cy2, layer, style);
+                let line =
+                    dxf::entities::Line::new(Point::new(cx1, cy1, 0.0), Point::new(cx2, cy2, 0.0));
+                let mut entity = Self::styled_entity(EntityType::Line(line), layer, style);
+                entity.common.x_data.push(xdata.clone());
+                self.drawing.add_entity(entity);
             }
         }
     }
diff --git a/src/importer.rs b/src/importer.rs
index 68dcfa6..71a4f74 100644
--- a/src/importer.rs
+++ b/src/importer.rs
@@ -1,9 +1,10 @@
 //! DXF importer — converts DXF layers/entities into CADspec `.cf` + `project.toml`.
 
 use crate::color::aci_to_hex;
+use crate::dxf_writer::HATCH_XDATA_APP;
 use anyhow::{anyhow, Context, Result};
 use dxf::entities::EntityType;
-use dxf::Drawing;
+use dxf::{Drawing, XData, XDataItem};
 use std::collections::BTreeMap;
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -92,6 +93,59 @@ enum Shape {
     Fill {
         points: Vec<[f64; 2]>,
     },
+    /// A hatched region, recovered from the pattern lines it expanded into by
+    /// reading the `CADSPEC_HATCH` XDATA those lines carry.
+    Hatch {
+        points: Vec<[f64; 2]>,
+        angle: f64,
+        scale: f64,
+        pattern: String,
+    },
+}
+
+/// Hatch parameters recovered from one pattern line's `CADSPEC_HATCH` XDATA.
+struct HatchMeta {
+    group: i32,
+    angle: f64,
+    scale: f64,
+    pattern: String,
+    points: Vec<[f64; 2]>,
+}
+
+/// Read the `CADSPEC_HATCH` XDATA payload (group id, angle, scale, pattern, then
+/// the boundary polygon vertices) off a line entity. Returns `None` for any line
+/// that this tool did not emit as part of a hatch, so foreign DXF lines are never
+/// mistaken for hatch pattern.
+fn parse_hatch_xdata(xdata: &[XData]) -> Option<HatchMeta> {
+    let x = xdata
+        .iter()
+        .find(|x| x.application_name == HATCH_XDATA_APP)?;
+    let mut group = None;
+    let mut angle = None;
+    let mut scale = None;
+    let mut pattern = None;
+    let mut points = Vec::new();
+    for item in &x.items {
+        match item {
+            XDataItem::Long(v) if group.is_none() => group = Some(*v),
+            XDataItem::Real(v) if angle.is_none() => angle = Some(*v),
+            XDataItem::Real(v) if scale.is_none() => scale = Some(*v),
+            XDataItem::Str(s) if pattern.is_none() => pattern = Some(s.clone()),
+            XDataItem::WorldSpacePosition(p) => points.push([p.x, p.y]),
+            _ => {}
+        }
+    }
+    // A hatch needs at least a triangle of boundary to be reconstructable.
+    if points.len() < 3 {
+        return None;
+    }
+    Some(HatchMeta {
+        group: group?,
+        angle: angle?,
+        scale: scale?,
+        pattern: pattern.unwrap_or_else(|| "ansi31".to_string()),
+        points,
+    })
 }
 
 struct Imported {
@@ -119,6 +173,9 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
     let mut layers: BTreeMap<String, LayerFile> = BTreeMap::new();
     let mut layer_colors: BTreeMap<String, String> = BTreeMap::new();
     let mut unsupported = 0usize;
+    // Pattern lines of the same hatch (same XDATA group id) are collected here
+    // and re-fused into one `[[hatch]]` after the entity pass, keyed by group id.
+    let mut hatch_groups: BTreeMap<i32, (String, Imported)> = BTreeMap::new();
 
     match Drawing::load_file(input) {
         Ok(drawing) => {
@@ -140,6 +197,30 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
                 }
 
                 let style = StyleAttrs::from_common(&entity.common);
+
+                // A line stamped with CADSPEC_HATCH XDATA is one of a hatch's
+                // pattern lines: register its group (once) and drop the line, so
+                // the round-trip yields one `[[hatch]]` instead of N `[[line]]`.
+                if matches!(&entity.specific, EntityType::Line(_)) {
+                    if let Some(meta) = parse_hatch_xdata(&entity.common.x_data) {
+                        hatch_groups.entry(meta.group).or_insert_with(|| {
+                            (
+                                layer_name.clone(),
+                                Imported {
+                                    shape: Shape::Hatch {
+                                        points: meta.points,
+                                        angle: meta.angle,
+                                        scale: meta.scale,
+                                        pattern: meta.pattern,
+                                    },
+                                    style: style.clone(),
+                                },
+                            )
+                        });
+                        continue;
+                    }
+                }
+
                 let shape = match &entity.specific {
                     EntityType::Line(e) => Some(Shape::Line {
                         from: [e.p1.x, e.p1.y],
@@ -191,6 +272,16 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
                 }
             }
 
+            // Emit one hatch per collected group into its layer (ordered by
+            // group id for deterministic output).
+            for (_group, (layer_name, imported)) in hatch_groups {
+                layers
+                    .entry(layer_name)
+                    .or_default()
+                    .entities
+                    .push(imported);
+            }
+
             for layer in layers.values_mut() {
                 remove_dim_companions(&mut layer.entities);
                 fuse_solids(&mut layer.entities);
@@ -690,6 +781,28 @@ fn emit_shape(shape: &Shape) -> (&'static str, String) {
                 .join(", ");
             ("fl", format!("points = [{}]\n", pts))
         }
+        Shape::Hatch {
+            points,
+            angle,
+            scale,
+            pattern,
+        } => {
+            let pts = points
+                .iter()
+                .map(|p| format!("[{}, {}]", n(p[0]), n(p[1])))
+                .collect::<Vec<_>>()
+                .join(", ");
+            (
+                "ht",
+                format!(
+                    "points = [{}]\npattern = \"{}\"\nangle = {}\nscale = {}\n",
+                    pts,
+                    escape_string(pattern),
+                    n(*angle),
+                    n(*scale)
+                ),
+            )
+        }
     }
 }
 
@@ -703,6 +816,7 @@ fn header_for(prefix: &str) -> &'static str {
         "pt" => "point",
         "dm" => "dim",
         "fl" => "fill",
+        "ht" => "hatch",
         _ => "line",
     }
 }
diff --git a/src/model.rs b/src/model.rs
index a2490d9..eb09619 100644
--- a/src/model.rs
+++ b/src/model.rs
@@ -143,7 +143,12 @@ pub enum DimType {
 
 #[derive(Debug, Clone, Deserialize)]
 pub struct CfHatch {
-    pub boundary: String,
+    /// Reference to a closed polyline or rect id, or inline points.
+    #[serde(default)]
+    pub boundary: Option<String>,
+    /// Inline points (alternative to boundary reference). Used by DXF import to
+    /// round-trip a hatch's region without depending on a separate boundary id.
+    pub points: Option<Vec<[f64; 2]>>,
     #[serde(default = "default_pattern")]
     pub pattern: String,
     #[serde(default = "default_scale")]
diff --git a/src/svg.rs b/src/svg.rs
index a6767d7..57c4ba3 100644
--- a/src/svg.rs
+++ b/src/svg.rs
@@ -526,7 +526,14 @@ pub fn enumerate_entities(cf: &CfFile) -> Vec<EntityRecord> {
         });
     }
     for e in &cf.hatches {
-        if let Some(pts) = resolve_boundary(&e.boundary, cf) {
+        let pts = if let Some(boundary_id) = &e.boundary {
+            resolve_boundary(boundary_id, cf)
+        } else {
+            e.points
+                .as_ref()
+                .map(|p| p.iter().map(|v| (v[0], v[1])).collect())
+        };
+        if let Some(pts) = pts {
             out.push(EntityRecord {
                 id: e.common.id.clone(),
                 kind: "hatch",
@@ -700,7 +707,14 @@ fn render_layer(c: &mut Canvas, cf: &CfFile, layer_color: &str, default_weight:
     }
 
     for e in cf.hatches.iter().filter(|e| e.common.visible) {
-        if let Some(boundary) = resolve_boundary(&e.boundary, cf) {
+        let boundary = if let Some(boundary_id) = &e.boundary {
+            resolve_boundary(boundary_id, cf)
+        } else {
+            e.points
+                .as_ref()
+                .map(|p| p.iter().map(|v| (v[0], v[1])).collect())
+        };
+        if let Some(boundary) = boundary {
             let s = resolve_style(&e.common, layer_color, default_weight);
             draw_hatch(
                 c,
diff --git a/src/transform.rs b/src/transform.rs
index 62c0bcc..63e3489 100644
--- a/src/transform.rs
+++ b/src/transform.rs
@@ -279,8 +279,15 @@ fn copy_targets(
     let mut new_hatches = Vec::new();
     for e in out.hatches.iter().filter(|e| hit(&e.common.id, targets)) {
         let mut c = e.clone();
-        if targets.contains(&e.boundary) {
-            c.boundary = format!("{}{}", e.boundary, suffix);
+        if let Some(boundary) = &e.boundary {
+            if targets.contains(boundary) {
+                c.boundary = Some(format!("{}{}", boundary, suffix));
+            }
+        }
+        if let Some(points) = &mut c.points {
+            for p in points {
+                *p = op.apply(*p);
+            }
         }
         c.common.id = suffixed(&e.common.id, suffix);
         new_hatches.push(c);
@@ -477,7 +484,7 @@ offset = [3.0, 0.0]
         );
         let out = expand_cf(&cf);
         assert_eq!(out.hatches.len(), 2);
-        assert_eq!(out.hatches[1].boundary, "zona@1");
+        assert_eq!(out.hatches[1].boundary.as_deref(), Some("zona@1"));
         assert_eq!(out.polylines[1].points[0], [3.0, 0.0]);
     }
 }
diff --git a/tests/integration.rs b/tests/integration.rs
index f108efe..063165e 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -163,7 +163,7 @@ angle = 45.0
 
     let cf: cadspec::model::CfFile = toml::from_str(toml).unwrap();
     assert_eq!(cf.hatches.len(), 1);
-    assert_eq!(cf.hatches[0].boundary, "pl-room");
+    assert_eq!(cf.hatches[0].boundary.as_deref(), Some("pl-room"));
 
     // Compile it to verify no panic
     use cadspec::dxf_writer::DxfWriter;
@@ -525,3 +525,87 @@ offset = -1.2
     let _ = fs::remove_dir_all(dir);
     let _ = fs::remove_dir_all(imported);
 }
+
+#[test]
+fn import_refuses_hatch_lines_into_single_hatch() {
+    // A hatch expands into many DXF pattern lines. On import they must collapse
+    // back into one `[[hatch]]` (with its region + pattern/angle/scale), while a
+    // genuine standalone line on the same layer survives as a `[[line]]`.
+    let dir = Path::new("/tmp/cadspec_hatch_roundtrip");
+    let _ = fs::remove_dir_all(dir);
+    fs::create_dir_all(dir).unwrap();
+    fs::write(
+        dir.join("project.toml"),
+        "[project]\nname = \"ht\"\nunits = \"m\"\n\n[layers]\nzona = { file = \"zona.cf\", locked = false }\n",
+    )
+    .unwrap();
+    fs::write(
+        dir.join("zona.cf"),
+        r##"[layer]
+name = "zona"
+color = "#C0C0C0"
+
+[[polyline]]
+id = "pl-room"
+points = [[0.0, 0.0], [4.0, 0.0], [4.0, 3.0], [0.0, 3.0]]
+closed = true
+
+[[hatch]]
+id = "ht-room"
+boundary = "pl-room"
+pattern = "ansi31"
+scale = 2.0
+angle = 45.0
+
+[[line]]
+id = "ln-real"
+from = [0.0, 0.0]
+to = [4.0, 3.0]
+"##,
+    )
+    .unwrap();
+
+    let dxf_path = dir.join("output.dxf");
+    compile_project(dir, None, Some(&dxf_path)).unwrap();
+    // The hatch really did expand into several tagged pattern lines in the DXF.
+    let dxf_text = fs::read_to_string(&dxf_path).unwrap();
+    assert!(
+        dxf_text.matches("CADSPEC_HATCH").count() > 3,
+        "expected the hatch to expand into multiple tagged pattern lines"
+    );
+
+    let imported = Path::new("/tmp/cadspec_hatch_roundtrip_out");
+    let _ = fs::remove_dir_all(imported);
+    import_dxf(&dxf_path, imported, None).unwrap();
+    let cf = fs::read_to_string(imported.join("zona.cf")).unwrap();
+
+    // Exactly one hatch comes back, carrying its region and source parameters.
+    assert_eq!(
+        cf.matches("[[hatch]]").count(),
+        1,
+        "hatch not re-fused:\n{cf}"
+    );
+    assert!(cf.contains("pattern = \"ansi31\""), "pattern lost:\n{cf}");
+    assert!(cf.contains("angle = 45.0000"), "angle lost:\n{cf}");
+    assert!(cf.contains("scale = 2.0000"), "scale lost:\n{cf}");
+    // The genuine line survives; hatch pattern lines are not emitted as lines.
+    assert_eq!(
+        cf.matches("[[line]]").count(),
+        1,
+        "hatch pattern lines leaked as lines:\n{cf}"
+    );
+
+    // The reimported hatch (now using inline points) still compiles and expands
+    // back into the same tagged pattern lines — a stable round-trip.
+    let dxf2 = imported.join("output2.dxf");
+    compile_project(imported, None, Some(&dxf2)).unwrap();
+    let dxf2_text = fs::read_to_string(&dxf2).unwrap();
+    assert_eq!(
+        dxf_text.matches("CADSPEC_HATCH").count(),
+        dxf2_text.matches("CADSPEC_HATCH").count(),
+        "hatch pattern-line count drifted across a round-trip"
+    );
+
+    let _ = fs::remove_dir_all(dir);
+    let _ = fs::remove_dir_all(imported);
+}

From 472c9a4bc158a58d87a414f64345fc5e43e0c3fd Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 19:33:29 -0500
Subject: [PATCH 28/39] feat(preview): warn on unresolved hatch/fill boundaries
 in preview and svg

Boundaries were already resolved per layer file in build (warns and skips
since 209d345), but preview/serve rendering and the svg module resolved
the same boundaries silently. Reuse the compiler's warning at the two
render_layer sites (fills, hatches) so the same condition is visible
regardless of which command triggered the render, and document that
per-file resolution is the intended design (cross-layer references use
inline `points`, not a project-wide boundary index).
---
 docs/cf-format.md    |  6 +++--
 src/compiler.rs      | 10 +++++--
 src/svg.rs           | 40 +++++++++++++++++++++++++---
 tests/integration.rs | 62 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 110 insertions(+), 8 deletions(-)

diff --git a/docs/cf-format.md b/docs/cf-format.md
index 14135c2..9a2153f 100644
--- a/docs/cf-format.md
+++ b/docs/cf-format.md
@@ -92,8 +92,10 @@ angle = 45.0
 ```
 
 Boundaries resolve per layer file: a `boundary` id defined in another layer
-will not resolve (the build warns and skips the region); use inline `points`
-to cross that boundary.
+will not resolve. This is by design — layer files are the resolution
+boundary, not an oversight to fix — and both `build` and `preview`/`serve`
+warn on stderr and skip the region rather than failing or dropping it
+silently. Use inline `points` to reference geometry from another layer.
 
 At build time a `hatch` expands into DXF `LINE`s (there is no native HATCH
 entity in the DXF format this tool targets). Those pattern lines carry a
diff --git a/src/compiler.rs b/src/compiler.rs
index 31b0d2d..fbc2615 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -732,8 +732,14 @@ fn compile_cf(writer: &mut DxfWriter, cf: &CfFile, default_layer: &str) {
 /// Warn (without failing the build) when a hatch/fill references a boundary id
 /// that does not resolve to any closed polyline or rect in the same layer file.
 /// Boundaries are resolved per layer file; a reference to an id defined in a
-/// different layer will not resolve and the region is skipped.
-fn warn_unresolved_boundary(kind: &str, entity_id: Option<&str>, boundary: &str, layer: &str) {
+/// different layer will not resolve and the region is skipped. Shared with
+/// `svg.rs` so preview/SVG rendering warns on the same condition as `build`.
+pub(crate) fn warn_unresolved_boundary(
+    kind: &str,
+    entity_id: Option<&str>,
+    boundary: &str,
+    layer: &str,
+) {
     let who = entity_id
         .map(|id| format!("'{}'", id))
         .unwrap_or_else(|| "<unnamed>".to_string());
diff --git a/src/svg.rs b/src/svg.rs
index 57c4ba3..441f76b 100644
--- a/src/svg.rs
+++ b/src/svg.rs
@@ -341,7 +341,14 @@ fn render_layers(
             continue;
         }
         let _ = write!(canvas.out, r#"<g data-layer="{}">"#, xml_escape(layer_name));
-        render_layer(&mut canvas, cf, &layer_color, default_weight, units);
+        render_layer(
+            &mut canvas,
+            cf,
+            layer_name,
+            &layer_color,
+            default_weight,
+            units,
+        );
         canvas.out.push_str("</g>");
     }
 
@@ -613,7 +620,14 @@ fn draw_grid(c: &mut Canvas, bounds: &Bounds) {
     c.out.push_str("</g>");
 }
 
-fn render_layer(c: &mut Canvas, cf: &CfFile, layer_color: &str, default_weight: f64, units: &str) {
+fn render_layer(
+    c: &mut Canvas,
+    cf: &CfFile,
+    layer_name: &str,
+    layer_color: &str,
+    default_weight: f64,
+    units: &str,
+) {
     for e in cf.lines.iter().filter(|e| e.common.visible) {
         let s = resolve_style(&e.common, layer_color, default_weight);
         let (x1, y1) = c.world_to_px(e.from[0], e.from[1]);
@@ -688,7 +702,16 @@ fn render_layer(c: &mut Canvas, cf: &CfFile, layer_color: &str, default_weight:
     // Fills and hatches go before text so labels stay readable on top.
     for e in cf.fills.iter().filter(|e| e.common.visible) {
         let pts = if let Some(boundary_id) = &e.boundary {
-            resolve_boundary(boundary_id, cf)
+            let resolved = resolve_boundary(boundary_id, cf);
+            if resolved.is_none() {
+                crate::compiler::warn_unresolved_boundary(
+                    "fill",
+                    e.common.id.as_deref(),
+                    boundary_id,
+                    layer_name,
+                );
+            }
+            resolved
         } else {
             e.points
                 .as_ref()
@@ -708,7 +731,16 @@ fn render_layer(c: &mut Canvas, cf: &CfFile, layer_color: &str, default_weight:
 
     for e in cf.hatches.iter().filter(|e| e.common.visible) {
         let boundary = if let Some(boundary_id) = &e.boundary {
-            resolve_boundary(boundary_id, cf)
+            let resolved = resolve_boundary(boundary_id, cf);
+            if resolved.is_none() {
+                crate::compiler::warn_unresolved_boundary(
+                    "hatch",
+                    e.common.id.as_deref(),
+                    boundary_id,
+                    layer_name,
+                );
+            }
+            resolved
         } else {
             e.points
                 .as_ref()
diff --git a/tests/integration.rs b/tests/integration.rs
index 063165e..98eda7d 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -609,3 +609,65 @@ to = [4.0, 3.0]
     let _ = fs::remove_dir_all(dir);
     let _ = fs::remove_dir_all(imported);
 }
+
+#[test]
+fn preview_warns_on_unresolved_hatch_and_fill_boundary() {
+    let dir = Path::new("/tmp/cadspec_preview_unresolved_boundary");
+    let _ = fs::remove_dir_all(dir);
+    fs::create_dir_all(dir).unwrap();
+
+    fs::write(
+        dir.join("project.toml"),
+        r#"[project]
+name = "boundary-fixture"
+scale = "1:100"
+units = "m"
+
+[layers]
+main = { file = "main.cf" }
+"#,
+    )
+    .unwrap();
+
+    fs::write(
+        dir.join("main.cf"),
+        r##"[layer]
+name = "main"
+
+[[hatch]]
+id = "ht-missing"
+boundary = "does-not-exist"
+pattern = "ansi31"
+scale = 1.0
+angle = 45.0
+
+[[fill]]
+id = "fl-missing"
+boundary = "also-missing"
+"##,
+    )
+    .unwrap();
+
+    let output = std::process::Command::new(env!("CARGO_BIN_EXE_cadspec"))
+        .args(["preview", "-p"])
+        .arg(dir)
+        .args(["--format", "svg"])
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "preview should not fail on an unresolved boundary, it should warn and skip the region"
+    );
+
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("hatch 'ht-missing'") && stderr.contains("does-not-exist"),
+        "expected a warning for the unresolved hatch boundary, got:\n{stderr}"
+    );
+    assert!(
+        stderr.contains("fill 'fl-missing'") && stderr.contains("also-missing"),
+        "expected a warning for the unresolved fill boundary, got:\n{stderr}"
+    );
+
+    let _ = fs::remove_dir_all(dir);
+}

From 92a4eb04b8c79f5dc65ba03b8ecffb4f3a171801 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 19:34:49 -0500
Subject: [PATCH 29/39] test(fmt): add integration coverage for fmt on a real
 project

D8 gap: fmt only had unit tests over inline TOML snippets, never an
end-to-end pass over a real multi-file project. Copy examples/vivienda's
sources into a tmp dir and drive format_project directly: verify the
first pass, that the result still compiles to a valid DXF, that
--check reports nothing outstanding, and that a second pass is a
byte-for-byte no-op across every file.
---
 tests/integration.rs | 58 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/tests/integration.rs b/tests/integration.rs
index 98eda7d..4d42fb4 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -671,3 +671,61 @@ boundary = "also-missing"
 
     let _ = fs::remove_dir_all(dir);
 }
+
+/// Copy a project's source files (project.toml + *.cf) into `dest`, skipping
+/// generated/gitignored artifacts like output.dxf or preview.*.
+fn copy_project_sources(src: &Path, dest: &Path) {
+    fs::create_dir_all(dest).unwrap();
+    for entry in fs::read_dir(src).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        let name = entry.file_name();
+        let is_source = name == "project.toml" || path.extension().is_some_and(|e| e == "cf");
+        if path.is_file() && is_source {
+            fs::copy(&path, dest.join(&name)).unwrap();
+        }
+    }
+}
+
+#[test]
+fn fmt_is_idempotent_on_a_real_project() {
+    use cadspec::fmt::format_project;
+
+    let dir = Path::new("/tmp/cadspec_fmt_real_project");
+    let _ = fs::remove_dir_all(dir);
+    copy_project_sources(Path::new("examples/vivienda"), dir);
+
+    // First pass may or may not need changes; either way it must succeed.
+    format_project(dir, false).unwrap();
+    let after_first: Vec<(std::path::PathBuf, String)> = fs::read_dir(dir)
+        .unwrap()
+        .map(|e| e.unwrap().path())
+        .filter(|p| p.extension().is_some_and(|e| e == "cf") || p.ends_with("project.toml"))
+        .map(|p| {
+            let content = fs::read_to_string(&p).unwrap();
+            (p, content)
+        })
+        .collect();
+
+    // A formatted project must still compile to a valid DXF.
+    let dxf_path = dir.join("output.dxf");
+    compile_project(dir, None, Some(&dxf_path)).unwrap();
+    assert!(dxf_path.exists());
+
+    // `fmt --check` on an already-formatted project reports nothing to do.
+    format_project(dir, true).unwrap();
+
+    // A second `fmt` pass must be a no-op (idempotent) on every file.
+    format_project(dir, false).unwrap();
+    for (path, before) in after_first {
+        let after = fs::read_to_string(&path).unwrap();
+        assert_eq!(
+            before,
+            after,
+            "fmt was not idempotent on {}",
+            path.display()
+        );
+    }
+
+    let _ = fs::remove_dir_all(dir);
+}

From e61bb4722113a2711e1c1804c6393c9126890cee Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 19:36:26 -0500
Subject: [PATCH 30/39] test(planos): add end-to-end coverage for
 generate_plano

D8 gap: planos.rs only had 2 unit tests exercising render_plano directly
with a hand-built Plano struct; nothing drove the CLI-facing
generate_plano, which looks a plano up by name in project.toml. Declare
a [[plano]] on a copy of examples/vivienda and verify the happy path
(preview.png/svg written, title block content present) and that an
unknown name fails with a helpful error instead of panicking.
---
 tests/integration.rs | 60 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/tests/integration.rs b/tests/integration.rs
index 4d42fb4..f112f3b 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -729,3 +729,63 @@ fn fmt_is_idempotent_on_a_real_project() {
 
     let _ = fs::remove_dir_all(dir);
 }
+
+#[test]
+fn generate_plano_renders_a_declared_sheet_end_to_end() {
+    use cadspec::preview::{generate_plano, PreviewOutputs};
+
+    let dir = Path::new("/tmp/cadspec_generate_plano_e2e");
+    let _ = fs::remove_dir_all(dir);
+    copy_project_sources(Path::new("examples/vivienda"), dir);
+
+    // examples/vivienda has no [[plano]] declared; append one so generate_plano
+    // (the CLI-facing `preview --plano` path) has a sheet to look up by name.
+    let mut project_toml = fs::read_to_string(dir.join("project.toml")).unwrap();
+    project_toml.push_str(
+        r#"
+[[plano]]
+name = "P-01"
+view = "plan"
+size = [420.0, 297.0]
+scale = "1:50"
+title = "Planta baja"
+"#,
+    );
+    fs::write(dir.join("project.toml"), project_toml).unwrap();
+
+    generate_plano(
+        dir,
+        "P-01",
+        1200,
+        900,
+        PreviewOutputs {
+            png: true,
+            svg: true,
+        },
+    )
+    .unwrap();
+
+    assert!(dir.join("preview.png").exists());
+    let svg = fs::read_to_string(dir.join("preview.svg")).unwrap();
+    assert!(svg.contains(r#"data-view="plano""#));
+    assert!(svg.contains("Planta baja"));
+
+    // An unknown plano name is a clear error, not a panic.
+    let err = generate_plano(
+        dir,
+        "does-not-exist",
+        1200,
+        900,
+        PreviewOutputs {
+            png: true,
+            svg: true,
+        },
+    )
+    .unwrap_err();
+    assert!(
+        err.to_string().contains("P-01"),
+        "error should list the available plano names: {err}"
+    );
+
+    let _ = fs::remove_dir_all(dir);
+}

From f983e000450826ec83f1016182baa12e2b531c04 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 20:32:52 -0500
Subject: [PATCH 31/39] test(serve,watch): add end-to-end coverage for serve
 and watch

serve_project blocks forever in listener.incoming() and watch_project
blocks forever in rx.recv(), so both are exercised by spawning them on
a (deliberately leaked) thread and driving them from the outside: raw
TCP/HTTP against an OS-assigned port for serve (GET /state, /preview.svg,
404, and a rebuild triggered by editing a .cf file), and a filesystem
edit followed by polling for output.dxf for watch. Closes out D8.
---
 tests/integration.rs | 150 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)

diff --git a/tests/integration.rs b/tests/integration.rs
index f112f3b..d3778a5 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -789,3 +789,153 @@ title = "Planta baja"
 
     let _ = fs::remove_dir_all(dir);
 }
+
+/// An OS-assigned free port: bind to port 0, read back what the OS picked,
+/// then drop the listener so `serve_project` can bind it itself.
+fn free_local_port() -> u16 {
+    std::net::TcpListener::bind(("127.0.0.1", 0))
+        .unwrap()
+        .local_addr()
+        .unwrap()
+        .port()
+}
+
+fn wait_for_port(port: u16, timeout: std::time::Duration) -> bool {
+    let addr = std::net::SocketAddr::from(([127, 0, 0, 1], port));
+    let deadline = std::time::Instant::now() + timeout;
+    while std::time::Instant::now() < deadline {
+        if std::net::TcpStream::connect_timeout(&addr, std::time::Duration::from_millis(200))
+            .is_ok()
+        {
+            return true;
+        }
+        std::thread::sleep(std::time::Duration::from_millis(50));
+    }
+    false
+}
+
+/// GET `path` from the local `serve` instance and return (status, body).
+/// Sends `Connection: close` so the server closes the socket once done and we
+/// can just read to EOF instead of tracking Content-Length ourselves.
+fn http_get(port: u16, path: &str) -> (u16, String) {
+    use std::io::{Read, Write};
+    let mut stream = std::net::TcpStream::connect(("127.0.0.1", port)).unwrap();
+    stream
+        .write_all(
+            format!("GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")
+                .as_bytes(),
+        )
+        .unwrap();
+    stream.shutdown(std::net::Shutdown::Write).ok();
+    let mut raw = String::new();
+    stream.read_to_string(&mut raw).unwrap();
+    let (head, body) = raw.split_once("\r\n\r\n").unwrap_or((raw.as_str(), ""));
+    let status = head
+        .lines()
+        .next()
+        .and_then(|l| l.split_whitespace().nth(1))
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(0);
+    (status, body.to_string())
+}
+
+fn state_version(port: u16) -> u64 {
+    let (status, body) = http_get(port, "/state");
+    assert_eq!(status, 200, "GET /state failed: {body}");
+    let json: serde_json::Value = serde_json::from_str(&body).unwrap();
+    json["version"].as_u64().unwrap()
+}
+
+#[test]
+fn serve_project_serves_state_and_rebuilds_on_file_change_e2e() {
+    let dir = Path::new("/tmp/cadspec_serve_e2e");
+    let _ = fs::remove_dir_all(dir);
+    copy_project_sources(Path::new("examples/vivienda"), dir);
+
+    let port = free_local_port();
+    let serve_dir = dir.to_path_buf();
+    std::thread::spawn(move || {
+        // Leaked on purpose: serve_project blocks forever in listener.incoming()
+        // (no shutdown hook exists); the thread dies with the test process.
+        let _ = cadspec::serve::serve_project(&serve_dir, port, false);
+    });
+    assert!(
+        wait_for_port(port, std::time::Duration::from_secs(5)),
+        "serve did not start listening on 127.0.0.1:{port} in time"
+    );
+
+    let (status, body) = http_get(port, "/state");
+    assert_eq!(status, 200);
+    assert!(body.contains("Vivienda Unifamiliar Lote 12"));
+    let initial_version = state_version(port);
+
+    let (svg_status, svg_body) = http_get(port, "/preview.svg");
+    assert_eq!(svg_status, 200);
+    assert!(svg_body.contains("<svg"));
+
+    let (missing_status, _) = http_get(port, "/does-not-exist");
+    assert_eq!(missing_status, 404);
+
+    // Editing a watched .cf file must trigger a rebuild: bump the state version.
+    let muros = dir.join("muros.cf");
+    let mut contents = fs::read_to_string(&muros).unwrap();
+    contents
+        .push_str("\n# touched by serve_project_serves_state_and_rebuilds_on_file_change_e2e\n");
+    fs::write(&muros, contents).unwrap();
+
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
+    let mut rebuilt_version = initial_version;
+    while std::time::Instant::now() < deadline && rebuilt_version <= initial_version {
+        std::thread::sleep(std::time::Duration::from_millis(100));
+        rebuilt_version = state_version(port);
+    }
+    assert!(
+        rebuilt_version > initial_version,
+        "expected a rebuild (version > {initial_version}) after editing muros.cf, got {rebuilt_version}"
+    );
+
+    let _ = fs::remove_dir_all(dir);
+}
+
+#[test]
+fn watch_project_rebuilds_dxf_on_file_change_e2e() {
+    let dir = Path::new("/tmp/cadspec_watch_e2e");
+    let _ = fs::remove_dir_all(dir);
+    copy_project_sources(Path::new("examples/vivienda"), dir);
+
+    let output = dir.join("output.dxf");
+    assert!(!output.exists());
+
+    let watch_dir = dir.to_path_buf();
+    std::thread::spawn(move || {
+        // Leaked on purpose: watch_project blocks forever on rx.recv() (no
+        // shutdown hook exists); the thread dies with the test process.
+        let _ = cadspec::watch::watch_project(&watch_dir);
+    });
+
+    // Give the watcher time to register and clear its own startup debounce
+    // window (a change within DEBOUNCE=300ms of start is silently dropped,
+    // since `last_build` is initialized before the watch loop even starts).
+    std::thread::sleep(std::time::Duration::from_millis(500));
+
+    let muros = dir.join("muros.cf");
+    let mut contents = fs::read_to_string(&muros).unwrap();
+    contents.push_str("\n# touched by watch_project_rebuilds_dxf_on_file_change_e2e\n");
+    fs::write(&muros, contents).unwrap();
+
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
+    while std::time::Instant::now() < deadline && !output.exists() {
+        std::thread::sleep(std::time::Duration::from_millis(100));
+    }
+    assert!(
+        output.exists(),
+        "watch did not rebuild output.dxf after editing muros.cf"
+    );
+    let dxf = fs::read_to_string(&output).unwrap();
+    assert!(
+        dxf.contains("SECTION"),
+        "output.dxf does not look like a DXF file"
+    );
+
+    let _ = fs::remove_dir_all(dir);
+}

From 20d9f6337ca858f77799928bd71f04e8e1e27075 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 21:41:22 -0500
Subject: [PATCH 32/39] feat(color): expand hex_to_aci to the full 255-entry
 ACI palette

hex_to_aci and aci_to_hex only knew about the 9 standard ACI colors, so
any layer color outside that small set (or a DXF layer index above 9 on
import) fell back to white. Both now use the full AutoCAD Color Index
table (indices 1-255), giving a much closer nearest-color match on
export and exact recovery of more colors on import.

aci_to_hex now returns an owned String since it looks up entries in a
255-color const table instead of matching a handful of literals.
---
 src/color.rs         | 324 ++++++++++++++++++++++++++++++++++++++-----
 src/importer.rs      |  11 +-
 tests/integration.rs |   7 +-
 3 files changed, 297 insertions(+), 45 deletions(-)

diff --git a/src/color.rs b/src/color.rs
index ac38766..8d53aa5 100644
--- a/src/color.rs
+++ b/src/color.rs
@@ -1,20 +1,268 @@
 //! Color and weight conversion utilities for DXF output.
 
-/// Standard ACI palette (indices 1-9) as RGB triples.
-const ACI_PALETTE: [(u8, (u8, u8, u8)); 9] = [
-    (1, (0xFF, 0x00, 0x00)), // red
-    (2, (0xFF, 0xFF, 0x00)), // yellow
-    (3, (0x00, 0xFF, 0x00)), // green
-    (4, (0x00, 0xFF, 0xFF)), // cyan
-    (5, (0x00, 0x00, 0xFF)), // blue
-    (6, (0xFF, 0x00, 0xFF)), // magenta
-    (7, (0xFF, 0xFF, 0xFF)), // white
-    (8, (0x80, 0x80, 0x80)), // dark grey
-    (9, (0xC0, 0xC0, 0xC0)), // light grey
+/// Full AutoCAD Color Index (ACI) palette, indices 1-255, as RGB triples.
+/// This is the standard DXF color table (same values used by AutoCAD,
+/// LibreCAD, dxflib and ezdxf), not something specific to cadspec.
+const ACI_PALETTE: [(u8, (u8, u8, u8)); 255] = [
+    (1, (0xFF, 0x00, 0x00)),
+    (2, (0xFF, 0xFF, 0x00)),
+    (3, (0x00, 0xFF, 0x00)),
+    (4, (0x00, 0xFF, 0xFF)),
+    (5, (0x00, 0x00, 0xFF)),
+    (6, (0xFF, 0x00, 0xFF)),
+    (7, (0xFF, 0xFF, 0xFF)),
+    (8, (0x80, 0x80, 0x80)),
+    (9, (0xC0, 0xC0, 0xC0)),
+    (10, (0xFF, 0x00, 0x00)),
+    (11, (0xFF, 0x7F, 0x7F)),
+    (12, (0xA5, 0x00, 0x00)),
+    (13, (0xA5, 0x52, 0x52)),
+    (14, (0x7F, 0x00, 0x00)),
+    (15, (0x7F, 0x3F, 0x3F)),
+    (16, (0x4C, 0x00, 0x00)),
+    (17, (0x4C, 0x26, 0x26)),
+    (18, (0x26, 0x00, 0x00)),
+    (19, (0x26, 0x13, 0x13)),
+    (20, (0xFF, 0x3F, 0x00)),
+    (21, (0xFF, 0x9F, 0x7F)),
+    (22, (0xA5, 0x29, 0x00)),
+    (23, (0xA5, 0x67, 0x52)),
+    (24, (0x7F, 0x1F, 0x00)),
+    (25, (0x7F, 0x4F, 0x3F)),
+    (26, (0x4C, 0x13, 0x00)),
+    (27, (0x4C, 0x2F, 0x26)),
+    (28, (0x26, 0x09, 0x00)),
+    (29, (0x26, 0x17, 0x13)),
+    (30, (0xFF, 0x7F, 0x00)),
+    (31, (0xFF, 0xBF, 0x7F)),
+    (32, (0xA5, 0x52, 0x00)),
+    (33, (0xA5, 0x7C, 0x52)),
+    (34, (0x7F, 0x3F, 0x00)),
+    (35, (0x7F, 0x5F, 0x3F)),
+    (36, (0x4C, 0x26, 0x00)),
+    (37, (0x4C, 0x39, 0x26)),
+    (38, (0x26, 0x13, 0x00)),
+    (39, (0x26, 0x1C, 0x13)),
+    (40, (0xFF, 0xBF, 0x00)),
+    (41, (0xFF, 0xDF, 0x7F)),
+    (42, (0xA5, 0x7C, 0x00)),
+    (43, (0xA5, 0x91, 0x52)),
+    (44, (0x7F, 0x5F, 0x00)),
+    (45, (0x7F, 0x6F, 0x3F)),
+    (46, (0x4C, 0x39, 0x00)),
+    (47, (0x4C, 0x42, 0x26)),
+    (48, (0x26, 0x1C, 0x00)),
+    (49, (0x26, 0x21, 0x13)),
+    (50, (0xFF, 0xFF, 0x00)),
+    (51, (0xFF, 0xFF, 0x7F)),
+    (52, (0xA5, 0xA5, 0x00)),
+    (53, (0xA5, 0xA5, 0x52)),
+    (54, (0x7F, 0x7F, 0x00)),
+    (55, (0x7F, 0x7F, 0x3F)),
+    (56, (0x4C, 0x4C, 0x00)),
+    (57, (0x4C, 0x4C, 0x26)),
+    (58, (0x26, 0x26, 0x00)),
+    (59, (0x26, 0x26, 0x13)),
+    (60, (0xBF, 0xFF, 0x00)),
+    (61, (0xDF, 0xFF, 0x7F)),
+    (62, (0x7C, 0xA5, 0x00)),
+    (63, (0x91, 0xA5, 0x52)),
+    (64, (0x5F, 0x7F, 0x00)),
+    (65, (0x6F, 0x7F, 0x3F)),
+    (66, (0x39, 0x4C, 0x00)),
+    (67, (0x42, 0x4C, 0x26)),
+    (68, (0x1C, 0x26, 0x00)),
+    (69, (0x21, 0x26, 0x13)),
+    (70, (0x7F, 0xFF, 0x00)),
+    (71, (0xBF, 0xFF, 0x7F)),
+    (72, (0x52, 0xA5, 0x00)),
+    (73, (0x7C, 0xA5, 0x52)),
+    (74, (0x3F, 0x7F, 0x00)),
+    (75, (0x5F, 0x7F, 0x3F)),
+    (76, (0x26, 0x4C, 0x00)),
+    (77, (0x39, 0x4C, 0x26)),
+    (78, (0x13, 0x26, 0x00)),
+    (79, (0x1C, 0x26, 0x13)),
+    (80, (0x3F, 0xFF, 0x00)),
+    (81, (0x9F, 0xFF, 0x7F)),
+    (82, (0x29, 0xA5, 0x00)),
+    (83, (0x67, 0xA5, 0x52)),
+    (84, (0x1F, 0x7F, 0x00)),
+    (85, (0x4F, 0x7F, 0x3F)),
+    (86, (0x13, 0x4C, 0x00)),
+    (87, (0x2F, 0x4C, 0x26)),
+    (88, (0x09, 0x26, 0x00)),
+    (89, (0x17, 0x26, 0x13)),
+    (90, (0x00, 0xFF, 0x00)),
+    (91, (0x7F, 0xFF, 0x7F)),
+    (92, (0x00, 0xA5, 0x00)),
+    (93, (0x52, 0xA5, 0x52)),
+    (94, (0x00, 0x7F, 0x00)),
+    (95, (0x3F, 0x7F, 0x3F)),
+    (96, (0x00, 0x4C, 0x00)),
+    (97, (0x26, 0x4C, 0x26)),
+    (98, (0x00, 0x26, 0x00)),
+    (99, (0x13, 0x26, 0x13)),
+    (100, (0x00, 0xFF, 0x3F)),
+    (101, (0x7F, 0xFF, 0x9F)),
+    (102, (0x00, 0xA5, 0x29)),
+    (103, (0x52, 0xA5, 0x67)),
+    (104, (0x00, 0x7F, 0x1F)),
+    (105, (0x3F, 0x7F, 0x4F)),
+    (106, (0x00, 0x4C, 0x13)),
+    (107, (0x26, 0x4C, 0x2F)),
+    (108, (0x00, 0x26, 0x09)),
+    (109, (0x13, 0x58, 0x17)),
+    (110, (0x00, 0xFF, 0x7F)),
+    (111, (0x7F, 0xFF, 0xBF)),
+    (112, (0x00, 0xA5, 0x52)),
+    (113, (0x52, 0xA5, 0x7C)),
+    (114, (0x00, 0x7F, 0x3F)),
+    (115, (0x3F, 0x7F, 0x5F)),
+    (116, (0x00, 0x4C, 0x26)),
+    (117, (0x26, 0x4C, 0x39)),
+    (118, (0x00, 0x26, 0x13)),
+    (119, (0x13, 0x58, 0x1C)),
+    (120, (0x00, 0xFF, 0xBF)),
+    (121, (0x7F, 0xFF, 0xDF)),
+    (122, (0x00, 0xA5, 0x7C)),
+    (123, (0x52, 0xA5, 0x91)),
+    (124, (0x00, 0x7F, 0x5F)),
+    (125, (0x3F, 0x7F, 0x6F)),
+    (126, (0x00, 0x4C, 0x39)),
+    (127, (0x26, 0x4C, 0x42)),
+    (128, (0x00, 0x26, 0x1C)),
+    (129, (0x13, 0x58, 0x58)),
+    (130, (0x00, 0xFF, 0xFF)),
+    (131, (0x7F, 0xFF, 0xFF)),
+    (132, (0x00, 0xA5, 0xA5)),
+    (133, (0x52, 0xA5, 0xA5)),
+    (134, (0x00, 0x7F, 0x7F)),
+    (135, (0x3F, 0x7F, 0x7F)),
+    (136, (0x00, 0x4C, 0x4C)),
+    (137, (0x26, 0x4C, 0x4C)),
+    (138, (0x00, 0x26, 0x26)),
+    (139, (0x13, 0x58, 0x58)),
+    (140, (0x00, 0xBF, 0xFF)),
+    (141, (0x7F, 0xDF, 0xFF)),
+    (142, (0x00, 0x7C, 0xA5)),
+    (143, (0x52, 0x91, 0xA5)),
+    (144, (0x00, 0x5F, 0x7F)),
+    (145, (0x3F, 0x6F, 0x7F)),
+    (146, (0x00, 0x39, 0x4C)),
+    (147, (0x26, 0x42, 0x7E)),
+    (148, (0x00, 0x1C, 0x26)),
+    (149, (0x13, 0x58, 0x58)),
+    (150, (0x00, 0x7F, 0xFF)),
+    (151, (0x7F, 0xBF, 0xFF)),
+    (152, (0x00, 0x52, 0xA5)),
+    (153, (0x52, 0x7C, 0xA5)),
+    (154, (0x00, 0x3F, 0x7F)),
+    (155, (0x3F, 0x5F, 0x7F)),
+    (156, (0x00, 0x26, 0x4C)),
+    (157, (0x26, 0x39, 0x7E)),
+    (158, (0x00, 0x13, 0x26)),
+    (159, (0x13, 0x1C, 0x58)),
+    (160, (0x00, 0x3F, 0xFF)),
+    (161, (0x7F, 0x9F, 0xFF)),
+    (162, (0x00, 0x29, 0xA5)),
+    (163, (0x52, 0x67, 0xA5)),
+    (164, (0x00, 0x1F, 0x7F)),
+    (165, (0x3F, 0x4F, 0x7F)),
+    (166, (0x00, 0x13, 0x4C)),
+    (167, (0x26, 0x2F, 0x7E)),
+    (168, (0x00, 0x09, 0x26)),
+    (169, (0x13, 0x17, 0x58)),
+    (170, (0x00, 0x00, 0xFF)),
+    (171, (0x7F, 0x7F, 0xFF)),
+    (172, (0x00, 0x00, 0xA5)),
+    (173, (0x52, 0x52, 0xA5)),
+    (174, (0x00, 0x00, 0x7F)),
+    (175, (0x3F, 0x3F, 0x7F)),
+    (176, (0x00, 0x00, 0x4C)),
+    (177, (0x26, 0x26, 0x7E)),
+    (178, (0x00, 0x00, 0x26)),
+    (179, (0x13, 0x13, 0x58)),
+    (180, (0x3F, 0x00, 0xFF)),
+    (181, (0x9F, 0x7F, 0xFF)),
+    (182, (0x29, 0x00, 0xA5)),
+    (183, (0x67, 0x52, 0xA5)),
+    (184, (0x1F, 0x00, 0x7F)),
+    (185, (0x4F, 0x3F, 0x7F)),
+    (186, (0x13, 0x00, 0x4C)),
+    (187, (0x2F, 0x26, 0x7E)),
+    (188, (0x09, 0x00, 0x26)),
+    (189, (0x17, 0x13, 0x58)),
+    (190, (0x7F, 0x00, 0xFF)),
+    (191, (0xBF, 0x7F, 0xFF)),
+    (192, (0x52, 0x00, 0xA5)),
+    (193, (0x7C, 0x52, 0xA5)),
+    (194, (0x3F, 0x00, 0x7F)),
+    (195, (0x5F, 0x3F, 0x7F)),
+    (196, (0x26, 0x00, 0x4C)),
+    (197, (0x39, 0x26, 0x7E)),
+    (198, (0x13, 0x00, 0x26)),
+    (199, (0x1C, 0x13, 0x58)),
+    (200, (0xBF, 0x00, 0xFF)),
+    (201, (0xDF, 0x7F, 0xFF)),
+    (202, (0x7C, 0x00, 0xA5)),
+    (203, (0x91, 0x52, 0xA5)),
+    (204, (0x5F, 0x00, 0x7F)),
+    (205, (0x6F, 0x3F, 0x7F)),
+    (206, (0x39, 0x00, 0x4C)),
+    (207, (0x42, 0x26, 0x4C)),
+    (208, (0x1C, 0x00, 0x26)),
+    (209, (0x58, 0x13, 0x58)),
+    (210, (0xFF, 0x00, 0xFF)),
+    (211, (0xFF, 0x7F, 0xFF)),
+    (212, (0xA5, 0x00, 0xA5)),
+    (213, (0xA5, 0x52, 0xA5)),
+    (214, (0x7F, 0x00, 0x7F)),
+    (215, (0x7F, 0x3F, 0x7F)),
+    (216, (0x4C, 0x00, 0x4C)),
+    (217, (0x4C, 0x26, 0x4C)),
+    (218, (0x26, 0x00, 0x26)),
+    (219, (0x58, 0x13, 0x58)),
+    (220, (0xFF, 0x00, 0xBF)),
+    (221, (0xFF, 0x7F, 0xDF)),
+    (222, (0xA5, 0x00, 0x7C)),
+    (223, (0xA5, 0x52, 0x91)),
+    (224, (0x7F, 0x00, 0x5F)),
+    (225, (0x7F, 0x3F, 0x6F)),
+    (226, (0x4C, 0x00, 0x39)),
+    (227, (0x4C, 0x26, 0x42)),
+    (228, (0x26, 0x00, 0x1C)),
+    (229, (0x58, 0x13, 0x58)),
+    (230, (0xFF, 0x00, 0x7F)),
+    (231, (0xFF, 0x7F, 0xBF)),
+    (232, (0xA5, 0x00, 0x52)),
+    (233, (0xA5, 0x52, 0x7C)),
+    (234, (0x7F, 0x00, 0x3F)),
+    (235, (0x7F, 0x3F, 0x5F)),
+    (236, (0x4C, 0x00, 0x26)),
+    (237, (0x4C, 0x26, 0x39)),
+    (238, (0x26, 0x00, 0x13)),
+    (239, (0x58, 0x13, 0x1C)),
+    (240, (0xFF, 0x00, 0x3F)),
+    (241, (0xFF, 0x7F, 0x9F)),
+    (242, (0xA5, 0x00, 0x29)),
+    (243, (0xA5, 0x52, 0x67)),
+    (244, (0x7F, 0x00, 0x1F)),
+    (245, (0x7F, 0x3F, 0x4F)),
+    (246, (0x4C, 0x00, 0x13)),
+    (247, (0x4C, 0x26, 0x2F)),
+    (248, (0x26, 0x00, 0x09)),
+    (249, (0x58, 0x13, 0x17)),
+    (250, (0x00, 0x00, 0x00)),
+    (251, (0x65, 0x65, 0x65)),
+    (252, (0x66, 0x66, 0x66)),
+    (253, (0x99, 0x99, 0x99)),
+    (254, (0xCC, 0xCC, 0xCC)),
+    (255, (0xFF, 0xFF, 0xFF)),
 ];
 
-/// ACI color index from hex string: nearest color in the standard palette
-/// (unparseable input falls back to 7, white).
+/// ACI color index from hex string: nearest color in the full 255-entry
+/// ACI palette (unparseable input falls back to 7, white).
 pub fn hex_to_aci(hex: &str) -> u8 {
     let hex = hex.trim_start_matches('#');
     let Ok(rgb) = u32::from_str_radix(hex, 16) else {
@@ -38,20 +286,14 @@ pub fn hex_to_aci(hex: &str) -> u8 {
         .unwrap_or(7)
 }
 
-/// Hex color from an ACI color index (inverse of `hex_to_aci`).
-pub fn aci_to_hex(index: u8) -> &'static str {
-    match index {
-        1 => "#FF0000", // red
-        2 => "#FFFF00", // yellow
-        3 => "#00FF00", // green
-        4 => "#00FFFF", // cyan
-        5 => "#0000FF", // blue
-        6 => "#FF00FF", // magenta
-        7 => "#FFFFFF", // white
-        8 => "#808080", // dark grey
-        9 => "#C0C0C0", // light grey
-        _ => "#FFFFFF", // default white
-    }
+/// Hex color from an ACI color index (inverse of `hex_to_aci`). Indices
+/// outside 1-255 (e.g. 0, BYBLOCK) fall back to white.
+pub fn aci_to_hex(index: u8) -> String {
+    ACI_PALETTE
+        .iter()
+        .find(|(i, _)| *i == index)
+        .map(|(_, (r, g, b))| format!("#{r:02X}{g:02X}{b:02X}"))
+        .unwrap_or_else(|| "#FFFFFF".to_string())
 }
 
 /// Convert hex color string to 24-bit integer for DXF true color.
@@ -78,10 +320,10 @@ mod tests {
 
     #[test]
     fn hex_to_aci_maps_arbitrary_colors_to_nearest() {
-        assert_eq!(hex_to_aci("#FF4444"), 1); // reddish → red
-        assert_eq!(hex_to_aci("#00CC44"), 3); // greenish → green
-        assert_eq!(hex_to_aci("#2244CC"), 5); // bluish → blue
-        assert_eq!(hex_to_aci("#123456"), 8); // dark muted → dark grey
+        assert_eq!(hex_to_aci("#FF4444"), 20); // reddish → nearest ACI red-orange shade
+        assert_eq!(hex_to_aci("#00CC44"), 112); // greenish → nearest ACI green-cyan shade
+        assert_eq!(hex_to_aci("#2244CC"), 152); // bluish → nearest ACI blue shade
+        assert_eq!(hex_to_aci("#123456"), 146); // dark muted → nearest ACI dark blue shade
         assert_eq!(hex_to_aci("#invalid"), 7); // unparseable → white
         assert_eq!(hex_to_aci("#FFF"), 7); // wrong length → white
     }
@@ -89,9 +331,25 @@ mod tests {
     #[test]
     fn aci_roundtrips_standard_palette() {
         for index in 1..=9u8 {
-            assert_eq!(hex_to_aci(aci_to_hex(index)), index);
+            assert_eq!(hex_to_aci(&aci_to_hex(index)), index);
+        }
+        assert_eq!(aci_to_hex(0), "#FFFFFF"); // out of range (e.g. BYBLOCK) → white
+    }
+
+    #[test]
+    fn aci_roundtrips_full_palette_by_color() {
+        // Some ACI indices share the exact same RGB value (e.g. several dark
+        // greys), so hex_to_aci may not return the original index — but it
+        // must always land on an index with the identical color.
+        for index in 1..=255u8 {
+            let hex = aci_to_hex(index);
+            let roundtripped = hex_to_aci(&hex);
+            assert_eq!(
+                aci_to_hex(roundtripped),
+                hex,
+                "index {index} ({hex}) drifted to a different color on roundtrip"
+            );
         }
-        assert_eq!(aci_to_hex(42), "#FFFFFF"); // unknown → white
     }
 
     #[test]
diff --git a/src/importer.rs b/src/importer.rs
index 71a4f74..5b8e689 100644
--- a/src/importer.rs
+++ b/src/importer.rs
@@ -22,11 +22,7 @@ impl StyleAttrs {
         let color = if common.color_24_bit > 0 {
             Some(format!("#{:06X}", common.color_24_bit))
         } else {
-            common
-                .color
-                .index()
-                .filter(|i| (1..=9).contains(i))
-                .map(|i| aci_to_hex(i).to_string())
+            common.color.index().filter(|i| *i > 0).map(aci_to_hex)
         };
         let weight = (common.lineweight_enum_value > 0)
             .then(|| f64::from(common.lineweight_enum_value) / 100.0);
@@ -181,10 +177,7 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
         Ok(drawing) => {
             for layer in drawing.layers() {
                 if let Some(index) = layer.color.index() {
-                    layer_colors.insert(
-                        normalize_layer_name(&layer.name),
-                        aci_to_hex(index).to_string(),
-                    );
+                    layer_colors.insert(normalize_layer_name(&layer.name), aci_to_hex(index));
                 }
             }
 
diff --git a/tests/integration.rs b/tests/integration.rs
index d3778a5..7362f18 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -490,10 +490,11 @@ offset = -1.2
     import_dxf(&dxf_path, imported, None).unwrap();
     let cf = fs::read_to_string(imported.join("plano.cf")).unwrap();
 
-    // Layer color survives via the DXF layer table (ACI): #FF4444 is not in
-    // the standard palette, so it comes back as the nearest ACI color (red).
+    // Layer color survives via the DXF layer table (ACI): #FF4444 is not
+    // itself an ACI color, so it comes back as the nearest ACI palette
+    // entry (#FF3F00, ACI 20).
     assert!(
-        cf.contains("color = \"#FF0000\""),
+        cf.contains("color = \"#FF3F00\""),
         "layer color lost:\n{cf}"
     );
     // Entity style survives via true color, lineweight and line type

From 37bbc9cd1f45604aae9322dbb5b2b4d5a921be63 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 21:42:58 -0500
Subject: [PATCH 33/39] fix(dxf): register CADSPEC_HATCH in the APPID table

The writer stamped hatch pattern lines with XDATA under the
CADSPEC_HATCH application name but never declared that name in the
DXF's APPID table. cadspec's own importer tolerated this (it reads
XDATA regardless of table registration), but strict DXF readers are
expected to ignore XDATA from unregistered apps. DxfWriter::new now
registers CADSPEC_HATCH via drawing.add_app_id, matching how AutoCAD's
own reserved app names are already ensured present.
---
 src/dxf_writer.rs | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/dxf_writer.rs b/src/dxf_writer.rs
index 7291dc2..ab060e6 100644
--- a/src/dxf_writer.rs
+++ b/src/dxf_writer.rs
@@ -3,7 +3,7 @@
 use anyhow::Result;
 use dxf::entities::{Entity, EntityType, LwPolyline};
 use dxf::enums::AcadVersion;
-use dxf::tables::Layer;
+use dxf::tables::{AppId, Layer};
 use dxf::{Color, Drawing, LwPolylineVertex, Point, XData, XDataItem};
 use std::path::Path;
 
@@ -45,6 +45,13 @@ impl DxfWriter {
         drawing.add_line_type(Self::make_line_type("DOTTED", &[0.0, -0.25]));
         drawing.add_line_type(Self::make_line_type("DASHDOT", &[0.5, -0.25, 0.0, -0.25]));
 
+        // Register the APPID our hatch pattern lines stamp XDATA under, so
+        // strict readers don't have to fall back on undeclared-app tolerance.
+        drawing.add_app_id(AppId {
+            name: HATCH_XDATA_APP.to_string(),
+            ..Default::default()
+        });
+
         Self {
             drawing,
             hatch_group_seq: 0,

From 241983c78f8473d38ce65fe19ca6c00633fcf2ea Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 22:32:56 -0500
Subject: [PATCH 34/39] fix(dxf): remove duplicate too_many_arguments attribute
 on dim_linear

---
 src/dxf_writer.rs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/dxf_writer.rs b/src/dxf_writer.rs
index ab060e6..181fa02 100644
--- a/src/dxf_writer.rs
+++ b/src/dxf_writer.rs
@@ -210,7 +210,6 @@ impl DxfWriter {
         self.add_entity(EntityType::ModelPoint(pt), layer, style);
     }
 
-    #[allow(clippy::too_many_arguments)]
     #[allow(clippy::too_many_arguments)]
     pub fn dim_linear(
         &mut self,

From e5969cb5e510e789df931b4db0c337b50162c3eb Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Sun, 5 Jul 2026 22:33:01 -0500
Subject: [PATCH 35/39] test(config): add unit test coverage for config_set and
 config_show

config_path() reads $HOME directly, so config_set/config_show had zero
test coverage (testing them would have written into the real user's
~/.cadspec/config.toml). Split the path resolution out into
config_set_at/config_show_at, taking an explicit path like the rest of
the codebase's testable functions (fmt::format_project,
scaffold::create_project, etc.), and added tests against scratch paths
under /tmp.
---
 src/config.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 75 insertions(+), 8 deletions(-)

diff --git a/src/config.rs b/src/config.rs
index d1c296a..d9cdd14 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -2,7 +2,7 @@
 
 use anyhow::{anyhow, Context, Result};
 use std::fs;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use toml_edit::{value, DocumentMut, Item, Table};
 
 const SUPPORTED_KEYS: &[&str] = &["author", "units"];
@@ -12,7 +12,7 @@ fn config_path() -> Result<PathBuf> {
     Ok(PathBuf::from(home).join(".cadspec").join("config.toml"))
 }
 
-fn load_document(path: &PathBuf) -> Result<DocumentMut> {
+fn load_document(path: &Path) -> Result<DocumentMut> {
     if !path.exists() {
         return Ok(DocumentMut::new());
     }
@@ -34,6 +34,10 @@ fn ensure_defaults_table(doc: &mut DocumentMut) -> Result<&mut Table> {
 }
 
 pub fn config_set(key: &str, val: &str) -> Result<()> {
+    config_set_at(&config_path()?, key, val)
+}
+
+fn config_set_at(path: &Path, key: &str, val: &str) -> Result<()> {
     if !SUPPORTED_KEYS.contains(&key) {
         let options = SUPPORTED_KEYS.join(", ");
         return Err(anyhow!(
@@ -43,26 +47,27 @@ pub fn config_set(key: &str, val: &str) -> Result<()> {
         ));
     }
 
-    let path = config_path()?;
     if let Some(parent) = path.parent() {
         fs::create_dir_all(parent)
             .with_context(|| format!("Cannot create {}", parent.display()))?;
     }
 
-    let mut doc = load_document(&path)?;
+    let mut doc = load_document(path)?;
     let defaults = ensure_defaults_table(&mut doc)?;
     defaults[key] = value(val);
 
-    fs::write(&path, doc.to_string())
-        .with_context(|| format!("Cannot write {}", path.display()))?;
+    fs::write(path, doc.to_string()).with_context(|| format!("Cannot write {}", path.display()))?;
     println!("✓ config {} = {}", key, val);
     println!("  {}", path.display());
     Ok(())
 }
 
 pub fn config_show() -> Result<()> {
-    let path = config_path()?;
-    let doc = load_document(&path)?;
+    config_show_at(&config_path()?)
+}
+
+fn config_show_at(path: &Path) -> Result<()> {
+    let doc = load_document(path)?;
     println!("Global config: {}", path.display());
     if let Some(defaults) = doc.get("defaults").and_then(Item::as_table) {
         for key in SUPPORTED_KEYS {
@@ -73,3 +78,65 @@ pub fn config_show() -> Result<()> {
     }
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn scratch_path(name: &str) -> PathBuf {
+        let dir = PathBuf::from("/tmp").join(name);
+        let _ = fs::remove_dir_all(&dir);
+        dir.join("config.toml")
+    }
+
+    #[test]
+    fn config_set_rejects_unsupported_key() {
+        let path = scratch_path("cadspec_test_config_bad_key");
+
+        let err = config_set_at(&path, "bogus", "x").unwrap_err();
+
+        assert!(err.to_string().contains("Unsupported config key 'bogus'"));
+        assert!(!path.exists());
+    }
+
+    #[test]
+    fn config_set_creates_parent_dir_and_writes_value() {
+        let path = scratch_path("cadspec_test_config_new");
+
+        config_set_at(&path, "author", "Jheison").unwrap();
+
+        let doc = load_document(&path).unwrap();
+        assert_eq!(
+            doc["defaults"]["author"].as_str(),
+            Some("Jheison"),
+            "config file: {}",
+            fs::read_to_string(&path).unwrap()
+        );
+
+        let _ = fs::remove_dir_all(path.parent().unwrap());
+    }
+
+    #[test]
+    fn config_set_preserves_other_keys_and_overwrites_target() {
+        let path = scratch_path("cadspec_test_config_overwrite");
+
+        config_set_at(&path, "author", "Jheison").unwrap();
+        config_set_at(&path, "units", "mm").unwrap();
+        config_set_at(&path, "author", "Someone Else").unwrap();
+
+        let doc = load_document(&path).unwrap();
+        assert_eq!(doc["defaults"]["author"].as_str(), Some("Someone Else"));
+        assert_eq!(doc["defaults"]["units"].as_str(), Some("mm"));
+
+        let _ = fs::remove_dir_all(path.parent().unwrap());
+    }
+
+    #[test]
+    fn config_show_on_missing_file_does_not_error() {
+        let path = scratch_path("cadspec_test_config_missing");
+
+        config_show_at(&path).unwrap();
+
+        assert!(!path.exists());
+    }
+}

From c70689ce3b958a3bfa64a8c1ccecf96ddc1aa0d6 Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Tue, 7 Jul 2026 13:37:20 -0500
Subject: [PATCH 36/39] feat(serve): dark-only viewer, favicon, and editor
 auto-reload

Resolve the three D13 issues with the `serve` web viewer:

- Branding (13a): add an inline SVG favicon served at `/favicon.svg`
  and linked from the page head, so the tab has a "cs" monogram instead
  of a blank icon. The "cadspec live" wordmark already lived in the
  header.
- Themes (13b): drop the three-way theme toggle. The SVG background is
  hardcoded dark, so the light theme only ever recolored the chrome and
  read as a redundant second dark. Remove the toggle button, the
  pre-paint init script, the `[data-theme="light"]` and
  `prefers-color-scheme` CSS, and the `cadspec-theme` localStorage key,
  leaving a single dark theme.
- Editor auto-reload (13c): the built-in .cf editor now resyncs from
  disk when a file changes externally (another editor, git checkout).
  On every SSE tick `refresh()` calls a new `__reloadEditorIfClean`
  hook that reloads the current file unless there are unsaved edits or
  the user typed within the last 2s while focused, so in-progress edits
  are never clobbered.

Tests: unit tests assert the served HTML has the favicon/branding, no
theme-toggle remnants, and the reload hook; the serve e2e test now
checks `/favicon.svg` returns 200 with SVG content.
---
 src/serve.rs         | 113 ++++++++++++++++++-------------------------
 tests/integration.rs |   4 ++
 2 files changed, 51 insertions(+), 66 deletions(-)

diff --git a/src/serve.rs b/src/serve.rs
index 19b3432..ea407f3 100644
--- a/src/serve.rs
+++ b/src/serve.rs
@@ -501,6 +501,7 @@ fn handle_connection(stream: TcpStream, state: &Shared) -> std::io::Result<()> {
             }
         }
         "/events" => serve_events(stream, state),
+        "/favicon.svg" => respond(stream, "200 OK", "image/svg+xml", FAVICON_SVG.as_bytes()),
         _ => respond(stream, "404 Not Found", "text/plain", b"not found"),
     }
 }
@@ -740,25 +741,17 @@ fn html_escape(s: &str) -> String {
         .replace('>', "&gt;")
 }
 
+const FAVICON_SVG: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#0d0e11"/><text x="16" y="22" font-family="monospace" font-size="16" font-weight="700" fill="#6ec6e6" text-anchor="middle">cs</text></svg>"##;
+
 const INDEX_HTML: &str = r##"<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <title>{{PROJECT_NAME}} — cadspec live</title>
-<script>
-  // Theme: follow the OS unless the user toggled an explicit choice. Pre-paint
-  // so there is no flash.
-  (function () {
-    try {
-      var t = localStorage.getItem('cadspec-theme');
-      if (t === 'light' || t === 'dark') document.documentElement.dataset.theme = t;
-    } catch (e) {}
-  })();
-</script>
+<link rel="icon" href="/favicon.svg">
 <style>
   @import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&display=swap');
-  /* Dark is the default (the lab). System light, or the toggle, flips to the
-     plan-white. `[data-theme]` (set by the toggle) overrides the system. */
+  /* Dark only — this is the lab, not the plan-white. */
   :root {
     --bg: #0d0e11; --panel: #14161a; --panel-2: #181b20;
     --ink: #d6dadf; --ink-strong: #ffffff; --ink-dim: #aab0b8;
@@ -769,28 +762,6 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
     --code-bg: #0a0b0d; --code-ink: #cdd6df;
     --t-num: #d9a35f; --t-hdr: #c79be0;
   }
-  :root[data-theme="light"], :root[data-theme="light"] :root {
-    --bg: #f6f8fa; --panel: #ffffff; --panel-2: #eef2f5;
-    --ink: #1b2630; --ink-strong: #0a1218; --ink-dim: #41505b;
-    --ink-mute: #6b7882; --ink-faint: #97a2ab;
-    --line: #dde5ea; --line-2: #cdd7de;
-    --accent: #156c80; --accent-soft: rgba(21,108,128,0.12);
-    --ok: #1f8f5a; --err: #b23b34; --err-soft: #fbeae9; --err-ink: #9a3027;
-    --code-bg: #f0f3f5; --code-ink: #1b2630;
-    --t-num: #9a6516; --t-hdr: #7a3fa0;
-  }
-  @media (prefers-color-scheme: light) {
-    :root:not([data-theme]) {
-      --bg: #f6f8fa; --panel: #ffffff; --panel-2: #eef2f5;
-      --ink: #1b2630; --ink-strong: #0a1218; --ink-dim: #41505b;
-      --ink-mute: #6b7882; --ink-faint: #97a2ab;
-      --line: #dde5ea; --line-2: #cdd7de;
-      --accent: #156c80; --accent-soft: rgba(21,108,128,0.12);
-      --ok: #1f8f5a; --err: #b23b34; --err-soft: #fbeae9; --err-ink: #9a3027;
-      --code-bg: #f0f3f5; --code-ink: #1b2630;
-      --t-num: #9a6516; --t-hdr: #7a3fa0;
-    }
-  }
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body { background: var(--bg); color: var(--ink); font-family: 'IBM Plex Mono', ui-monospace, 'Cascadia Code', monospace; height: 100vh; display: flex; flex-direction: column; overflow: hidden; }
   header { display: flex; align-items: center; gap: 12px; padding: 9px 14px; background: var(--panel-2); border-bottom: 1px solid var(--line-2); user-select: none; }
@@ -887,7 +858,6 @@ const INDEX_HTML: &str = r##"<!DOCTYPE html>
   <button id="btn3d" title="extruded 3D view (key: 3)">3D</button>
   <button id="btnfit" title="fit to view (key: F)">fit</button>
   <button id="btneditor" class="active" title="toggle editor (key: E)">editor</button>
-  <button id="btntheme" title="theme — follow system / light / dark">◐</button>
   <span id="hint">edit .cf files — preview updates automatically</span>
 </header>
 <main>
@@ -1120,6 +1090,7 @@ async function refresh() {
     if (!fitted) fitToView();
     if (mode3d && window.gl3d) window.gl3d.reload();
   }
+  if (window.__reloadEditorIfClean) window.__reloadEditorIfClean();
 }
 
 // ── input ───────────────────────────────────────────────────────────
@@ -1250,34 +1221,6 @@ events.onerror = () => dot.classList.add('err');
 refresh();
 </script>
 <script>
-  // ── Theme toggle: auto (follow system) → light → dark → auto ───────────────
-  (function () {
-    var root = document.documentElement;
-    var btn = document.getElementById('btntheme');
-    var mq = matchMedia('(prefers-color-scheme: light)');
-    function mode() {
-      var t = root.dataset.theme;
-      return t === 'light' || t === 'dark' ? t : 'auto';
-    }
-    function apply(m) {
-      if (m === 'auto') {
-        delete root.dataset.theme;
-        try { localStorage.removeItem('cadspec-theme'); } catch (e) {}
-      } else {
-        root.dataset.theme = m;
-        try { localStorage.setItem('cadspec-theme', m); } catch (e) {}
-      }
-      var eff = m === 'auto' ? (mq.matches ? 'light' : 'dark') : m;
-      btn.textContent = m === 'auto' ? '◐' : m === 'light' ? '☀' : '☾';
-      btn.title = 'theme: ' + m + (m === 'auto' ? ' (' + eff + ')' : '') + ' — click to change';
-    }
-    btn.addEventListener('click', function () {
-      apply({ auto: 'light', light: 'dark', dark: 'auto' }[mode()]);
-    });
-    mq.addEventListener('change', function () { if (mode() === 'auto') apply('auto'); });
-    apply(mode());
-  })();
-
   // ── Built-in .cf editor: syntax highlight + debounced auto-save ─────────────
   (function () {
     var editor = document.getElementById('editor');
@@ -1291,6 +1234,8 @@ refresh();
     var current = null; // the file currently loaded in the textarea
     var timer = null;
     var SAVE_DELAY = 600;
+    var dirty = false;     // unsaved edits pending (or in-flight)
+    var lastInput = 0;     // Date.now() of the last keystroke
 
     function setStatus(msg, cls) { status.textContent = msg; status.className = cls || ''; }
     function escHtml(s) { return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
@@ -1323,7 +1268,10 @@ refresh();
       setStatus('saving…');
       fetch('/save?name=' + encodeURIComponent(name), { method: 'POST', body: text.value })
         .then(function (r) { return r.json(); })
-        .then(function (j) { setStatus(j.ok ? 'saved · ' + name : 'saved · build error (see viewer)', j.ok ? 'ok' : 'err'); })
+        .then(function (j) {
+          dirty = false;
+          setStatus(j.ok ? 'saved · ' + name : 'saved · build error (see viewer)', j.ok ? 'ok' : 'err');
+        })
         .catch(function () { setStatus('save failed', 'err'); });
     }
     function scheduleSave() {
@@ -1335,7 +1283,7 @@ refresh();
       clearTimeout(timer); timer = null;
       fetch('/file?name=' + encodeURIComponent(name))
         .then(function (r) { return r.text(); })
-        .then(function (t) { current = name; text.value = t; paint(); syncScroll(); setStatus(name); })
+        .then(function (t) { current = name; text.value = t; paint(); syncScroll(); setStatus(name); dirty = false; })
         .catch(function () { setStatus('cannot load ' + name, 'err'); });
     }
     function loadFiles() {
@@ -1354,7 +1302,10 @@ refresh();
       if (timer) save();          // flush the pending edit to the old file first
       loadFile(sel.value);
     });
-    text.addEventListener('input', function () { paint(); scheduleSave(); });
+    text.addEventListener('input', function () {
+      dirty = true; lastInput = Date.now();
+      paint(); scheduleSave();
+    });
     text.addEventListener('scroll', syncScroll);
     saveBtn.addEventListener('click', save);
     // Keep editor keystrokes out of the viewer's shortcuts (3 / f / 1-9 / esc).
@@ -1383,6 +1334,15 @@ refresh();
     });
     window.addEventListener('mouseup', function () { drag = false; resizer.classList.remove('dragging'); });
 
+    // Called on every SSE tick so external edits (another editor, git checkout)
+    // get picked up — but never while the user has unsaved or in-progress edits.
+    window.__reloadEditorIfClean = function () {
+      if (!current) return;
+      var editingNow = document.activeElement === text && (Date.now() - lastInput) < 2000;
+      if (dirty || editingNow) return;   // don't clobber in-progress edits
+      loadFile(current);
+    };
+
     loadFiles();
   })();
 </script>
@@ -1475,6 +1435,27 @@ mod tests {
         assert!(!html.contains("{{PROJECT_NAME}}"));
     }
 
+    #[test]
+    fn index_html_has_favicon_and_branding() {
+        let html = index_html("proj");
+        assert!(html.contains("favicon.svg"));
+        assert!(html.contains("cadspec"));
+    }
+
+    #[test]
+    fn index_html_is_dark_only_no_theme_toggle() {
+        let html = index_html("proj");
+        assert!(!html.contains("data-theme"));
+        assert!(!html.contains("btntheme"));
+        assert!(!html.contains("prefers-color-scheme"));
+    }
+
+    #[test]
+    fn index_html_exposes_editor_reload_hook() {
+        let html = index_html("proj");
+        assert!(html.contains("__reloadEditorIfClean"));
+    }
+
     #[test]
     fn relevant_events_filter_by_extension() {
         use notify::event::{CreateKind, EventAttributes};
diff --git a/tests/integration.rs b/tests/integration.rs
index 7362f18..c81518b 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -874,6 +874,10 @@ fn serve_project_serves_state_and_rebuilds_on_file_change_e2e() {
     assert_eq!(svg_status, 200);
     assert!(svg_body.contains("<svg"));
 
+    let (favicon_status, favicon_body) = http_get(port, "/favicon.svg");
+    assert_eq!(favicon_status, 200);
+    assert!(favicon_body.contains("<svg"));
+
     let (missing_status, _) = http_get(port, "/does-not-exist");
     assert_eq!(missing_status, 404);
 

From 92899d28ae277293fa4c78c3ff988fe0a0592bcf Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Tue, 7 Jul 2026 15:54:25 -0500
Subject: [PATCH 37/39] chore(demo): remove stale demo assets from demo
 directory

---
 demo/README.md |  21 ----------
 demo/demo.toml | 105 -------------------------------------------------
 2 files changed, 126 deletions(-)
 delete mode 100644 demo/README.md
 delete mode 100644 demo/demo.toml

diff --git a/demo/README.md b/demo/README.md
deleted file mode 100644
index 11b1ec7..0000000
--- a/demo/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# cadspec demo
-
-The cadspec demo as code, recorded with [DemoStage](https://github.com/UniverLab/demo-stage).
-It shows the terminal scaffolding a CAD project and starting the live preview, with
-the rendered drawing in a browser pane.
-
-## Regenerate
-
-```sh
-demo check  demo/demo.toml
-demo export demo/demo.toml --target gif   # → demo/dist/cadspec.gif
-# or --target mp4
-```
-
-- `gif`/`mp4` of a terminal + browser pane need a Chromium (auto-downloaded by
-  DemoStage on first use, or use a system install) and, for mp4, ffmpeg.
-- The browser pane is captured after the terminal run, so this score leaves the
-  `cadspec serve` server running; stop it afterwards with
-  `cd /tmp/cadspec-demo/bracket && cadspec serve --stop`.
-
-Edit `demo/demo.toml` to change the commands, captions, layout or timing.
diff --git a/demo/demo.toml b/demo/demo.toml
deleted file mode 100644
index 1c33d2a..0000000
--- a/demo/demo.toml
+++ /dev/null
@@ -1,105 +0,0 @@
-# cadspec demo — terminal (CAD as code) + the live SVG preview in a browser pane.
-#
-# Generate the GIF with DemoStage (https://github.com/UniverLab/demo-stage):
-#   demo check demo/demo.toml
-#   demo export demo/demo.toml --target gif      # → demo/dist/cadspec.gif
-#
-# NOTE: browser panes are captured *after* the terminal run, so the
-# `cadspec serve` background server must still be up at capture time — this demo
-# deliberately does NOT stop it. Afterwards: `cd /tmp/cadspec-demo/bracket &&
-# cadspec serve --stop`. Adjust commands/url to your build if they drift.
-
-[demo]
-name = "cadspec"
-output_dir = "demo/dist"
-
-[typing]
-base_ms = 70
-salt_ms = 14
-seed = 7
-
-[env]
-isolated = true
-setup_script = "rm -rf /tmp/cadspec-demo && mkdir -p /tmp/cadspec-demo && cd /tmp/cadspec-demo"
-
-[layout]
-width = 1280
-height = 720
-fps = 12
-background = "#0b0f14"
-
-  [[layout.panes]]
-  id = "console"
-  type = "terminal"
-  x = 0
-  y = 0
-  width = 760
-  height = 720
-  font_size = 15
-
-  [[layout.panes]]
-  id = "preview"
-  type = "browser"
-  x = 760
-  y = 0
-  width = 520
-  height = 720
-  url = "http://127.0.0.1:4377"
-
-[[timeline]]
-action = "focus"
-pane = "console"
-
-[[timeline]]
-action = "caption"
-text = "1 — scaffold a CAD project"
-
-[[timeline]]
-action = "type"
-text = "cadspec new bracket && cd bracket"
-human_salt = true
-
-[[timeline]]
-action = "keypress"
-key = "enter"
-
-[[timeline]]
-action = "wait"
-duration_ms = 1500
-
-[[timeline]]
-action = "caption"
-text = "2 — start the live preview"
-
-[[timeline]]
-action = "type"
-text = "cadspec serve"
-human_salt = true
-
-[[timeline]]
-action = "keypress"
-key = "enter"
-
-[[timeline]]
-action = "wait_for_stdout"
-match = "127.0.0.1:4377"
-
-[[timeline]]
-action = "wait"
-duration_ms = 1500
-
-[[timeline]]
-action = "caption"
-text = "3 — the drawing renders in the browser"
-
-[[timeline]]
-action = "focus"
-pane = "preview"
-
-[[timeline]]
-action = "scroll"
-direction = "down"
-duration_ms = 2500
-
-[[timeline]]
-action = "terminate"

From 25897b6d343caa1a9d6964e43d5f1eec94e0af4d Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Thu, 9 Jul 2026 17:57:51 -0500
Subject: [PATCH 38/39] feat: add text styling fields (font, rotation, bold,
 italic)

---
 README.md            |  2 ++
 docs/cf-format.md    | 32 ++++++++++++++++++
 src/compiler.rs      |  1 +
 src/dxf_writer.rs    |  4 +++
 src/fmt.rs           | 19 +++++++++++
 src/importer.rs      | 16 ++++++---
 src/model.rs         |  4 +++
 src/schema.rs        |  4 +++
 src/svg.rs           | 78 ++++++++++++++++++++++++++++++++++++++++++--
 tests/integration.rs | 61 ++++++++++++++++++++++++++++++++++
 10 files changed, 214 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index a46b719..bfecc63 100644
--- a/README.md
+++ b/README.md
@@ -190,6 +190,8 @@ id = "tx-001"
 position = [4.0, 3.0]
 content = "SALA"
 size = 0.2
+font = "serif"
+rotation = 15.0
 
 [[dim]]
 id = "dm-001"
diff --git a/docs/cf-format.md b/docs/cf-format.md
index 9a2153f..6fbf3af 100644
--- a/docs/cf-format.md
+++ b/docs/cf-format.md
@@ -66,11 +66,43 @@ id = "tx-001"
 position = [4.0, 3.0]
 content = "SALA"
 size = 0.2
+align = "center"
+font = "serif"
+rotation = 15.0
+bold = true
+italic = false
 ```
 
 Every entity has a stable `id` — that is what makes plans diffable and
 lets agents target precise edits.
 
+### Text styling fields
+
+`[[text]]` entities accept four optional styling fields, all of which
+default to a plain, unrotated, monospace label when omitted:
+
+- `font` — a CSS `font-family` value, passed through verbatim to the SVG
+  renderer (default: `"monospace"`). No fonts are downloaded; the value
+  is resolved by the browser/renderer against generic CSS families and
+  whatever fonts are installed locally.
+- `rotation` — degrees, counter-clockwise, around the text anchor point
+  (default: `0`).
+- `bold` — `true`/`false` (default: `false`).
+- `italic` — `true`/`false` (default: `false`).
+
+Two limitations to keep in mind:
+
+1. `font`, `bold` and `italic` only affect the SVG/PNG preview. They are
+   **not** written to DXF — DXF has no simple equivalent short of
+   managing a `STYLE` table, which is out of scope. Only `rotation` is
+   carried through to the DXF `TEXT` entity (group code 50) and survives
+   a `build` → `import` roundtrip.
+2. Text bounding boxes and `align` anchoring are approximated using
+   monospace glyph proportions. This approximation is increasingly
+   inaccurate for non-monospace `font` values and does not account for
+   `rotation` at all, so treat computed text extents as approximate
+   whenever either field is set.
+
 ## Filled and hatched regions
 
 `fill` (solid color) and `hatch` (parallel pattern lines) mark an area. The
diff --git a/src/compiler.rs b/src/compiler.rs
index fbc2615..97b1a9a 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -636,6 +636,7 @@ fn compile_cf(writer: &mut DxfWriter, cf: &CfFile, default_layer: &str) {
             e.position[1],
             e.size,
             &e.content,
+            e.rotation.unwrap_or(0.0),
             resolve_layer(&e.common, default_layer),
             &style,
         );
diff --git a/src/dxf_writer.rs b/src/dxf_writer.rs
index 181fa02..9ca919b 100644
--- a/src/dxf_writer.rs
+++ b/src/dxf_writer.rs
@@ -184,12 +184,14 @@ impl DxfWriter {
         self.polyline(&points, true, layer, style);
     }
 
+    #[allow(clippy::too_many_arguments)]
     pub fn text(
         &mut self,
         x: f64,
         y: f64,
         height: f64,
         content: &str,
+        rotation: f64,
         layer: &str,
         style: &EntityStyle,
     ) {
@@ -197,6 +199,7 @@ impl DxfWriter {
             location: Point::new(x, y, 0.0),
             text_height: height,
             value: content.to_string(),
+            rotation,
             ..Default::default()
         };
         self.add_entity(EntityType::Text(text), layer, style);
@@ -256,6 +259,7 @@ impl DxfWriter {
             (ay + by) / 2.0 + ny * text_height * 0.5,
             text_height,
             label,
+            0.0,
             layer,
             &text_style,
         );
diff --git a/src/fmt.rs b/src/fmt.rs
index 14a333b..9bac02c 100644
--- a/src/fmt.rs
+++ b/src/fmt.rs
@@ -351,4 +351,23 @@ mod tests {
         let input = "invalid [[[ toml";
         assert_eq!(format_source(input), input);
     }
+
+    #[test]
+    fn preserves_text_font_rotation_bold_italic() {
+        let input = "[layer]\nname = \"x\"\n\n[[text]]\nid = \"tx-1\"\nposition = [1.0, 2.0]\ncontent = \"hi\"\nsize = 0.3\nfont = \"serif\"\nrotation = 30.0\nbold = true\nitalic = true\n";
+        let once = format_source(input);
+        let twice = format_source(&once);
+        assert_eq!(once, twice, "fmt not idempotent for text styling fields");
+        for needle in [
+            "font = \"serif\"",
+            "rotation = 30.0",
+            "bold = true",
+            "italic = true",
+        ] {
+            assert!(
+                once.contains(needle),
+                "expected {needle:?} to survive fmt, got:\n{once}"
+            );
+        }
+    }
 }
diff --git a/src/importer.rs b/src/importer.rs
index 5b8e689..e96ec3c 100644
--- a/src/importer.rs
+++ b/src/importer.rs
@@ -75,6 +75,7 @@ enum Shape {
         position: [f64; 2],
         content: String,
         size: f64,
+        rotation: f64,
     },
     Point {
         position: [f64; 2],
@@ -237,6 +238,7 @@ pub fn import_dxf(input: &Path, output_dir: &Path, layer_filter: Option<&str>) -
                         position: [e.location.x, e.location.y],
                         content: e.value.clone(),
                         size: e.text_height.max(0.1),
+                        rotation: e.rotation,
                     }),
                     EntityType::ModelPoint(e) => Some(Shape::Point {
                         position: [e.location.x, e.location.y],
@@ -741,16 +743,20 @@ fn emit_shape(shape: &Shape) -> (&'static str, String) {
             position,
             content,
             size,
-        } => (
-            "tx",
-            format!(
+            rotation,
+        } => {
+            let mut body = format!(
                 "position = [{}, {}]\ncontent = \"{}\"\nsize = {}\n",
                 n(position[0]),
                 n(position[1]),
                 escape_string(content),
                 n(*size)
-            ),
-        ),
+            );
+            if *rotation != 0.0 {
+                body.push_str(&format!("rotation = {}\n", n(*rotation)));
+            }
+            ("tx", body)
+        }
         Shape::Point { position } => (
             "pt",
             format!("position = [{}, {}]\n", n(position[0]), n(position[1])),
diff --git a/src/model.rs b/src/model.rs
index eb09619..f7e0fb6 100644
--- a/src/model.rs
+++ b/src/model.rs
@@ -88,6 +88,10 @@ pub struct CfText {
     #[serde(default = "default_text_size")]
     pub size: f64,
     pub align: Option<TextAlign>,
+    pub font: Option<String>,
+    pub rotation: Option<f64>,
+    pub bold: Option<bool>,
+    pub italic: Option<bool>,
     #[serde(flatten)]
     pub common: CommonAttrs,
 }
diff --git a/src/schema.rs b/src/schema.rs
index 90d9590..d061681 100644
--- a/src/schema.rs
+++ b/src/schema.rs
@@ -110,6 +110,10 @@ position = [4.0, 3.0]
 content = "SALA"
 size = 0.25            # text height in world units
 align = "center"       # left | center | right
+font = "monospace"     # CSS font-family, SVG/PNG preview only (default: monospace)
+rotation = 0.0          # degrees, counterclockwise, about the anchor point (DXF-compatible)
+bold = false            # SVG/PNG preview only
+italic = false          # SVG/PNG preview only
 
 [[point]]              # reference marker (drawn as a cross)
 position = [3.0, 3.0]
diff --git a/src/svg.rs b/src/svg.rs
index 441f76b..2c64660 100644
--- a/src/svg.rs
+++ b/src/svg.rs
@@ -488,7 +488,11 @@ pub fn enumerate_entities(cf: &CfFile) -> Vec<EntityRecord> {
         });
     }
     for e in &cf.texts {
-        // Approximate extent from monospace glyph proportions.
+        // Approximate extent from monospace glyph proportions. This is a rough
+        // estimate even for the default monospace font, and it is only more
+        // wrong when `font` names a non-monospace family or `rotation` is set
+        // (the bbox below is axis-aligned and ignores rotation entirely), so
+        // `align` anchoring and this bbox are approximate in those cases.
         let w = 0.6 * e.size * e.content.chars().count() as f64;
         out.push(EntityRecord {
             id: e.common.id.clone(),
@@ -791,14 +795,33 @@ fn render_layer(
             _ => "start",
         };
         let font_px = (e.size * c.scale).max(1.0);
+        let font_family = xml_escape(e.font.as_deref().unwrap_or("monospace"));
+        let mut extra_attrs = String::new();
+        if e.bold == Some(true) {
+            extra_attrs.push_str(r#" font-weight="bold""#);
+        }
+        if e.italic == Some(true) {
+            extra_attrs.push_str(r#" font-style="italic""#);
+        }
+        if let Some(angle) = e.rotation {
+            if angle != 0.0 {
+                let _ = write!(
+                    extra_attrs,
+                    r#" transform="rotate({:.2}, {:.2}, {:.2})""#,
+                    -angle, px, py
+                );
+            }
+        }
         let _ = write!(
             c.out,
-            r#"<text x="{:.2}" y="{:.2}" font-size="{:.2}" font-family="monospace" text-anchor="{}" fill="{}"{}>{}</text>"#,
+            r#"<text x="{:.2}" y="{:.2}" font-size="{:.2}" font-family="{}" text-anchor="{}" fill="{}"{}{}>{}</text>"#,
             px,
             py,
             font_px,
+            font_family,
             anchor,
             s.color,
+            extra_attrs,
             id_attr(&e.common),
             xml_escape(&e.content)
         );
@@ -1111,4 +1134,55 @@ pattern = "ansi31"
         assert_eq!(grid_step(30.0), 1.0);
         assert_eq!(grid_step(300.0), 10.0);
     }
+
+    fn text_layer(extra_fields: &str) -> Vec<(String, CfFile)> {
+        let toml = format!(
+            r##"
+[layer]
+name = "test"
+color = "#FFFFFF"
+
+[[text]]
+id = "tx-1"
+position = [5.0, 5.0]
+content = "HOLA"
+size = 0.3
+{extra_fields}
+"##
+        );
+        let cf: CfFile = toml::from_str(&toml).unwrap();
+        vec![("test".to_string(), cf)]
+    }
+
+    #[test]
+    fn text_font_is_emitted_in_font_family() {
+        let svg = render_layers("demo", "m", &text_layer(r#"font = "serif""#), 1200, &[]).svg;
+        assert!(svg.contains(r#"font-family="serif""#));
+    }
+
+    #[test]
+    fn text_without_font_defaults_to_monospace() {
+        let svg = render_layers("demo", "m", &text_layer(""), 1200, &[]).svg;
+        assert!(svg.contains(r#"font-family="monospace""#));
+    }
+
+    #[test]
+    fn text_rotation_emits_negated_svg_transform() {
+        let svg = render_layers("demo", "m", &text_layer("rotation = 45.0"), 1200, &[]).svg;
+        assert!(svg.contains("transform=\"rotate(-45.00,"));
+    }
+
+    #[test]
+    fn text_bold_and_italic_emit_style_attrs() {
+        let svg = render_layers(
+            "demo",
+            "m",
+            &text_layer("bold = true\nitalic = true"),
+            1200,
+            &[],
+        )
+        .svg;
+        assert!(svg.contains(r#"font-weight="bold""#));
+        assert!(svg.contains(r#"font-style="italic""#));
+    }
 }
diff --git a/tests/integration.rs b/tests/integration.rs
index c81518b..a723abc 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -527,6 +527,67 @@ offset = -1.2
     let _ = fs::remove_dir_all(imported);
 }
 
+#[test]
+fn import_roundtrip_preserves_text_rotation() {
+    // `rotation` on [[text]] must survive a build -> import roundtrip via the
+    // DXF TEXT group-code-50 field. Unrotated text must not gain a spurious
+    // `rotation` key (today's DXF output has none, and roundtrip fidelity
+    // should not regress for the common case).
+    let dir = Path::new("/tmp/cadspec_text_rotation_roundtrip");
+    let _ = fs::remove_dir_all(dir);
+    fs::create_dir_all(dir).unwrap();
+    fs::write(
+        dir.join("project.toml"),
+        "[project]\nname = \"rt\"\nunits = \"m\"\n\n[layers]\nplano = { file = \"plano.cf\", locked = false }\n",
+    )
+    .unwrap();
+    fs::write(
+        dir.join("plano.cf"),
+        r##"[layer]
+name = "plano"
+color = "#FFFFFF"
+
+[[text]]
+id = "tx-rotated"
+position = [1.0, 2.0]
+content = "ROTATED"
+size = 0.3
+rotation = 30.0
+
+[[text]]
+id = "tx-plain"
+position = [4.0, 2.0]
+content = "PLAIN"
+size = 0.3
+"##,
+    )
+    .unwrap();
+
+    let dxf_path = dir.join("output.dxf");
+    compile_project(dir, None, Some(&dxf_path)).unwrap();
+
+    let imported = Path::new("/tmp/cadspec_text_rotation_roundtrip_out");
+    let _ = fs::remove_dir_all(imported);
+    import_dxf(&dxf_path, imported, None).unwrap();
+    let cf = fs::read_to_string(imported.join("plano.cf")).unwrap();
+
+    assert!(
+        cf.contains("rotation = 30"),
+        "rotated text lost its rotation on roundtrip:\n{cf}"
+    );
+    let plain_block = cf.split("PLAIN").next().unwrap();
+    let plain_tx_start = plain_block.rfind("[[text]]").unwrap();
+    assert!(
+        !plain_block[plain_tx_start..].contains("rotation"),
+        "unrotated text should not gain a rotation key:\n{cf}"
+    );
+
+    compile_project(imported, None, None).unwrap();
+
+    let _ = fs::remove_dir_all(dir);
+    let _ = fs::remove_dir_all(imported);
+}
+
 #[test]
 fn import_refuses_hatch_lines_into_single_hatch() {
     // A hatch expands into many DXF pattern lines. On import they must collapse

From 0b33d0de04f60958ccdbe01e4a7169e05e30ac9c Mon Sep 17 00:00:00 2001
From: Jheison Martinez Bolivar <jheison.mb@gmail.com>
Date: Thu, 9 Jul 2026 17:58:53 -0500
Subject: [PATCH 39/39] chore: add .mimocode/ to gitignore

---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 92e211d..a77efdb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,3 +58,5 @@ preview.meta.json
 # AI agent instruction files — not part of this repo
 CLAUDE.md
 AGENTS.md
+
+.mimocode/