feat: multi-agent chat for collaborative CAD design

Replace single-prompt generation with a multi-agent chat experience:
- 4 AI agents (Design, Engineering, CNC, CAD Coder) in shared group chat
- Hybrid orchestration: single-call JSON for Gemini/Mock, CrewAI for paid APIs
- @mention support to address specific agents
- Fullscreen 3D viewer with collapsible slide-out chat panel
- On-demand 3D preview generation
- Refactored codebase into core/, server/, agents/ packages

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

Dockerfile

@@ -28,7 +28,9 @@ WORKDIR /app
 COPY --from=builder /app/.venv /app/.venv
 
 # Copy application source
-COPY --from=builder /app/*.py /app/
+COPY --from=builder /app/core /app/core/
+COPY --from=builder /app/server /app/server/
+COPY --from=builder /app/agents /app/agents/
 COPY --from=builder /app/web /app/web/
 COPY --from=builder /app/entrypoint.sh /app/
 

agents/crew_orchestrator.py

@@ -0,0 +1,95 @@
+"""CrewAI multi-call orchestrator for paid API backends (Anthropic/OpenAI).
+
+Uses CrewAI's hierarchical process where a manager agent routes to
+specialist agents. Each agent gets its own focused LLM call.
+Better quality but uses 2-4 API calls per turn.
+
+Note: Falls back to SingleCallOrchestrator if CrewAI is not installed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from agents.definitions import AGENTS, AGENT_COLORS, AGENT_NAMES, AGENT_AVATARS
+from agents.prompts import route_by_keywords
+
+
+DEFAULT_OUTPUT_DIR = Path(__file__).parent.parent / "output"
+
+
+class CrewOrchestrator:
+    """Multi-call orchestrator using CrewAI hierarchical process.
+
+    Each agent gets its own LLM call with focused context.
+    Falls back to SingleCallOrchestrator if CrewAI is unavailable.
+    """
+
+    def __init__(self, backend_name: str = "anthropic", output_dir: Path | str = DEFAULT_OUTPUT_DIR):
+        self.backend_name = backend_name
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self._crew_available = self._check_crewai()
+
+    def _check_crewai(self) -> bool:
+        """Check if CrewAI is installed and usable."""
+        try:
+            import crewai
+            return True
+        except ImportError:
+            return False
+
+    def chat_turn(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None = None,
+        max_history: int = 30,
+    ) -> dict:
+        """Run one chat turn using CrewAI multi-call process.
+
+        Falls back to SingleCallOrchestrator if CrewAI is not available.
+
+        Returns same format as SingleCallOrchestrator:
+            {"responses": [...], "preview": None | {...}}
+        """
+        if not self._crew_available:
+            # Fallback to single-call
+            from agents.orchestrator import SingleCallOrchestrator
+            from core.backends import AnthropicBackend, OpenAIBackend
+
+            backends = {"anthropic": AnthropicBackend, "openai": OpenAIBackend}
+            backend_cls = backends.get(self.backend_name, AnthropicBackend)
+
+            try:
+                backend = backend_cls()
+            except Exception:
+                from agents.orchestrator import MockChatBackend
+                mock = MockChatBackend()
+                return mock.chat_turn(message, history, mentions)
+
+            orchestrator = SingleCallOrchestrator(
+                backend=backend, output_dir=self.output_dir
+            )
+            return orchestrator.chat_turn(message, history, mentions, max_history)
+
+        # TODO: Implement CrewAI hierarchical process
+        # For now, delegate to single-call as well
+        from agents.orchestrator import SingleCallOrchestrator
+        from core.backends import AnthropicBackend, OpenAIBackend
+
+        backends = {"anthropic": AnthropicBackend, "openai": OpenAIBackend}
+        backend_cls = backends.get(self.backend_name, AnthropicBackend)
+
+        try:
+            backend = backend_cls()
+        except Exception:
+            from agents.orchestrator import MockChatBackend
+            mock = MockChatBackend()
+            return mock.chat_turn(message, history, mentions)
+
+        orchestrator = SingleCallOrchestrator(
+            backend=backend, output_dir=self.output_dir
+        )
+        return orchestrator.chat_turn(message, history, mentions, max_history)

agents/definitions.py

@@ -0,0 +1,83 @@
+"""Multi-agent definitions for NeuralCAD collaborative design chat."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentDef:
+    """Definition of a chat agent."""
+    id: str
+    name: str
+    role: str
+    color: str
+    avatar: str
+    goal: str
+    backstory: str
+
+
+AGENTS: dict[str, AgentDef] = {
+    "design": AgentDef(
+        id="design",
+        name="Design Agent",
+        role="Industrial Designer",
+        color="#7c3aed",
+        avatar="DA",
+        goal="Understand the user's intent and propose optimal form factors, shapes, and aesthetic choices for mechanical parts.",
+        backstory=(
+            "You are an experienced industrial designer specializing in mechanical parts. "
+            "You think about form, function, ergonomics, and visual appeal. You ask clarifying "
+            "questions about the part's purpose, environment, and constraints before proposing "
+            "designs. You suggest shapes, proportions, and features that balance aesthetics with "
+            "manufacturability."
+        ),
+    ),
+    "engineering": AgentDef(
+        id="engineering",
+        name="Engineering Agent",
+        role="Mechanical Engineer",
+        color="#00b4d8",
+        avatar="EA",
+        goal="Ensure parts are structurally sound with correct dimensions, tolerances, materials, and fastener specifications.",
+        backstory=(
+            "You are a senior mechanical engineer with deep knowledge of materials science, "
+            "stress analysis, and fastener standards. You specify wall thicknesses, fillet radii, "
+            "clearance holes (M3=3.4mm, M4=4.5mm, M5=5.5mm, M6=6.6mm, M8=9.0mm), and material "
+            "recommendations. You flag structural concerns and suggest reinforcements like ribs "
+            "or gussets when loads are significant."
+        ),
+    ),
+    "cnc": AgentDef(
+        id="cnc",
+        name="CNC Agent",
+        role="CNC Manufacturing Advisor",
+        color="#00e676",
+        avatar="CA",
+        goal="Advise on manufacturability: tool access, wall thickness limits, pocket ratios, axis requirements, and cost implications.",
+        backstory=(
+            "You are a CNC machinist with 20 years of shop floor experience. You know what "
+            "tool geometries can reach, what aspect ratios cause chatter, and when to recommend "
+            "3-axis vs 3+2 vs 5-axis. You flag undercuts, thin walls (<1.5mm), deep pockets "
+            "(>4:1 ratio), and features that need special fixturing. You think about setup count "
+            "and machining time."
+        ),
+    ),
+    "cad": AgentDef(
+        id="cad",
+        name="CAD Coder",
+        role="CadQuery Code Generator",
+        color="#ffab40",
+        avatar="CC",
+        goal="Generate valid CadQuery Python code that produces the agreed-upon 3D model.",
+        backstory=(
+            "You are an expert CadQuery programmer. You only speak when asked to generate "
+            "a preview or produce code. You take the design specifications agreed upon by the "
+            "team and translate them into precise CadQuery Python code. Your code always assigns "
+            "the result to a variable called `result` as a cq.Workplane object."
+        ),
+    ),
+}
+
+# Agent metadata for frontend rendering
+AGENT_COLORS = {agent.id: agent.color for agent in AGENTS.values()}
+AGENT_AVATARS = {agent.id: agent.avatar for agent in AGENTS.values()}
+AGENT_NAMES = {agent.id: agent.name for agent in AGENTS.values()}

agents/llm_adapter.py

@@ -0,0 +1,48 @@
+"""CrewAI BaseLLM adapter for NeuralCAD's LLMBackend interface."""
+
+from __future__ import annotations
+from typing import Any
+
+try:
+    from crewai import LLM as BaseLLM
+except ImportError:
+    # Fallback if crewai not installed — allows import without dependency
+    class BaseLLM:
+        def __init__(self, model: str, **kwargs):
+            self.model = model
+        def call(self, messages, **kwargs) -> str:
+            raise NotImplementedError
+
+
+class NeuralCADLLMAdapter(BaseLLM):
+    """Adapter that wraps NeuralCAD's LLMBackend for CrewAI compatibility.
+
+    Usage:
+        from core.backends import GeminiBackend
+        backend = GeminiBackend()
+        adapter = NeuralCADLLMAdapter(backend, model="gemini-2.5-flash")
+        # Now usable as CrewAI agent's llm parameter
+    """
+
+    def __init__(self, backend, model: str = "custom", **kwargs):
+        super().__init__(model=model, **kwargs)
+        self.backend = backend
+
+    def call(
+        self,
+        messages: str | list[dict],
+        tools: Any = None,
+        callbacks: Any = None,
+        available_functions: Any = None,
+        **kwargs,
+    ) -> str:
+        # If messages is a string, wrap it in standard format
+        if isinstance(messages, str):
+            messages = [{"role": "user", "content": messages}]
+        return self.backend.generate(messages)
+
+    def supports_function_calling(self) -> bool:
+        return False
+
+    def supports_stop_words(self) -> bool:
+        return False

agents/orchestrator.py

@@ -0,0 +1,365 @@
+"""Single-call orchestrator for multi-agent chat (Gemini/Mock mode).
+
+One LLM call per user turn. The orchestrator builds a system prompt containing
+all agent personas, sends a single request, and parses the JSON response into
+individual agent messages.  For mock mode no LLM call is made at all — canned
+responses are returned based on keyword matching.
+
+Both ``MockChatBackend`` and ``SingleCallOrchestrator`` return the same shape::
+
+    {
+        "responses": [{"agent_id", "agent_name", "message", "color", "avatar", "code"}, ...],
+        "preview": None | { ... execution + validation data ... }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from agents.definitions import AGENTS, AGENT_COLORS, AGENT_NAMES, AGENT_AVATARS
+from agents.prompts import (
+    build_orchestrator_system_prompt,
+    build_chat_messages,
+    parse_mentions,
+    route_by_keywords,
+    parse_orchestrator_response,
+)
+from core.backends import LLMBackend, MockBackend
+from core.executor import execute_cadquery, export_all
+from core.validator import validate_for_cnc
+
+
+DEFAULT_OUTPUT_DIR = Path(__file__).parent.parent / "output"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _format_response(agent_id: str, message: str, code: str | None = None) -> dict:
+    """Wrap a raw agent reply into the standard response envelope."""
+    return {
+        "agent_id": agent_id,
+        "agent_name": AGENT_NAMES[agent_id],
+        "message": message,
+        "color": AGENT_COLORS[agent_id],
+        "avatar": AGENT_AVATARS[agent_id],
+        "code": code,
+    }
+
+
+def _execute_cad_code(code: str, prompt: str, output_dir: Path) -> dict | None:
+    """Execute CadQuery *code* and return preview data (or error dict)."""
+    exec_result = execute_cadquery(code)
+
+    if not exec_result.success:
+        return {"success": False, "error": exec_result.error}
+
+    # Derive a filesystem-safe part name from the prompt
+    part_name = prompt[:40].strip().replace(" ", "_").lower()
+    part_name = "".join(c for c in part_name if c.isalnum() or c == "_")
+    if not part_name:
+        part_name = "part"
+
+    # Export STL + STEP
+    base_path = output_dir / part_name
+    try:
+        export_all(exec_result.result, base_path)
+    except Exception as exc:
+        return {"success": False, "error": f"Export failed: {exc}"}
+
+    # CNC validation
+    validation = validate_for_cnc(exec_result.result, part_name=part_name)
+
+    return {
+        "success": True,
+        "part_name": part_name,
+        "stl_url": f"/api/models/{part_name}.stl",
+        "step_url": f"/api/models/{part_name}.step",
+        "execution": {
+            "success": True,
+            "volume_mm3": exec_result.volume,
+            "bounding_box_mm": list(exec_result.bounding_box),
+            "face_count": exec_result.face_count,
+            "edge_count": exec_result.edge_count,
+        },
+        "validation": {
+            "machinable": validation.machinable,
+            "axis_recommendation": validation.axis_recommendation,
+            "error_count": validation.error_count,
+            "warning_count": validation.warning_count,
+            "issues": [
+                {"severity": i.severity, "category": i.category, "message": i.message}
+                for i in validation.issues
+            ],
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# MockChatBackend — template-based, no LLM call
+# ---------------------------------------------------------------------------
+
+class MockChatBackend:
+    """Template-based chat responses for mock mode (no LLM call).
+
+    Generates canned agent responses based on keyword matching.
+    For the CAD Coder agent, delegates to ``MockBackend`` for code generation.
+    """
+
+    def __init__(self, output_dir: Path | str = DEFAULT_OUTPUT_DIR):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    # -- public interface ----------------------------------------------------
+
+    def chat_turn(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None = None,
+        max_history: int = 30,
+    ) -> dict:
+        """Return ``{"responses": [...], "preview": ...}``."""
+        lower = message.lower()
+
+        # Determine which agents respond
+        if mentions:
+            active = mentions
+        else:
+            active = route_by_keywords(message)
+
+        responses: list[dict] = []
+        preview = None
+
+        if "design" in active:
+            responses.append(
+                _format_response("design", self._design_response(lower))
+            )
+
+        if "engineering" in active:
+            responses.append(
+                _format_response("engineering", self._engineering_response(lower))
+            )
+
+        if "cnc" in active:
+            responses.append(
+                _format_response("cnc", self._cnc_response(lower))
+            )
+
+        if "cad" in active:
+            # Use MockBackend for actual code generation
+            from core.cadquery_prompts import build_messages
+
+            mock = MockBackend()
+            code = mock.generate(build_messages(message))
+            responses.append(
+                _format_response(
+                    "cad",
+                    "Model generated. Click the 3D viewer to inspect it.",
+                    code=code,
+                )
+            )
+            preview = _execute_cad_code(code, message, self.output_dir)
+
+        return {"responses": responses, "preview": preview}
+
+    # -- canned response templates -------------------------------------------
+
+    @staticmethod
+    def _design_response(lower: str) -> str:
+        if any(w in lower for w in ("bracket", "mount")):
+            return (
+                "For a mounting bracket, I'd suggest an L-shaped profile with "
+                "filleted corners for rigidity. What's the intended load direction?"
+            )
+        if any(w in lower for w in ("gear", "spur")):
+            return (
+                "For a spur gear, we'll need to define the module, tooth count, "
+                "and bore diameter. What's the mating gear specification?"
+            )
+        if any(w in lower for w in ("enclosure", "box", "housing")):
+            return (
+                "For an enclosure, I'd recommend rounded external corners for "
+                "aesthetics and a pocket on the top face for the lid. What "
+                "components go inside?"
+            )
+        return (
+            "I can help design that. Could you tell me more about the part's "
+            "purpose and any dimensional constraints?"
+        )
+
+    @staticmethod
+    def _engineering_response(lower: str) -> str:
+        if any(w in lower for w in ("m3", "m4", "m5", "m6", "m8")):
+            return (
+                "Good fastener choice. I'll specify the clearance holes per ISO "
+                "standards. Shall I add counterbores or keep them as through-holes?"
+            )
+        if any(w in lower for w in ("load", "stress", "strength")):
+            return (
+                "For the expected loads, I'd recommend 3mm minimum wall thickness "
+                "in aluminum 6061-T6. Adding reinforcement ribs would increase "
+                "stiffness significantly."
+            )
+        return (
+            "I'll specify the critical dimensions and tolerances. What material "
+            "are you planning to machine this from?"
+        )
+
+    @staticmethod
+    def _cnc_response(lower: str) -> str:
+        if any(w in lower for w in ("pocket", "deep", "slot")):
+            return (
+                "Keep pocket depth-to-width ratio under 4:1 for clean machining. "
+                "I'd recommend a 6mm endmill for this geometry."
+            )
+        if any(w in lower for w in ("5-axis", "undercut")):
+            return (
+                "That feature would require 5-axis machining. Consider redesigning "
+                "to avoid undercuts for 3-axis compatibility."
+            )
+        return (
+            "This looks achievable with standard 3-axis milling. No undercuts or "
+            "access issues detected so far."
+        )
+
+
+# ---------------------------------------------------------------------------
+# SingleCallOrchestrator — one LLM call per turn
+# ---------------------------------------------------------------------------
+
+class SingleCallOrchestrator:
+    """Orchestrator that uses a single LLM call per chat turn.
+
+    Builds a system prompt containing all agent personas, sends one LLM call,
+    and parses the JSON response into individual agent messages.
+    Used for Gemini free tier and other rate-limited backends.
+    """
+
+    def __init__(self, backend: LLMBackend, output_dir: Path | str = DEFAULT_OUTPUT_DIR):
+        self.backend = backend
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def chat_turn(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None = None,
+        max_history: int = 30,
+    ) -> dict:
+        """Run one chat turn: user message -> agent responses.
+
+        Args:
+            message: The user's message text (with @mentions already stripped).
+            history: Previous messages [{role, agent_id, content}, ...].
+            mentions: Agent IDs explicitly mentioned by user. ``None`` = auto-route.
+            max_history: Max history messages to include in context.
+
+        Returns:
+            ``{"responses": [...], "preview": None | {...}}``
+        """
+        # Determine which agents are active
+        active_agents = mentions if mentions else None  # None lets orchestrator decide
+
+        # Check if CAD context is needed
+        include_cad = mentions is not None and "cad" in mentions
+        if not include_cad:
+            cad_keywords = [
+                "generate", "build", "preview", "show me",
+                "create", "model", "render",
+            ]
+            include_cad = any(kw in message.lower() for kw in cad_keywords)
+
+        # Build orchestrator prompt
+        system_prompt = build_orchestrator_system_prompt(
+            active_agents=active_agents,
+            include_cad_context=include_cad,
+        )
+
+        # Build message list
+        messages = build_chat_messages(
+            user_message=message,
+            history=history,
+            system_prompt=system_prompt,
+            max_history=max_history,
+        )
+
+        # Single LLM call
+        try:
+            raw_response = self.backend.generate(messages)
+            agent_responses = parse_orchestrator_response(raw_response)
+        except Exception:
+            # Fallback: keyword routing with generic replies
+            fallback_agents = route_by_keywords(message)
+            agent_responses = [
+                {
+                    "id": aid,
+                    "message": "I can help with that aspect of the design.",
+                    "code": None,
+                }
+                for aid in fallback_agents
+            ]
+
+        # Format responses with metadata
+        formatted: list[dict] = []
+        preview = None
+
+        for resp in agent_responses:
+            agent_id = resp["id"]
+            if agent_id not in AGENTS:
+                continue
+
+            formatted.append(
+                _format_response(agent_id, resp["message"], code=resp.get("code"))
+            )
+
+            # If CAD Coder responded with code, execute it
+            if agent_id == "cad" and resp.get("code"):
+                preview = _execute_cad_code(resp["code"], message, self.output_dir)
+
+        return {"responses": formatted, "preview": preview}
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def get_orchestrator(
+    backend_name: str = "mock",
+    output_dir: str | Path = DEFAULT_OUTPUT_DIR,
+) -> MockChatBackend | SingleCallOrchestrator:
+    """Create the appropriate orchestrator for the given backend.
+
+    Args:
+        backend_name: ``"mock"``, ``"gemini"``, ``"anthropic"``, or ``"openai"``.
+        output_dir: Directory for exported model files.
+    """
+    if backend_name == "mock":
+        return MockChatBackend(output_dir=output_dir)
+
+    # For all LLM backends, use SingleCallOrchestrator.
+    # (CrewAI multi-call variant can be added later for anthropic/openai.)
+    from core.backends import AnthropicBackend, OpenAIBackend, GeminiBackend
+
+    backends = {
+        "gemini": GeminiBackend,
+        "anthropic": AnthropicBackend,
+        "openai": OpenAIBackend,
+    }
+
+    backend_cls = backends.get(backend_name)
+    if backend_cls is None:
+        return MockChatBackend(output_dir=output_dir)
+
+    try:
+        backend = backend_cls()
+    except Exception:
+        # API key missing, model unavailable, etc. — fall back to mock.
+        return MockChatBackend(output_dir=output_dir)
+
+    return SingleCallOrchestrator(backend=backend, output_dir=output_dir)

agents/prompts.py

@@ -0,0 +1,223 @@
+"""Orchestrator prompts and routing logic for multi-agent chat."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+from agents.definitions import AGENTS, AgentDef
+
+
+def build_orchestrator_system_prompt(
+    active_agents: list[str] | None = None,
+    include_cad_context: bool = False,
+) -> str:
+    """Build the orchestrator system prompt for single-call mode.
+
+    Args:
+        active_agents: List of agent IDs to include. None = all except 'cad'.
+        include_cad_context: Whether to include CadQuery reference for the CAD agent.
+    """
+    if active_agents is None:
+        active_agents = ["design", "engineering", "cnc"]
+
+    prompt_parts = [
+        "You are the orchestrator for a multi-agent CAD design team. "
+        "You control multiple specialist agents who collaborate with a user "
+        "to design mechanical parts for CNC machining.\n",
+        "## Your Agents\n",
+    ]
+
+    for agent_id in active_agents:
+        agent = AGENTS[agent_id]
+        prompt_parts.append(
+            f"### {agent.name} (id: \"{agent.id}\")\n"
+            f"Role: {agent.role}\n"
+            f"Goal: {agent.goal}\n"
+            f"Personality: {agent.backstory}\n"
+        )
+
+    prompt_parts.append(
+        "## Instructions\n"
+        "Given the conversation history and the user's latest message, "
+        "decide which agents should respond and generate their messages.\n\n"
+        "Rules:\n"
+        "- Select 1-3 agents that are most relevant to the user's message.\n"
+        "- Each agent should respond in character with their expertise.\n"
+        "- Keep responses concise and actionable (2-4 sentences each).\n"
+        "- Do NOT include the CAD Coder agent unless the user explicitly asks "
+        "for a preview, says 'generate', 'build it', 'show me', 'create the model', "
+        "or similar.\n"
+        "- When the CAD Coder responds, include a 'code' field with valid CadQuery Python "
+        "that assigns the result to a variable called `result` as a cq.Workplane.\n"
+        "- Agents should build on each other's points, not repeat them.\n"
+    )
+
+    if include_cad_context and "cad" in active_agents:
+        from core.cadquery_prompts import CADQUERY_SYSTEM_PROMPT
+        prompt_parts.append(
+            "\n## CadQuery Reference (for CAD Coder agent)\n"
+            f"{CADQUERY_SYSTEM_PROMPT}\n"
+        )
+
+    prompt_parts.append(
+        "\n## Response Format\n"
+        "Respond with ONLY valid JSON in this exact format:\n"
+        "```json\n"
+        '{"agents": [\n'
+        '  {"id": "design", "message": "Your design suggestion here..."},\n'
+        '  {"id": "engineering", "message": "Your engineering input here..."}\n'
+        "]}\n"
+        "```\n\n"
+        "When the CAD Coder agent responds, add a 'code' field:\n"
+        "```json\n"
+        '{"agents": [\n'
+        '  {"id": "cad", "message": "Model generated.", '
+        '"code": "import cadquery as cq\\nresult = cq.Workplane(\'XY\').box(10,10,10)"}\n'
+        "]}\n"
+        "```\n\n"
+        "Output ONLY the JSON. No other text."
+    )
+
+    return "\n".join(prompt_parts)
+
+
+def build_chat_messages(
+    user_message: str,
+    history: list[dict],
+    system_prompt: str,
+    max_history: int = 30,
+) -> list[dict]:
+    """Build the message list for the orchestrator LLM call.
+
+    Args:
+        user_message: The user's current message.
+        history: Previous messages [{role, agent_id, content}, ...].
+        system_prompt: The orchestrator system prompt.
+        max_history: Maximum number of history messages to include.
+    """
+    messages = [{"role": "system", "content": system_prompt}]
+
+    # Truncate history to last N messages
+    recent = history[-max_history:] if len(history) > max_history else history
+
+    for msg in recent:
+        if msg.get("role") == "user":
+            messages.append({"role": "user", "content": msg["content"]})
+        else:
+            # Agent messages become assistant messages with agent label
+            agent_id = msg.get("agent_id", "unknown")
+            agent_name = AGENTS.get(agent_id, AGENTS["design"]).name
+            messages.append({
+                "role": "assistant",
+                "content": f"[{agent_name}]: {msg['content']}"
+            })
+
+    # Add current user message
+    messages.append({"role": "user", "content": user_message})
+
+    return messages
+
+
+def parse_mentions(message: str) -> tuple[str, list[str]]:
+    """Extract @mentions from a message and return cleaned message + mention list.
+
+    Returns:
+        (cleaned_message, mentions) where mentions is list of agent IDs.
+    """
+    mentions = []
+    cleaned = message
+
+    for agent_id in AGENTS:
+        pattern = rf"@{agent_id}\b"
+        if re.search(pattern, message, re.IGNORECASE):
+            mentions.append(agent_id)
+            cleaned = re.sub(pattern, "", cleaned, flags=re.IGNORECASE).strip()
+
+    return cleaned, mentions
+
+
+# ── Keyword-based fallback routing ────────────────────────────────────────
+
+_ROUTING_KEYWORDS: dict[str, list[str]] = {
+    "design": [
+        "design", "look", "shape", "style", "form", "aesthetic", "appearance",
+        "layout", "concept", "idea", "propose", "suggest",
+    ],
+    "engineering": [
+        "dimension", "tolerance", "material", "strength", "load", "stress",
+        "thickness", "wall", "fillet", "radius", "clearance",
+        "m2", "m3", "m4", "m5", "m6", "m8", "m10", "m12",
+        "aluminum", "steel", "brass", "titanium", "nylon",
+    ],
+    "cnc": [
+        "machine", "mill", "cnc", "manufacture", "machinable", "axis",
+        "tool", "fixture", "setup", "pocket", "undercut", "access",
+        "3-axis", "5-axis", "cost",
+    ],
+    "cad": [
+        "generate", "build", "preview", "show me", "create", "model it",
+        "render", "code", "make it", "produce",
+    ],
+}
+
+
+def route_by_keywords(message: str) -> list[str]:
+    """Fallback agent routing based on keyword matching.
+
+    Returns list of agent IDs that should respond.
+    """
+    lower = message.lower()
+    scores: dict[str, int] = {agent_id: 0 for agent_id in AGENTS}
+
+    for agent_id, keywords in _ROUTING_KEYWORDS.items():
+        for kw in keywords:
+            if kw in lower:
+                scores[agent_id] += 1
+
+    # Select agents with score > 0, sorted by score descending
+    active = [aid for aid, score in sorted(scores.items(), key=lambda x: -x[1]) if score > 0]
+
+    # Default: design + engineering for general discussion
+    if not active:
+        active = ["design", "engineering"]
+
+    # Cap at 3 agents
+    return active[:3]
+
+
+def parse_orchestrator_response(response_text: str) -> list[dict]:
+    """Parse the orchestrator's JSON response into agent messages.
+
+    Returns list of dicts: [{"id": str, "message": str, "code": str|None}, ...]
+    Falls back to treating entire response as design agent message if JSON fails.
+    """
+    text = response_text.strip()
+
+    # Try to extract JSON from markdown code fences
+    json_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if json_match:
+        text = json_match.group(1)
+
+    try:
+        data = json.loads(text)
+        agents = data.get("agents", [])
+
+        # Validate structure
+        result = []
+        for agent in agents:
+            if isinstance(agent, dict) and "id" in agent and "message" in agent:
+                result.append({
+                    "id": agent["id"],
+                    "message": agent["message"],
+                    "code": agent.get("code"),
+                })
+
+        if result:
+            return result
+    except (json.JSONDecodeError, KeyError, TypeError):
+        pass
+
+    # Fallback: treat entire response as design agent message
+    return [{"id": "design", "message": response_text, "code": None}]

core/backends.py

@@ -0,0 +1,740 @@
+"""
+LLM backend implementations for CadQuery code generation.
+
+Supports multiple backends:
+  - Anthropic Claude
+  - OpenAI GPT-4o
+  - Google Gemini (free tier available)
+  - Mock (dynamic generation, no API key required)
+  - NeuralCAD (local neural pipeline, not yet implemented)
+"""
+
+import base64
+import mimetypes
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+
+# ── LLM Backends ──────────────────────────────────────────────────────────
+
+
+class LLMBackend:
+    """Base class for LLM code generation backends."""
+
+    def generate(self, messages: list[dict]) -> str:
+        raise NotImplementedError
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        """Generate code from messages that include an image.
+        Override in backends that support vision."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support image input"
+        )
+
+
+class AnthropicBackend(LLMBackend):
+    """Generate CadQuery code using Anthropic Claude."""
+
+    def __init__(
+        self, model: str = "claude-sonnet-4-20250514", api_key: Optional[str] = None
+    ):
+        import anthropic
+
+        self.client = anthropic.Anthropic(
+            api_key=api_key or os.environ.get("ANTHROPIC_API_KEY")
+        )
+        self.model = model
+
+    def generate(self, messages: list[dict]) -> str:
+        # Anthropic uses system param separately
+        system_msg = ""
+        user_messages = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            else:
+                user_messages.append(m)
+
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=4096,
+            system=system_msg,
+            messages=user_messages,
+        )
+        return response.content[0].text
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        image_path = Path(image_path)
+        media_type = mimetypes.guess_type(str(image_path))[0] or "image/png"
+        image_data = base64.b64encode(image_path.read_bytes()).decode("utf-8")
+
+        system_msg = ""
+        user_messages = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            else:
+                msg = dict(m)
+                # Inject image into the last user message
+                if msg["role"] == "user" and msg is not m:
+                    user_messages.append(msg)
+                else:
+                    user_messages.append(msg)
+
+        # Replace last user message content with multimodal blocks
+        last_user = user_messages[-1]
+        last_user["content"] = [
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": media_type,
+                    "data": image_data,
+                },
+            },
+            {"type": "text", "text": last_user["content"]},
+        ]
+
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=4096,
+            system=system_msg,
+            messages=user_messages,
+        )
+        return response.content[0].text
+
+
+class OpenAIBackend(LLMBackend):
+    """Generate CadQuery code using OpenAI GPT-4o."""
+
+    def __init__(self, model: str = "gpt-4o", api_key: Optional[str] = None):
+        import openai
+
+        self.client = openai.OpenAI(api_key=api_key or os.environ.get("OPENAI_API_KEY"))
+        self.model = model
+
+    def generate(self, messages: list[dict]) -> str:
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            max_tokens=4096,
+            temperature=0.2,
+        )
+        return response.choices[0].message.content
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        image_path = Path(image_path)
+        media_type = mimetypes.guess_type(str(image_path))[0] or "image/png"
+        image_data = base64.b64encode(image_path.read_bytes()).decode("utf-8")
+        data_url = f"data:{media_type};base64,{image_data}"
+
+        # Copy messages, replace last user message with multimodal content
+        patched = [dict(m) for m in messages]
+        last_user = patched[-1]
+        last_user["content"] = [
+            {"type": "image_url", "image_url": {"url": data_url}},
+            {"type": "text", "text": last_user["content"]},
+        ]
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=patched,
+            max_tokens=4096,
+            temperature=0.2,
+        )
+        return response.choices[0].message.content
+
+
+class GeminiBackend(LLMBackend):
+    """Generate CadQuery code using Google Gemini (free tier available)."""
+
+    def __init__(self, model: str = "gemini-2.5-flash", api_key: Optional[str] = None):
+        from google import genai
+
+        self.client = genai.Client(api_key=api_key or os.environ.get("GEMINI_API_KEY"))
+        self.model = model
+
+    def generate(self, messages: list[dict]) -> str:
+        # Convert messages to Gemini format: system instruction + contents
+        system_msg = ""
+        contents = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            elif m["role"] == "user":
+                contents.append({"role": "user", "parts": [{"text": m["content"]}]})
+            elif m["role"] == "assistant":
+                contents.append({"role": "model", "parts": [{"text": m["content"]}]})
+
+        from google.genai import types
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=contents,
+            config=types.GenerateContentConfig(
+                system_instruction=system_msg,
+                max_output_tokens=4096,
+                temperature=0.2,
+            ),
+        )
+        return response.text
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        from google.genai import types
+
+        image_path = Path(image_path)
+        image_data = image_path.read_bytes()
+        media_type = mimetypes.guess_type(str(image_path))[0] or "image/png"
+
+        system_msg = ""
+        contents = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            elif m["role"] == "user":
+                contents.append({"role": "user", "parts": [{"text": m["content"]}]})
+            elif m["role"] == "assistant":
+                contents.append({"role": "model", "parts": [{"text": m["content"]}]})
+
+        # Add image to the last user message
+        if contents and contents[-1]["role"] == "user":
+            contents[-1]["parts"].insert(0, {
+                "inline_data": {"mime_type": media_type, "data": image_data}
+            })
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=contents,
+            config=types.GenerateContentConfig(
+                system_instruction=system_msg,
+                max_output_tokens=4096,
+                temperature=0.2,
+            ),
+        )
+        return response.text
+
+
+class MockBackend(LLMBackend):
+    """
+    Mock backend that dynamically generates CadQuery code from any prompt.
+    Parses dimensions, shape type, and features from the text, then assembles
+    parametric code. No API key required.
+    """
+
+    # Word-to-number mapping for natural language counts
+    _WORD_NUMS = {
+        "one": 1,
+        "two": 2,
+        "three": 3,
+        "four": 4,
+        "five": 5,
+        "six": 6,
+        "seven": 7,
+        "eight": 8,
+        "nine": 9,
+        "ten": 10,
+        "twelve": 12,
+        "sixteen": 16,
+        "twenty": 20,
+    }
+
+    # Metric thread clearance hole diameters
+    _THREAD_CLEARANCE = {
+        "m2": 2.4,
+        "m3": 3.4,
+        "m4": 4.5,
+        "m5": 5.5,
+        "m6": 6.6,
+        "m8": 9.0,
+        "m10": 11.0,
+        "m12": 13.5,
+    }
+
+    # Shape detection patterns → base shape key
+    _SHAPE_PATTERNS = {
+        "cylinder": [
+            "cylinder",
+            "rod",
+            "shaft",
+            "axle",
+            "spacer",
+            "washer",
+            "bushing",
+            "sleeve",
+            "tube",
+            "pipe",
+            "dowel",
+            "pin",
+        ],
+        "plate": [
+            "plate",
+            "bracket",
+            "mount",
+            "flange",
+            "baseplate",
+            "panel",
+            "shim",
+            "cover",
+            "lid",
+        ],
+        "box": [
+            "box",
+            "block",
+            "enclosure",
+            "housing",
+            "case",
+            "cube",
+            "container",
+            "shell",
+        ],
+        "l_bracket": [
+            "l-bracket",
+            "l bracket",
+            "angle bracket",
+            "corner bracket",
+            "l-shaped",
+        ],
+    }
+
+    # Feature detection keywords
+    _FEATURE_KEYWORDS = {
+        "holes": ["hole", "holes", "bolt", "bolts", "screw", "screws", "bore", "bores"],
+        "pocket": ["pocket", "recess", "cavity", "cutout", "mortise"],
+        "slot": ["slot", "slots", "groove", "channel", "keyway"],
+        "fillet": ["fillet", "fillets", "round", "rounded"],
+        "chamfer": ["chamfer", "chamfers", "bevel", "beveled"],
+        "through_hole": ["through hole", "through-hole", "thru hole", "thru-hole"],
+        "counterbore": ["counterbore", "counterbored", "cbore"],
+        "fins": ["fin", "fins", "cooling", "heatsink", "heat sink", "radiator"],
+        "ribs": ["rib", "ribs", "stiffener", "stiffeners", "web"],
+        "boss": ["boss", "bosses", "standoff", "standoffs", "pillar"],
+    }
+
+    def _parse_prompt(self, text: str) -> dict:
+        """Extract dimensions, shape, and features from natural language."""
+        lower = text.lower()
+
+        # Extract all numbers with optional units
+        raw_nums = re.findall(r"(\d+\.?\d*)\s*(?:mm|cm|m\b)?", lower)
+        dimensions = [float(n) for n in raw_nums if 0.1 < float(n) < 2000]
+
+        # Detect metric thread sizes (M3, M6, etc.)
+        thread_match = re.search(r"\bm(\d+)\b", lower)
+        hole_dia = None
+        if thread_match:
+            key = f"m{thread_match.group(1)}"
+            hole_dia = self._THREAD_CLEARANCE.get(
+                key, float(thread_match.group(1)) * 1.1
+            )
+
+        # Detect hole diameter from "Xmm hole"
+        hole_dim_match = re.search(
+            r"(\d+\.?\d*)\s*mm\s*(?:hole|bore|holes|bores)", lower
+        )
+        if hole_dim_match and not hole_dia:
+            hole_dia = float(hole_dim_match.group(1))
+
+        # Detect count (numeric or word)
+        count = None
+        count_match = re.search(
+            r"(\d+)\s*(?:hole|bolt|screw|bore|fin|rib|slot|boss)", lower
+        )
+        if count_match:
+            count = int(count_match.group(1))
+        else:
+            for word, num in self._WORD_NUMS.items():
+                if re.search(rf"\b{word}\b.*(?:hole|bolt|screw|bore|fin|slot)", lower):
+                    count = num
+                    break
+
+        # Detect base shape
+        shape = "box"
+        for shape_key, keywords in self._SHAPE_PATTERNS.items():
+            if any(kw in lower for kw in keywords):
+                shape = shape_key
+                break
+
+        # Detect features
+        features = set()
+        for feat, keywords in self._FEATURE_KEYWORDS.items():
+            if any(kw in lower for kw in keywords):
+                features.add(feat)
+
+        # If holes mentioned but no specific feature, add generic holes
+        if (
+            any(w in lower for w in ["hole", "holes", "bolt", "screw"])
+            and "holes" not in features
+        ):
+            features.add("holes")
+
+        return {
+            "dimensions": dimensions,
+            "shape": shape,
+            "features": features,
+            "hole_dia": hole_dia or 5.5,
+            "count": count or 4,
+            "prompt": text,
+        }
+
+    def _generate_code(self, p: dict) -> str:
+        """Build CadQuery code from parsed parameters."""
+        dims = p["dimensions"]
+        shape = p["shape"]
+        features = p["features"]
+        prompt = p["prompt"]
+
+        lines = ["import cadquery as cq"]
+        if shape == "cylinder" and "fins" in features:
+            lines.append("import math")
+        lines.append(f"")
+        lines.append(f"# Generated from: {prompt}")
+
+        if shape == "cylinder":
+            radius = dims[0] / 2 if dims else 15.0
+            height = dims[1] if len(dims) > 1 else radius * 2
+            lines.append(f"# Cylinder: radius={radius}mm, height={height}mm")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XY')")
+            lines.append(f"    .cylinder({height}, {radius})")
+
+            if "holes" in features or "through_hole" in features:
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .hole({p['hole_dia']})")
+
+            if "chamfer" in features or "fillet" not in features:
+                lines.append(f"    .edges('>Z or <Z').chamfer(0.5)")
+
+            if "fillet" in features:
+                lines.append(f"    .edges('>Z or <Z').fillet(1.0)")
+
+            lines.append(f")")
+
+            if "fins" in features:
+                n_fins = p["count"] if p["count"] > 4 else 8
+                fin_h = max(height * 0.8, 5)
+                fin_w = 1.5
+                lines.append(f"")
+                lines.append(f"# Add {n_fins} cooling fins")
+                lines.append(f"for i in range({n_fins}):")
+                lines.append(f"    angle = i * 360 / {n_fins}")
+                lines.append(f"    rad = math.radians(angle)")
+                lines.append(f"    fx = {radius + 3} * math.cos(rad)")
+                lines.append(f"    fy = {radius + 3} * math.sin(rad)")
+                lines.append(f"    fin = (")
+                lines.append(f"        cq.Workplane('XY')")
+                lines.append(
+                    f"        .transformed(offset=(fx, fy, 0), rotate=(0, 0, angle))"
+                )
+                lines.append(f"        .rect({fin_w}, {radius * 0.6})")
+                lines.append(f"        .extrude({fin_h})")
+                lines.append(f"    )")
+                lines.append(f"    result = result.union(fin)")
+
+        elif shape == "plate":
+            w = dims[0] if dims else 80.0
+            h = dims[1] if len(dims) > 1 else w * 0.6
+            t = dims[2] if len(dims) > 2 else 5.0
+            lines.append(f"# Plate: {w}x{h}x{t}mm")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XY')")
+            lines.append(f"    .box({w}, {h}, {t})")
+
+            if "holes" in features or "through_hole" in features:
+                n = p["count"]
+                dia = p["hole_dia"]
+                # Distribute holes in a grid or circle
+                if "flange" in p["prompt"].lower() or n >= 6:
+                    # Bolt circle pattern
+                    r = min(w, h) * 0.35
+                    lines.append(f"    .faces('>Z').workplane()")
+                    lines.append(f"    .polarArray({r}, 0, 360, {n})")
+                    lines.append(f"    .hole({dia})")
+                    if "bore" in p["prompt"].lower() or "flange" in p["prompt"].lower():
+                        lines.append(f"    .faces('>Z').workplane()")
+                        lines.append(f"    .hole({dia * 3})  # Center bore")
+                else:
+                    # Rectangular pattern
+                    ox = w * 0.35
+                    oy = h * 0.35
+                    pts = []
+                    if n == 1:
+                        pts = [(0, 0)]
+                    elif n == 2:
+                        pts = [(-ox, 0), (ox, 0)]
+                    elif n == 4:
+                        pts = [(-ox, -oy), (-ox, oy), (ox, -oy), (ox, oy)]
+                    else:
+                        pts = [(-ox, -oy), (-ox, oy), (ox, -oy), (ox, oy)]
+                    lines.append(f"    .faces('>Z').workplane()")
+                    lines.append(f"    .pushPoints({pts})")
+                    lines.append(f"    .hole({dia})")
+
+            if "pocket" in features:
+                pw = w * 0.4
+                ph = h * 0.35
+                pd = t * 0.6
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .rect({pw}, {ph})")
+                lines.append(f"    .cutBlind(-{pd})  # Central pocket")
+
+            if "slot" in features:
+                sl = w * 0.35
+                sw = max(t * 0.8, 4)
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .slot2D({sl}, {sw}).cutBlind(-{t})")
+
+            if "fillet" in features:
+                lines.append(f"    .edges('|Z').fillet({max(t * 0.4, 1.5)})")
+            else:
+                lines.append(f"    .edges('>Z').chamfer(0.5)")
+
+            lines.append(f")")
+
+        elif shape == "l_bracket":
+            arm = dims[0] if dims else 50.0
+            width = dims[1] if len(dims) > 1 else 20.0
+            t = dims[2] if len(dims) > 2 else 4.0
+            lines.append(f"# L-bracket: {arm}mm arms, {width}mm wide, {t}mm thick")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XZ')")
+            lines.append(f"    .moveTo(0, 0)")
+            lines.append(f"    .lineTo({arm}, 0)")
+            lines.append(f"    .lineTo({arm}, {t})")
+            lines.append(f"    .lineTo({t}, {t})")
+            lines.append(f"    .lineTo({t}, {arm})")
+            lines.append(f"    .lineTo(0, {arm})")
+            lines.append(f"    .close()")
+            lines.append(f"    .extrude({width})")
+            lines.append(f"    .edges('|Y').fillet({max(t * 0.5, 1.5)})")
+
+            if "holes" in features:
+                lines.append(
+                    f"    .faces('>Z').workplane(centerOption='CenterOfBoundBox')"
+                )
+                lines.append(f"    .center({arm * 0.5}, 0)")
+                lines.append(f"    .hole({p['hole_dia']})")
+                lines.append(
+                    f"    .faces('>X').workplane(centerOption='CenterOfBoundBox')"
+                )
+                lines.append(f"    .center(0, {arm * 0.5})")
+                lines.append(f"    .hole({p['hole_dia']})")
+
+            lines.append(f"    .edges().chamfer(0.5)")
+            lines.append(f")")
+
+        else:  # box / enclosure / housing
+            w = dims[0] if dims else 60.0
+            h = dims[1] if len(dims) > 1 else w * 0.65
+            d = dims[2] if len(dims) > 2 else 20.0
+            lines.append(f"# Box: {w}x{h}x{d}mm")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XY')")
+            lines.append(f"    .box({w}, {h}, {d})")
+
+            if "holes" in features or "through_hole" in features:
+                ox = w * 0.35
+                oy = h * 0.35
+                pts = [(-ox, -oy), (-ox, oy), (ox, -oy), (ox, oy)]
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .pushPoints({pts})")
+                lines.append(f"    .hole({p['hole_dia']})")
+
+            if "pocket" in features:
+                pw = w * 0.5
+                ph = h * 0.4
+                pd = d * 0.4
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .rect({pw}, {ph})")
+                lines.append(f"    .cutBlind(-{pd})")
+
+            if "slot" in features:
+                sl = w * 0.4
+                sw = 6
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .slot2D({sl}, {sw}).cutBlind(-{d})")
+
+            if "boss" in features:
+                n = min(p["count"], 4)
+                bx = w * 0.3
+                by = h * 0.3
+                boss_pts = [(-bx, -by), (-bx, by), (bx, -by), (bx, by)][:n]
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .pushPoints({boss_pts})")
+                lines.append(f"    .circle(4).extrude(6)  # Mounting bosses")
+
+            if "ribs" in features:
+                n_ribs = p["count"] if p["count"] <= 8 else 4
+                spacing = w / (n_ribs + 1)
+                lines.append(f"    .faces('>Z').workplane()")
+                for i in range(n_ribs):
+                    rx = -w / 2 + spacing * (i + 1)
+                    lines.append(f"    .center({rx if i == 0 else spacing}, 0)")
+                    lines.append(f"    .rect(2, {h * 0.8}).extrude({d * 0.3})")
+
+            if "fillet" in features:
+                lines.append(f"    .edges('|Z').fillet({min(d * 0.2, 3)})")
+            elif "chamfer" in features:
+                lines.append(f"    .edges('>Z').chamfer(1.0)")
+            else:
+                lines.append(f"    .edges('>Z').chamfer(0.5)")
+
+            lines.append(f")")
+
+        return "\n".join(lines) + "\n"
+
+    # Curated hero responses for specific prompts
+    _CURATED = {
+        "gear": """\
+import cadquery as cq
+import math
+
+# Simple spur gear approximation: 20 teeth, module 2, 10mm thick
+module = 2
+teeth = 20
+pitch_radius = module * teeth / 2
+outer_radius = pitch_radius + module
+tooth_angle = 360 / teeth
+
+result = (
+    cq.Workplane("XY")
+    .cylinder(10, outer_radius)
+    .faces(">Z").workplane()
+    .hole(12)
+)
+
+for i in range(teeth):
+    angle = i * tooth_angle
+    rad = math.radians(angle)
+    gap_x = pitch_radius * math.cos(rad)
+    gap_y = pitch_radius * math.sin(rad)
+    cutter = (
+        cq.Workplane("XY")
+        .transformed(offset=(gap_x, gap_y, 0), rotate=(0, 0, angle))
+        .rect(module * 0.8, module * 2.5)
+        .extrude(12)
+    )
+    result = result.cut(cutter)
+
+result = result.edges(">Z or <Z").chamfer(0.3)
+""",
+    }
+
+    def generate(self, messages: list[dict]) -> str:
+        user_msg = messages[-1]["content"]
+        lower = user_msg.lower()
+
+        # Check curated responses first
+        for key, code in self._CURATED.items():
+            if key in lower:
+                return code
+
+        # Dynamic generation for everything else
+        params = self._parse_prompt(user_msg)
+        return self._generate_code(params)
+
+
+class NeuralCADBackend(LLMBackend):
+    """
+    Neural CAD pipeline backend.
+
+    Runs trained models locally:
+      Text/Image → CLIP encoder → contrastive latent
+        → Diffusion prior → latent
+        → Transformer decoder → CAD command sequence
+        → OpenCascade kernel → B-rep solid
+
+    Unlike LLM backends, this does not generate CadQuery code strings.
+    Instead it produces CAD command sequences decoded directly into geometry.
+    """
+
+    def __init__(
+        self,
+        model_dir: str | Path = "./models",
+        device: str = "cuda",
+        clip_model: str = "clip_encoder.pt",
+        prior_model: str = "diffusion_prior.pt",
+        decoder_model: str = "transformer_decoder.pt",
+    ):
+        self.model_dir = Path(model_dir)
+        self.device = device
+        self.clip_encoder = None
+        self.diffusion_prior = None
+        self.transformer_decoder = None
+        self._model_config = {
+            "clip": clip_model,
+            "prior": prior_model,
+            "decoder": decoder_model,
+        }
+
+    def load_models(self):
+        """Load all model weights from disk. Call once before inference."""
+        raise NotImplementedError(
+            f"Model loading not yet implemented. "
+            f"Expected model files in: {self.model_dir}"
+        )
+
+    def encode_text(self, text: str):
+        """Encode text prompt to CLIP latent vector."""
+        raise NotImplementedError("CLIP text encoder not yet implemented")
+
+    def encode_image(self, image_path: str | Path):
+        """Encode image (photo/sketch) to CLIP latent vector."""
+        raise NotImplementedError("CLIP image encoder not yet implemented")
+
+    def run_diffusion_prior(self, clip_embedding):
+        """Map CLIP embedding to CAD latent via diffusion prior."""
+        raise NotImplementedError("Diffusion prior not yet implemented")
+
+    def decode_to_cad_sequence(self, latent):
+        """Decode latent to CAD command sequence."""
+        raise NotImplementedError("Transformer decoder not yet implemented")
+
+    def cad_sequence_to_solid(self, cad_commands: list[dict]):
+        """Execute CAD command sequence through OpenCascade kernel → B-rep solid."""
+        raise NotImplementedError("CAD kernel execution not yet implemented")
+
+    def generate(self, messages: list[dict]) -> str:
+        """
+        LLMBackend-compatible interface.
+
+        Extracts the text prompt from messages, runs the full neural pipeline,
+        and returns CadQuery-equivalent code as a string for compatibility
+        with the existing execution/validation/export pipeline.
+        """
+        user_msg = messages[-1]["content"]
+
+        clip_emb = self.encode_text(user_msg)
+        latent = self.run_diffusion_prior(clip_emb)
+        cad_commands = self.decode_to_cad_sequence(latent)
+        return self._cad_commands_to_code(cad_commands)
+
+    def generate_from_image(self, image_path: str | Path, text_hint: str = "") -> str:
+        """
+        Image-conditioned generation (not available on LLM backends).
+
+        Args:
+            image_path: Path to photo or sketch of the desired part.
+            text_hint: Optional text to guide generation alongside the image.
+
+        Returns:
+            CadQuery code string for pipeline compatibility.
+        """
+        img_emb = self.encode_image(image_path)
+        if text_hint:
+            txt_emb = self.encode_text(text_hint)
+            # Fuse text + image embeddings (strategy TBD — average, concat, cross-attn)
+            clip_emb = (img_emb + txt_emb) / 2  # placeholder fusion
+        else:
+            clip_emb = img_emb
+
+        latent = self.run_diffusion_prior(clip_emb)
+        cad_commands = self.decode_to_cad_sequence(latent)
+        return self._cad_commands_to_code(cad_commands)
+
+    def _cad_commands_to_code(self, cad_commands: list[dict]) -> str:
+        """Convert internal CAD command sequence to CadQuery Python code string."""
+        raise NotImplementedError(
+            "CAD command → CadQuery code serializer not yet implemented"
+        )

core/cadquery_prompts.py

@@ -0,0 +1,151 @@
+"""
+System prompt and few-shot examples for the CadQuery code generation LLM.
+This module defines the domain knowledge the LLM needs to produce valid,
+CNC-machinable CadQuery scripts.
+"""
+
+CADQUERY_SYSTEM_PROMPT = """\
+You are an expert CNC machinist and CAD engineer. Your job is to generate
+CadQuery Python code that creates a 3D solid model from a natural-language
+description of a mechanical part.
+
+## Rules
+1. Output ONLY valid Python code. No markdown fences, no explanations.
+2. Always `import cadquery as cq` at the top.
+3. The final result MUST be assigned to a variable called `result` and must be
+   a `cq.Workplane` object (not a raw Shape).
+4. Design for CNC machinability:
+   - Prefer prismatic geometry (boxes, cylinders, slots, pockets, holes).
+   - Add fillets >= 1mm on internal corners (tool radius constraint).
+   - Avoid undercuts that a 3-axis mill cannot reach.
+   - Avoid infinitely thin walls — minimum 1.5mm wall thickness.
+   - Chamfer sharp external edges (0.5mm default) for deburring.
+5. Use millimeters as the unit system.
+6. Keep the code concise but readable. Add a brief comment header describing
+   the part.
+7. If the description is ambiguous, make reasonable engineering assumptions
+   and note them in comments.
+8. Center the part on the origin when practical.
+
+## CadQuery Quick Reference
+- `cq.Workplane("XY")` — start a workplane
+- `.box(length, width, height)` — centered box
+- `.cylinder(height, radius)` — centered cylinder
+- `.hole(diameter)` — through hole
+- `.cboreHole(diameter, cboreDiameter, cboreDepth)` — counterbore hole
+- `.cskHole(diameter, cskDiameter, cskAngle)` — countersink hole
+- `.slot2D(length, width)` — 2D slot profile, then extrude
+- `.rect(x, y)` / `.circle(radius)` — 2D sketch primitives
+- `.extrude(distance)` — extrude sketch into solid
+- `.cut(other_solid)` — boolean subtract
+- `.union(other_solid)` — boolean add
+- `.fillet(radius)` — fillet edges
+- `.chamfer(distance)` — chamfer edges
+- `.faces(">Z")` / `.faces("<Z")` — select top/bottom faces
+- `.edges("|Z")` — select edges parallel to Z
+- `.pushPoints([(x,y), ...])` — array of features
+- `.polarArray(radius, startAngle, angle, count)` — circular pattern
+- `.workplane(offset=d)` — offset workplane
+- `.transformed(offset=(x,y,z), rotate=(rx,ry,rz))` — transformed workplane
+
+## Output Format
+Return ONLY the Python code. Nothing else.
+"""
+
+FEW_SHOT_EXAMPLES = [
+    {
+        "prompt": "A simple mounting bracket with two M5 bolt holes, 60mm wide, 40mm tall, 5mm thick",
+        "code": """\
+import cadquery as cq
+
+# Mounting bracket: 60x40x5mm plate with two M5 (5.5mm clearance) holes
+# Holes spaced 40mm apart, centered horizontally, 15mm from top
+
+result = (
+    cq.Workplane("XY")
+    .box(60, 40, 5)  # Main plate
+    .faces(">Z")
+    .workplane()
+    .pushPoints([(-20, 5), (20, 5)])  # Two hole positions
+    .hole(5.5)  # M5 clearance holes
+    .edges("|Z")
+    .fillet(2)  # Fillet vertical edges for machinability
+    .edges(">Z")
+    .chamfer(0.5)  # Chamfer top edges
+)
+"""
+    },
+    {
+        "prompt": "A cylindrical spacer, 25mm outer diameter, 10mm inner hole, 15mm tall",
+        "code": """\
+import cadquery as cq
+
+# Cylindrical spacer: OD=25mm, ID=10mm, height=15mm
+# Chamfered top and bottom edges for deburring
+
+result = (
+    cq.Workplane("XY")
+    .cylinder(15, 25 / 2)  # OD=25mm cylinder, height=15mm
+    .faces(">Z")
+    .workplane()
+    .hole(10)  # 10mm through hole
+    .edges()
+    .chamfer(0.5)  # Chamfer all edges
+)
+"""
+    },
+    {
+        "prompt": "An L-shaped bracket, 50mm on each arm, 20mm wide, 4mm thick, with a 6mm hole in each arm",
+        "code": """\
+import cadquery as cq
+
+# L-shaped bracket: two arms 50mm each, 20mm wide, 4mm thick
+# One 6mm hole centered in each arm
+# Internal corner filleted for CNC tool access
+
+# Build as a 2D profile extruded to width
+result = (
+    cq.Workplane("XZ")
+    .moveTo(0, 0)
+    .lineTo(50, 0)     # Horizontal arm
+    .lineTo(50, 4)
+    .lineTo(4, 4)
+    .lineTo(4, 50)     # Vertical arm
+    .lineTo(0, 50)
+    .close()
+    .extrude(20)        # Extrude to 20mm width
+
+    # Internal fillet for CNC machinability (min tool radius)
+    .edges("|Y").fillet(3)
+
+    # Hole in horizontal arm
+    .faces(">Z")
+    .workplane(centerOption="CenterOfBoundBox")
+    .center(25, 0)
+    .hole(6)
+
+    # Hole in vertical arm
+    .faces(">X")
+    .workplane(centerOption="CenterOfBoundBox")
+    .center(0, 25)
+    .hole(6)
+
+    # Chamfer external edges
+    .edges().chamfer(0.5)
+)
+"""
+    },
+]
+
+
+def build_messages(user_prompt: str) -> list[dict]:
+    """Build the message list for the LLM API call, including system prompt
+    and few-shot examples."""
+    messages = [{"role": "system", "content": CADQUERY_SYSTEM_PROMPT}]
+
+    for ex in FEW_SHOT_EXAMPLES:
+        messages.append({"role": "user", "content": ex["prompt"]})
+        messages.append({"role": "assistant", "content": ex["code"]})
+
+    messages.append({"role": "user", "content": user_prompt})
+    return messages

core/executor.py

@@ -0,0 +1,189 @@
+"""
+Safe CadQuery code execution engine.
+Executes LLM-generated CadQuery code in a sandboxed namespace,
+validates the result, and exports to STEP/STL.
+"""
+
+import io
+import sys
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import cadquery as cq
+
+
+@dataclass
+class ExecutionResult:
+    """Result of executing a CadQuery script."""
+    success: bool
+    result: Optional[cq.Workplane] = None
+    code: str = ""
+    error: Optional[str] = None
+    stdout: str = ""
+    volume: float = 0.0
+    bounding_box: tuple = ()
+    face_count: int = 0
+    edge_count: int = 0
+
+    def summary(self) -> str:
+        if not self.success:
+            return f"FAILED: {self.error}"
+        bb = self.bounding_box
+        return (
+            f"OK | Volume: {self.volume:.1f} mm³ | "
+            f"BBox: {bb[0]:.1f}×{bb[1]:.1f}×{bb[2]:.1f} mm | "
+            f"Faces: {self.face_count} | Edges: {self.edge_count}"
+        )
+
+
+# Allowed imports in the sandboxed namespace
+SAFE_NAMESPACE = {
+    "cq": cq,
+    "cadquery": cq,
+    "math": __import__("math"),
+    "__builtins__": {
+        "range": range,
+        "len": len,
+        "abs": abs,
+        "min": min,
+        "max": max,
+        "round": round,
+        "int": int,
+        "float": float,
+        "tuple": tuple,
+        "list": list,
+        "True": True,
+        "False": False,
+        "None": None,
+        "print": print,
+        "enumerate": enumerate,
+        "zip": zip,
+        "__import__": __import__,
+    },
+}
+
+
+def sanitize_code(code: str) -> str:
+    """Clean up LLM output — strip markdown fences, trailing whitespace,
+    and redundant import statements (already in namespace)."""
+    code = code.strip()
+
+    # Remove markdown code fences if present
+    if code.startswith("```python"):
+        code = code[len("```python"):]
+    elif code.startswith("```"):
+        code = code[3:]
+    if code.endswith("```"):
+        code = code[:-3]
+
+    # Strip import lines for modules already in namespace
+    lines = code.strip().splitlines()
+    cleaned = []
+    for line in lines:
+        stripped = line.strip()
+        # Keep the line unless it's a redundant cadquery/math import
+        if stripped.startswith("import cadquery") or stripped.startswith("from cadquery"):
+            continue
+        if stripped == "import math":
+            continue
+        cleaned.append(line)
+
+    return "\n".join(cleaned).strip()
+
+
+def execute_cadquery(code: str) -> ExecutionResult:
+    """
+    Execute a CadQuery script string and return the result.
+    The script must assign its output to a variable called `result`.
+    """
+    code = sanitize_code(code)
+
+    # Capture stdout
+    old_stdout = sys.stdout
+    sys.stdout = captured = io.StringIO()
+
+    namespace = dict(SAFE_NAMESPACE)
+
+    try:
+        exec(code, namespace)  # noqa: S102
+    except Exception:
+        sys.stdout = old_stdout
+        return ExecutionResult(
+            success=False,
+            code=code,
+            error=traceback.format_exc(),
+            stdout=captured.getvalue(),
+        )
+
+    sys.stdout = old_stdout
+    stdout_text = captured.getvalue()
+
+    # Extract the result
+    result_obj = namespace.get("result")
+    if result_obj is None:
+        return ExecutionResult(
+            success=False,
+            code=code,
+            error="Script did not assign a value to `result`.",
+            stdout=stdout_text,
+        )
+
+    if not isinstance(result_obj, cq.Workplane):
+        return ExecutionResult(
+            success=False,
+            code=code,
+            error=f"Expected cq.Workplane, got {type(result_obj).__name__}",
+            stdout=stdout_text,
+        )
+
+    # Extract geometry metadata
+    try:
+        shape = result_obj.val()
+        bb = result_obj.val().BoundingBox()
+        bbox_dims = (bb.xlen, bb.ylen, bb.zlen)
+        volume = shape.Volume()
+        faces = len(result_obj.faces().vals())
+        edges = len(result_obj.edges().vals())
+    except Exception as e:
+        return ExecutionResult(
+            success=False,
+            code=code,
+            error=f"Geometry extraction failed: {e}",
+            stdout=stdout_text,
+        )
+
+    return ExecutionResult(
+        success=True,
+        result=result_obj,
+        code=code,
+        stdout=stdout_text,
+        volume=volume,
+        bounding_box=bbox_dims,
+        face_count=faces,
+        edge_count=edges,
+    )
+
+
+def export_step(result: cq.Workplane, path: str | Path) -> Path:
+    """Export a CadQuery workplane to STEP format."""
+    path = Path(path)
+    cq.exporters.export(result, str(path), exportType="STEP")
+    return path
+
+
+def export_stl(result: cq.Workplane, path: str | Path, tolerance: float = 0.01) -> Path:
+    """Export a CadQuery workplane to STL format."""
+    path = Path(path)
+    cq.exporters.export(result, str(path), exportType="STL", tolerance=tolerance)
+    return path
+
+
+def export_all(result: cq.Workplane, base_path: str | Path) -> dict[str, Path]:
+    """Export to both STEP and STL."""
+    base = Path(base_path)
+    return {
+        "step": export_step(result, base.with_suffix(".step")),
+        "stl": export_stl(result, base.with_suffix(".stl")),
+    }

core/pipeline.py

@@ -0,0 +1,192 @@
+"""
+Text-to-CNC Pipeline — Main orchestrator.
+
+Pipeline stages:
+  1. Text prompt → LLM → CadQuery code
+  2. CadQuery code → Execute → 3D Solid
+  3. 3D Solid → CNC Validation
+  4. 3D Solid → STEP / STL export
+  5. (Optional) Auto-retry with error feedback if execution fails
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from core.cadquery_prompts import build_messages
+from core.executor import ExecutionResult, execute_cadquery, export_all
+from core.validator import validate_for_cnc, CNCValidationResult
+from core.backends import (
+    LLMBackend, MockBackend, AnthropicBackend, OpenAIBackend,
+    GeminiBackend, NeuralCADBackend
+)
+
+
+# ── Pipeline ──────────────────────────────────────────────────────────────
+
+
+@dataclass
+class PipelineResult:
+    prompt: str
+    generated_code: str
+    execution: ExecutionResult
+    validation: Optional[CNCValidationResult] = None
+    exported_files: dict[str, Path] = None
+    retry_count: int = 0
+
+    def summary(self) -> str:
+        lines = [
+            "=" * 60,
+            "TEXT-TO-CNC PIPELINE RESULT",
+            "=" * 60,
+            f"Prompt: {self.prompt}",
+            f"Retries: {self.retry_count}",
+            "",
+            "── Execution ──",
+            self.execution.summary(),
+            "",
+        ]
+        if self.validation:
+            lines += ["── CNC Validation ──", self.validation.summary(), ""]
+        if self.exported_files:
+            lines += ["── Exported Files ──"]
+            for fmt, path in self.exported_files.items():
+                lines.append(f"  {fmt.upper()}: {path}")
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+
+def run_pipeline(
+    prompt: str,
+    backend: Optional[LLMBackend] = None,
+    output_dir: str | Path = "./output",
+    max_retries: int = 2,
+    export: bool = True,
+    validate: bool = True,
+    part_name: Optional[str] = None,
+) -> PipelineResult:
+    """
+    Run the full text-to-CNC pipeline.
+
+    Args:
+        prompt: Natural language description of the part.
+        backend: LLM backend to use. Defaults to MockBackend.
+        output_dir: Directory for exported files.
+        max_retries: Number of retry attempts if code execution fails.
+        export: Whether to export STEP/STL files.
+        validate: Whether to run CNC validation.
+        part_name: Name for the part (used in filenames).
+
+    Returns:
+        PipelineResult with all pipeline outputs.
+    """
+    if backend is None:
+        backend = MockBackend()
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if part_name is None:
+        # Generate a filename-safe name from the prompt
+        part_name = prompt[:40].strip().replace(" ", "_").lower()
+        part_name = "".join(c for c in part_name if c.isalnum() or c == "_")
+
+    # Stage 1: Generate code
+    messages = build_messages(prompt)
+    generated_code = backend.generate(messages)
+
+    # Stage 2: Execute with retry loop
+    execution = execute_cadquery(generated_code)
+    retry_count = 0
+
+    while not execution.success and retry_count < max_retries:
+        retry_count += 1
+        print(f"  Retry {retry_count}/{max_retries}: fixing error...")
+
+        # Feed the error back to the LLM for self-correction
+        error_feedback = (
+            f"The previous code failed with this error:\n"
+            f"```\n{execution.error}\n```\n\n"
+            f"Please fix the code and return only the corrected Python code. "
+            f"Original request: {prompt}"
+        )
+        messages_retry = build_messages(error_feedback)
+        generated_code = backend.generate(messages_retry)
+        execution = execute_cadquery(generated_code)
+
+    # Stage 3: Validate for CNC
+    validation = None
+    if execution.success and validate:
+        validation = validate_for_cnc(execution.result, part_name=part_name)
+
+    # Stage 4: Export
+    exported_files = {}
+    if execution.success and export:
+        base_path = output_dir / part_name
+        try:
+            exported_files = export_all(execution.result, base_path)
+        except Exception as e:
+            print(f"  Export warning: {e}")
+
+    return PipelineResult(
+        prompt=prompt,
+        generated_code=generated_code,
+        execution=execution,
+        validation=validation,
+        exported_files=exported_files or {},
+        retry_count=retry_count,
+    )
+
+
+# ── CLI Entry Point ───────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Text-to-CNC Model Generator")
+    parser.add_argument("prompt", nargs="?", default=None, help="Part description")
+    parser.add_argument(
+        "--backend", choices=["mock", "anthropic", "openai", "gemini", "neural"], default="mock"
+    )
+    parser.add_argument("--output-dir", default="./output")
+    parser.add_argument("--retries", type=int, default=2)
+    parser.add_argument("--name", default=None, help="Part name for file output")
+    parser.add_argument("--no-validate", action="store_true")
+    parser.add_argument("--no-export", action="store_true")
+    args = parser.parse_args()
+
+    if args.prompt is None:
+        args.prompt = "A simple mounting bracket with two M5 bolt holes"
+
+    # Select backend
+    if args.backend == "neural":
+        backend = NeuralCADBackend()
+    elif args.backend == "anthropic":
+        backend = AnthropicBackend()
+    elif args.backend == "openai":
+        backend = OpenAIBackend()
+    elif args.backend == "gemini":
+        backend = GeminiBackend()
+    else:
+        backend = MockBackend()
+
+    print(f"Generating CNC model for: '{args.prompt}'")
+    print(f"Backend: {args.backend}")
+    print()
+
+    result = run_pipeline(
+        prompt=args.prompt,
+        backend=backend,
+        output_dir=args.output_dir,
+        max_retries=args.retries,
+        export=not args.no_export,
+        validate=not args.no_validate,
+        part_name=args.name,
+    )
+
+    print(result.summary())
+
+    if result.execution.success:
+        print("\nGenerated Code:")
+        print("-" * 40)
+        print(result.generated_code)

core/validator.py

@@ -0,0 +1,224 @@
+"""
+CNC Manufacturability Validator.
+Checks a CadQuery solid for common CNC machining issues:
+- Thin walls
+- Sharp internal corners (no fillet / too small for tool)
+- Deep narrow pockets (aspect ratio)
+- Overall size feasibility
+- Undercut detection (basic heuristic)
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import cadquery as cq
+
+
+@dataclass
+class CNCIssue:
+    severity: str  # "error", "warning", "info"
+    category: str
+    message: str
+
+
+@dataclass
+class CNCValidationResult:
+    part_name: str
+    issues: list[CNCIssue] = field(default_factory=list)
+    machinable: bool = True
+    axis_recommendation: str = "3-axis"
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for i in self.issues if i.severity == "error")
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for i in self.issues if i.severity == "warning")
+
+    def summary(self) -> str:
+        status = "PASS" if self.machinable else "FAIL"
+        lines = [
+            f"CNC Validation [{status}] — {self.part_name}",
+            f"  Recommended: {self.axis_recommendation} milling",
+            f"  Errors: {self.error_count} | Warnings: {self.warning_count}",
+        ]
+        for issue in self.issues:
+            icon = {"error": "✗", "warning": "⚠", "info": "ℹ"}[issue.severity]
+            lines.append(f"  {icon} [{issue.category}] {issue.message}")
+        return "\n".join(lines)
+
+
+# --- Configurable thresholds ---
+
+DEFAULT_CONFIG = {
+    "min_wall_thickness_mm": 1.5,
+    "min_fillet_radius_mm": 1.0,  # Typical smallest endmill radius
+    "max_pocket_depth_ratio": 4.0,  # depth / width ratio
+    "max_part_size_mm": 500.0,  # Typical CNC work envelope
+    "min_part_size_mm": 1.0,
+    "min_hole_diameter_mm": 1.0,
+}
+
+
+def validate_for_cnc(
+    workplane: cq.Workplane,
+    part_name: str = "Part",
+    config: Optional[dict] = None,
+) -> CNCValidationResult:
+    """
+    Run manufacturability checks on a CadQuery solid.
+    Returns a CNCValidationResult with issues found.
+    """
+    cfg = {**DEFAULT_CONFIG, **(config or {})}
+    result = CNCValidationResult(part_name=part_name)
+    shape = workplane.val()
+    bb = shape.BoundingBox()
+
+    # --- 1. Bounding box / size checks ---
+    dims = sorted([bb.xlen, bb.ylen, bb.zlen])
+    max_dim = dims[-1]
+    min_dim = dims[0]
+
+    if max_dim > cfg["max_part_size_mm"]:
+        result.issues.append(
+            CNCIssue(
+                "error",
+                "Size",
+                f"Part too large: {max_dim:.1f}mm exceeds {cfg['max_part_size_mm']}mm work envelope",
+            )
+        )
+        result.machinable = False
+
+    if min_dim < cfg["min_part_size_mm"]:
+        result.issues.append(
+            CNCIssue(
+                "warning",
+                "Size",
+                f"Very small dimension: {min_dim:.2f}mm — may be difficult to fixture",
+            )
+        )
+
+    # --- 2. Volume sanity check ---
+    volume = shape.Volume()
+    bb_volume = bb.xlen * bb.ylen * bb.zlen
+    if bb_volume > 0:
+        fill_ratio = volume / bb_volume
+        if fill_ratio < 0.05:
+            result.issues.append(
+                CNCIssue(
+                    "warning",
+                    "Geometry",
+                    f"Very low fill ratio ({fill_ratio:.1%}) — complex geometry, high machining time",
+                )
+            )
+        result.issues.append(
+            CNCIssue(
+                "info",
+                "Geometry",
+                f"Fill ratio: {fill_ratio:.1%} (volume/bounding box)",
+            )
+        )
+
+    # --- 3. Face and edge complexity ---
+    faces = workplane.faces().vals()
+    edges = workplane.edges().vals()
+
+    n_faces = len(faces)
+    n_edges = len(edges)
+
+    if n_faces > 100:
+        result.issues.append(
+            CNCIssue(
+                "warning",
+                "Complexity",
+                f"{n_faces} faces detected — may require multi-setup or 5-axis",
+            )
+        )
+        result.axis_recommendation = "5-axis"
+    elif n_faces > 50:
+        result.issues.append(
+            CNCIssue(
+                "info",
+                "Complexity",
+                f"{n_faces} faces — consider 4-axis or indexed 5-axis",
+            )
+        )
+        result.axis_recommendation = "3+2 axis"
+
+    # --- 4. Edge length analysis (thin feature proxy) ---
+    edge_lengths = []
+    for edge in edges:
+        try:
+            edge_lengths.append(edge.Length())
+        except Exception:
+            pass
+
+    if edge_lengths:
+        min_edge = min(edge_lengths)
+        if min_edge < cfg["min_wall_thickness_mm"]:
+            result.issues.append(
+                CNCIssue(
+                    "warning",
+                    "Thin Feature",
+                    f"Shortest edge: {min_edge:.2f}mm — below min wall thickness "
+                    f"({cfg['min_wall_thickness_mm']}mm)",
+                )
+            )
+
+    # --- 5. Aspect ratio check (deep pocket heuristic) ---
+    # Only flag if the narrowest dimension is small enough to be a pocket/slot
+    if dims[0] > 0 and dims[0] < 20:
+        aspect = dims[2] / dims[0]  # tallest / narrowest
+        if aspect > cfg["max_pocket_depth_ratio"]:
+            result.issues.append(
+                CNCIssue(
+                    "warning",
+                    "Deep Feature",
+                    f"Aspect ratio {aspect:.1f}:1 — may require long-reach tooling or "
+                    f"special fixturing",
+                )
+            )
+
+    # --- 6. Surface type analysis ---
+    has_freeform = False
+    planar_count = 0
+    cylindrical_count = 0
+
+    for face in faces:
+        try:
+            geom_type = face.geomType()
+            if geom_type == "PLANE":
+                planar_count += 1
+            elif geom_type == "CYLINDER":
+                cylindrical_count += 1
+            elif geom_type in ("BSPLINE", "BEZIER", "OTHER"):
+                has_freeform = True
+        except Exception:
+            pass
+
+    if has_freeform:
+        result.issues.append(
+            CNCIssue(
+                "warning",
+                "Surface",
+                "Freeform/spline surfaces detected — requires 3D contouring toolpaths",
+            )
+        )
+        if result.axis_recommendation == "3-axis":
+            result.axis_recommendation = "3-axis (with 3D finishing)"
+
+    result.issues.append(
+        CNCIssue(
+            "info",
+            "Surface",
+            f"Faces: {planar_count} planar, {cylindrical_count} cylindrical, "
+            f"{n_faces - planar_count - cylindrical_count} other",
+        )
+    )
+
+    # --- 7. Set final machinable flag ---
+    if result.error_count > 0:
+        result.machinable = False
+
+    return result

docker-compose.yml

@@ -1,7 +1,7 @@
 services:
   mcp-server:
     build: .
-    command: python mcp_server.py --transport sse --port 8000
+    command: python -m server.mcp --transport sse --port 8000
     ports:
       - "8000:8000"
     volumes:
@@ -9,7 +9,7 @@ services:
 
   web:
     build: .
-    command: python web_server.py --host 0.0.0.0 --port 5000
+    command: python -m server.web --host 0.0.0.0 --port 5000
     ports:
       - "5000:5000"
     environment:

entrypoint.sh

@@ -5,7 +5,7 @@ echo "=== NeuralCAD Container Starting ==="
 
 # Start MCP CAD server in background
 echo "Starting MCP CAD server on port 8000..."
-python mcp_server.py --transport sse --port 8000 &
+python -m server.mcp --transport sse --port 8000 &
 MCP_PID=$!
 
 # Wait for MCP server to be ready
@@ -22,4 +22,4 @@ echo "MCP server running (PID $MCP_PID)"
 export MCP_SERVER_URL=http://localhost:8000/sse
 PORT=${PORT:-7860}
 echo "Starting web server on port $PORT..."
-exec python web_server.py --host 0.0.0.0 --port "$PORT"
+exec python -m server.web --host 0.0.0.0 --port "$PORT"

pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "anthropic>=0.25.0",
     "openai>=1.30.0",
     "google-genai>=1.0.0",
+    "crewai>=0.80.0",
     "mcp>=1.0.0",
     "fastapi>=0.110.0",
     "uvicorn>=0.29.0",

server/mcp.py

@@ -0,0 +1,499 @@
+#!/usr/bin/env python3
+"""
+Text-to-CNC MCP Server
+======================
+Exposes the text-to-CNC pipeline as MCP tools over stdio transport.
+
+Tools:
+  - generate_cnc_model: Text prompt → CadQuery code → 3D solid → STEP/STL
+  - validate_cnc_model: Run CNC manufacturability checks on CadQuery code
+  - execute_cadquery:   Run arbitrary CadQuery code and get geometry info
+  - list_models:        List previously generated models in the output dir
+
+Usage:
+  python -m server.mcp                    # stdio transport (default)
+  python -m server.mcp --transport sse    # SSE transport on port 8000
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from core.cadquery_prompts import build_messages, CADQUERY_SYSTEM_PROMPT
+from core.executor import ExecutionResult, execute_cadquery, export_all, sanitize_code
+from core.validator import validate_for_cnc, CNCValidationResult
+
+# ── Server Setup ──────────────────────────────────────────────────────────
+
+mcp = FastMCP(
+    "text-to-cnc",
+    instructions=(
+        "Generate CNC-machinable 3D models from text descriptions. "
+        "Converts natural language → CadQuery code → validated STEP/STL files. "
+        "Version 1.0.0"
+    ),
+)
+
+DEFAULT_OUTPUT_DIR = Path(__file__).parent.parent / "output"
+DEFAULT_OUTPUT_DIR.mkdir(exist_ok=True)
+
+
+# ── Helper: LLM Backend Selection ────────────────────────────────────────
+
+def get_backend(backend_name: str = "mock"):
+    """Get the appropriate LLM backend."""
+    from core.backends import MockBackend, AnthropicBackend, OpenAIBackend, GeminiBackend, NeuralCADBackend
+
+    if backend_name == "neural":
+        return NeuralCADBackend()
+    elif backend_name == "anthropic" and os.environ.get("ANTHROPIC_API_KEY"):
+        return AnthropicBackend()
+    elif backend_name == "openai" and os.environ.get("OPENAI_API_KEY"):
+        return OpenAIBackend()
+    elif backend_name == "gemini" and os.environ.get("GEMINI_API_KEY"):
+        return GeminiBackend()
+    else:
+        return MockBackend()
+
+
+# ── Tool: generate_cnc_model ─────────────────────────────────────────────
+
+@mcp.tool()
+def generate_cnc_model(
+    prompt: str,
+    part_name: str = "",
+    backend: str = "mock",
+    max_retries: int = 2,
+    output_format: str = "both",
+) -> str:
+    """
+    Generate a CNC-machinable 3D model from a text description.
+
+    Takes a natural language description of a mechanical part, generates
+    CadQuery Python code via an LLM, executes it to produce a 3D solid,
+    validates it for CNC manufacturability, and exports STEP/STL files.
+
+    Args:
+        prompt: Natural language description of the part to generate.
+                Example: "A mounting bracket with four M6 bolt holes, 80mm wide"
+        part_name: Optional name for the part (used in filenames).
+                   If empty, auto-generated from the prompt.
+        backend: LLM backend to use: "mock" (no API key), "anthropic", or "openai".
+        max_retries: Number of retry attempts if code generation fails (0-3).
+        output_format: Export format: "step", "stl", or "both".
+
+    Returns:
+        JSON string with generation results including:
+        - generated_code: The CadQuery Python code
+        - execution: Success/failure status and geometry metadata
+        - validation: CNC manufacturability analysis
+        - exported_files: Paths to generated STEP/STL files
+    """
+    from core.pipeline import run_pipeline
+
+    if not part_name:
+        part_name = prompt[:40].strip().replace(" ", "_").lower()
+        part_name = "".join(c for c in part_name if c.isalnum() or c == "_")
+
+    llm_backend = get_backend(backend)
+
+    result = run_pipeline(
+        prompt=prompt,
+        backend=llm_backend,
+        output_dir=DEFAULT_OUTPUT_DIR,
+        max_retries=min(max_retries, 3),
+        export=True,
+        validate=True,
+        part_name=part_name,
+    )
+
+    # Build response
+    response = {
+        "success": result.execution.success,
+        "prompt": prompt,
+        "part_name": part_name,
+        "retries": result.retry_count,
+        "generated_code": result.generated_code,
+        "execution": {
+            "success": result.execution.success,
+            "volume_mm3": result.execution.volume,
+            "bounding_box_mm": list(result.execution.bounding_box) if result.execution.bounding_box else [],
+            "face_count": result.execution.face_count,
+            "edge_count": result.execution.edge_count,
+            "error": result.execution.error,
+        },
+    }
+
+    if result.validation:
+        response["validation"] = {
+            "machinable": result.validation.machinable,
+            "axis_recommendation": result.validation.axis_recommendation,
+            "error_count": result.validation.error_count,
+            "warning_count": result.validation.warning_count,
+            "issues": [
+                {"severity": i.severity, "category": i.category, "message": i.message}
+                for i in result.validation.issues
+            ],
+        }
+
+    if result.exported_files:
+        response["exported_files"] = {
+            fmt: str(path) for fmt, path in result.exported_files.items()
+        }
+
+    return json.dumps(response, indent=2)
+
+
+# ── Tool: validate_cnc_model ─────────────────────────────────────────────
+
+@mcp.tool()
+def validate_cnc_model(
+    cadquery_code: str,
+    part_name: str = "Part",
+    min_wall_thickness_mm: float = 1.5,
+    max_part_size_mm: float = 500.0,
+) -> str:
+    """
+    Validate CadQuery code for CNC manufacturability without generating new code.
+
+    Executes the provided CadQuery code, then runs manufacturability checks
+    including wall thickness, tool access, aspect ratios, and surface complexity.
+
+    Args:
+        cadquery_code: Valid CadQuery Python code that assigns result to `result`.
+                       Example: 'import cadquery as cq\\nresult = cq.Workplane("XY").box(10,10,10)'
+        part_name: Name for the part in the validation report.
+        min_wall_thickness_mm: Minimum acceptable wall thickness in mm (default 1.5).
+        max_part_size_mm: Maximum part dimension in mm (default 500).
+
+    Returns:
+        JSON string with execution status and CNC validation results including
+        machinable flag, axis recommendation, and list of issues.
+    """
+    exec_result = execute_cadquery(cadquery_code)
+
+    response = {
+        "execution_success": exec_result.success,
+        "error": exec_result.error,
+        "volume_mm3": exec_result.volume,
+        "bounding_box_mm": list(exec_result.bounding_box) if exec_result.bounding_box else [],
+    }
+
+    if exec_result.success:
+        config = {
+            "min_wall_thickness_mm": min_wall_thickness_mm,
+            "max_part_size_mm": max_part_size_mm,
+        }
+        validation = validate_for_cnc(exec_result.result, part_name=part_name, config=config)
+        response["validation"] = {
+            "machinable": validation.machinable,
+            "axis_recommendation": validation.axis_recommendation,
+            "error_count": validation.error_count,
+            "warning_count": validation.warning_count,
+            "issues": [
+                {"severity": i.severity, "category": i.category, "message": i.message}
+                for i in validation.issues
+            ],
+            "summary": validation.summary(),
+        }
+
+    return json.dumps(response, indent=2)
+
+
+# ── Tool: execute_cadquery ───────────────────────────────────────────────
+
+@mcp.tool()
+def execute_cadquery_code(
+    code: str,
+    export_path: str = "",
+) -> str:
+    """
+    Execute CadQuery Python code and return geometry information.
+
+    Runs CadQuery code in a sandboxed environment and returns metadata
+    about the resulting 3D solid (volume, bounding box, face/edge counts).
+    Optionally exports to STEP/STL.
+
+    Args:
+        code: CadQuery Python code. Must assign the final solid to a variable
+              called `result`. Example:
+              'import cadquery as cq\\nresult = cq.Workplane("XY").box(20,20,20).hole(8)'
+        export_path: Optional base file path for STEP/STL export (without extension).
+                     Example: "output/my_part" → creates my_part.step and my_part.stl
+
+    Returns:
+        JSON string with execution results including success status,
+        geometry metadata, stdout output, and export file paths if requested.
+    """
+    exec_result = execute_cadquery(code)
+
+    response = {
+        "success": exec_result.success,
+        "error": exec_result.error,
+        "stdout": exec_result.stdout,
+        "volume_mm3": exec_result.volume,
+        "bounding_box_mm": list(exec_result.bounding_box) if exec_result.bounding_box else [],
+        "face_count": exec_result.face_count,
+        "edge_count": exec_result.edge_count,
+    }
+
+    if exec_result.success and export_path:
+        try:
+            files = export_all(exec_result.result, export_path)
+            response["exported_files"] = {fmt: str(p) for fmt, p in files.items()}
+        except Exception as e:
+            response["export_error"] = str(e)
+
+    return json.dumps(response, indent=2)
+
+
+# ── Tool: list_models ────────────────────────────────────────────────────
+
+@mcp.tool()
+def list_models(output_dir: str = "") -> str:
+    """
+    List all previously generated CNC models in the output directory.
+
+    Returns a list of generated STEP and STL files with their sizes.
+
+    Args:
+        output_dir: Directory to scan. Defaults to the server's output directory.
+
+    Returns:
+        JSON string with a list of model files and their sizes in bytes.
+    """
+    scan_dir = Path(output_dir) if output_dir else DEFAULT_OUTPUT_DIR
+
+    if not scan_dir.exists():
+        return json.dumps({"error": f"Directory not found: {scan_dir}"})
+
+    models = {}
+    for ext in ("*.step", "*.stl"):
+        for f in scan_dir.glob(ext):
+            name = f.stem
+            if name not in models:
+                models[name] = {"name": name, "files": {}}
+            models[name]["files"][f.suffix.lstrip(".")] = {
+                "path": str(f),
+                "size_bytes": f.stat().st_size,
+            }
+
+    return json.dumps({
+        "output_dir": str(scan_dir),
+        "model_count": len(models),
+        "models": list(models.values()),
+    }, indent=2)
+
+
+# ── Tool: generate_from_image ───────────────────────────────────────────
+
+@mcp.tool()
+def generate_from_image(
+    image_path: str,
+    text_hint: str = "",
+    part_name: str = "",
+    backend: str = "anthropic",
+    max_retries: int = 2,
+) -> str:
+    """
+    Generate a CNC-machinable 3D model from a photo or sketch image.
+
+    Sends the image to a vision-capable LLM (Claude or GPT-4o) along with
+    the CadQuery system prompt to generate code, then executes, validates,
+    and exports the result.
+
+    Args:
+        image_path: Path to an image file (photo, sketch, or CAD screenshot).
+        text_hint: Optional text to guide generation alongside the image.
+                   Example: "This is a mounting bracket — add M6 bolt holes"
+        part_name: Optional name for the part (used in filenames).
+        backend: LLM backend: "anthropic" or "openai". Must support vision.
+        max_retries: Number of retry attempts if code execution fails (0-3).
+
+    Returns:
+        JSON string with generation results including generated code,
+        execution status, validation, and exported file paths.
+    """
+    if not Path(image_path).exists():
+        return json.dumps({"success": False, "error": f"Image not found: {image_path}"})
+
+    if not part_name:
+        part_name = Path(image_path).stem
+
+    llm_backend = get_backend(backend)
+
+    # Build prompt with optional text hint
+    prompt = "Generate CadQuery code for the mechanical part shown in this image."
+    if text_hint:
+        prompt += f"\n\nAdditional context: {text_hint}"
+
+    messages = build_messages(prompt)
+
+    # Use vision-capable generate_with_image
+    generated_code = llm_backend.generate_with_image(messages, image_path)
+
+    # Run through standard execution/validation/export
+    exec_result = execute_cadquery(generated_code)
+    retry_count = 0
+
+    while not exec_result.success and retry_count < min(max_retries, 3):
+        retry_count += 1
+        error_feedback = (
+            f"The previous code failed with this error:\n"
+            f"```\n{exec_result.error}\n```\n\n"
+            f"Please fix the code and return only the corrected Python code."
+        )
+        retry_messages = build_messages(error_feedback)
+        generated_code = llm_backend.generate_with_image(retry_messages, image_path)
+        exec_result = execute_cadquery(generated_code)
+
+    response = {
+        "success": exec_result.success,
+        "image_path": image_path,
+        "text_hint": text_hint,
+        "part_name": part_name,
+        "backend": backend,
+        "retries": retry_count,
+        "generated_code": generated_code,
+        "execution": {
+            "success": exec_result.success,
+            "volume_mm3": exec_result.volume,
+            "bounding_box_mm": list(exec_result.bounding_box) if exec_result.bounding_box else [],
+            "face_count": exec_result.face_count,
+            "edge_count": exec_result.edge_count,
+            "error": exec_result.error,
+        },
+    }
+
+    if exec_result.success:
+        validation = validate_for_cnc(exec_result.result, part_name=part_name)
+        response["validation"] = {
+            "machinable": validation.machinable,
+            "axis_recommendation": validation.axis_recommendation,
+            "error_count": validation.error_count,
+            "warning_count": validation.warning_count,
+            "issues": [
+                {"severity": i.severity, "category": i.category, "message": i.message}
+                for i in validation.issues
+            ],
+        }
+
+        base_path = DEFAULT_OUTPUT_DIR / part_name
+        try:
+            exported = export_all(exec_result.result, base_path)
+            response["exported_files"] = {fmt: str(p) for fmt, p in exported.items()}
+        except Exception as e:
+            response["export_error"] = str(e)
+
+    return json.dumps(response, indent=2)
+
+
+# ── Tool: chat_turn ───────────────────────��─────────────────────────────
+
+@mcp.tool()
+def chat_turn(
+    message: str,
+    history: str = "[]",
+    mentions: str = "[]",
+    backend: str = "mock",
+) -> str:
+    """
+    Multi-agent chat turn for collaborative CAD design.
+
+    Send a message to the design team agents (Design, Engineering, CNC, CAD Coder).
+    Agents collaborate to help you design a mechanical part step by step.
+
+    Args:
+        message: Your message to the design team.
+                 Use @design, @engineering, @cnc, or @cad to address specific agents.
+        history: JSON string of previous messages. Format:
+                 [{"role": "user"|"agent", "agent_id": "design", "content": "..."}]
+        mentions: JSON string of agent IDs to address. Format: ["design", "engineering"]
+                  Empty list = auto-route based on message content.
+        backend: LLM backend: "mock", "gemini", "anthropic", "openai".
+
+    Returns:
+        JSON string with agent responses and optional 3D preview data.
+    """
+    import json as json_mod
+
+    from agents.orchestrator import get_orchestrator
+    from agents.crew_orchestrator import CrewOrchestrator
+    from agents.prompts import parse_mentions
+
+    history_list = json_mod.loads(history) if isinstance(history, str) else history
+    mentions_list = json_mod.loads(mentions) if isinstance(mentions, str) else mentions
+
+    # Parse @mentions from message if not provided
+    if not mentions_list:
+        message, mentions_list = parse_mentions(message)
+
+    mentions_or_none = mentions_list if mentions_list else None
+
+    if backend in ("anthropic", "openai"):
+        orchestrator = CrewOrchestrator(backend_name=backend, output_dir=DEFAULT_OUTPUT_DIR)
+    else:
+        orchestrator = get_orchestrator(backend, output_dir=DEFAULT_OUTPUT_DIR)
+
+    result = orchestrator.chat_turn(
+        message=message,
+        history=history_list,
+        mentions=mentions_or_none,
+    )
+
+    return json_mod.dumps(result, indent=2)
+
+
+# ── Resource: System prompt (for transparency) ───────────────────────────
+
+@mcp.resource("text-to-cnc://system-prompt")
+def get_system_prompt() -> str:
+    """The CadQuery generation system prompt used by the LLM."""
+    return CADQUERY_SYSTEM_PROMPT
+
+
+@mcp.resource("text-to-cnc://capabilities")
+def get_capabilities() -> str:
+    """Server capabilities and configuration."""
+    backends = ["mock (always available)", "neural (local models — requires trained weights)"]
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        backends.append("anthropic (API key detected)")
+    if os.environ.get("OPENAI_API_KEY"):
+        backends.append("openai (API key detected)")
+    if os.environ.get("GEMINI_API_KEY"):
+        backends.append("gemini (API key detected)")
+
+    return json.dumps({
+        "name": "text-to-cnc",
+        "version": "1.0.0",
+        "available_backends": backends,
+        "output_dir": str(DEFAULT_OUTPUT_DIR),
+        "export_formats": ["STEP", "STL"],
+        "cnc_validation": True,
+        "max_retries": 3,
+    }, indent=2)
+
+
+# ── Entry Point ──────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Text-to-CNC MCP Server")
+    parser.add_argument(
+        "--transport", choices=["stdio", "sse"], default="stdio",
+        help="MCP transport (default: stdio)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=8000,
+        help="Port for SSE transport (default: 8000)"
+    )
+    args = parser.parse_args()
+
+    if args.transport == "sse":
+        mcp.run(transport="sse")
+    else:
+        mcp.run(transport="stdio")

server/routes.py

@@ -0,0 +1,152 @@
+"""Chat API routes for multi-agent design conversation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+from agents.orchestrator import get_orchestrator
+from agents.crew_orchestrator import CrewOrchestrator
+from agents.prompts import parse_mentions
+from agents.definitions import AGENTS
+
+router = APIRouter()
+
+OUTPUT_DIR = Path(__file__).parent.parent / "output"
+
+
+@router.post("/api/chat")
+async def chat(body: dict):
+    """Multi-agent chat turn.
+
+    Request body:
+        {
+            "message": "I need a servo bracket 60mm wide",
+            "history": [{"role": "user"|"agent", "agent_id": "...", "content": "..."}, ...],
+            "mentions": ["design", "engineering"],  // or [] for auto-routing
+            "backend": "mock"|"gemini"|"anthropic"|"openai"
+        }
+
+    Response:
+        {
+            "responses": [
+                {"agent_id", "agent_name", "message", "color", "avatar", "code"}, ...
+            ],
+            "preview": null | {"success", "part_name", "stl_url", "step_url", "execution", "validation"}
+        }
+    """
+    message = body.get("message", "").strip()
+    if not message:
+        return JSONResponse({"error": "Empty message"}, status_code=400)
+
+    history = body.get("history", [])
+    backend_name = body.get("backend", "mock")
+
+    # Parse @mentions from message if not provided
+    raw_mentions = body.get("mentions", [])
+    if not raw_mentions:
+        message, raw_mentions = parse_mentions(message)
+
+    mentions = raw_mentions if raw_mentions else None
+
+    # Select orchestrator based on backend
+    if backend_name in ("anthropic", "openai"):
+        orchestrator = CrewOrchestrator(
+            backend_name=backend_name, output_dir=OUTPUT_DIR
+        )
+    else:
+        orchestrator = get_orchestrator(backend_name, output_dir=OUTPUT_DIR)
+
+    # Run chat turn
+    try:
+        result = orchestrator.chat_turn(
+            message=message,
+            history=history,
+            mentions=mentions,
+        )
+        return JSONResponse(result)
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+@router.post("/api/report")
+async def report(body: dict):
+    """Generate a design report from conversation history.
+
+    Request body:
+        {
+            "part_name": "servo_bracket",
+            "history": [...],
+            "backend": "gemini"
+        }
+    """
+    part_name = body.get("part_name", "part")
+    history = body.get("history", [])
+    backend_name = body.get("backend", "mock")
+
+    # Build report from conversation
+    report_sections = []
+    report_sections.append(f"# Design Report: {part_name}\n")
+
+    design_decisions = []
+    engineering_specs = []
+    cnc_notes = []
+
+    for msg in history:
+        agent_id = msg.get("agent_id", "")
+        content = msg.get("content", "")
+        if agent_id == "design":
+            design_decisions.append(content)
+        elif agent_id == "engineering":
+            engineering_specs.append(content)
+        elif agent_id == "cnc":
+            cnc_notes.append(content)
+
+    if design_decisions:
+        report_sections.append("## Design Decisions")
+        for d in design_decisions:
+            report_sections.append(f"- {d}")
+
+    if engineering_specs:
+        report_sections.append("\n## Engineering Specifications")
+        for s in engineering_specs:
+            report_sections.append(f"- {s}")
+
+    if cnc_notes:
+        report_sections.append("\n## Manufacturing Notes")
+        for n in cnc_notes:
+            report_sections.append(f"- {n}")
+
+    # Check if model files exist
+    stl_path = OUTPUT_DIR / f"{part_name}.stl"
+    step_path = OUTPUT_DIR / f"{part_name}.step"
+
+    report_sections.append("\n## Exported Files")
+    report_sections.append(f"- STEP: {'Available' if step_path.exists() else 'Not generated'}")
+    report_sections.append(f"- STL: {'Available' if stl_path.exists() else 'Not generated'}")
+
+    report_text = "\n".join(report_sections)
+
+    return JSONResponse({
+        "part_name": part_name,
+        "report": report_text,
+    })
+
+
+@router.get("/api/agents")
+async def list_agents():
+    """List available agents and their metadata."""
+    return JSONResponse({
+        "agents": [
+            {
+                "id": agent.id,
+                "name": agent.name,
+                "role": agent.role,
+                "color": agent.color,
+                "avatar": agent.avatar,
+            }
+            for agent in AGENTS.values()
+        ]
+    })

server/web.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+NeuralCAD Web Demo Server
+=========================
+FastAPI server that proxies REST requests to the MCP CAD server (SSE transport)
+and serves the web frontend.
+
+Usage:
+    # Start MCP server first:
+    python -m server.mcp --transport sse --port 8000
+
+    # Then start web server:
+    python -m server.web
+
+    # Or auto-launch MCP server:
+    python -m server.web --start-mcp
+
+    # Open http://localhost:5000
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, File, Form, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+
+from server.routes import router
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+# ── Config ───────────────────────────────────────────────────────────────
+
+MCP_SERVER_URL = os.environ.get("MCP_SERVER_URL", "http://localhost:8000/sse")
+OUTPUT_DIR = Path(__file__).parent.parent / "output"
+WEB_DIR = Path(__file__).parent.parent / "web"
+PORT = int(os.environ.get("WEB_PORT", "5000"))
+
+# ── MCP Client Management ───────────────────────────────────────────────
+
+_mcp_process = None
+
+
+async def call_mcp_tool(tool_name: str, arguments: dict) -> dict:
+    """Connect to MCP server, call a tool, return parsed JSON result."""
+    async with sse_client(url=MCP_SERVER_URL) as streams:
+        async with ClientSession(*streams) as session:
+            await session.initialize()
+            result = await session.call_tool(name=tool_name, arguments=arguments)
+            if result.content:
+                return json.loads(result.content[0].text)
+            return {"error": "Empty response from MCP server"}
+
+
+async def read_mcp_resource(uri: str) -> str:
+    """Connect to MCP server and read a resource."""
+    async with sse_client(url=MCP_SERVER_URL) as streams:
+        async with ClientSession(*streams) as session:
+            await session.initialize()
+            result = await session.read_resource(uri=uri)
+            if result.contents:
+                return result.contents[0].text
+            return "{}"
+
+
+def start_mcp_server(port: int = 8000):
+    """Launch mcp.py as a subprocess with SSE transport."""
+    global _mcp_process
+    mcp_script = Path(__file__).parent / "mcp.py"
+    _mcp_process = subprocess.Popen(
+        [sys.executable, str(mcp_script), "--transport", "sse", "--port", str(port)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    # Give it a moment to start
+    time.sleep(2)
+    if _mcp_process.poll() is not None:
+        stderr = _mcp_process.stderr.read().decode() if _mcp_process.stderr else ""
+        raise RuntimeError(f"MCP server failed to start: {stderr}")
+    print(f"  MCP server started (PID {_mcp_process.pid}) on port {port}")
+
+
+# ── FastAPI App ──────────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    OUTPUT_DIR.mkdir(exist_ok=True)
+    yield
+    global _mcp_process
+    if _mcp_process:
+        _mcp_process.terminate()
+        _mcp_process.wait()
+
+
+app = FastAPI(title="NeuralCAD Web Demo", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(router)
+
+
+# ── Routes ───────────────────────────────────────────────────────────────
+
+@app.get("/", response_class=HTMLResponse)
+async def index():
+    index_file = WEB_DIR / "index.html"
+    return HTMLResponse(index_file.read_text())
+
+
+@app.post("/api/generate")
+async def generate(body: dict):
+    result = await call_mcp_tool("generate_cnc_model", {
+        "prompt": body.get("prompt", ""),
+        "part_name": body.get("part_name", ""),
+        "backend": body.get("backend", "mock"),
+        "max_retries": body.get("max_retries", 2),
+    })
+    return JSONResponse(result)
+
+
+@app.post("/api/generate-image")
+async def generate_image(
+    image: UploadFile = File(...),
+    text_hint: str = Form(""),
+    part_name: str = Form(""),
+    backend: str = Form("anthropic"),
+):
+    # Save uploaded image to temp file
+    suffix = Path(image.filename or "upload.png").suffix
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        tmp.write(await image.read())
+        tmp_path = tmp.name
+
+    try:
+        result = await call_mcp_tool("generate_from_image", {
+            "image_path": tmp_path,
+            "text_hint": text_hint,
+            "part_name": part_name,
+            "backend": backend,
+        })
+        return JSONResponse(result)
+    finally:
+        os.unlink(tmp_path)
+
+
+@app.post("/api/validate")
+async def validate(body: dict):
+    result = await call_mcp_tool("validate_cnc_model", {
+        "cadquery_code": body.get("code", ""),
+        "part_name": body.get("part_name", "Part"),
+    })
+    return JSONResponse(result)
+
+
+@app.get("/api/models")
+async def list_models():
+    result = await call_mcp_tool("list_models", {
+        "output_dir": str(OUTPUT_DIR),
+    })
+    return JSONResponse(result)
+
+
+@app.get("/api/models/{name}.stl")
+async def get_stl(name: str):
+    path = OUTPUT_DIR / f"{name}.stl"
+    if not path.exists():
+        return JSONResponse({"error": f"STL not found: {name}"}, status_code=404)
+    return FileResponse(path, media_type="model/stl", filename=f"{name}.stl")
+
+
+@app.get("/api/models/{name}.step")
+async def get_step(name: str):
+    path = OUTPUT_DIR / f"{name}.step"
+    if not path.exists():
+        return JSONResponse({"error": f"STEP not found: {name}"}, status_code=404)
+    return FileResponse(path, media_type="application/step", filename=f"{name}.step")
+
+
+@app.get("/api/capabilities")
+async def capabilities():
+    try:
+        text = await read_mcp_resource("text-to-cnc://capabilities")
+        return JSONResponse(json.loads(text))
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=502)
+
+
+# ── Entry Point ──────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="NeuralCAD Web Demo Server")
+    parser.add_argument("--port", type=int, default=PORT, help="Web server port (default: 5000)")
+    parser.add_argument("--host", default="0.0.0.0", help="Bind host (default: 0.0.0.0)")
+    parser.add_argument(
+        "--start-mcp", action="store_true",
+        help="Auto-launch MCP server as subprocess before starting web server"
+    )
+    parser.add_argument("--mcp-port", type=int, default=8000, help="MCP server port (default: 8000)")
+    args = parser.parse_args()
+
+    if args.start_mcp:
+        MCP_SERVER_URL = f"http://localhost:{args.mcp_port}/sse"
+        print(f"Starting MCP CAD server on port {args.mcp_port}...")
+        start_mcp_server(args.mcp_port)
+
+    print(f"Starting NeuralCAD Web Demo on http://localhost:{args.port}")
+    print(f"MCP server: {MCP_SERVER_URL}")
+    uvicorn.run(app, host=args.host, port=args.port)

web/index.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>NeuralCAD — Text-to-CNC Pipeline</title>
+<title>NeuralCAD — Multi-Agent Design</title>
 
 <!-- Three.js -->
 <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
@@ -37,6 +37,11 @@
     --machined-steel: #8899aa;
     --font-mono: 'JetBrains Mono', 'Cascadia Code', monospace;
     --font-body: 'DM Sans', system-ui, sans-serif;
+    --agent-design: #7c3aed;
+    --agent-engineering: #00b4d8;
+    --agent-cnc: #00e676;
+    --agent-cad: #ffab40;
+    --chat-width: 340px;
   }
 
   html, body {
@@ -47,15 +52,23 @@
     font-family: var(--font-body);
   }
 
-  /* ── LAYOUT ─────────────────────────────────────── */
+  /* ---- Scrollbar ---- */
+  ::-webkit-scrollbar { width: 5px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+  ::-webkit-scrollbar-thumb:hover { background: var(--border-active); }
+
+  /* ---- LAYOUT ---- */
 
   #app {
     display: flex;
     flex-direction: column;
     height: 100vh;
+    width: 100vw;
+    overflow: hidden;
   }
 
