docs: add ArchAgent Phase 1 design spec

Greenfield successor to NeuralCAD targeting house-scale architectural
design. Two-service architecture (web + Blender worker), LangGraph
agent orchestration, HouseSpec Pydantic DSL with deterministic bpy
translator, gallery + per-item persistence, chat + image inputs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-05-09-archagent-phase-1-design.md

@@ -0,0 +1,748 @@
+# ArchAgent — Phase 1: Foundation + Architectural Shell
+
+**Date:** 2026-05-09
+**Status:** Draft
+**Repo:** new (ArchAgent — greenfield, to be created)
+**Phase:** 1 of 3 (this spec)
+
+> Phase 2 (Interior composition) and Phase 3 (Exterior + site) are out of scope for this spec — they get their own spec → plan → implementation cycles after Phase 1 ships.
+
+## Context
+
+ArchAgent is a multi-agent platform for generating 3D architectural designs from natural language and sketches. It is a greenfield successor to NeuralCAD (a CadQuery-based CNC mechanical design tool); none of NeuralCAD's code is carried over. ArchAgent targets house-scale architectural shells: walls, floors, doors, windows, roof, stairs, interior partitions, structural columns and beams, and fixed cabinetry.
+
+The product is a conversational web app. A user opens a gallery of past designs, creates a new project, and converses with a team of specialist agents (Architect, Structural Engineer, Code Compliance, plus a Blender Coder and Construction Documenter). The agents accumulate design decisions across turns, gate generation behind readiness checks, and produce a 3D model plus floor plans plus a bill of materials when the user approves. Phase 1 deliberately excludes interior decoration, exterior visualization, and rendering quality concerns.
+
+## Decision Log
+
+| # | Decision | Rationale |
+|---|---|---|
+| 1 | Greenfield repo, not a migration | NeuralCAD's identity, deploy story, and several architectural assumptions don't fit architectural CAD. Carrying old code adds friction without compounding value. |
+| 2 | Phase 1 scope: extended architectural shell | Standard shell (walls/doors/windows/roof) plus structural elements and partitions makes the validators meaningful and matches what users mean by "house." |
+| 3 | Two-service architecture: web + Blender worker | Failure isolation, lighter web image, Python-version freedom for the web service, clean local docker-compose deploy. |
+| 4 | Blender worker uses persistent Blender subprocess | Full Blender features (Geometry Nodes, modifiers, all exporters), no bpy-wheel Python pin, more battle-tested than the bpy pip module. |
+| 5 | Structured DSL (HouseSpec) → deterministic translator | LLMs emit JSON reliably; bpy code generation has retry-loop tax. Validators work on typed data, not on parsed bpy scenes. |
+| 6 | LangGraph for agent orchestration | Five-out-of-six flow primitives we need (cycles, conditional branches, parallel fan-out, human-in-loop interrupts, typed state, checkpointed resumability) are first-class in LangGraph. CrewAI's strengths (emergent multi-agent collaboration) don't apply. |
+| 7 | Standalone HTML + Three.js for viewer | All Phase 1 rendering needs (glTF, PBR materials, shadows, picking, clipping, labels) work without a build step. ~500 LOC ceiling before reconsidering. |
+| 8 | SQLite + filesystem gallery, single-user | Right-sized for a personal tool. Multi-user is a clean later layer if needed. |
+| 9 | Inputs: text + image upload | Vision-capable LLM can parse sketches into HouseSpec deltas. Big UX win for architects, modest implementation cost. |
+| 10 | UX: chat-primary with inline structured-question cards | Surfaces multi-agent reasoning without ambiguity tax. Cards are LangGraph `interrupt()` payloads rendered as small inline forms. |
+| 11 | No HuggingFace Spaces deploy constraint | Default deploy is `docker-compose` on any Docker host. Cloud Run / Kubernetes work by swapping the shared volume for object storage. |
+| 12 | Clean cutover: NeuralCAD CNC product is not preserved by ArchAgent | NeuralCAD repo is left as-is. ArchAgent is a separate codebase. |
+
+## System Architecture
+
+```
+                    ┌──────────────────────────────────┐
+   browser ◀────────│  Web service (Python 3.12)        │
+                    │                                    │
+                    │  FastAPI ── /api/{chat,gallery,...}│
+                    │  FastMCP ── 8 MCP tools            │
+                    │  LangGraph ── agent state graph    │
+                    │     ├─ Architect node              │
+                    │     ├─ Structural node             │
+                    │     ├─ Code Compliance node        │
+                    │     ├─ Coder node (HouseSpec)      │
+                    │     └─ Documenter node             │
+                    │  Pydantic ── HouseSpec, DesignState│
+                    │  ezdxf ── DXF/PDF floor plans      │
+                    │  SQLite ── gallery metadata        │
+                    │  static/ ── index.html (Three.js)  │
+                    └──────────────┬───────────────────────┘
+                                   │ HTTP REST (private)
+                                   ▼
+                    ┌─────��────────────────────────────┐
+                    │  Blender worker (Python 3.11+)    │
+                    │                                    │
+                    │  FastAPI ── /translate /thumbnail  │
+                    │     │                              │
+                    │     ▼ (JSON over UNIX socket)     │
+                    │  Blender 4.x (--background)       │
+                    │  ↑ persistent subprocess           │
+                    │  ↑ command-server addon            │
+                    │  ↑ translator builds bpy scene     │
+                    │  ↑ exports glTF/blend/stl          │
+                    └──────────────┬───────────────────────┘
+                                   │ writes
+                                   ▼
+                    ┌──────────────────────────────────┐
+                    │  data/ (shared volume)             │
+                    │  ├─ gallery.db (SQLite)            │
+                    │  └─ items/<id>/                    │
+                    │     ├─ state.json                  │
+                    │     ├─ spec.json                   │
+                    │     ├─ history.jsonl               │
+                    │     ├─ thumbnail.png               │
+                    │     └─ artifacts/                  │
+                    │        ├─ house.gltf               │
+                    │        ├─ house.blend              │
+                    │        ├─ floor_plan_l1.dxf        │
+                    │        ├─ floor_plan_l1.pdf        │
+                    │        └─ bom.json                 │
+                    └────────────────────────────────────┘
+```
+
+### Data flow per chat turn
+
+1. Browser POSTs `/api/chat` with `{item_id, message, image?}`.
+2. Web service loads `Item` from gallery: rehydrates `DesignState`, recent chat history.
+3. LangGraph runs with the loaded state as initial input.
+4. Advisor nodes execute (parallel where possible) and return `READY` / `NOT_READY` with optional gap questions.
+5. Readiness gate (conditional edge):
+   - Any `NOT_READY` → emit `structured_question` interrupt → return to user as inline card.
+   - All `READY` plus generation-intent → continue to Coder node.
+   - All `READY` plus chat-only intent → continue to advisor consensus reply, no Coder.
+6. Coder node calls LLM with `HouseSpec` schema as a tool. Output is type-checked. If invalid, retry up to 3 times with the validation error appended.
+7. Schema-valid `HouseSpec` passes through reference validation and semantic validators. Failure → retry or surface to user.
+8. Web posts `HouseSpec` to worker `/translate`. Worker writes artifacts and returns geometric violations.
+9. Geometric validators surface failures the same way.
+10. Documenter node generates BoM and queues DXF/PDF export (web-side via `ezdxf`).
+11. Web persists updated `DesignState` and chat turn to `data/items/<id>/`.
+12. Response streams back to browser: text, validation summary, artifact URLs (gltf, dxf, pdf, bom).
+
+## HouseSpec DSL
+
+`HouseSpec` is the central abstraction. It is a Pydantic v2 model emitted by the Coder agent and consumed by the translator. All units are meters; coordinates use a right-handed system with z up. Centerlines for linear elements (walls, beams).
+
+```python
+# core/spec.py (lives in web service; imported by worker too)
+
+from pydantic import BaseModel, Field
+from typing import Literal
+
+Point2D = tuple[float, float]
+Polygon = list[Point2D]   # closed implicit; first ≠ last
+
+WallMaterial = Literal["wood_frame", "cmu", "concrete", "steel_stud"]
+StructuralSystem = Literal["wood_frame", "steel", "concrete"]
+RoofType = Literal["gable", "hip", "flat", "shed"]
+RoomProgram = Literal[
+    "bedroom", "bathroom", "kitchen", "living", "dining",
+    "circulation", "storage", "utility", "garage", "office"
+]
+
+class ProjectMetadata(BaseModel):
+    name: str
+    occupancy_type: Literal["R-3", "R-2", "B"] = "R-3"
+    units: Literal["meters"] = "meters"
+
+class SiteContext(BaseModel):
+    north_angle_deg: float = 0.0
+    lot_polygon: Polygon | None = None
+
+class Level(BaseModel):
+    id: str
+    name: str                   # "Ground", "Second", "Basement"
+    elevation_m: float          # absolute z of floor surface
+    height_m: float             # floor-to-floor
+
+class Wall(BaseModel):
+    id: str
+    level_id: str
+    start: Point2D
+    end: Point2D
+    height_m: float
+    thickness_m: float = 0.2
+    material: WallMaterial = "wood_frame"
+    is_load_bearing: bool = False
+
+class InteriorPartition(BaseModel):
+    id: str
+    level_id: str
+    start: Point2D
+    end: Point2D
+    height_m: float
+    thickness_m: float = 0.1
+    material: WallMaterial = "wood_frame"
+
+class Floor(BaseModel):
+    id: str
+    level_id: str
+    outline: Polygon
+    thickness_m: float = 0.25
+
+class Door(BaseModel):
+    id: str
+    parent_wall_id: str
+    offset_along_wall_m: float
+    width_m: float
+    height_m: float
+    handing: Literal["left", "right"] = "left"
+    swing: Literal["in", "out"] = "in"
+    is_egress: bool = False
+
+class Window(BaseModel):
+    id: str
+    parent_wall_id: str
+    offset_along_wall_m: float
+    sill_height_m: float
+    width_m: float
+    height_m: float
+    operable: bool = True
+
+class Roof(BaseModel):
+    type: RoofType
+    parent_outline: Polygon
+    pitch_deg: float = 0.0      # 0 for flat
+    overhang_m: float = 0.5
+    base_elevation_m: float
+
+class Stairs(BaseModel):
+    id: str
+    from_level_id: str
+    to_level_id: str
+    run_polyline: list[Point2D]
+    width_m: float
+    tread_depth_m: float = 0.25
+    riser_height_m: float = 0.18
+
+class Column(BaseModel):
+    id: str
+    level_id: str
+    position: Point2D
+    height_m: float
+    cross_section_m: tuple[float, float] = (0.2, 0.2)
+    material: Literal["wood", "steel", "concrete"] = "steel"
+
+class Beam(BaseModel):
+    id: str
+    level_id: str
+    start: Point2D
+    end: Point2D
+    elevation_offset_m: float = 0.0
+    cross_section_m: tuple[float, float] = (0.2, 0.4)
+    material: Literal["wood", "steel", "concrete"] = "steel"
+
+class FixedCabinetry(BaseModel):
+    id: str
+    level_id: str
+    cabinet_type: Literal["kitchen_lower", "kitchen_upper", "bath_vanity", "closet", "builtin"]
+    footprint: Polygon
+    height_m: float
+
+class Room(BaseModel):
+    id: str
+    name: str
+    program: RoomProgram
+    level_id: str
+    bounded_by_wall_ids: list[str]   # closed loop required
+    floor_id: str
+
+class HouseSpec(BaseModel):
+    metadata: ProjectMetadata
+    site: SiteContext = Field(default_factory=SiteContext)
+    structural_system: StructuralSystem = "wood_frame"
+    levels: list[Level]
+    walls: list[Wall] = []
+    floors: list[Floor] = []
+    roof: Roof | None = None
+    doors: list[Door] = []
+    windows: list[Window] = []
+    stairs: list[Stairs] = []
+    interior_partitions: list[InteriorPartition] = []
+    columns: list[Column] = []
+    beams: list[Beam] = []
+    cabinetry: list[FixedCabinetry] = []
+    rooms: list[Room] = []
+```
+
+### Validation layers
+
+1. **Schema** (Pydantic): types, required fields, enums, ranges.
+2. **Reference** (`core/validators/reference.py`): every `parent_wall_id` and `bounded_by_wall_ids` resolves; every Room's wall loop is closed.
+3. **Architect** (`core/validators/architect.py`): room minimum areas (jurisdiction-dependent), program adjacencies (no bedroom adjacent to garage without buffer), corridor widths.
+4. **Structural** (`core/validators/structural.py`): load-bearing walls have continuous foundation below; beams span column-to-column or column-to-load-bearing; max spans per material from `config/materials.yaml`.
+5. **Code Compliance** (`core/validators/code.py`): egress doors per occupancy; ceiling heights ≥ jurisdiction min; window-to-floor-area ratio for habitable rooms; stair geometry; ADA where applicable. Rules data-driven via `config/jurisdictions/IRC_2021.yaml`.
+6. **Geometric** (worker, `geometric_validator.py`): collisions between non-adjacent solids, manifold check on each primitive, no overlapping walls.
+
+`Violation` shape:
+
+```python
+class Violation(BaseModel):
+    level: Literal["error", "warning"]
+    code: str                 # "IRC_R304_3", "ARCH_ROOM_MIN_AREA", "GEOM_COLLISION"
+    primitive_ids: list[str]
+    message: str
+    suggested_fix: str | None = None
+```
+
+## Agent Layer (LangGraph)
+
+Five agents, all defined as nodes in a LangGraph `StateGraph`. State is a Pydantic model.
+
+```python
+# agents/state.py
+
+class AdvisorReport(BaseModel):
+    agent: Literal["architect", "structural", "code"]
+    status: Literal["READY", "NOT_READY"]
+    text: str
+    gap_questions: list["StructuredQuestion"] = []
+
+class StructuredQuestion(BaseModel):
+    field: str                                    # "program.bedroom_count"
+    label: str                                    # "How many bedrooms?"
+    type: Literal["int", "float", "enum", "text"]
+    options: list[str] | None = None
+    default: str | int | float | None = None
+    required: bool = True
+
+class ArchAgentState(BaseModel):
+    item_id: str
+    user_message: str
+    user_image_b64: str | None = None
+    history: list[dict]                           # prior turns, last 20
+    design_state: DesignState
+    advisor_reports: list[AdvisorReport] = []
+    intent: Literal["chat", "generate"] = "chat"
+    spec: HouseSpec | None = None
+    spec_violations: list[Violation] = []
+    geometric_violations: list[Violation] = []
+    artifacts: dict[str, str] = {}                # {"gltf": "data/items/<id>/artifacts/house.gltf", ...}
+    documenter_output: dict | None = None
+    structured_questions: list[StructuredQuestion] = []
+    error: str | None = None
+```
+
+### Graph topology
+
+```
+START
+  │
+  ▼
+classify_intent          ── decides: "chat" | "generate"
+  │
+  ▼
+fan_out_advisors         ── Send to architect, structural, code in parallel
+  │
+  ▼  (joins)
+readiness_gate           ── conditional edge:
+  │                          all READY + generate → coder
+  │                          all READY + chat     → advisor_reply
+  │                          any NOT_READY         → emit_questions (interrupt)
+  │
+  ├──▶ emit_questions  ──▶ END (interrupt; resumed on next turn with answers)
+  │
+  ├──▶ advisor_reply   ──▶ persist ──▶ END
+  │
+  └──▶ coder
+        │
+        ▼
+      validate_schema_and_references
+        │  on fail: retry coder up to 3 times
+        ▼
+      validate_semantic        (architect + structural + code on the spec)
+        │  on fail: retry coder up to 3 times
+        ▼
+      call_worker_translate
+        │
+        ▼
+      handle_geometric_violations
+        │  on fail: retry coder up to 2 times
+        ▼
+      documenter
+        │
+        ▼
+      persist  ──▶ END
+```
+
+Conditional edges and cycles are first-class LangGraph features. The graph is compiled once at startup and reused per turn.
+
+### Agent node prompts
+
+Each advisor node has a prompt scaffold defined in `config/agents.yaml`:
+
+```yaml
+architect:
+  role: "Senior residential architect"
+  goal: "Refine room program, layout intent, and aesthetic constraints into a buildable HouseSpec."
+  responsibilities:
+    - "Translate user wishes into specific room counts, sizes, adjacencies."
+    - "Flag missing info as structured_questions."
+    - "Return READY only when program + dimensions + structural system are all set."
+  output_format: "JSON: {status, text, gap_questions}"
+```
+
+The Coder is a thin LangGraph node that calls the LLM with `HouseSpec` as a tool schema (Anthropic / OpenAI structured outputs). No CrewAI-style backstory needed — its job is fully constrained by the typed output.
+
+### Advisors vs validators — same names, different roles
+
+`architect`, `structural`, and `code` exist as **two distinct things**:
+
+- **Advisor nodes** (in `agents/nodes/`) — LangGraph nodes that call an LLM with the agent's role prompt. They run *before* generation, read `DesignState` + chat history, and return guidance + gap questions.
+- **Validator modules** (in `core/validators/`) — pure-Python rule-based checks that run *after* the Coder emits a spec. They take a `HouseSpec` and return a list of `Violation`s. No LLM calls.
+
+The two layers are complementary: advisors prevent missing information from reaching the Coder; validators catch mistakes the Coder made anyway. The Documenter node consumes the same spec + violations and renders the final outputs.
+
+### Documenter node outputs
+
+When invoked after geometric validation passes, the Documenter writes:
+
+- `data/items/<id>/artifacts/bom.json` — counted primitives by type and material, total wall length per material, opening counts, total floor area per level, total enclosed volume.
+- `data/items/<id>/artifacts/floor_plan_<level_id>.dxf` — one DXF per level. Walls as polylines, doors as arcs (showing swing), windows as breaks, room labels as text entities.
+- `data/items/<id>/artifacts/floor_plan_<level_id>.pdf` — matplotlib render of the corresponding DXF.
+
+DXF and PDF generation runs in the web service via `ezdxf` — no worker call needed. The Documenter node returns paths and a short summary text rendered in chat ("Generated BoM, 2 floor plans, 1 PDF").
+
+### Checkpointing
+
+LangGraph's `SqliteSaver` persists graph state per `thread_id`. We use `item_id` as `thread_id` so resumes happen automatically when a user re-opens an item. The checkpoint database is separate from the gallery DB to keep concerns clean: `data/checkpoints.db` (LangGraph) vs `data/gallery.db` (gallery metadata).
+
+## Web Service
+
+```
+services/web/
+├── core/
+│   ├── spec.py                    # HouseSpec models (single source of truth)
+│   ├── design_state.py            # DesignState model
+│   ├── llm/
+│   │   ├── anthropic_backend.py
+│   │   ├── openai_backend.py
+│   │   ├── gemini_backend.py
+│   │   └── mock_backend.py
+│   ├── validators/
+│   │   ├── reference.py
+│   │   ├── architect.py
+│   │   ├── structural.py
+│   │   └── code.py
+│   ├── jurisdictions.py           # loader for config/jurisdictions/*.yaml
+│   ├── exporters/
+│   │   ├── dxf.py                 # ezdxf — runs without bpy
+│   │   ├── pdf.py                 # ezdxf matplotlib renderer
+│   │   └── bom.py                 # JSON bill of materials
+│   ├── gallery/
+│   │   ├── store.py               # SQLite + filesystem
+│   │   ├── models.py
+│   │   └── schema.sql
+│   └── worker_client.py           # httpx client for worker /translate, /thumbnail
+├── agents/
+│   ├── state.py                   # ArchAgentState, AdvisorReport, StructuredQuestion
+│   ├── graph.py                   # build_graph() returns compiled LangGraph
+│   ├── nodes/
+│   │   ├── classify_intent.py
+│   │   ├── architect.py
+│   │   ├── structural.py
+│   │   ├── code.py
+│   │   ├── coder.py
+│   │   ├── documenter.py
+│   │   └── readiness.py
+│   └── prompts.py                 # loaded from config/agents.yaml
+├── server/
+│   ├── routes.py                  # FastAPI endpoints
+│   ├── mcp.py                     # FastMCP server (8 tools)
+│   ├── streaming.py               # SSE for chat streaming
+│   └── deps.py                    # DI: gallery, llm, worker client
+├── config/
+│   ├── settings.py                # Pydantic Settings
+│   ├── agents.yaml
+│   ├── materials.yaml
+│   └── jurisdictions/
+│       └── IRC_2021.yaml
+├── static/
+│   └── index.html                 # Three.js + chat UI (vanilla)
+├── tests/
+│   ├── test_spec.py
+│   ├── test_validators_*.py
+│   ├── test_gallery.py
+│   ├── test_graph.py              # LangGraph compile + happy path with mock backend
+│   └── test_routes.py
+├── Dockerfile
+└── pyproject.toml
+```
+
+### REST endpoints
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/api/chat` | POST | Run a chat turn for an item. Returns text + violations + artifact URLs. Supports SSE streaming. |
+| `/api/gallery` | GET | List items (filter, sort, paginate) |
+| `/api/gallery` | POST | Create new item |
+| `/api/gallery/{id}` | GET | Get full item (state, spec, recent history) |
+| `/api/gallery/{id}` | PATCH | Rename, change status |
+| `/api/gallery/{id}` | DELETE | Soft delete (`?hard=true` for hard delete) |
+| `/api/gallery/{id}/duplicate` | POST | Fork an item |
+| `/api/gallery/{id}/approve` | POST | Lock spec from edits |
+| `/api/gallery/{id}/artifacts/{format}` | GET | Stream artifact (gltf, blend, dxf, pdf, bom, stl) |
+| `/api/gallery/{id}/thumbnail.png` | GET | Stream thumbnail |
+| `/api/jurisdictions` | GET | List supported codes |
+| `/api/agents` | GET | List agent metadata for UI |
+| `/api/healthz` | GET | Health (and worker reachability) |
+
+### MCP tools
+
+| Tool | Signature | Purpose |
+|---|---|---|
+| `chat_turn` | `(message, item_id?, mentions?, image?, backend?) -> ChatTurnResponse` | Multi-agent dialog |
+| `generate_house` | `(prompt, name?, backend?, max_retries?) -> {item_id, gltf_url, validation, bom}` | One-shot end-to-end |
+| `validate_spec` | `(spec_json, jurisdiction) -> [Violation]` | Validate without rendering |
+| `list_items` | `(status_filter?, sort_by?, limit?, offset?) -> [ItemSummary]` | Gallery browse |
+| `get_item` | `(item_id) -> Item` | Full state |
+| `delete_item` | `(item_id, hard?) -> {ok}` | Soft/hard delete |
+| `duplicate_item` | `(item_id, new_name) -> Item` | Fork |
+| `get_jurisdictions` | `() -> [Jurisdiction]` | List code rules |
+
+Resources: `archagent://schema`, `archagent://jurisdictions/{id}`.
+
+## Blender Worker Service
+
+```
+services/worker/
+├── app.py                         # FastAPI; spawns Blender subprocess at startup
+├── blender_client.py              # JSON-over-UNIX-socket client to Blender addon
+├── translator/
+│   ├── walls.py
+│   ├── floors.py
+│   ├── doors_windows.py
+│   ├── roof.py
+│   ├── stairs.py
+│   ├── partitions.py
+│   ├── columns_beams.py
+│   └── cabinetry.py
+├── exporters.py                   # gltf, blend, stl via bpy
+├── geometric_validator.py         # collision/manifold checks
+├── thumbnail.py                   # camera + Eevee render to PNG
+├── addons/
+│   └── archagent_command_server/  # custom Blender addon
+│       ├── __init__.py
+│       └── server.py              # listens on UNIX socket, dispatches commands
+├── Dockerfile                     # apt: blender-4.x; pip: fastapi, httpx
+├── requirements.txt
+└── tests/
+    ├── test_translator_*.py       # goldens: spec → expected bpy ops
+    └── test_exporters.py
+```
+
+### Worker startup
+
+1. Container starts.
+2. `app.py` lifespan handler launches Blender:
+   ```bash
+   blender --background --addons archagent_command_server --python-expr "register()"
+   ```
+3. Addon registers a UNIX socket listener at `/tmp/archagent.sock`.
+4. FastAPI is ready; `/healthz` returns OK once socket connection succeeds.
+5. On crash (Blender exits), the lifespan handler restarts it; in-flight requests fail with 503 and the web service retries once.
+
+### Worker HTTP API
+
+| Endpoint | Body | Returns |
+|---|---|---|
+| `POST /translate` | `{spec: HouseSpec, item_id: str}` | `{artifacts: {gltf, blend, stl}, geometric_violations: [Violation]}` |
+| `POST /thumbnail` | `{item_id: str, view: "iso"\|"plan"}` | `{path: str}` |
+| `POST /validate-geometric` | `{spec, item_id}` | `[Violation]` (no artifacts written) |
+| `GET /healthz` | — | `{ok: true, blender_version: str}` |
+
+### Translator design
+
+`translator/__init__.py:translate(spec: HouseSpec) -> dict[str, str]` is the entry point. It clears the bpy scene, then calls each per-primitive builder in dependency order:
+
+1. Levels (just data; not built)
+2. Floors (extrude polygons by thickness, anchor to level elevation)
+3. Walls (extrude centerline rectangles; subtract door + window openings)
+4. Interior partitions (same as walls but flagged non-load-bearing)
+5. Columns (extrude rectangles)
+6. Beams (extrude rectangles along centerline at level elevation + offset)
+7. Roof (build per type: gable/hip/flat/shed)
+8. Stairs (sweep tread profile along run polyline)
+9. Doors and windows (placeholder geometry in their wall openings)
+10. Cabinetry (extrude footprint by height, place at level)
+11. Rooms (no geometry; tagged metadata for room nodes in glTF)
+
+Each builder returns a list of bpy object names; the dispatcher accumulates an `id_to_bpy_name` mapping for the geometric validator.
+
+Output: `{gltf: "data/items/<id>/artifacts/house.gltf", blend: "...", stl: "..."}`.
+
+## Gallery & Persistence
+
+```sql
+-- core/gallery/schema.sql
+CREATE TABLE items (
+    id            TEXT PRIMARY KEY,
+    name          TEXT NOT NULL,
+    status        TEXT NOT NULL,            -- draft|generated|approved|archived
+    created_at    TEXT NOT NULL,
+    updated_at    TEXT NOT NULL,
+    jurisdiction  TEXT,
+    occupancy     TEXT,
+    num_stories   INTEGER,
+    gross_area_m2 REAL,
+    validation    TEXT,                     -- JSON {errors, warnings}
+    thumb_path    TEXT
+);
+CREATE INDEX idx_items_updated ON items(updated_at DESC);
+CREATE INDEX idx_items_status  ON items(status);
+```
+
+Per-item filesystem layout under `data/items/<id>/`:
+
+- `state.json` — `DesignState` snapshot
+- `spec.json` — latest `HouseSpec`
+- `history.jsonl` — append-only chat log (one turn per line)
+- `inputs/` — uploaded images
+- `thumbnail.png` — 512×512 iso render
+- `artifacts/` — generated outputs
+
+Item lifecycle:
+
+| Op | Effect |
+|---|---|
+| Create | UUIDv7 → mkdir, insert row (`status=draft`) |
+| Load | read state.json + spec.json + tail of history.jsonl into memory |
+| Update (turn) | overwrite state.json, append history.jsonl, update `updated_at` |
+| Generate | write spec.json, call worker, write artifacts/, render thumbnail, `status=generated` |
+| Approve | `status=approved` |
+| Duplicate | copy directory, new id, name="<original> (copy)" |
+| Delete | soft `status=archived`; hard removes directory |
+
+In-memory LRU cache (max 16 items) avoids re-reading on rapid turns. Invalidated on duplicate/delete/approve.
+
+## Web Viewer
+
+`services/web/static/index.html` — single file. Estimated 500-700 LOC of JS plus inline CSS.
+
+- Three.js r160+ via importmap from jsdelivr.
+- Modules: `GLTFLoader`, `OrbitControls`, `RGBELoader` (HDRI environment), `CSS2DRenderer` (room labels), `Raycaster` (picking).
+- Three render modes: 3D iso (default), top-down floor plan (clipping plane at level + 0.6m, orthographic camera), exploded axonometric (Phase 2 candidate).
+- Click a primitive → highlight (outline pass) + sidebar shows spec id, type, dimensions, validation issues touching it.
+- Validation overlay: red outline for primitives with errors; yellow for warnings.
+- Chat panel on the right: messages, agent avatars (color-coded), inline `structured_question` cards.
+- Gallery view: grid of cards, thumbnail + name + status pill + last-modified.
+
+## Inputs & UX
+
+### Image upload
+
+- File picker accepts JPEG/PNG, max 8 MB.
+- Encoded base64 alongside the user message in `/api/chat`.
+- Web service forwards image to a vision-capable model (Anthropic Claude Sonnet 4.6 default; OpenAI GPT-4o, Gemini 2.x as alternates).
+- System prompt includes: "If an image is attached, treat it as a sketch or photo of a floor plan. Extract architectural intent: room layout, approximate dimensions, openings. Propose HouseSpec deltas as advisors gather more information."
+- Uploaded image stored in `data/items/<id>/inputs/<timestamp>.png`, referenced from history.jsonl.
+
+### Inline structured-question cards
+
+When an advisor returns `gap_questions`, LangGraph emits an `interrupt`. The web layer renders each `StructuredQuestion` as a small inline card:
+
+```
+┌──────────────────────────────────────────┐
+│ Architect needs to know:                  │
+│                                            │
+│ How many bedrooms?                         │
+│ ( ) 2  ( ) 3  ( ) 4  ( ) 5+               │
+│                                            │
+│ What ceiling height?                       │
+│ [ 2.7 ] meters                             │
+│                                            │
+│       [ Submit answers ]                   │
+└──────────────────────────────────────────┘
+```
+
+Submit posts `{item_id, answers: {field: value, ...}}` to `/api/chat/resume`; LangGraph resumes from the interrupt, advisor re-runs with the new info, and the turn proceeds.
+
+## Build Sequence
+
+| # | Milestone | Scope | Deliverable |
+|---|---|---|---|
+| **M0** | Bootstrap (1-2 days) | Monorepo, `services/web` + `services/worker` scaffolds, `docker-compose.yml` with shared `./data` mount, ruff/pytest/mypy at workspace root, GitHub Actions builds both images, ArchAgent repo created on GitHub | `docker compose up` brings both `/healthz` green |
+| **M1** | Spec + Translator + Worker (week 1) | `core/spec.py`, full `translator/` per-primitive builders, worker `/translate`, gltf/blend/stl exporters, golden tests for ranch/two-story/ADU | `curl POST /translate` produces valid gltf in `data/items/test/artifacts/`; goldens pass |
+| **M2** | Validators + jurisdictions (week 2) | reference / architect / structural / code validators in web; geometric validator in worker; `IRC_2021.yaml`; ezdxf DXF + PDF exporters; BoM | `archagent validate sample/ranch.json` works; DXF + PDF written |
+| **M3** | LLM backends + Coder node (week 3) | `core/llm/`, Coder LangGraph node with structured-output enforcement, three retry stages | `archagent generate "small ranch" --backend anthropic` emits valid spec end-to-end |
+| **M4** | Multi-agent flow (week 4) | LangGraph nodes for advisors, readiness gate, Documenter, parallel fan-out, interrupt-based gap questions | CLI multi-turn chat with advisor gating works |
+| **M5** | Gallery & persistence (week 5) | SQLite store, item CRUD, per-item DesignState rehydration, MCP gallery tools, thumbnail trigger to worker, LangGraph SqliteSaver | `archagent gallery list/show/duplicate` works; items survive restart; resumed turns work |
+| **M6** | Server + MCP + web UI (week 6) | FastAPI routes, FastMCP, Three.js + GLTFLoader frontend, gallery grid, item view, structured-question cards, image upload, validation overlay | Browser flow: gallery → new design → chat (with image) → 3D model → approve → re-open later |
+| **M7** | Polish + deploy (week 7) | Docker images published to GHCR, README with `docker compose up` quickstart, deploy guide for self-hosted VPS, Playwright happy-path tests, perf budget (cold start <30s, warm chat turn <10s) | Tagged release, deploy guide verified on a clean VPS |
+
+## Risks
+
+1. **LangGraph ramp-up.** Solo developer learning a new framework. Mitigation: prototype the readiness-gate-with-interrupts pattern in M0/M1 before building all five nodes.
+2. **LLM JSON-vs-schema reliability.** Even with structured outputs, models miss enums or violate constraints. Mitigation: 3 retries per stage with the validation error appended; budget caps prevent runaway loops; fall back to "I couldn't generate, try rephrasing" with the violation summary visible.
+3. **Translator complexity.** Extended shell already includes 11 primitive types. Mitigation: hold the Phase 1 line — no MEP, electrical, framing detail, or rendering.
+4. **DXF rendering quality.** ezdxf's matplotlib backend is functional but not architectural-publication quality. Acceptable for Phase 1; revisit in M7 or Phase 2 if users push back.
+5. **Worker crash recovery.** Persistent Blender subprocess can crash on malformed bpy state. Mitigation: lifespan handler restarts; web retries once; surface clear error to chat.
+6. **Shared volume permissions.** Docker uid/gid mismatch is a common footgun. Mitigation: pin a non-root user with explicit uid/gid in both Dockerfiles, document in README.
+7. **Vision LLM hallucinations on sketches.** Sketches are noisy; vision models will guess. Mitigation: parse the result through advisor agents who flag low-confidence inferences as `structured_question`s rather than committing them silently.
+
+## Out of Scope (Phase 2 / Phase 3)
+
+Phase 2 (Interior composition):
+- Asset library integrations (Poly Haven, Sketchfab, Hyper3D Rodin, Hunyuan3D)
+- Furniture placement, materials, lighting
+- Interior Designer / Lighting Designer / Materials specialist agents
+- Higher-fidelity material authoring
+
+Phase 3 (Exterior + site):
+- Site grading, landscaping, plantings
+- Facade detailing
+- Sun study and analytical lighting
+- Render-quality output (path tracing, denoising)
+
+Other deferrals:
+- Multi-user / auth / sharing
+- DXF / IFC import
+- Direct-manipulation canvas UX
+- IFC export
+- Rendering presets beyond glTF preview
+- Mobile / native apps
+- Real-time collaboration
+- Subscription / billing flows
+
+## Open Questions
+
+These are not blockers for writing the implementation plan; they can be settled in M0 or with a small RFC during build:
+
+1. **Repo location** (GitHub user/org for `ArchAgent`). Default: `github.com/danghoangnhan/ArchAgent`.
+2. **LLM default** for the Coder. Default: Claude Sonnet 4.6. Confirm based on tool-use reliability for `HouseSpec` schema.
+3. **Jurisdiction default**. IRC 2021 (US residential) is a reasonable default; international users will want IBC + local codes later.
+4. **Thumbnail style** — flat shading / clay render / styled. Default: clay render with single sun for fast Eevee.
+5. **Rate limits** on chat endpoint. Default: per-IP 60 turns/hour; revisit when deploy target is fixed.
+6. **Shared volume vs. object storage** for multi-host deploys. Phase 1 ships volume-only; document the swap path.
+
+## Appendix A — Sample HouseSpec
+
+```json
+{
+  "metadata": {"name": "Sunset Ranch", "occupancy_type": "R-3"},
+  "structural_system": "wood_frame",
+  "levels": [{"id": "l1", "name": "Ground", "elevation_m": 0.0, "height_m": 2.7}],
+  "walls": [
+    {"id": "w1", "level_id": "l1", "start": [0, 0], "end": [12, 0],
+     "height_m": 2.7, "thickness_m": 0.2, "material": "wood_frame", "is_load_bearing": true},
+    {"id": "w2", "level_id": "l1", "start": [12, 0], "end": [12, 8],
+     "height_m": 2.7, "thickness_m": 0.2, "material": "wood_frame", "is_load_bearing": true}
+  ],
+  "floors": [
+    {"id": "f1", "level_id": "l1",
+     "outline": [[0, 0], [12, 0], [12, 8], [0, 8]], "thickness_m": 0.25}
+  ],
+  "doors": [
+    {"id": "d1", "parent_wall_id": "w1", "offset_along_wall_m": 1.5,
+     "width_m": 0.9, "height_m": 2.1, "is_egress": true}
+  ],
+  "windows": [
+    {"id": "win1", "parent_wall_id": "w1", "offset_along_wall_m": 4.0,
+     "sill_height_m": 0.9, "width_m": 1.5, "height_m": 1.2, "operable": true}
+  ],
+  "rooms": [
+    {"id": "r1", "name": "Living", "program": "living", "level_id": "l1",
+     "bounded_by_wall_ids": ["w1", "w2", "w3", "w4"], "floor_id": "f1"}
+  ],
+  "roof": {"type": "gable", "parent_outline": [[0, 0], [12, 0], [12, 8], [0, 8]],
+           "pitch_deg": 22.5, "overhang_m": 0.5, "base_elevation_m": 2.7}
+}
+```
+
+## Appendix B — Tech Stack Summary
+
+| Layer | Choice | Notes |
+|---|---|---|
+| Web language | Python 3.12 | No bpy → free of Python pin |
+| Worker language | Python 3.11+ | Blender 4.x bundles Python 3.11 |
+| Web framework | FastAPI | Async, OpenAPI |
+| MCP server | FastMCP | Same process as web |
+| Agent orchestration | LangGraph | Cycles, interrupts, checkpointing |
+| LLM SDKs | Anthropic, OpenAI, Gemini | Direct, no LangChain wrappers needed |
+| Schema | Pydantic v2 | HouseSpec, DesignState, all messages |
+| Persistence | SQLite + filesystem | Two DBs: gallery, checkpoints |
+| Frontend | Three.js r160+ vanilla | Single HTML, importmap |
+| Floor plans | ezdxf | DXF + PDF (matplotlib backend) |
+| Container runtime | Docker + docker-compose | Default deploy |
+| Tooling | uv, ruff, pytest, mypy | Workspace at repo root |