-  /* ── TOP BAR ────────────────────────────────────── */
+  /* ---- TOP BAR ---- */
 
   #topbar {
     flex: 0 0 44px;
@@ -65,7 +78,7 @@
     align-items: center;
     justify-content: space-between;
     padding: 0 16px;
-    z-index: 10;
+    z-index: 100;
     position: relative;
   }
 
@@ -85,21 +98,10 @@
     gap: 10px;
   }
 
-  .logo-mark {
-    width: 22px; height: 22px;
-    border: 2px solid var(--accent);
-    transform: rotate(45deg);
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    position: relative;
-  }
-
-  .logo-mark::after {
-    content: '';
-    width: 6px; height: 6px;
-    background: var(--accent);
-    border-radius: 1px;
+  .logo-diamond {
+    color: var(--accent);
+    font-size: 18px;
+    line-height: 1;
   }
 
   .logo-text {
@@ -122,6 +124,12 @@
     border-left: 1px solid var(--border);
   }
 
+  .topbar-center {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+
   .topbar-right {
     display: flex;
     align-items: center;
@@ -131,7 +139,7 @@
   .backend-toggle {
     display: flex;
     align-items: center;
-    gap: 2px;
+    gap: 0;
     background: var(--bg-void);
     border: 1px solid var(--border);
     border-radius: 4px;
@@ -146,8 +154,11 @@
     cursor: pointer;
     color: var(--text-muted);
     transition: all 0.2s;
+    border-right: 1px solid var(--border);
   }
 
+  .backend-toggle button:last-child { border-right: none; }
+
   .backend-toggle button.active {
     background: var(--accent-glow);
     color: var(--accent);
@@ -157,8 +168,28 @@
     color: var(--text-secondary);
   }
 
+  .gallery-btn {
+    all: unset;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 12px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--text-secondary);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    cursor: pointer;
+    transition: all 0.2s;
+  }
+
+  .gallery-btn:hover {
+    border-color: var(--accent-dim);
+    color: var(--accent);
+  }
+
   .status-dot {
-    width: 6px; height: 6px;
+    width: 7px; height: 7px;
     border-radius: 50%;
     background: var(--success);
     box-shadow: 0 0 6px var(--success);
@@ -170,19 +201,20 @@
     50% { opacity: 0.4; }
   }
 
-  .version-tag {
-    font-family: var(--font-mono);
-    font-size: 10px;
-    color: var(--text-muted);
-    padding: 2px 8px;
-    border: 1px solid var(--border);
-    border-radius: 3px;
+  /* ---- MAIN AREA ---- */
+
+  #main {
+    flex: 1;
+    display: flex;
+    position: relative;
+    min-height: 0;
+    overflow: hidden;
   }
 
-  /* ── 3D VIEWER ──────────────────────────────────── */
+  /* ---- 3D VIEWER ---- */
 
   #viewer-container {
-    flex: 1 1 60%;
+    flex: 1;
     position: relative;
     background: var(--bg-void);
     overflow: hidden;
@@ -195,42 +227,12 @@
     display: block;
   }
 
-  /* Viewport grid effect */
-  #viewer-container::before {
-    content: '';
-    position: absolute;
-    inset: 0;
-    background-image:
-      linear-gradient(var(--border) 1px, transparent 1px),
-      linear-gradient(90deg, var(--border) 1px, transparent 1px);
-    background-size: 60px 60px;
-    opacity: 0.15;
-    pointer-events: none;
-    z-index: 1;
-  }
-
-  /* Corner brackets */
-  .corner-bracket {
-    position: absolute;
-    width: 20px; height: 20px;
-    border-color: var(--accent-dim);
-    border-style: solid;
-    border-width: 0;
-    opacity: 0.5;
-    z-index: 2;
-    pointer-events: none;
-  }
-  .corner-bracket.tl { top: 12px; left: 12px; border-top-width: 2px; border-left-width: 2px; }
-  .corner-bracket.tr { top: 12px; right: 12px; border-top-width: 2px; border-right-width: 2px; }
-  .corner-bracket.bl { bottom: 12px; left: 12px; border-bottom-width: 2px; border-left-width: 2px; }
-  .corner-bracket.br { bottom: 12px; right: 12px; border-bottom-width: 2px; border-right-width: 2px; }
-
-  /* Stats overlay */
+  /* Geo stats overlay - top left */
   #geo-stats {
     position: absolute;
     top: 14px;
-    right: 14px;
-    z-index: 3;
+    left: 14px;
+    z-index: 10;
     background: rgba(6, 8, 12, 0.85);
     border: 1px solid var(--border);
     border-radius: 4px;
@@ -247,17 +249,19 @@
   .stat-label { color: var(--text-muted); }
   .stat-value { color: var(--accent); }
 
-  /* CNC badge */
+  /* CNC badge - top right of viewer (NOT behind chat) */
   #cnc-badge {
     position: absolute;
     top: 14px;
-    left: 14px;
-    z-index: 3;
+    right: 14px;
+    z-index: 10;
     display: none;
     gap: 6px;
+    transition: right 0.35s cubic-bezier(0.4, 0, 0.2, 1);
   }
 
   #cnc-badge.visible { display: flex; }
+  body.chat-open #cnc-badge { right: calc(var(--chat-width) + 14px); }
 
   .badge {
     font-family: var(--font-mono);
@@ -293,12 +297,12 @@
     color: var(--accent);
   }
 
-  /* Download buttons */
+  /* Download buttons - bottom left */
   #download-btns {
     position: absolute;
     bottom: 14px;
-    right: 14px;
-    z-index: 3;
+    left: 14px;
+    z-index: 10;
     display: none;
     gap: 6px;
   }
@@ -330,20 +334,23 @@
   #viewer-hint {
     position: absolute;
     bottom: 16px;
-    left: 16px;
-    z-index: 3;
+    right: 16px;
+    z-index: 10;
     font-family: var(--font-mono);
     font-size: 10px;
     color: var(--text-muted);
     letter-spacing: 0.5px;
     pointer-events: none;
+    transition: right 0.35s cubic-bezier(0.4, 0, 0.2, 1);
   }
 
+  body.chat-open #viewer-hint { right: calc(var(--chat-width) + 16px); }
+
   /* Loading spinner */
   #viewer-loading {
     position: absolute;
     inset: 0;
-    z-index: 4;
+    z-index: 20;
     display: none;
     align-items: center;
     justify-content: center;
@@ -376,12 +383,12 @@
   #viewer-empty {
     position: absolute;
     inset: 0;
-    z-index: 2;
+    z-index: 5;
     display: flex;
     align-items: center;
     justify-content: center;
     flex-direction: column;
-    gap: 12px;
+    gap: 16px;
     pointer-events: none;
   }
 
@@ -393,6 +400,7 @@
     align-items: center;
     justify-content: center;
     transform: rotate(45deg);
+    opacity: 0.5;
   }
 
   .empty-icon-inner {
@@ -405,267 +413,537 @@
 
   .empty-text {
     font-family: var(--font-mono);
-    font-size: 11px;
+    font-size: 12px;
     color: var(--text-muted);
     letter-spacing: 1px;
+    text-align: center;
+    line-height: 1.6;
   }
 
-  /* ── BOTTOM PANEL ───────────────────────────────── */
+  /* ---- CHAT PANEL ---- */
 
-  #bottom-panel {
-    flex: 0 0 auto;
-    height: 40vh;
-    min-height: 240px;
-    max-height: 360px;
-    background: var(--bg-panel);
-    border-top: 1px solid var(--border);
+  #chat-panel {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: var(--chat-width);
+    height: 100%;
+    background: rgba(10, 14, 20, 0.92);
+    backdrop-filter: blur(16px);
+    border-left: 1px solid var(--border);
     display: flex;
     flex-direction: column;
-    position: relative;
+    z-index: 50;
+    transform: translateX(0);
+    transition: transform 0.35s cubic-bezier(0.4, 0, 0.2, 1);
   }
 
-  #bottom-panel::before {
-    content: '';
+  #chat-panel.collapsed {
+    transform: translateX(100%);
+  }
+
+  /* Collapse toggle */
+  #chat-toggle {
+    all: unset;
     position: absolute;
-    top: -1px;
-    left: 0; right: 0;
-    height: 1px;
-    background: linear-gradient(90deg, transparent, var(--accent-dim), transparent);
-    opacity: 0.3;
+    top: 50%;
+    left: -28px;
+    transform: translateY(-50%);
+    width: 28px;
+    height: 56px;
+    background: rgba(10, 14, 20, 0.92);
+    backdrop-filter: blur(16px);
+    border: 1px solid var(--border);
+    border-right: none;
+    border-radius: 6px 0 0 6px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    color: var(--text-secondary);
+    font-size: 14px;
+    transition: all 0.2s;
+    z-index: 51;
+  }
+
+  #chat-toggle:hover {
+    color: var(--accent);
+    background: rgba(10, 14, 20, 0.98);
+  }
+
+  /* Floating open pill */
+  #chat-open-pill {
+    position: fixed;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 60;
+    display: none;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 20px;
+    background: rgba(10, 14, 20, 0.95);
+    backdrop-filter: blur(16px);
+    border: 1px solid var(--border);
+    border-radius: 24px;
+    cursor: pointer;
+    font-family: var(--font-mono);
+    font-size: 12px;
+    color: var(--text-primary);
+    letter-spacing: 0.5px;
+    transition: all 0.3s;
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
+  }
+
+  #chat-open-pill:hover {
+    border-color: var(--accent-dim);
+    box-shadow: 0 4px 32px rgba(0, 180, 216, 0.15);
+  }
+
+  #chat-open-pill.visible { display: flex; }
+
+  .pill-dots {
+    display: flex;
+    gap: 4px;
   }
 
-  /* Tabs */
-  #tabs {
-    flex: 0 0 36px;
+  .pill-dot {
+    width: 8px; height: 8px;
+    border-radius: 50%;
+  }
+
+  /* Chat header */
+  .chat-header {
+    flex: 0 0 48px;
     display: flex;
-    gap: 0;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 16px;
     border-bottom: 1px solid var(--border);
-    padding: 0 12px;
-    background: var(--bg-panel);
   }
 
-  .tab-btn {
-    all: unset;
+  .chat-header-left {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+  }
+
+  .chat-header-title {
     font-family: var(--font-mono);
     font-size: 11px;
-    font-weight: 400;
-    letter-spacing: 0.5px;
-    color: var(--text-muted);
-    padding: 0 16px;
-    cursor: pointer;
-    position: relative;
-    transition: color 0.2s;
+    font-weight: 600;
+    letter-spacing: 2px;
+    color: var(--text-secondary);
+    text-transform: uppercase;
+  }
+
+  .agent-dots {
+    display: flex;
+    gap: 5px;
+  }
+
+  .agent-dot {
+    width: 8px; height: 8px;
+    border-radius: 50%;
+    opacity: 0.8;
+  }
+
+  /* Messages area */
+  #chat-messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 16px 12px;
     display: flex;
+    flex-direction: column;
+    gap: 12px;
+    min-height: 0;
+  }
+
+  /* Quick examples */
+  .quick-examples {
+    display: flex;
+    flex-direction: column;
     align-items: center;
+    gap: 12px;
+    padding: 40px 16px 20px;
+  }
+
+  .quick-examples-label {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    letter-spacing: 2px;
+    text-transform: uppercase;
+  }
+
+  .quick-chips {
+    display: flex;
+    flex-wrap: wrap;
     gap: 6px;
+    justify-content: center;
   }
 
-  .tab-btn:hover { color: var(--text-secondary); }
+  .quick-chip {
+    all: unset;
+    padding: 6px 12px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--text-secondary);
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 16px;
+    cursor: pointer;
+    transition: all 0.2s;
+    white-space: nowrap;
+  }
 
-  .tab-btn.active {
+  .quick-chip:hover {
+    border-color: var(--accent-dim);
     color: var(--accent);
+    background: var(--accent-glow);
   }
 
-  .tab-btn.active::after {
-    content: '';
-    position: absolute;
-    bottom: -1px;
-    left: 8px; right: 8px;
-    height: 1px;
-    background: var(--accent);
+  /* Message bubbles */
+  .msg {
+    display: flex;
+    gap: 8px;
+    max-width: 100%;
+    animation: msg-in 0.25s ease-out both;
   }
 
-  .tab-count {
-    font-size: 9px;
-    padding: 1px 5px;
-    border-radius: 3px;
-    background: var(--bg-void);
-    color: var(--text-muted);
+  @keyframes msg-in {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: translateY(0); }
   }
 
-  .tab-btn.active .tab-count {
-    background: var(--accent-glow);
-    color: var(--accent);
+  .msg-user {
+    justify-content: flex-end;
+  }
+
+  .msg-user .msg-bubble {
+    background: #1a2a3a;
+    border: 1px solid rgba(0, 180, 216, 0.15);
+    border-radius: 12px 12px 4px 12px;
+    padding: 8px 12px;
+    font-size: 13px;
+    line-height: 1.5;
+    color: var(--text-primary);
+    max-width: 85%;
+    word-wrap: break-word;
+  }
+
+  .msg-agent {
+    align-items: flex-start;
+  }
+
+  .msg-avatar {
+    flex-shrink: 0;
+    width: 24px; height: 24px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 11px;
+    font-weight: 700;
+    color: rgba(0, 0, 0, 0.7);
+    margin-top: 2px;
   }
 
-  /* Tab content */
-  .tab-content {
+  .msg-agent-body {
     flex: 1;
-    min-height: 0;
-    overflow: auto;
-    display: none;
-    padding: 12px 16px;
+    min-width: 0;
   }
 
-  .tab-content.active { display: flex; }
+  .msg-agent-name {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.5px;
+    margin-bottom: 3px;
+    text-transform: uppercase;
+  }
 
-  /* Scrollbar */
-  .tab-content::-webkit-scrollbar { width: 4px; }
-  .tab-content::-webkit-scrollbar-track { background: transparent; }
-  .tab-content::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }
+  .msg-agent-bubble {
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 4px 12px 12px 12px;
+    padding: 8px 12px;
+    font-size: 13px;
+    line-height: 1.5;
+    color: var(--text-primary);
+    word-wrap: break-word;
+  }
 
-  /* ── GENERATE TAB ───────────────────────────────── */
+  /* CAD Coder special styling */
+  .msg-agent-bubble.cad-bubble {
+    background: rgba(255, 171, 64, 0.08);
+    border-color: rgba(255, 171, 64, 0.2);
+  }
 
-  #tab-generate {
-    gap: 12px;
+  .msg-view-code {
+    display: inline-block;
+    margin-top: 6px;
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--warning);
+    cursor: pointer;
+    text-decoration: none;
+    letter-spacing: 0.5px;
+    transition: opacity 0.2s;
   }
 
-  .input-area {
-    flex: 1;
+  .msg-view-code:hover { opacity: 0.7; }
+
+  /* Typing indicator */
+  .typing-indicator {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 12px;
+  }
+
+  .typing-dots {
+    display: flex;
+    gap: 4px;
+  }
+
+  .typing-dots span {
+    width: 6px; height: 6px;
+    border-radius: 50%;
+    background: var(--text-muted);
+    animation: typing-bounce 1.2s ease-in-out infinite;
+  }
+
+  .typing-dots span:nth-child(2) { animation-delay: 0.15s; }
+  .typing-dots span:nth-child(3) { animation-delay: 0.3s; }
+
+  @keyframes typing-bounce {
+    0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
+    30% { transform: translateY(-4px); opacity: 1; }
+  }
+
+  .typing-label {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    letter-spacing: 0.5px;
+  }
+
+  /* Chat input area */
+  .chat-input-area {
+    flex: 0 0 auto;
+    padding: 12px;
+    border-top: 1px solid var(--border);
     display: flex;
     flex-direction: column;
     gap: 8px;
-    min-width: 0;
   }
 
-  #prompt-input {
+  .chat-input-row {
+    display: flex;
+    gap: 6px;
+    align-items: flex-end;
+  }
+
+  #chat-input {
     flex: 1;
-    min-height: 60px;
+    min-height: 38px;
+    max-height: 120px;
     background: var(--bg-input);
     border: 1px solid var(--border);
-    border-radius: 4px;
-    padding: 10px 12px;
+    border-radius: 8px;
+    padding: 8px 12px;
     color: var(--text-primary);
     font-family: var(--font-body);
     font-size: 13px;
-    line-height: 1.5;
+    line-height: 1.4;
     resize: none;
     outline: none;
     transition: border-color 0.2s;
   }
 
-  #prompt-input::placeholder { color: var(--text-muted); }
-  #prompt-input:focus { border-color: var(--accent-dim); }
+  #chat-input::placeholder { color: var(--text-muted); }
+  #chat-input:focus { border-color: var(--accent-dim); }
 
-  .action-row {
+  .chat-btn {
+    all: unset;
+    flex-shrink: 0;
+    width: 34px; height: 34px;
+    border-radius: 8px;
     display: flex;
-    gap: 8px;
     align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    transition: all 0.2s;
+    font-size: 16px;
   }
 
-  .btn-generate {
-    all: unset;
+  .chat-btn-preview {
+    background: rgba(255, 171, 64, 0.1);
+    border: 1px solid rgba(255, 171, 64, 0.25);
+    color: var(--warning);
+  }
+
+  .chat-btn-preview:hover {
+    background: rgba(255, 171, 64, 0.2);
+    border-color: var(--warning);
+  }
+
+  .chat-btn-send {
+    background: var(--accent-glow);
+    border: 1px solid rgba(0, 180, 216, 0.3);
+    color: var(--accent);
+  }
+
+  .chat-btn-send:hover {
+    background: rgba(0, 180, 216, 0.25);
+    border-color: var(--accent);
+  }
+
+  .chat-shortcut-hint {
+    font-family: var(--font-mono);
+    font-size: 9px;
+    color: var(--text-muted);
+    text-align: right;
+    letter-spacing: 0.3px;
+  }
+
+  /* @mention autocomplete */
+  #mention-dropdown {
+    display: none;
+    position: absolute;
+    bottom: 100%;
+    left: 12px;
+    right: 12px;
+    margin-bottom: 4px;
+    background: var(--bg-panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    overflow: hidden;
+    box-shadow: 0 -8px 24px rgba(0, 0, 0, 0.4);
+    z-index: 55;
+  }
+
+  #mention-dropdown.visible { display: block; }
+
+  .mention-option {
     display: flex;
     align-items: center;
-    justify-content: center;
-    gap: 8px;
-    flex: 1;
-    padding: 8px 20px;
-    background: linear-gradient(135deg, var(--accent-dim), var(--accent));
-    border-radius: 4px;
+    gap: 10px;
+    padding: 8px 12px;
+    cursor: pointer;
+    transition: background 0.15s;
+    font-size: 12px;
+  }
+
+  .mention-option:hover,
+  .mention-option.active {
+    background: var(--bg-surface);
+  }
+
+  .mention-dot {
+    width: 10px; height: 10px;
+    border-radius: 50%;
+    flex-shrink: 0;
+  }
+
+  .mention-name {
     font-family: var(--font-mono);
+    font-weight: 500;
+    color: var(--text-primary);
     font-size: 12px;
-    font-weight: 600;
-    color: var(--bg-void);
-    letter-spacing: 1px;
-    cursor: pointer;
-    transition: all 0.2s;
   }
 
-  .btn-generate:hover { filter: brightness(1.15); }
-
-  .btn-generate:disabled {
-    opacity: 0.4;
-    cursor: not-allowed;
-    filter: none;
-  }
+  .mention-role {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    margin-left: auto;
+  }
+
+  /* ---- CODE VIEWER MODAL ---- */
+
+  #code-modal {
+    display: none;
+    position: fixed;
+    inset: 0;
+    z-index: 200;
+    align-items: center;
+    justify-content: center;
+    background: rgba(6, 8, 12, 0.85);
+    backdrop-filter: blur(8px);
+  }
+
+  #code-modal.visible { display: flex; }
 
-  .btn-image {
-    all: unset;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 36px; height: 36px;
-    background: var(--bg-surface);
+  .code-modal-inner {
+    width: min(720px, 90vw);
+    max-height: 80vh;
+    background: var(--bg-panel);
     border: 1px solid var(--border);
-    border-radius: 4px;
-    color: var(--text-muted);
-    cursor: pointer;
-    font-size: 16px;
-    transition: all 0.2s;
+    border-radius: 8px;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    box-shadow: 0 16px 64px rgba(0, 0, 0, 0.5);
+    animation: modal-in 0.25s ease-out;
   }
 
-  .btn-image:hover {
-    border-color: var(--accent-dim);
-    color: var(--accent);
+  @keyframes modal-in {
+    from { opacity: 0; transform: scale(0.96) translateY(12px); }
+    to { opacity: 1; transform: scale(1) translateY(0); }
   }
 
-  .examples-sidebar {
-    flex: 0 0 220px;
+  .code-modal-header {
     display: flex;
-    flex-direction: column;
-    gap: 4px;
-    overflow-y: auto;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--border);
   }
 
-  .examples-label {
+  .code-modal-title {
     font-family: var(--font-mono);
-    font-size: 9px;
-    color: var(--text-muted);
-    letter-spacing: 2px;
+    font-size: 11px;
+    font-weight: 600;
+    color: var(--text-secondary);
+    letter-spacing: 1px;
     text-transform: uppercase;
-    margin-bottom: 2px;
   }
 
-  .example-btn {
+  .code-modal-close {
     all: unset;
+    width: 28px; height: 28px;
     display: flex;
     align-items: center;
-    gap: 8px;
-    padding: 7px 10px;
-    background: var(--bg-surface);
-    border: 1px solid var(--border);
+    justify-content: center;
     border-radius: 4px;
-    font-family: var(--font-mono);
-    font-size: 10px;
-    color: var(--text-secondary);
     cursor: pointer;
-    transition: all 0.2s;
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
-  }
-
-  .example-btn:hover {
-    border-color: var(--accent-dim);
-    color: var(--text-primary);
-    background: var(--bg-input);
-  }
-
-  .example-arrow {
     color: var(--text-muted);
-    font-size: 8px;
-    flex-shrink: 0;
+    font-size: 18px;
+    transition: all 0.15s;
   }
 
-  /* ── CODE TAB ───────────────────────────────────── */
-
-  #tab-code {
-    padding: 0;
+  .code-modal-close:hover {
+    background: var(--bg-surface);
+    color: var(--text-primary);
   }
 
   #code-display {
-    width: 100%;
-    height: 100%;
+    flex: 1;
     margin: 0;
-    padding: 14px 16px;
+    padding: 16px;
     background: var(--bg-input);
-    border: none;
     color: var(--machined-steel);
     font-family: var(--font-mono);
-    font-size: 11.5px;
+    font-size: 12px;
     line-height: 1.7;
     overflow: auto;
     white-space: pre;
     tab-size: 4;
   }
 
-  .code-empty {
-    color: var(--text-muted) !important;
-    font-style: italic;
-  }
-
-  /* Syntax coloring via JS */
+  /* Syntax coloring */
   .kw { color: #c792ea; }
   .fn { color: #82aaff; }
   .cm { color: #546e7a; }
@@ -673,102 +951,84 @@
   .nu { color: #f78c6c; }
   .op { color: #89ddff; }
 
-  /* ── VALIDATION TAB ─────────────────────────────── */
+  /* ---- GALLERY MODAL ---- */
 
-  #tab-validation {
-    flex-direction: column;
-    gap: 10px;
-  }
-
-  .validation-empty {
-    font-family: var(--font-mono);
-    font-size: 11px;
-    color: var(--text-muted);
-    letter-spacing: 0.5px;
-    margin: auto;
-  }
-
-  .validation-header {
-    display: flex;
+  #gallery-modal {
+    display: none;
+    position: fixed;
+    inset: 0;
+    z-index: 200;
     align-items: center;
-    gap: 12px;
-    padding-bottom: 10px;
-    border-bottom: 1px solid var(--border);
+    justify-content: center;
+    background: rgba(6, 8, 12, 0.85);
+    backdrop-filter: blur(8px);
   }
 
-  .validation-header .badge { font-size: 11px; }
-
-  .validation-axis {
-    font-family: var(--font-mono);
-    font-size: 11px;
-    color: var(--text-secondary);
-  }
+  #gallery-modal.visible { display: flex; }
 
-  .issue-list {
+  .gallery-modal-inner {
+    width: min(800px, 90vw);
+    max-height: 80vh;
+    background: var(--bg-panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
     display: flex;
     flex-direction: column;
-    gap: 4px;
+    overflow: hidden;
+    box-shadow: 0 16px 64px rgba(0, 0, 0, 0.5);
+    animation: modal-in 0.25s ease-out;
   }
 
-  .issue-item {
+  .gallery-modal-header {
     display: flex;
-    align-items: flex-start;
-    gap: 10px;
-    padding: 6px 8px;
-    border-radius: 3px;
-    font-size: 12px;
-    font-family: var(--font-mono);
-    line-height: 1.4;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--border);
   }
 
-  .issue-item.error { background: rgba(255, 82, 82, 0.05); }
-  .issue-item.warning { background: rgba(255, 171, 64, 0.05); }
-  .issue-item.info { background: rgba(0, 180, 216, 0.03); }
-
-  .issue-severity {
-    flex-shrink: 0;
-    font-size: 10px;
+  .gallery-modal-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
     font-weight: 600;
+    color: var(--text-secondary);
+    letter-spacing: 1px;
     text-transform: uppercase;
-    letter-spacing: 0.5px;
-    width: 52px;
   }
 
-  .issue-severity.error { color: var(--error); }
-  .issue-severity.warning { color: var(--warning); }
-  .issue-severity.info { color: var(--accent); }
-
-  .issue-message { color: var(--text-secondary); }
-
-  /* ── GALLERY TAB ────────────────────────────────── */
-
-  #tab-gallery {
-    gap: 8px;
+  .gallery-grid {
+    flex: 1;
+    overflow-y: auto;
+    padding: 16px;
+    display: flex;
     flex-wrap: wrap;
+    gap: 12px;
     align-content: flex-start;
   }
 
   .gallery-empty {
+    width: 100%;
+    text-align: center;
+    padding: 40px;
     font-family: var(--font-mono);
     font-size: 11px;
     color: var(--text-muted);
     letter-spacing: 0.5px;
-    margin: auto;
   }
 
   .gallery-card {
     all: unset;
     flex: 0 0 auto;
-    width: 160px;
+    width: 180px;
     background: var(--bg-surface);
     border: 1px solid var(--border);
-    border-radius: 4px;
-    padding: 10px;
+    border-radius: 6px;
+    padding: 12px;
     cursor: pointer;
     transition: all 0.2s;
     display: flex;
     flex-direction: column;
-    gap: 6px;
+    gap: 8px;
   }
 
   .gallery-card:hover {
@@ -794,7 +1054,7 @@
     gap: 8px;
   }
 
-  /* ── ANIMATIONS ─────────────────────────────────── */
+  /* ---- ANIMATIONS ---- */
 
   @keyframes fade-in-up {
     from { opacity: 0; transform: translateY(8px); }
@@ -805,138 +1065,175 @@
     animation: fade-in-up 0.3s ease-out both;
   }
 
-  /* ── RESPONSIVE ─────────────────────────────────── */
+  /* ---- RESPONSIVE ---- */
 
   @media (max-width: 768px) {
-    .examples-sidebar { display: none; }
     .logo-sub { display: none; }
-    #bottom-panel { height: 50vh; max-height: none; }
+    :root { --chat-width: 100vw; }
+    #chat-toggle { display: none; }
+    .gallery-btn span { display: none; }
   }
 </style>
 </head>
-<body>
+<body class="chat-open">
 <div id="app">
 
-  <!-- ── TOP BAR ─────────────────────────────────── -->
+  <!-- ---- TOP BAR ---- -->
   <div id="topbar">
     <div class="logo">
-      <div class="logo-mark"></div>
+      <span class="logo-diamond">&#9670;</span>
       <span class="logo-text">NeuralCAD</span>
-      <span class="logo-sub">Text-to-CNC Pipeline</span>
+      <span class="logo-sub">Multi-Agent Design</span>
     </div>
     <div class="topbar-right">
       <div class="backend-toggle">
         <button id="btn-mock" class="active" onclick="setBackend('mock')">MOCK</button>
         <button id="btn-gemini" onclick="setBackend('gemini')">GEMINI</button>
-        <button id="btn-api" onclick="setBackend('anthropic')">CLAUDE</button>
+        <button id="btn-claude" onclick="setBackend('anthropic')">CLAUDE</button>
       </div>
-      <div class="status-dot" id="status-dot" title="MCP Server Connected"></div>
-      <div class="version-tag">v1.0.0</div>
+      <button class="gallery-btn" onclick="openGallery()">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/></svg>
+        <span>GALLERY</span>
+      </button>
+      <div class="status-dot" id="status-dot" title="Server Connected"></div>
     </div>
   </div>
 
-  <!-- ── 3D VIEWER ───────────────────────────────── -->
-  <div id="viewer-container">
-    <canvas id="viewer-canvas"></canvas>
+  <!-- ---- MAIN AREA ---- -->
+  <div id="main">
 
-    <div class="corner-bracket tl"></div>
-    <div class="corner-bracket tr"></div>
-    <div class="corner-bracket bl"></div>
-    <div class="corner-bracket br"></div>
+    <!-- 3D Viewer -->
+    <div id="viewer-container">
+      <canvas id="viewer-canvas"></canvas>
 
-    <div id="geo-stats">
-      <div><span class="stat-label">VOL </span><span class="stat-value" id="stat-volume">—</span></div>
-      <div><span class="stat-label">BBOX </span><span class="stat-value" id="stat-bbox">—</span></div>
-      <div><span class="stat-label">FACES </span><span class="stat-value" id="stat-faces">—</span><span class="stat-label"> EDGES </span><span class="stat-value" id="stat-edges">—</span></div>
-    </div>
+      <div id="geo-stats">
+        <div><span class="stat-label">VOL </span><span class="stat-value" id="stat-volume">&mdash;</span></div>
+        <div><span class="stat-label">BBOX </span><span class="stat-value" id="stat-bbox">&mdash;</span></div>
+        <div><span class="stat-label">FACES </span><span class="stat-value" id="stat-faces">&mdash;</span><span class="stat-label"> EDGES </span><span class="stat-value" id="stat-edges">&mdash;</span></div>
+      </div>
 
-    <div id="cnc-badge">
-      <div class="badge badge-success" id="badge-cnc"></div>
-      <div class="badge badge-info" id="badge-axis"></div>
-    </div>
+      <div id="cnc-badge">
+        <div class="badge badge-success" id="badge-cnc"></div>
+        <div class="badge badge-info" id="badge-axis"></div>
+      </div>
 
-    <div id="download-btns">
-      <a class="dl-btn" id="dl-step" download>STEP</a>
-      <a class="dl-btn" id="dl-stl" download>STL</a>
-    </div>
+      <div id="download-btns">
+        <a class="dl-btn" id="dl-step" download>STEP</a>
+        <a class="dl-btn" id="dl-stl" download>STL</a>
+        <a class="dl-btn" id="dl-report" download>REPORT</a>
+      </div>
 
-    <div id="viewer-hint">DRAG ROTATE &middot; SCROLL ZOOM &middot; RIGHT-DRAG PAN</div>
+      <div id="viewer-hint">DRAG ROTATE &middot; SCROLL ZOOM &middot; RIGHT-DRAG PAN</div>
 
-    <div id="viewer-loading">
-      <div class="spinner"></div>
-      <div class="loading-text" id="loading-msg">GENERATING MODEL...</div>
-    </div>
+      <div id="viewer-loading">
+        <div class="spinner"></div>
+        <div class="loading-text" id="loading-msg">GENERATING MODEL...</div>
+      </div>
 
-    <div id="viewer-empty">
-      <div class="empty-icon"><div class="empty-icon-inner"></div></div>
-      <div class="empty-text">DESCRIBE A PART TO BEGIN</div>
+      <div id="viewer-empty">
+        <div class="empty-icon"><div class="empty-icon-inner"></div></div>
+        <div class="empty-text">Start a conversation to<br>design your part</div>
+      </div>
     </div>
-  </div>
 
-  <!-- ── BOTTOM PANEL ────────────────────────────── -->
-  <div id="bottom-panel">
-    <div id="tabs">
-      <button class="tab-btn active" data-tab="generate">GENERATE</button>
-      <button class="tab-btn" data-tab="code">CODE</button>
-      <button class="tab-btn" data-tab="validation">VALIDATION <span class="tab-count" id="issue-count" style="display:none">0</span></button>
-      <button class="tab-btn" data-tab="gallery">GALLERY <span class="tab-count" id="gallery-count" style="display:none">0</span></button>
-    </div>
+    <!-- Chat Panel -->
+    <div id="chat-panel">
+      <button id="chat-toggle" onclick="toggleChat()" title="Toggle chat panel">&#9664;</button>
+
+      <div class="chat-header">
+        <div class="chat-header-left">
+          <span class="chat-header-title">Design Chat</span>
+          <div class="agent-dots">
+            <div class="agent-dot" style="background: var(--agent-design);" title="Design Agent"></div>
+            <div class="agent-dot" style="background: var(--agent-engineering);" title="Engineering Agent"></div>
+            <div class="agent-dot" style="background: var(--agent-cnc);" title="CNC Agent"></div>
+            <div class="agent-dot" style="background: var(--agent-cad);" title="CAD Coder Agent"></div>
+          </div>
+        </div>
+      </div>
+
+      <div id="chat-messages">
+        <div class="quick-examples" id="quick-examples">
+          <div class="quick-examples-label">Quick Start</div>
+          <div class="quick-chips">
+            <button class="quick-chip" onclick="quickSend('Design a servo bracket')">Design a servo bracket</button>
+            <button class="quick-chip" onclick="quickSend('I need a spur gear')">I need a spur gear</button>
+            <button class="quick-chip" onclick="quickSend('Create a heatsink')">Create a heatsink</button>
+            <button class="quick-chip" onclick="quickSend('Design a pipe flange')">Design a pipe flange</button>
+          </div>
+        </div>
+      </div>
 
-    <!-- Generate Tab -->
-    <div class="tab-content active" id="tab-generate">
-      <div class="input-area">
-        <textarea id="prompt-input" placeholder="Describe a mechanical part...&#10;&#10;e.g. A mounting bracket with four M6 bolt holes, 80mm wide, with rounded corners"></textarea>
-        <div class="action-row">
-          <button class="btn-generate" id="btn-gen" onclick="doGenerate()">
-            <span id="btn-gen-text">GENERATE MODEL</span>
+      <div class="chat-input-area" style="position: relative;">
+        <div id="mention-dropdown">
+          <div class="mention-option" data-agent="design" onclick="insertMention('design')">
+            <div class="mention-dot" style="background: var(--agent-design);"></div>
+            <span class="mention-name">@design</span>
+            <span class="mention-role">Design Agent</span>
+          </div>
+          <div class="mention-option" data-agent="engineering" onclick="insertMention('engineering')">
+            <div class="mention-dot" style="background: var(--agent-engineering);"></div>
+            <span class="mention-name">@engineering</span>
+            <span class="mention-role">Engineering Agent</span>
+          </div>
+          <div class="mention-option" data-agent="cnc" onclick="insertMention('cnc')">
+            <div class="mention-dot" style="background: var(--agent-cnc);"></div>
+            <span class="mention-name">@cnc</span>
+            <span class="mention-role">CNC Agent</span>
+          </div>
+          <div class="mention-option" data-agent="cad" onclick="insertMention('cad')">
+            <div class="mention-dot" style="background: var(--agent-cad);"></div>
+            <span class="mention-name">@cad</span>
+            <span class="mention-role">CAD Coder</span>
+          </div>
+        </div>
+        <div class="chat-input-row">
+          <textarea id="chat-input" rows="1" placeholder="Type your message..."></textarea>
+          <button class="chat-btn chat-btn-preview" onclick="sendPreview()" title="Generate 3D preview">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg>
           </button>
-          <button class="btn-image" title="Generate from image" onclick="document.getElementById('image-input').click()">
-            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><path d="M21 15l-5-5L5 21"/></svg>
+          <button class="chat-btn chat-btn-send" onclick="sendFromInput()" title="Send message">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="5" y1="12" x2="19" y2="12"/><polyline points="12 5 19 12 12 19"/></svg>
           </button>
-          <input type="file" id="image-input" accept="image/*" style="display:none" onchange="doImageGenerate(this)">
         </div>
-      </div>
-      <div class="examples-sidebar">
-        <div class="examples-label">Quick Examples</div>
-        <button class="example-btn" onclick="runExample('A mounting bracket with four M6 bolt holes, 80mm wide')">
-          <span class="example-arrow">&#9654;</span> Mounting bracket
-        </button>
-        <button class="example-btn" onclick="runExample('A spur gear with 20 teeth, module 2, 10mm thick')">
-          <span class="example-arrow">&#9654;</span> Spur gear
-        </button>
-        <button class="example-btn" onclick="runExample('A 100mm pipe flange with 8 M8 bolt holes and center bore')">
-          <span class="example-arrow">&#9654;</span> Pipe flange
-        </button>
-        <button class="example-btn" onclick="runExample('A 30mm cylinder with 12 cooling fins, heatsink')">
-          <span class="example-arrow">&#9654;</span> Heatsink
-        </button>
-        <button class="example-btn" onclick="runExample('An L-bracket 60mm arms with M5 holes, 25mm wide')">
-          <span class="example-arrow">&#9654;</span> L-bracket
-        </button>
-        <button class="example-btn" onclick="runExample('An enclosure 120x80x40mm with pocket, slots, and rounded corners')">
-          <span class="example-arrow">&#9654;</span> Electronics enclosure
-        </button>
-        <button class="example-btn" onclick="runExample('A 50x50x10mm plate with central slot and two M6 holes')">
-          <span class="example-arrow">&#9654;</span> Slotted plate
-        </button>
-        <button class="example-btn" onclick="runExample('A box 80x60x30mm with 4 mounting bosses and chamfered edges')">
-          <span class="example-arrow">&#9654;</span> Boss mount
-        </button>
+        <div class="chat-shortcut-hint">Ctrl+Enter to send</div>
       </div>
     </div>
 
-    <!-- Code Tab -->
-    <div class="tab-content" id="tab-code">
-      <pre id="code-display" class="code-empty">No generated code yet. Run a generation to see the CadQuery output.</pre>
-    </div>
+  </div>
+</div>
+
+<!-- Floating open pill (when chat collapsed) -->
+<div id="chat-open-pill" onclick="toggleChat()">
+  <span>Open Chat</span>
+  <div class="pill-dots">
+    <div class="pill-dot" style="background: var(--agent-design);"></div>
+    <div class="pill-dot" style="background: var(--agent-engineering);"></div>
+    <div class="pill-dot" style="background: var(--agent-cnc);"></div>
+    <div class="pill-dot" style="background: var(--agent-cad);"></div>
+  </div>
+  <span>&#9654;</span>
+</div>
 
-    <!-- Validation Tab -->
-    <div class="tab-content" id="tab-validation">
-      <div class="validation-empty">No validation data. Generate a model first.</div>
+<!-- Code Viewer Modal -->
+<div id="code-modal">
+  <div class="code-modal-inner">
+    <div class="code-modal-header">
+      <span class="code-modal-title">CadQuery Code</span>
+      <button class="code-modal-close" onclick="closeCodeModal()">&times;</button>
     </div>
+    <pre id="code-display"></pre>
+  </div>
+</div>
 
-    <!-- Gallery Tab -->
-    <div class="tab-content" id="tab-gallery">
+<!-- Gallery Modal -->
+<div id="gallery-modal">
+  <div class="gallery-modal-inner">
+    <div class="gallery-modal-header">
+      <span class="gallery-modal-title">Model Gallery</span>
+      <button class="code-modal-close" onclick="closeGallery()">&times;</button>
+    </div>
+    <div class="gallery-grid" id="gallery-grid">
       <div class="gallery-empty">No models generated yet.</div>
     </div>
   </div>
@@ -946,9 +1243,21 @@
 // ── STATE ─────────────────────────────────────────────
 
 let currentBackend = 'mock';
+let chatHistory = [];
+let chatPanelOpen = true;
 let currentPartName = '';
-let scene, camera, renderer, controls, currentMesh;
+let currentCode = '';
+let scene, camera, renderer, controls, currentMesh, gridHelper;
 const galleryItems = [];
+let mentionActive = false;
+let mentionIndex = 0;
+
+const AGENTS = {
+  design:      { name: 'Design',      color: '#7c3aed', avatar: 'D' },
+  engineering: { name: 'Engineering', color: '#00b4d8', avatar: 'E' },
+  cnc:         { name: 'CNC',         color: '#00e676', avatar: 'C' },
+  cad:         { name: 'CAD Coder',   color: '#ffab40', avatar: '{}'  },
+};
 
 // ── THREE.JS SETUP ────────────────────────────────────
 
@@ -986,6 +1295,11 @@ function initViewer() {
   rimLight.position.set(0, -50, 100);
   scene.add(rimLight);
 
+  // Grid helper
+  gridHelper = new THREE.GridHelper(400, 40, 0x1a2636, 0x111822);
+  gridHelper.position.y = -0.5;
+  scene.add(gridHelper);
+
   // Controls
   controls = new THREE.OrbitControls(camera, renderer.domElement);
   controls.enableDamping = true;
@@ -1017,14 +1331,12 @@ function loadSTL(url) {
   return new Promise((resolve, reject) => {
     const loader = new THREE.STLLoader();
     loader.load(url, (geometry) => {
-      // Remove existing mesh
       if (currentMesh) {
         scene.remove(currentMesh);
         currentMesh.geometry.dispose();
         currentMesh.material.dispose();
       }
 
-      // Material: machined steel look
       const material = new THREE.MeshPhongMaterial({
         color: 0x7799aa,
         specular: 0x445566,
@@ -1036,7 +1348,6 @@ function loadSTL(url) {
       mesh.castShadow = true;
       mesh.receiveShadow = true;
 
-      // Center geometry
       geometry.computeBoundingBox();
       const center = new THREE.Vector3();
       geometry.boundingBox.getCenter(center);
@@ -1046,15 +1357,19 @@ function loadSTL(url) {
       currentMesh = mesh;
 
       // Fit camera
-      const box = geometry.boundingBox;
       const size = new THREE.Vector3();
-      box.getSize(size);
+      geometry.boundingBox.getSize(size);
       const maxDim = Math.max(size.x, size.y, size.z);
       const dist = maxDim * 2.5;
       camera.position.set(dist * 0.7, dist * 0.5, dist * 0.7);
       controls.target.set(0, 0, 0);
       controls.update();
 
+      // Update grid to match model scale
+      if (gridHelper) {
+        gridHelper.position.y = -size.y / 2 - 0.5;
+      }
+
       document.getElementById('viewer-empty').style.display = 'none';
       resolve();
     }, undefined, reject);
@@ -1067,132 +1382,279 @@ function setBackend(name) {
   currentBackend = name;
   document.getElementById('btn-mock').classList.toggle('active', name === 'mock');
   document.getElementById('btn-gemini').classList.toggle('active', name === 'gemini');
-  document.getElementById('btn-api').classList.toggle('active', name === 'anthropic');
+  document.getElementById('btn-claude').classList.toggle('active', name === 'anthropic');
 }
 
-// ── TABS ──────────────────────────────────────────────
+// ── CHAT PANEL TOGGLE ─────────────────────────────────
+
+function toggleChat() {
+  chatPanelOpen = !chatPanelOpen;
+  const panel = document.getElementById('chat-panel');
+  const pill = document.getElementById('chat-open-pill');
+  const toggle = document.getElementById('chat-toggle');
+
+  if (chatPanelOpen) {
+    panel.classList.remove('collapsed');
+    pill.classList.remove('visible');
+    toggle.innerHTML = '&#9664;';
+    document.body.classList.add('chat-open');
+  } else {
+    panel.classList.add('collapsed');
+    pill.classList.add('visible');
+    toggle.innerHTML = '&#9654;';
+    document.body.classList.remove('chat-open');
+  }
+}
 
-document.getElementById('tabs').addEventListener('click', (e) => {
-  const btn = e.target.closest('.tab-btn');
-  if (!btn) return;
-  const tabName = btn.dataset.tab;
+// ── CHAT MESSAGING ────────────────────────────────────
 
-  document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
-  document.querySelectorAll('.tab-content').forEach(c => c.classList.remove('active'));
+async function sendMessage(text) {
+  if (!text.trim()) return;
 
-  btn.classList.add('active');
-  document.getElementById('tab-' + tabName).classList.add('active');
-});
+  // Parse @mentions
+  const mentions = [];
+  const mentionRegex = /@(design|engineering|cnc|cad)\b/gi;
+  let match;
+  while ((match = mentionRegex.exec(text)) !== null) {
+    mentions.push(match[1].toLowerCase());
+  }
+  const cleanedText = text.replace(mentionRegex, '').trim();
 
-// ── GENERATION ────────────────────────────────────────
+  // Hide quick examples
+  const examples = document.getElementById('quick-examples');
+  if (examples) examples.style.display = 'none';
 
-async function doGenerate() {
-  const prompt = document.getElementById('prompt-input').value.trim();
-  if (!prompt) return;
+  // Add user message
+  addMessage({ role: 'user', content: text });
+  chatHistory.push({ role: 'user', content: text });
 
-  setLoading(true, 'GENERATING MODEL...');
+  // Show typing
+  showTyping();
 
   try {
-    const resp = await fetch('/api/generate', {
+    const resp = await fetch('/api/chat', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ prompt, backend: currentBackend }),
+      body: JSON.stringify({
+        message: cleanedText,
+        history: chatHistory,
+        mentions: mentions,
+        backend: currentBackend,
+      }),
     });
     const data = await resp.json();
-    handleResult(data);
+
+    hideTyping();
+
+    // Add agent responses
+    for (const r of data.responses) {
+      addMessage({
+        role: 'agent',
+        agent_id: r.agent_id,
+        agent_name: r.agent_name,
+        content: r.message,
+        color: r.color,
+        avatar: r.avatar,
+        code: r.code,
+      });
+      chatHistory.push({ role: 'agent', agent_id: r.agent_id, content: r.message });
+    }
+
+    // If preview available, load 3D model
+    if (data.preview && data.preview.success) {
+      setViewerLoading(true, 'LOADING 3D MODEL...');
+      try {
+        await loadSTL(data.preview.stl_url);
+      } catch (e) {
+        console.warn('STL load failed:', e);
+      }
+      setViewerLoading(false);
+      updateGeoStats(data.preview.execution);
+      updateCNCBadge(data.preview.validation);
+      updateDownloads(data.preview.part_name);
+
+      if (data.preview.part_name) {
+        currentPartName = data.preview.part_name;
+        addToGallery(data.preview);
+      }
+    }
   } catch (err) {
-    setLoading(false);
-    alert('Error: ' + err.message);
+    hideTyping();
+    addMessage({
+      role: 'agent',
+      agent_id: 'system',
+      agent_name: 'System',
+      content: 'Error: ' + err.message,
+      color: '#ff5252',
+      avatar: '!',
+    });
   }
 }
 
-async function doImageGenerate(input) {
-  const file = input.files[0];
-  if (!file) return;
+function sendFromInput() {
+  const input = document.getElementById('chat-input');
+  const text = input.value.trim();
+  if (!text) return;
+  input.value = '';
+  input.style.height = 'auto';
+  closeMentionDropdown();
+  sendMessage(text);
+}
+
+function sendPreview() {
+  sendMessage('@cad Generate a 3D preview based on our discussion');
+}
 
-  setLoading(true, 'ANALYZING IMAGE...');
+function quickSend(text) {
+  const examples = document.getElementById('quick-examples');
+  if (examples) examples.style.display = 'none';
+  sendMessage(text);
+}
 
-  const form = new FormData();
-  form.append('image', file);
-  form.append('backend', currentBackend === 'mock' ? 'anthropic' : currentBackend);
+// ── MESSAGE RENDERING ─────────────────────────────────
 
-  try {
-    const resp = await fetch('/api/generate-image', { method: 'POST', body: form });
-    const data = await resp.json();
-    handleResult(data);
-  } catch (err) {
-    setLoading(false);
-    alert('Error: ' + err.message);
+function addMessage(msg) {
+  const container = document.getElementById('chat-messages');
+
+  const el = document.createElement('div');
+
+  if (msg.role === 'user') {
+    el.className = 'msg msg-user';
+    el.innerHTML = '<div class="msg-bubble">' + escapeHtml(msg.content) + '</div>';
+  } else {
+    const agentId = msg.agent_id || 'system';
+    const agentInfo = AGENTS[agentId] || { name: msg.agent_name || 'Agent', color: msg.color || '#5a7089', avatar: '?' };
+    const color = msg.color || agentInfo.color;
+    const avatar = msg.avatar || agentInfo.avatar;
+    const name = msg.agent_name || agentInfo.name;
+    const isCad = agentId === 'cad';
+
+    el.className = 'msg msg-agent';
+
+    let html = '<div class="msg-avatar" style="background: ' + color + ';">' + avatar + '</div>';
+    html += '<div class="msg-agent-body">';
+    html += '<div class="msg-agent-name" style="color: ' + color + ';">' + escapeHtml(name) + '</div>';
+    html += '<div class="msg-agent-bubble' + (isCad ? ' cad-bubble' : '') + '">' + escapeHtml(msg.content);
+
+    if (msg.code) {
+      currentCode = msg.code;
+      html += '<br><a class="msg-view-code" onclick="openCodeModal()">&#9654; View code</a>';
+    }
+
+    html += '</div></div>';
+    el.innerHTML = html;
   }
 
-  input.value = '';
+  container.appendChild(el);
+  scrollChatToBottom();
 }
 
-function runExample(prompt) {
-  document.getElementById('prompt-input').value = prompt;
-  // Force mock for examples (reliability)
-  const prevBackend = currentBackend;
-  currentBackend = 'mock';
-  doGenerate().then(() => { currentBackend = prevBackend; });
+function showTyping() {
+  const container = document.getElementById('chat-messages');
+  const el = document.createElement('div');
+  el.className = 'typing-indicator';
+  el.id = 'typing-indicator';
+  el.innerHTML = '<div class="typing-dots"><span></span><span></span><span></span></div><span class="typing-label">Agents are thinking...</span>';
+  container.appendChild(el);
+  scrollChatToBottom();
 }
 
-async function handleResult(data) {
-  if (!data.success) {
-    setLoading(false);
-    alert('Generation failed: ' + (data.execution?.error || data.error || 'Unknown error'));
-    return;
-  }
+function hideTyping() {
+  const el = document.getElementById('typing-indicator');
+  if (el) el.remove();
+}
 
-  currentPartName = data.part_name;
+function scrollChatToBottom() {
+  const container = document.getElementById('chat-messages');
+  requestAnimationFrame(() => {
+    container.scrollTop = container.scrollHeight;
+  });
+}
 
-  // Update code tab
-  updateCodeTab(data.generated_code);
+// ── @MENTION AUTOCOMPLETE ─────────────────────────────
 
-  // Update validation tab
-  updateValidationTab(data.validation, data.execution);
+const mentionAgents = ['design', 'engineering', 'cnc', 'cad'];
 
-  // Update geometry stats
-  updateGeoStats(data.execution);
+function handleInputForMention(e) {
+  const input = document.getElementById('chat-input');
+  const val = input.value;
+  const pos = input.selectionStart;
 
-  // Update CNC badge
-  updateCNCBadge(data.validation);
+  // Find @ before cursor
+  const before = val.substring(0, pos);
+  const atMatch = before.match(/@(\w*)$/);
 
-  // Update downloads
-  updateDownloads(data.part_name, data.exported_files);
+  if (atMatch) {
+    const query = atMatch[1].toLowerCase();
+    const filtered = mentionAgents.filter(a => a.startsWith(query));
 
-  // Load 3D model
-  setLoading(true, 'LOADING 3D MODEL...');
-  try {
-    await loadSTL('/api/models/' + data.part_name + '.stl');
-  } catch (e) {
-    console.warn('STL load failed:', e);
+    if (filtered.length > 0) {
+      showMentionDropdown(filtered);
+      mentionActive = true;
+      return;
+    }
+  }
+
+  closeMentionDropdown();
+}
+
+function showMentionDropdown(filtered) {
+  const dropdown = document.getElementById('mention-dropdown');
+  const options = dropdown.querySelectorAll('.mention-option');
+  let visibleCount = 0;
+
+  options.forEach(opt => {
+    const agent = opt.dataset.agent;
+    if (filtered.includes(agent)) {
+      opt.style.display = 'flex';
+      visibleCount++;
+    } else {
+      opt.style.display = 'none';
+    }
+  });
+
+  if (visibleCount > 0) {
+    dropdown.classList.add('visible');
+    mentionIndex = 0;
+    updateMentionHighlight();
   }
+}
 
-  setLoading(false);
+function closeMentionDropdown() {
+  document.getElementById('mention-dropdown').classList.remove('visible');
+  mentionActive = false;
+}
 
-  // Add to gallery
-  addToGallery(data);
+function updateMentionHighlight() {
+  const options = Array.from(document.querySelectorAll('#mention-dropdown .mention-option'))
+    .filter(o => o.style.display !== 'none');
+  options.forEach((o, i) => o.classList.toggle('active', i === mentionIndex));
+}
 
-  // Switch to generate tab if not already there
-  loadGallery();
+function insertMention(agent) {
+  const input = document.getElementById('chat-input');
+  const val = input.value;
+  const pos = input.selectionStart;
+  const before = val.substring(0, pos);
+  const after = val.substring(pos);
+  const atPos = before.lastIndexOf('@');
+
+  input.value = before.substring(0, atPos) + '@' + agent + ' ' + after;
+  input.focus();
+  const newPos = atPos + agent.length + 2;
+  input.setSelectionRange(newPos, newPos);
+  closeMentionDropdown();
 }
 
 // ── UI UPDATES ────────────────────────────────────────
 
-function setLoading(on, msg) {
+function setViewerLoading(on, msg) {
   const el = document.getElementById('viewer-loading');
-  const btn = document.getElementById('btn-gen');
-  const btnText = document.getElementById('btn-gen-text');
-
   if (on) {
     el.classList.add('visible');
     document.getElementById('loading-msg').textContent = msg || 'GENERATING...';
-    btn.disabled = true;
-    btnText.textContent = 'GENERATING...';
   } else {
     el.classList.remove('visible');
-    btn.disabled = false;
-    btnText.textContent = 'GENERATE MODEL';
   }
 }
 
@@ -1211,8 +1673,8 @@ function updateGeoStats(exec) {
       bbox.map(v => v.toFixed(1)).join(' \u00D7 ') + ' mm';
   }
 
-  document.getElementById('stat-faces').textContent = exec.face_count || '—';
-  document.getElementById('stat-edges').textContent = exec.edge_count || '—';
+  document.getElementById('stat-faces').textContent = exec.face_count || '\u2014';
+  document.getElementById('stat-edges').textContent = exec.edge_count || '\u2014';
 }
 
 function updateCNCBadge(validation) {
@@ -1233,125 +1695,83 @@ function updateCNCBadge(validation) {
   axisBadge.textContent = (validation.axis_recommendation || '').toUpperCase();
 }
 
-function updateDownloads(partName, files) {
+function updateDownloads(partName) {
   const el = document.getElementById('download-btns');
-  if (!files) { el.classList.remove('visible'); return; }
+  if (!partName) { el.classList.remove('visible'); return; }
   el.classList.add('visible');
 
   document.getElementById('dl-step').href = '/api/models/' + partName + '.step';
   document.getElementById('dl-stl').href = '/api/models/' + partName + '.stl';
+  document.getElementById('dl-report').href = '/api/models/' + partName + '_report.json';
 }
 
-function updateCodeTab(code) {
-  const el = document.getElementById('code-display');
-  if (!code) {
-    el.textContent = 'No generated code yet.';
-    el.classList.add('code-empty');
-    return;
+// ── CODE MODAL ────────────────────────────────────────
+
+function openCodeModal() {
+  const modal = document.getElementById('code-modal');
+  const display = document.getElementById('code-display');
+
+  if (currentCode) {
+    display.innerHTML = highlightPython(currentCode);
+  } else {
+    display.textContent = 'No code available.';
   }
-  el.classList.remove('code-empty');
-  el.innerHTML = highlightPython(code);
+
+  modal.classList.add('visible');
+}
+
+function closeCodeModal() {
+  document.getElementById('code-modal').classList.remove('visible');
 }
 
 function highlightPython(code) {
-  // Simple Python syntax highlighting
   let escaped = code
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;');
 
-  // Comments
   escaped = escaped.replace(/(#.*$)/gm, '<span class="cm">$1</span>');
-  // Strings
   escaped = escaped.replace(/("""[\s\S]*?"""|'''[\s\S]*?'''|"[^"\n]*"|'[^'\n]*')/g, '<span class="st">$1</span>');
-  // Keywords
+
   const kw = /\b(import|from|as|def|class|return|if|else|elif|for|while|in|not|and|or|True|False|None|with|try|except|finally|raise|pass|break|continue|lambda|yield)\b/g;
   escaped = escaped.replace(kw, '<span class="kw">$1</span>');
-  // Numbers
   escaped = escaped.replace(/\b(\d+\.?\d*)\b/g, '<span class="nu">$1</span>');
-  // Function calls
   escaped = escaped.replace(/\.([a-zA-Z_]\w*)\(/g, '.<span class="fn">$1</span>(');
 
   return escaped;
 }
 
-function updateValidationTab(validation, exec) {
-  const el = document.getElementById('tab-validation');
-
-  if (!validation) {
-    el.innerHTML = '<div class="validation-empty">No validation data. Generate a model first.</div>';
-    document.getElementById('issue-count').style.display = 'none';
-    return;
-  }
-
-  let html = '<div class="validation-header">';
-
-  if (validation.machinable) {
-    html += '<div class="badge badge-success">\u2713 MACHINABLE</div>';
-  } else {
-    html += '<div class="badge badge-error">\u2717 NOT MACHINABLE</div>';
-  }
-
-  if (validation.axis_recommendation) {
-    html += '<div class="validation-axis">Recommended: ' + validation.axis_recommendation + '</div>';
-  }
-
-  const errs = validation.error_count || 0;
-  const warns = validation.warning_count || 0;
-  html += '<div class="validation-axis" style="margin-left:auto">' + errs + ' errors, ' + warns + ' warnings</div>';
-  html += '</div>';
-
-  if (validation.issues && validation.issues.length > 0) {
-    html += '<div class="issue-list">';
-    for (const issue of validation.issues) {
-      const sev = issue.severity || 'info';
-      html += '<div class="issue-item ' + sev + '">';
-      html += '<span class="issue-severity ' + sev + '">' + sev.toUpperCase() + '</span>';
-      html += '<span class="issue-message">' + escapeHtml(issue.message) + '</span>';
-      html += '</div>';
-    }
-    html += '</div>';
-  }
-
-  el.innerHTML = html;
-
-  const totalIssues = (validation.issues || []).length;
-  const countEl = document.getElementById('issue-count');
-  if (totalIssues > 0) {
-    countEl.textContent = totalIssues;
-    countEl.style.display = '';
-  } else {
-    countEl.style.display = 'none';
-  }
-}
+// ── GALLERY ───────────────────────────────────────────
 
 function addToGallery(data) {
   galleryItems.unshift({
     name: data.part_name,
-    prompt: data.prompt,
     volume: data.execution?.volume_mm3,
     faces: data.execution?.face_count,
     machinable: data.validation?.machinable,
   });
-  loadGallery();
 }
 
-function loadGallery() {
-  const el = document.getElementById('tab-gallery');
-  const countEl = document.getElementById('gallery-count');
+function openGallery() {
+  renderGallery();
+  document.getElementById('gallery-modal').classList.add('visible');
+}
+
+function closeGallery() {
+  document.getElementById('gallery-modal').classList.remove('visible');
+}
+
+function renderGallery() {
+  const grid = document.getElementById('gallery-grid');
 
   if (galleryItems.length === 0) {
-    el.innerHTML = '<div class="gallery-empty">No models generated yet.</div>';
-    countEl.style.display = 'none';
+    grid.innerHTML = '<div class="gallery-empty">No models generated yet.</div>';
     return;
   }
 
-  countEl.textContent = galleryItems.length;
-  countEl.style.display = '';
-
   let html = '';
   for (const item of galleryItems) {
-    html += '<button class="gallery-card fade-in" onclick="loadGalleryItem(\'' + item.name + '\')">';
+    html += '<button class="gallery-card fade-in" onclick="loadGalleryItem(\'' + escapeHtml(item.name) + '\')">';
     html += '<div class="gallery-card-name">' + escapeHtml(item.name) + '</div>';
     html += '<div class="gallery-card-meta">';
     if (item.faces) html += '<span>' + item.faces + ' faces</span>';
@@ -1362,19 +1782,22 @@ function loadGallery() {
     html += '</div></button>';
   }
 
-  el.innerHTML = html;
+  grid.innerHTML = html;
 }
 
 async function loadGalleryItem(name) {
-  setLoading(true, 'LOADING MODEL...');
+  closeGallery();
+  setViewerLoading(true, 'LOADING MODEL...');
   try {
     await loadSTL('/api/models/' + name + '.stl');
   } catch (e) {
     console.warn('Failed to load:', e);
   }
-  setLoading(false);
+  setViewerLoading(false);
 }
 
+// ── UTILS ─────────────────────────────────────────────
+
 function escapeHtml(str) {
   const div = document.createElement('div');
   div.textContent = str;
@@ -1390,26 +1813,89 @@ async function checkServer() {
     if (resp.ok) {
       dot.style.background = 'var(--success)';
       dot.style.boxShadow = '0 0 6px var(--success)';
-      dot.title = 'MCP Server Connected';
+      dot.title = 'Server Connected';
     } else {
       dot.style.background = 'var(--warning)';
       dot.style.boxShadow = '0 0 6px var(--warning)';
-      dot.title = 'MCP Server Error';
+      dot.title = 'Server Error';
     }
   } catch {
     const dot = document.getElementById('status-dot');
     dot.style.background = 'var(--error)';
     dot.style.boxShadow = '0 0 6px var(--error)';
-    dot.title = 'MCP Server Offline';
+    dot.title = 'Server Offline';
   }
 }
 
-// ── KEYBOARD SHORTCUT ─────────────────────────────────
+// ── KEYBOARD / INPUT EVENTS ──────────────────────────
+
+const chatInput = document.getElementById('chat-input');
+
+chatInput.addEventListener('input', (e) => {
+  // Auto-resize
+  chatInput.style.height = 'auto';
+  chatInput.style.height = Math.min(chatInput.scrollHeight, 120) + 'px';
+
+  // Check for @mention
+  handleInputForMention(e);
+});
+
+chatInput.addEventListener('keydown', (e) => {
+  if (mentionActive) {
+    const dropdown = document.getElementById('mention-dropdown');
+    const visibleOptions = Array.from(dropdown.querySelectorAll('.mention-option'))
+      .filter(o => o.style.display !== 'none');
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      mentionIndex = (mentionIndex + 1) % visibleOptions.length;
+      updateMentionHighlight();
+      return;
+    }
+    if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      mentionIndex = (mentionIndex - 1 + visibleOptions.length) % visibleOptions.length;
+      updateMentionHighlight();
+      return;
+    }
+    if (e.key === 'Enter' || e.key === 'Tab') {
+      e.preventDefault();
+      const agent = visibleOptions[mentionIndex]?.dataset.agent;
+      if (agent) insertMention(agent);
+      return;
+    }
+    if (e.key === 'Escape') {
+      closeMentionDropdown();
+      return;
+    }
+  }
 
-document.getElementById('prompt-input').addEventListener('keydown', (e) => {
   if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
     e.preventDefault();
-    doGenerate();
+    sendFromInput();
+  }
+
+  // Regular enter sends (without shift)
+  if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.metaKey) {
+    e.preventDefault();
+    sendFromInput();
+  }
+});
+
+// Close modals on backdrop click
+document.getElementById('code-modal').addEventListener('click', (e) => {
+  if (e.target === document.getElementById('code-modal')) closeCodeModal();
+});
+
+document.getElementById('gallery-modal').addEventListener('click', (e) => {
+  if (e.target === document.getElementById('gallery-modal')) closeGallery();
+});
+
+// Escape to close modals
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') {
+    closeCodeModal();
+    closeGallery();
   }
 });