deploy: matrix-builder@ae902df6985a

Source: https://github.com/agent-matrix/matrix-builder/commit/ae902df6985a7d7a550b94dc5634e76db0109a45

Dockerfile

@@ -30,7 +30,10 @@ ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PYTHONPATH=/app/services/api \
     AGENT_GENERATOR_MODE=sdk MATRIX_DEFINITIONS_MODE=sdk \
     # Public, absolute API base so the coder prompt's "Fetch the Matrix Bundle" link is a real,
     # fetchable signed URL (build.matrixhub.io proxies /api/builder/* to this backend).
-    PUBLIC_API_BASE_URL=https://build.matrixhub.io/api/builder/api/v1
+    PUBLIC_API_BASE_URL=https://build.matrixhub.io/api/builder/api/v1 \
+    # Matrix Designer (the brain) runs as an internal service in this same container (started by
+    # start.sh). The control plane calls it here and falls back to deterministic generation if down.
+    MATRIX_DESIGNER_PORT=8077 MATRIX_DESIGNER_URL=http://127.0.0.1:8077
 WORKDIR /app
 RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-venv \
   && rm -rf /var/lib/apt/lists/* \

requirements.txt

@@ -36,3 +36,10 @@ httpx>=0.27
 jsonschema>=4.22
 ruff>=0.6
 mypy>=1.11
+
+# --- Matrix Designer (the brain) — installed alongside on Hugging Face ---
+# When this image is built (HF Space / Docker), Matrix Designer is installed and its
+# internal HTTP service is started by start.sh; the control plane reaches it at
+# MATRIX_DESIGNER_URL (default http://127.0.0.1:8077) and falls back to deterministic
+# generation if it's unavailable.
+matrix-designer[service] @ git+https://github.com/agent-matrix/matrix-designer.git

services/api/app/api/blueprints.py

@@ -1,13 +1,23 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Query
 
+from app.core.auth import optional_user_id
 from app.schemas.blueprint import (
     BlueprintCandidateResponse,
+    BlueprintChatRequest,
+    BlueprintChatResponse,
+    BlueprintDetails,
     BlueprintGenerationRequest,
     BlueprintResult,
+    BlueprintSavedResponse,
+    BlueprintSaveRequest,
+    DesignerCandidate,
+    DesignerCandidatesResponse,
 )
 from app.schemas.idea import IdeaRequest
+from app.services.designer_client import DesignerClient, get_designer_client
+from app.services.design_bundle_store import DesignBundleStore, get_design_bundle_store
 from app.services.matrix_builder_service import MatrixBuilderService
 from app.dependencies import get_matrix_builder_service
 
@@ -36,3 +46,67 @@ def generate_selected_blueprint(
     service: MatrixBuilderService = Depends(get_matrix_builder_service),
 ) -> BlueprintResult:
     return service.generate_blueprint(payload.idea_request, candidate_id=payload.candidate_id)
+
+
+# --- Matrix Designer: Blueprint Details page (fail-open via designer_client) -----------
+@router.get("/designer-candidates", response_model=DesignerCandidatesResponse)
+def designer_candidates(
+    idea: str = Query(..., description="The build idea to design the 3 blueprints for."),
+    designer: DesignerClient = Depends(get_designer_client),
+) -> DesignerCandidatesResponse:
+    data = designer.blueprints(idea)
+    return DesignerCandidatesResponse(
+        candidates=[DesignerCandidate.model_validate(c) for c in data.get("candidates", [])]
+    )
+
+
+@router.get("/{candidate_id}/details", response_model=BlueprintDetails)
+def blueprint_details(
+    candidate_id: str,
+    idea: str = Query(..., description="The build idea this blueprint is for."),
+    designer: DesignerClient = Depends(get_designer_client),
+) -> BlueprintDetails:
+    return BlueprintDetails.model_validate(designer.details(idea, candidate_id))
+
+
+@router.post("/{candidate_id}/chat", response_model=BlueprintChatResponse)
+def blueprint_chat(
+    candidate_id: str,
+    payload: BlueprintChatRequest,
+    designer: DesignerClient = Depends(get_designer_client),
+) -> BlueprintChatResponse:
+    out = designer.refine(payload.idea or "", payload.message, candidate_id)
+    details = out["details"].get(candidate_id) or out["details"].get("standard") or {}
+    return BlueprintChatResponse(reply=out.get("reply", ""), details=BlueprintDetails.model_validate(details))
+
+
+@router.post("/{candidate_id}/save", response_model=BlueprintDetails)
+def blueprint_save(
+    candidate_id: str,
+    payload: BlueprintSaveRequest,
+    owner_id: str = Depends(optional_user_id),
+    store: DesignBundleStore = Depends(get_design_bundle_store),
+) -> BlueprintDetails:
+    # batch-10 — persist the edited blueprint + chat for this build, owner-scoped (RLS), so
+    # reopening the build restores it. The contract only changes when the user saves.
+    if payload.build_id:
+        store.save(
+            owner_id=owner_id, build_id=payload.build_id, candidate_id=candidate_id,
+            idea=payload.idea or "", details=payload.details.model_dump(),
+            chat_history=[m.model_dump() for m in payload.details.chat_history],
+        )
+    return payload.details
+
+
+@router.get("/{candidate_id}/saved", response_model=BlueprintSavedResponse)
+def blueprint_saved(
+    candidate_id: str,
+    build_id: str = Query(..., description="The build to restore the saved blueprint for."),
+    owner_id: str = Depends(optional_user_id),
+    store: DesignBundleStore = Depends(get_design_bundle_store),
+) -> BlueprintSavedResponse:
+    rec = store.get(owner_id, build_id, candidate_id)
+    if not rec:
+        return BlueprintSavedResponse(found=False)
+    return BlueprintSavedResponse(found=True, idea=rec.get("idea", ""),
+                                  details=BlueprintDetails.model_validate(rec["details"]))

services/api/app/db/orm.py

@@ -39,6 +39,7 @@ RLS_TABLES: tuple[str, ...] = (
     "artifacts",
     "run_events",
     "gitpilot_runs",
+    "design_bundles",
 )
 
 
@@ -265,6 +266,28 @@ class GitPilotRun(Base):
     )
 
 
+class DesignBundleRecord(Base):
+    """A saved Matrix Designer Blueprint Details + chat for a build (batch-10).
+
+    Owner-scoped like every other workflow table. Keyed by (owner, build, candidate)
+    so reopening a build restores the same blueprint and Talk-to-blueprint history.
+    """
+
+    __tablename__ = "design_bundles"
+    id: Mapped[str] = _pk()
+    owner_id: Mapped[str] = mapped_column(String(36), nullable=False, index=True)
+    build_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    candidate_id: Mapped[str] = mapped_column(String(32), nullable=False)
+    idea: Mapped[str] = mapped_column(Text, default="")
+    details: Mapped[dict] = mapped_column(JSONB, default=dict)
+    chat_history: Mapped[list] = mapped_column(JSONB, default=list)
+    created_at: Mapped[datetime] = _ts()
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+    __table_args__ = (UniqueConstraint("owner_id", "build_id", "candidate_id", name="uq_design_bundle_owner_build_cand"),)
+
+
 __all__ = [
     "Base",
     "RLS_TABLES",
@@ -279,4 +302,5 @@ __all__ = [
     "RunEvent",
     "Artifact",
     "GitPilotRun",
+    "DesignBundleRecord",
 ]

services/api/app/schemas/blueprint.py

@@ -66,3 +66,91 @@ class BlueprintResult(StrictModel):
     tasks: list[BlueprintTask] = Field(default_factory=list)
     acceptance_commands: list[str] = Field(default_factory=list)
     standards_lock_ref: str = "MATRIX_STANDARDS.lock"
+
+
+# --- Matrix Designer: Blueprint Details (the dashboard the Details page renders) -------
+# Lenient models (ignore extra keys) so designer output maps cleanly even as it evolves.
+from pydantic import BaseModel  # noqa: E402
+
+
+class DesignerArchitectureNode(BaseModel):
+    name: str
+    description: str = ""
+    dependencies: list[str] = Field(default_factory=list)
+
+
+class DesignerFilePlanItem(BaseModel):
+    path: str
+    description: str = ""
+
+
+class DesignerBatch(BaseModel):
+    id: str
+    name: str
+    purpose: str = ""
+    tasks: list[str] = Field(default_factory=list)
+    allowed_files: list[str] = Field(default_factory=list)
+    depends_on: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    validation_checks: list[str] = Field(default_factory=list)
+    must_not_change: list[str] = Field(default_factory=list)
+
+
+class DesignerChatMessage(BaseModel):
+    id: str = ""
+    role: str = "blueprint"
+    content: str = ""
+    timestamp: str = ""
+
+
+class BlueprintDetails(BaseModel):
+    candidate_id: str
+    overview: str = ""
+    architecture: list[DesignerArchitectureNode] = Field(default_factory=list)
+    batches: list[DesignerBatch] = Field(default_factory=list)
+    file_plan: list[DesignerFilePlanItem] = Field(default_factory=list)
+    matrix_rules: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    validation_plan: list[str] = Field(default_factory=list)
+    risks: list[str] = Field(default_factory=list)
+    assumptions: list[str] = Field(default_factory=list)
+    design_brain: str | None = None
+    chat_history: list[DesignerChatMessage] = Field(default_factory=list)
+
+
+class BlueprintChatRequest(BaseModel):
+    message: str
+    idea: str | None = None
+
+
+class BlueprintChatResponse(BaseModel):
+    reply: str
+    details: BlueprintDetails
+
+
+class BlueprintSaveRequest(BaseModel):
+    idea: str | None = None
+    build_id: str | None = None
+    details: BlueprintDetails
+
+
+class BlueprintSavedResponse(BaseModel):
+    found: bool = False
+    idea: str = ""
+    details: BlueprintDetails | None = None
+
+
+class DesignerCandidate(BaseModel):
+    id: str
+    tier: str
+    title: str
+    summary: str = ""
+    file_count: int = 1
+    difficulty: str = "Medium"
+    estimate: str = "unknown"
+    stack: list[str] = Field(default_factory=list)
+    recommended: bool = False
+
+
+class DesignerCandidatesResponse(BaseModel):
+    candidates: list[DesignerCandidate] = Field(default_factory=list)

services/api/app/services/design_bundle_store.py

@@ -0,0 +1,105 @@
+"""Persistence for saved Matrix Designer blueprints + chat (batch-10).
+
+Stores the chosen blueprint's Details and Talk-to-blueprint chat per build, owner-scoped,
+so reopening a build restores the same state across devices.
+
+Backed by Postgres when ``DATABASE_URL`` is configured AND the ``design_bundles`` table
+exists (RLS-isolated per user); falls back to an in-memory store otherwise. Persistence is
+best-effort and must never break the Details page, so a missing table degrades to memory.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.exc import SQLAlchemyError
+
+from app.db.engine import is_configured, session_scope
+from app.db.orm import DesignBundleRecord
+
+logger = logging.getLogger("matrix_builder.design_bundle_store")
+
+# In-memory fallback, keyed by (owner, build, candidate) so isolation matches the DB's RLS.
+_MEM: dict[tuple[str, str, str], dict[str, Any]] = {}
+_LOCK = threading.Lock()
+_DB_OK: bool | None = None
+
+
+def _db_usable() -> bool:
+    global _DB_OK
+    if not is_configured():
+        return False
+    if _DB_OK is None:
+        try:
+            with session_scope() as session:
+                session.execute(select(DesignBundleRecord.id).limit(1))
+            _DB_OK = True
+        except SQLAlchemyError:
+            logger.warning("design_bundles table unavailable (migration not applied?); using in-memory store")
+            _DB_OK = False
+    return _DB_OK
+
+
+class DesignBundleStore:
+    def save(self, owner_id: str, build_id: str, candidate_id: str, idea: str,
+             details: dict[str, Any], chat_history: list[Any]) -> dict[str, Any]:
+        record = {
+            "owner_id": owner_id, "build_id": build_id, "candidate_id": candidate_id,
+            "idea": idea, "details": details, "chat_history": chat_history,
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+        }
+        if _db_usable():
+            try:
+                with session_scope(user_id=owner_id) as session:
+                    existing = session.execute(
+                        select(DesignBundleRecord).where(
+                            DesignBundleRecord.build_id == build_id,
+                            DesignBundleRecord.candidate_id == candidate_id,
+                        )
+                    ).scalar_one_or_none()
+                    if existing is None:
+                        session.add(DesignBundleRecord(
+                            id=str(uuid.uuid4()), owner_id=owner_id, build_id=build_id,
+                            candidate_id=candidate_id, idea=idea, details=details, chat_history=chat_history,
+                        ))
+                    else:
+                        existing.idea = idea
+                        existing.details = details
+                        existing.chat_history = chat_history
+                return record
+            except SQLAlchemyError:
+                logger.exception("design bundle save failed; falling back to memory")
+        with _LOCK:
+            _MEM[(owner_id, build_id, candidate_id)] = record
+        return record
+
+    def get(self, owner_id: str, build_id: str, candidate_id: str) -> dict[str, Any] | None:
+        if _db_usable():
+            try:
+                with session_scope(user_id=owner_id) as session:
+                    row = session.execute(
+                        select(DesignBundleRecord).where(
+                            DesignBundleRecord.build_id == build_id,
+                            DesignBundleRecord.candidate_id == candidate_id,
+                        )
+                    ).scalar_one_or_none()
+                    if row is not None:
+                        return {"owner_id": row.owner_id, "build_id": row.build_id, "candidate_id": row.candidate_id,
+                                "idea": row.idea, "details": row.details, "chat_history": row.chat_history}
+                    return None
+            except SQLAlchemyError:
+                logger.exception("design bundle get failed; falling back to memory")
+        with _LOCK:
+            return _MEM.get((owner_id, build_id, candidate_id))
+
+
+_STORE = DesignBundleStore()
+
+
+def get_design_bundle_store() -> DesignBundleStore:
+    return _STORE

services/api/app/services/designer_client.py

@@ -0,0 +1,196 @@
+"""Designer client — bridges Matrix Builder's control plane to Matrix Designer.
+
+Resolution order (fail-open, never 500):
+  1. HTTP service at ``MATRIX_DESIGNER_URL`` (the matrix-designer FastAPI service)
+  2. the ``matrix_designer`` package if importable in-process
+  3. a built-in deterministic fallback, so the Details page always has data even when
+     the brain is unavailable or the Matrix Designer toggle is off.
+
+All three return the same shape: ``{candidates, details, matrix_rules}`` where ``details``
+maps candidate_id → a Blueprint Details dict (the page's dashboard data).
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+DESIGNER_URL = os.environ.get("MATRIX_DESIGNER_URL", "").rstrip("/")
+RMD_RULES = [
+    "RMD-101: AI coders are workers, not architects.",
+    "RMD-103: Control files are protected.",
+    "RMD-111: Acceptance criteria are law.",
+]
+_TIERS = [
+    ("minimal", "Minimal", "Easy", "a weekend", 0.55, False),
+    ("standard", "Standard", "Medium", "about one week", 1.0, True),
+    ("production", "Production", "Hard", "about three weeks", 1.6, False),
+]
+
+
+class DesignerClient:
+    def __init__(self, url: str = DESIGNER_URL) -> None:
+        self.url = url
+
+    # -- public API ---------------------------------------------------------------------
+    def blueprints(self, idea: str, references=None, constraints=None) -> Dict[str, Any]:
+        return self._call("/design/blueprints", {"idea": idea, "references": references, "constraints": constraints},
+                          fallback=lambda: self._fallback_blueprints(idea))
+
+    def details(self, idea: str, candidate_id: str) -> Dict[str, Any]:
+        data = self.blueprints(idea)
+        return data["details"].get(candidate_id) or data["details"].get("standard") or {}
+
+    def refine(self, idea: str, message: str, candidate_id: str = "standard") -> Dict[str, Any]:
+        return self._call("/design/refine", {"idea": idea, "message": message, "candidate_id": candidate_id},
+                          fallback=lambda: self._fallback_refine(idea, message, candidate_id))
+
+    # -- resolution ---------------------------------------------------------------------
+    def _call(self, path: str, payload: Dict[str, Any], fallback) -> Dict[str, Any]:
+        if self.url:
+            try:
+                import httpx  # local import keeps it optional
+                r = httpx.post(f"{self.url}{path}", json=payload, timeout=8.0)
+                if r.status_code == 200:
+                    data = r.json()
+                    if not data.get("error"):
+                        return data
+            except Exception:
+                pass  # fall through to in-process / deterministic
+        try:
+            return self._via_import(path, payload)
+        except Exception:
+            return fallback()
+
+    def _via_import(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        from matrix_designer.graph import design_blueprints, refine, run_design  # type: ignore
+        if path.endswith("blueprints"):
+            out = design_blueprints(payload["idea"], payload.get("references"), payload.get("constraints"))
+            out.pop("_state", None)
+            return out
+        state = run_design(payload["idea"])
+        out = refine(state, payload["message"], payload.get("candidate_id", "standard"))
+        out.pop("_state", None)
+        return out
+
+    # -- deterministic fallback (self-contained) ---------------------------------------
+    def _fallback_blueprints(self, idea: str) -> Dict[str, Any]:
+        domain = self._domain(idea)
+        stack = self._stack(domain)
+        full = self._roadmap(domain)
+        candidates: List[Dict[str, Any]] = []
+        details: Dict[str, Any] = {}
+        for cid, tier, diff, est, scale, rec in _TIERS:
+            n = max(3, round(len(full) * scale))
+            batches = full[:n] if n <= len(full) else full + self._extra(len(full), n - len(full))
+            candidates.append({
+                "id": cid, "tier": tier,
+                "title": f"{tier} {'Matrix Bundle' if cid == 'standard' else 'controlled blueprint'}",
+                "summary": f"{'Recommended ' if rec else ''}controlled blueprint for: {idea.strip()[:90]}",
+                "file_count": max(8, round(len(self._files(domain)) * (2 + scale * 4))),
+                "difficulty": diff, "estimate": est, "stack": stack, "recommended": rec,
+            })
+            details[cid] = {
+                "candidate_id": cid,
+                "overview": f"This {tier.lower()} blueprint builds {idea.strip()[:120]}. Delivered in ordered, validated batches.",
+                "architecture": self._architecture(domain) if cid != "minimal" else self._architecture(domain)[:2],
+                "batches": batches,
+                "file_plan": self._files(domain),
+                "matrix_rules": RMD_RULES,
+                "acceptance_criteria": ["builds and runs", "core flow works with tests", "Matrix validation approves the build"],
+                "validation_plan": ["lint", "typecheck", "unit tests", "allowed-file check", "Matrix commit check"],
+                "risks": ["external credentials may be required"],
+                "assumptions": ["original assets only" if domain == "web-game" else "auth required if data is sensitive"],
+                "design_brain": f"Deterministic fallback · {len(batches)} batches · tier {tier}.",
+                "chat_history": [],
+            }
+        return {"candidates": candidates, "details": details, "matrix_rules": RMD_RULES, "violations": []}
+
+    def _fallback_refine(self, idea: str, message: str, candidate_id: str) -> Dict[str, Any]:
+        data = self._fallback_blueprints(idea)
+        det = data["details"].get(candidate_id, data["details"]["standard"])
+        m = message.lower()
+        if any(k in m for k in ("add", "boss", "level", "analytic", "audit", "auth", "dashboard")):
+            nid = f"batch-{len(det['batches']) + 1:02d}"
+            name = "Boss encounter" if "boss" in m else "Refinement"
+            det["batches"].append({"id": nid, "name": name, "purpose": f"Added from chat: {message.strip()}",
+                                   "tasks": [message.strip()], "allowed_files": ["src/**"], "depends_on": [],
+                                   "acceptance_criteria": ["feature works", "no runtime errors"], "validation_checks": ["unit tests"], "must_not_change": []})
+            reply = f"Added {nid} — {name}. Review and Save latest edits."
+        elif any(k in m for k in ("reduce", "simpler", "remove", "drop")) and len(det["batches"]) > 3:
+            dropped = det["batches"].pop()
+            reply = f"Reduced scope — removed {dropped['name']}."
+        else:
+            reply = "Noted. Save latest edits to keep this."
+        return {"reply": reply, "details": data["details"], "candidates": data["candidates"]}
+
+    # -- tiny domain heuristics --------------------------------------------------------
+    @staticmethod
+    def _domain(idea: str) -> str:
+        s = idea.lower()
+        if any(k in s for k in ("game", "platformer", "phaser", "arcade")):
+            return "web-game"
+        if any(k in s for k in ("api", "fastapi", "service", "endpoint")):
+            return "api"
+        return "web-app"
+
+    @staticmethod
+    def _stack(domain: str) -> List[str]:
+        return {"web-game": ["Phaser 3", "TypeScript", "Vite"], "api": ["FastAPI", "PostgreSQL", "Docker"]}.get(
+            domain, ["Next.js", "FastAPI", "PostgreSQL", "Docker"])
+
+    @staticmethod
+    def _architecture(domain: str) -> List[Dict[str, Any]]:
+        if domain == "web-game":
+            return [{"name": "Web Client (Phaser)", "description": "Canvas game", "dependencies": []},
+                    {"name": "Asset pipeline", "description": "Original art", "dependencies": ["Web Client (Phaser)"]},
+                    {"name": "Level engine", "description": "Data-driven levels", "dependencies": ["Web Client (Phaser)"]},
+                    {"name": "CI / Pages", "description": "Build + deploy", "dependencies": []}]
+        return [{"name": "Web App", "description": "Frontend", "dependencies": []},
+                {"name": "API", "description": "Business logic", "dependencies": ["Web App"]},
+                {"name": "Database", "description": "Storage", "dependencies": ["API"]},
+                {"name": "Worker / Queue", "description": "Background jobs", "dependencies": ["API"]},
+                {"name": "Admin Dashboard", "description": "Ops & analytics", "dependencies": ["Web App", "API"]}]
+
+    @staticmethod
+    def _files(domain: str) -> List[Dict[str, str]]:
+        if domain == "web-game":
+            return [{"path": p, "description": d} for p, d in [
+                ("src/scenes", "Boot/Preload/Game/…"), ("src/levels", "level data + builder"),
+                ("src/entities", "Player, enemies, Coin"), ("public/assets", "original art"), ("README.md", "overview")]]
+        return [{"path": p, "description": d} for p, d in [
+            ("apps/web", "Web app and dashboard"), ("services/api", "API and business logic"),
+            ("services/worker", "Background jobs"), ("packages/shared", "Shared types"), ("db", "Migrations"), ("README.md", "overview")]]
+
+    @staticmethod
+    def _roadmap(domain: str) -> List[Dict[str, Any]]:
+        if domain == "web-game":
+            spec = [("Game foundation", ["vite.config.ts", "src/main.ts"]), ("Asset pipeline", ["scripts/gen_assets.py", "public/assets/**"]),
+                    ("Tilemap world", ["src/levels/**"]), ("Player & controls", ["src/entities/Player.ts"]),
+                    ("Enemies & power-ups", ["src/entities/**"]), ("HUD & gate", ["src/ui/HUD.ts"]),
+                    ("Campaign & boss", ["src/levels/episodes.ts"]), ("Polish & release", [".github/workflows/deploy.yml"])]
+        else:
+            spec = [("Foundation", ["apps/web/**", "services/api/**"]), ("Integrations", ["services/api/**"]),
+                    ("Workflow & logic", ["services/api/**"]), ("Admin & analytics", ["apps/web/**"]),
+                    ("Hardening & deploy", ["docker-compose.yml", ".github/**"]), ("Validation & release", ["tests/**"])]
+        out = []
+        for i, (name, allowed) in enumerate(spec, 1):
+            out.append({"id": f"batch-{i:02d}", "name": name, "purpose": f"{name}.", "tasks": [name],
+                        "allowed_files": allowed, "depends_on": [f"batch-{i-1:02d}"] if i > 1 else [],
+                        "acceptance_criteria": ["builds", "feature works", "no runtime errors"],
+                        "validation_checks": ["lint", "typecheck", "tests"], "must_not_change": []})
+        return out
+
+    @staticmethod
+    def _extra(start: int, count: int) -> List[Dict[str, Any]]:
+        names = ["Observability", "Performance pass", "Security review", "Docs & onboarding", "Accessibility"]
+        out = []
+        for k in range(count):
+            i = start + k + 1
+            out.append({"id": f"batch-{i:02d}", "name": names[k % len(names)], "purpose": "Production hardening.",
+                        "tasks": ["hardening"], "allowed_files": ["**"], "depends_on": [f"batch-{i-1:02d}"],
+                        "acceptance_criteria": ["meets the production bar"], "validation_checks": ["tests"], "must_not_change": []})
+        return out
+
+
+def get_designer_client() -> DesignerClient:
+    return DesignerClient()

services/api/migrations/versions/0006_design_bundles.py

@@ -0,0 +1,49 @@
+"""Saved Matrix Designer Blueprint Details + chat per build (batch-10).
+
+Owner-scoped table that persists the chosen blueprint's details and the
+Talk-to-blueprint chat history for a build, so reopening it restores the same
+state across devices — RLS-isolated per user like every other workflow table.
+"""
+
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0006_design_bundles"
+down_revision = "0005_gitpilot_runs"
+branch_labels = None
+depends_on = None
+
+_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS design_bundles (
+  id            text PRIMARY KEY,
+  owner_id      text NOT NULL,
+  build_id      text NOT NULL,
+  candidate_id  text NOT NULL,
+  idea          text NOT NULL DEFAULT '',
+  details       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  chat_history  jsonb NOT NULL DEFAULT '[]'::jsonb,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT uq_design_bundle_owner_build_cand UNIQUE (owner_id, build_id, candidate_id)
+)
+"""
+
+
+def upgrade() -> None:
+    op.execute(_TABLE_SQL)
+    op.execute("CREATE INDEX IF NOT EXISTS ix_design_bundles_owner ON design_bundles(owner_id)")
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_design_bundles_owner_build "
+        "ON design_bundles(owner_id, build_id)"
+    )
+    op.execute("ALTER TABLE design_bundles ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE design_bundles FORCE ROW LEVEL SECURITY")
+    op.execute(
+        "CREATE POLICY design_bundles_owner ON design_bundles "
+        "USING (owner_id = app_current_user()) WITH CHECK (owner_id = app_current_user())"
+    )
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE IF EXISTS design_bundles CASCADE")

start.sh

@@ -1,7 +1,20 @@
 #!/usr/bin/env sh
 set -e
+# Matrix Designer (the brain) — internal HTTP service the control plane calls to design the
+# blueprints/batches. Best-effort: if it fails to boot, the control plane falls back to its
+# deterministic generator, so the app still works. Bound to localhost; never public.
+export MATRIX_DESIGNER_PORT="${MATRIX_DESIGNER_PORT:-8077}"
+export MATRIX_DESIGNER_URL="${MATRIX_DESIGNER_URL:-http://127.0.0.1:${MATRIX_DESIGNER_PORT}}"
+if python -c "import matrix_designer" 2>/dev/null; then
+  echo "-> starting Matrix Designer service on 127.0.0.1:${MATRIX_DESIGNER_PORT}"
+  ( cd /tmp && python -m matrix_designer.service ) &
+else
+  echo "-> Matrix Designer not installed; control plane will use the deterministic generator"
+fi
+
 # Backend (internal, same-origin target of the Next.js /api/builder rewrite).
 python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --proxy-headers &
+
 # Frontend (public). Next standalone honors PORT/HOSTNAME.
 cd /app/web
 export PORT="${PORT:-7860}" HOSTNAME=0.0.0.0

web/src/app/matrix-builder/MatrixBuilderClient.tsx

@@ -12,6 +12,11 @@ import { createBundleFiles } from "@/lib/matrix-bundle";
 import { createBlueprintCandidates } from "@/lib/matrix-demo-data";
 import { toUiBundleFiles, toUiCandidates } from "@/lib/engine-map";
 import { briefToIdea, enhanceProjectBrief, enrichBlueprintCandidates, explainValidationFindings, isOllaBridgeAssistAvailable, type EnrichmentMap } from "@/lib/ai-provider-manager";
+import { isMatrixDesignerEnabled } from "@/lib/ai-settings-store";
+import { fetchBlueprintDetails, saveBlueprintDetails, type DesignerCandidate } from "@/lib/blueprint-client";
+import { getCapabilities } from "@/lib/capabilities";
+import { generateCandidates } from "@/lib/blueprint-engine";
+import { useBlueprintWorkspace } from "@/lib/blueprint-store";
 import UploadExistingPlanModal, { type UploadSelection } from "@/components/matrix-builder/UploadExistingPlanModal";
 import {
   downloadBundleZip,
@@ -54,7 +59,7 @@ import type { ProjectBriefContract } from "@/lib/workflow-types";
 import type { CoderId } from "@/types/coder";
 import type { ValidationReportContract } from "@/types/contracts";
 
-type Phase = "hero" | "scanning" | "candidates" | "bundle" | "submit" | "running" | "validation" | "timeline" | "complete";
+type Phase = "hero" | "scanning" | "candidates" | "details" | "bundle" | "submit" | "running" | "validation" | "timeline" | "complete";
 
 // Paths the AI coder reports as changed (parsed from the pasted result) → validated against the
 // contract. status defaults to "modified".
@@ -736,7 +741,7 @@ function LandingHero({ idea, setIdea, generate, onUpload }: { idea: string; setI
   );
 }
 
-function CandidateCard({ candidate, choose, enrichment }: { candidate: BlueprintCandidate; choose: (candidate: BlueprintCandidate) => void; enrichment?: { displayName?: string; displaySummary?: string } }) {
+function CandidateCard({ candidate, choose, details, enrichment }: { candidate: BlueprintCandidate; choose: (candidate: BlueprintCandidate) => void; details: (candidate: BlueprintCandidate) => void; enrichment?: { displayName?: string; displaySummary?: string } }) {
   // Display-only: the deterministic candidate still drives bundle generation. AI may only soften
   // the visible name/summary; an explicit badge tells the user the wording was AI-assisted.
   const name = enrichment?.displayName ?? candidate.name;
@@ -755,7 +760,19 @@ function CandidateCard({ candidate, choose, enrichment }: { candidate: Blueprint
         <span className="mb-tag n">{candidate.time}</span>
       </div>
       <div className="cand-stack">{candidate.stack.map((stack) => <span className="mb-tag" key={stack}>{stack}</span>)}</div>
-      <button className="cand-choose" type="button">Choose this <MatrixIcon size={16}>{icons.arrow}</MatrixIcon></button>
+      {/* Secondary action: inspect the full plan before choosing. Primary stays "Choose this". */}
+      <div className="cand-actions">
+        <button
+          className="cand-details"
+          type="button"
+          onClick={(e) => { e.stopPropagation(); details(candidate); }}
+        >
+          Details
+        </button>
+        <button className="cand-choose" type="button" onClick={(e) => { e.stopPropagation(); choose(candidate); }}>
+          Choose this <MatrixIcon size={16}>{icons.arrow}</MatrixIcon>
+        </button>
+      </div>
     </article>
   );
 }
@@ -1584,12 +1601,280 @@ function BuildComplete({
   );
 }
 
+// ---------------------------------------------------------------------------------------------
+// Blueprint Details — a calm planning room for one blueprint. Cards stay simple; this page answers
+// "what exactly will this path build?". All sections are derived client-side from the deterministic
+// candidate + the idea (no backend route yet); the Matrix contract is never changed here.
+// ---------------------------------------------------------------------------------------------
+
+// Map a Matrix Designer candidate card onto the UI's BlueprintCandidate shape.
+function designerToUiCandidate(dc: DesignerCandidate): BlueprintCandidate {
+  return {
+    id: dc.id as BlueprintCandidate["id"],
+    tier: dc.tier as BlueprintCandidate["tier"],
+    name: dc.title,
+    summary: dc.summary,
+    stack: dc.stack,
+    files: dc.file_count,
+    difficulty: dc.difficulty as BlueprintCandidate["difficulty"],
+    time: dc.estimate,
+    standards: [],
+    recommended: dc.recommended,
+  };
+}
+
+// Map an architecture-node name to one of the existing line icons.
+function archIcon(name: string): IconDefinition {
+  const s = name.toLowerCase();
+  if (/api|backend|service/.test(s)) return icons.cpu;
+  if (/data|db|postgres|mysql|storage|mongo/.test(s)) return icons.cube;
+  if (/worker|queue|job/.test(s)) return icons.refresh;
+  if (/deploy|ci|pages|docker|kubernetes/.test(s)) return icons.shield;
+  if (/dashboard|admin|ui|doc/.test(s)) return icons.doc;
+  return icons.layers;
+}
+
+function BlueprintDetails({ candidate, subject, idea, designerOn, aiAssist, onBack, onChoose, onNotice }: {
+  candidate: BlueprintCandidate; subject: string; idea: string; designerOn: boolean; aiAssist: boolean;
+  onBack: () => void; onChoose: () => void; onNotice: (message: string) => void;
+}) {
+  // C0/C1/C2 — the workspace is a single client state object mutated by the in-browser engine.
+  // No fetch on the render path: generate + chat run locally, so the page is instant and works
+  // fully offline. (The server/LLM are optional enhancements, layered on via ws.setData later.)
+  const ws = useBlueprintWorkspace(candidate.id, idea);
+  const { data, messages, busy, dirty } = ws;
+  const [draft, setDraft] = useState("");
+  const [chatTab, setChatTab] = useState<"chat" | "activity">("chat");
+
+  // C5 — optional server sync behind a capability check. With no backend (offline / static
+  // hosting) this is a no-op and the UX is identical; with a backend it syncs the richer output.
+  useEffect(() => {
+    let active = true;
+    void getCapabilities().then((cap) => {
+      if (!active || !cap.server) return;            // no server → stay fully local
+      if (ws.data.chat_history.length > 0) return;   // don't clobber local edits
+      void fetchBlueprintDetails(candidate.id, idea, { useDesigner: designerOn })
+        .then((d) => { if (active) ws.setData(d); })
+        .catch(() => undefined);
+    });
+    return () => { active = false; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [candidate.id, idea, designerOn]);
+
+  function send() {
+    const text = draft.trim();
+    if (!text) return;
+    ws.applyInstruction(text); // instant, local, no network — sections patch from the engine
+    setDraft("");
+  }
+
+  function save() {
+    if (!dirty) { onNotice("No changes to save."); return; }
+    // Local state is already saved (localStorage). Server persistence is gated on a capability
+    // check so offline makes zero requests.
+    void getCapabilities().then((cap) => {
+      if (cap.server) void saveBlueprintDetails(candidate.id, idea, data).catch(() => undefined);
+    });
+    ws.markSaved();
+    onNotice("Blueprint updated.");
+  }
+
+  // Activity feed derived from the live state — what the engine changed.
+  const activity = [
+    `${data.batches.length} build batches planned`,
+    `${data.architecture.length} architecture components`,
+    `${data.file_plan.length} planned files`,
+    ...messages.filter((m) => m.role === "blueprint").map((m) => m.content),
+  ];
+
+  const batches = data.batches;
+  const architecture = data.architecture;
+  const filePlan = data.file_plan;
+
+  return (
+    <div className="bd-surface">
+    <div className="l-wrap mb-page bd-page">
+      <div className="bd-crumb reveal">
+        <span className="bd-step">Step 1 · Choose a blueprint</span>
+        <span className="bd-sep">/</span><span>{candidate.tier}</span>
+        <span className="bd-sep">/</span><span className="bd-cur">Details</span>
+      </div>
+
+      <div className="bd-head reveal">
+        <div className="bd-head-main">
+          <h1 className="bd-h1">{candidate.name}{candidate.recommended && <span className="bd-rec">Recommended</span>}</h1>
+          <p className="bd-lede">{candidate.summary}</p>
+          <div className="bd-pills">
+            <span className="mb-tag">Stack: {candidate.stack.join(", ")}</span>
+            <span className="mb-tag n">{candidate.files} files</span>
+            <span className="mb-tag n">{candidate.difficulty}</span>
+            <span className="mb-tag n">{candidate.time}</span>
+            {aiAssist && <span className="mb-tag bd-ai">AI assist</span>}
+            <span className="mb-tag bd-lock"><MatrixIcon size={12}>{icons.shield}</MatrixIcon> RMD locked</span>
+          </div>
+        </div>
+      </div>
+
+      <div className="bd-grid">
+        {/* LEFT — overview, batches, chat (history + bottom composer) */}
+        <div className="bd-col">
+          <section className="bd-card reveal">
+            <div className="bd-card-h"><MatrixIcon size={16}>{icons.doc}</MatrixIcon><h3>Blueprint overview</h3></div>
+            <div className="bd-ov-split">
+              <p className="bd-p">{data.overview}</p>
+              <div className="bd-ov">
+                <div className="bd-ov-scope"><span className="bd-ov-k">Scope</span><span className="bd-ov-v">{idea}</span></div>
+                <div className="bd-ov-row">
+                  <div><span className="bd-ov-k">Quality</span><span className="bd-ov-v">{candidate.tier}</span></div>
+                  <div><span className="bd-ov-k">Outcome</span><span className="bd-ov-v">{data.acceptance_criteria[0] ?? "builds and runs"}</span></div>
+                </div>
+              </div>
+            </div>
+          </section>
+
+          <section className="bd-card reveal">
+            <div className="bd-card-h"><MatrixIcon size={16}>{icons.layers}</MatrixIcon><h3>Build batches</h3>
+              <span className="bd-card-sub">{`${batches.length} controlled batches · built in order`}</span></div>
+            <ol className="bd-batches">
+              {batches.map((b, i) => (
+                <li className="bd-batch" key={b.id}>
+                  <span className="bd-batch-n">{String(i + 1).padStart(2, "0")}</span>
+                  <div className="bd-batch-body">
+                    <div className="bd-batch-top">
+                      <span className="bd-batch-name">{b.name}</span>
+                      <span className="bd-batch-desc">{b.purpose}</span>
+                    </div>
+                    <div className="bd-batch-meta">
+                      <span className="bd-batch-tag">Allowed: {b.allowed_files.slice(0, 2).join(", ")}{b.allowed_files.length > 2 ? "…" : ""}</span>
+                      {b.acceptance_criteria[0] && <span className="bd-batch-tag">Accept: {b.acceptance_criteria[0]}</span>}
+                    </div>
+                  </div>
+                  <span className="bd-batch-status"><span className="bd-status-dot" />Planned</span>
+                </li>
+              ))}
+            </ol>
+          </section>
+
+          {/* Chat — history + always-visible bottom composer (ChatGPT/Claude style) */}
+          <section className="bd-card reveal bd-chat">
+            <div className="bd-chat-head">
+              <div className="bd-chat-tabs">
+                <button className={`bd-tab${chatTab === "chat" ? " on" : ""}`} type="button" onClick={() => setChatTab("chat")}>Chat</button>
+                <button className={`bd-tab${chatTab === "activity" ? " on" : ""}`} type="button" onClick={() => setChatTab("activity")}>Activity</button>
+              </div>
+              {dirty && <span className="bd-unsaved" title="You have unsaved edits">Unsaved</span>}
+              <button className={`bd-save${dirty ? " on" : ""}`} type="button" onClick={save} title="Save latest edits" aria-label="Save latest edits">
+                <MatrixIcon size={15}>{icons.download}</MatrixIcon>
+              </button>
+            </div>
+
+            <div className="bd-chat-log">
+              {chatTab === "chat" ? (
+                messages.length === 0 ? (
+                  <p className="bd-chat-empty">Ask Blueprints to refine the architecture, batches, or scope — the plan updates live.</p>
+                ) : (
+                  messages.map((m) => (
+                    <div className={`bd-msg ${m.role}`} key={m.id}>
+                      <span className="bd-msg-av">{m.role === "user" ? "M" : <MatrixIcon size={14}>{icons.cube}</MatrixIcon>}</span>
+                      <div className="bd-msg-body">
+                        <div className="bd-msg-head"><span className="bd-msg-role">{m.role === "user" ? "You" : "Matrix Builder"}</span>{m.time && <span className="bd-msg-time">{m.time}</span>}</div>
+                        <div className="bd-msg-text">{m.content}</div>
+                      </div>
+                    </div>
+                  ))
+                )
+              ) : (
+                <ul className="bd-activity">
+                  {activity.map((a, i) => (
+                    <li className="bd-activity-row" key={`${i}-${a}`}><span className="bd-activity-dot" />{a}</li>
+                  ))}
+                </ul>
+              )}
+              {busy && chatTab === "chat" && (
+                <div className="bd-msg blueprint"><span className="bd-msg-av"><MatrixIcon size={14}>{icons.cube}</MatrixIcon></span>
+                  <div className="bd-msg-body"><div className="bd-msg-head"><span className="bd-msg-role">Matrix Builder</span></div><div className="bd-msg-text bd-typing">thinking…</div></div></div>
+              )}
+            </div>
+
+            <div className="bd-composer">
+              <button className="bd-composer-add" type="button" aria-label="Attach" title="Attach"><MatrixIcon size={16}>{icons.plus}</MatrixIcon></button>
+              <input className="bd-composer-input" value={draft} placeholder="Describe the change you want…" disabled={busy}
+                onChange={(e) => setDraft(e.target.value)} onKeyDown={(e) => { if (e.key === "Enter") send(); }} aria-label="Describe the change you want" />
+              <span className="bd-kbd" aria-hidden="true">⌘↵</span>
+              <button className="bd-composer-send" type="button" onClick={send} aria-label="Send" disabled={busy || !draft.trim()}>
+                <MatrixIcon size={16}>{icons.send}</MatrixIcon>
+              </button>
+            </div>
+          </section>
+        </div>
+
+        {/* RIGHT — sticky sidebar: architecture, file plan, matrix rules, design brain, actions */}
+        <aside className="bd-col bd-aside">
+          <section className="bd-card reveal">
+            <div className="bd-card-h"><MatrixIcon size={16}>{icons.git}</MatrixIcon><h3>Architecture</h3></div>
+            <div className="bd-arch">
+              {architecture.map((n) => (
+                <div className="bd-arch-node" key={n.name}>
+                  <span className="bd-arch-top"><span className="bd-arch-ic"><MatrixIcon size={15}>{archIcon(n.name)}</MatrixIcon></span><span className="bd-arch-label">{n.name}</span></span>
+                  <span className="bd-arch-sub">{n.description}</span>
+                </div>
+              ))}
+            </div>
+            <button className="bd-card-link" type="button" onClick={() => onNotice("Architecture detail view coming soon.")}>View details of Architecture <MatrixIcon size={13}>{icons.arrow}</MatrixIcon></button>
+          </section>
+
+          <section className="bd-card reveal">
+            <div className="bd-card-h"><MatrixIcon size={16}>{icons.doc}</MatrixIcon><h3>File plan</h3></div>
+            <ul className="bd-files">
+              {filePlan.map((f) => (
+                <li className="bd-file" key={f.path}><code className="bd-file-path">{f.path}</code><span className="bd-file-why">{f.description}</span></li>
+              ))}
+            </ul>
+          </section>
+
+          <section className="bd-card reveal">
+            <div className="bd-card-h"><MatrixIcon size={16}>{icons.shield}</MatrixIcon><h3>Matrix rules</h3></div>
+            <ul className="bd-rules">
+              {data.matrix_rules.map((rule) => (
+                <li key={rule}><MatrixIcon size={14}>{icons.check}</MatrixIcon> {rule.replace(/^RMD-\d+:\s*/, "")}</li>
+              ))}
+            </ul>
+          </section>
+
+          {designerOn && (
+            <section className="bd-card reveal bd-brain">
+              <div className="bd-card-h"><span className="bd-brain-ic">🧠</span><h3>Design Brain</h3>
+                <span className="bd-card-sub">Matrix Designer</span></div>
+              <span className="bd-brain-k">Product intent</span>
+              <p className="bd-brain-intent">{subject} — designed before batching so every batch fits the whole.</p>
+              {(data.risks.length > 0 || data.assumptions.length > 0) && (
+                <p className="bd-brain-note">{[...data.risks, ...data.assumptions].slice(0, 2).join(" · ")}</p>
+              )}
+              <button className="bd-card-link" type="button" onClick={() => setChatTab("activity")}>View details <MatrixIcon size={13}>{icons.arrow}</MatrixIcon></button>
+            </section>
+          )}
+
+          <div className="bd-actions">
+            <button className="bd-back" type="button" onClick={onBack}><MatrixIcon size={15}>{icons.back}</MatrixIcon> Back to blueprints</button>
+            <button className="bd-choose" type="button" onClick={onChoose}>Choose this blueprint <MatrixIcon size={16}>{icons.arrow}</MatrixIcon></button>
+          </div>
+        </aside>
+      </div>
+    </div>
+    </div>
+  );
+}
+
 export default function MatrixBuilderClient({ initialBuild }: { initialBuild?: InitialBuild } = {}) {
   // When reopened from My Builds we land directly on the active build screen, reconstructed
   // from the persisted build, so the user keeps full context (no state is lost).
   const [phase, setPhase] = useState<Phase>(initialBuild ? "bundle" : "hero");
   const [idea, setIdea] = useState(initialBuild?.idea ?? "");
   const [scanIndex, setScanIndex] = useState(0);
+  // Blueprint Details view — the candidate being inspected, and whether the Matrix Designer
+  // enhancement is on (read from settings when the user opens Details, so it reflects the toggle).
+  const [detailsCandidate, setDetailsCandidate] = useState<BlueprintCandidate | null>(null);
+  const [designerOn, setDesignerOn] = useState(false);
   const [candidates, setCandidates] = useState<BlueprintCandidate[]>([]);
   const [candidatesLoaded, setCandidatesLoaded] = useState(false);
   // Optional Internal AI: display-only copy overrides keyed by candidate id; the deterministic
@@ -1689,6 +1974,11 @@ export default function MatrixBuilderClient({ initialBuild }: { initialBuild?: I
       }
       setCandidates(list);
       setCandidatesLoaded(true);
+      // Matrix Designer toggle ON: source the 3 cards from the in-browser engine (no network).
+      // The server is an optional enhancement; the client engine is the primary, instant path.
+      if (isMatrixDesignerEnabled()) {
+        setCandidates(generateCandidates(ideaText).map(designerToUiCandidate));
+      }
       // Optional Internal AI assist (fail-open): improve display copy only, after candidates show.
       void enrichBlueprintCandidates(
         ideaText,
@@ -1712,6 +2002,14 @@ export default function MatrixBuilderClient({ initialBuild }: { initialBuild?: I
   }, [phase, scanIndex, candidatesLoaded]);
 
   // Step 2 — generate the chosen candidate's Matrix Bundle on the engine (the real file manifest).
+  // Open the premium Details view for a candidate (read the Designer toggle fresh each time).
+  const openDetails = (candidate: BlueprintCandidate) => {
+    setDetailsCandidate(candidate);
+    setDesignerOn(isMatrixDesignerEnabled());
+    setPhase("details");
+    window.scrollTo({ top: 0, behavior: "smooth" });
+  };
+
   const choose = (candidate: BlueprintCandidate) => {
     const localId = generateBundleId();
     setChosen(candidate);
@@ -2098,12 +2396,28 @@ export default function MatrixBuilderClient({ initialBuild }: { initialBuild?: I
               </details>
             )}
             <div className="cand-grid stag">
-              {candidates.map((candidate) => <CandidateCard key={candidate.id} candidate={candidate} choose={choose} enrichment={enrichedById[candidate.id]} />)}
+              {candidates.map((candidate) => <CandidateCard key={candidate.id} candidate={candidate} choose={choose} details={openDetails} enrichment={enrichedById[candidate.id]} />)}
             </div>
           </div>
         </>
       )}
 
+      {phase === "details" && detailsCandidate && (
+        <>
+          <BuilderBar onNew={reset} onNotice={showToast} />
+          <BlueprintDetails
+            candidate={detailsCandidate}
+            subject={headingSubject}
+            idea={effectiveIdea}
+            designerOn={designerOn}
+            aiAssist={isOllaBridgeAssistAvailable()}
+            onBack={() => setPhase("candidates")}
+            onChoose={() => choose(detailsCandidate)}
+            onNotice={showToast}
+          />
+        </>
+      )}
+
       {phase === "bundle" && chosen && (
         <BundleResult
           candidate={chosen}

web/src/components/settings/AiConfigurationSection.tsx

@@ -57,6 +57,16 @@ export default function AiConfigurationSection() {
     setDefaultCoder(next);
   }
 
+  // Optional Matrix Designer enhancement — persist immediately, like the default-coder preference.
+  function onToggleMatrixDesigner(enabled: boolean) {
+    setSettings((s) => {
+      const next = { ...s, matrixDesigner: { ...s.matrixDesigner, enabled } };
+      saveAISettings(next);
+      return next;
+    });
+    setSaveNote(null);
+  }
+
   const ob = settings.ollabridge;
   const localhost = isLocalhostLike(ob.baseUrl);
 
@@ -188,6 +198,28 @@ export default function AiConfigurationSection() {
         <p className="ai-help">AI assist is off. Matrix Builder will run deterministically.</p>
       )}
 
+      {/* Optional enhancement: Matrix Designer — the design brain. Default OFF. */}
+      <div className="ai-divider" />
+      <div className="settings-field-group">
+        <label className="ai-toggle md-toggle">
+          <input
+            type="checkbox"
+            checked={settings.matrixDesigner.enabled}
+            onChange={(e) => onToggleMatrixDesigner(e.target.checked)}
+          />
+          <span>
+            🧠 Matrix Designer <span className="md-badge">optional</span>
+            <em className="ai-toggle-hint">
+              {settings.matrixDesigner.enabled
+                ? settings.provider === "ollabridge" && settings.mode === "assisted"
+                  ? "On — uses your Internal AI (OllaBridge) to design the full batch plan and coder prompts for the next stages. The Matrix contract is unchanged."
+                  : "On — but it stays deterministic until Internal AI (OllaBridge) assist above is enabled; then it designs the batch plan with AI."
+                : "Off — the design brain that plans every batch before you build. Turn on to inspect a full plan on each blueprint’s Details page."}
+            </em>
+          </span>
+        </label>
+      </div>
+
       {settings.provider === "ollabridge" && (
         <>
           {/* Assisted-mode toggle */}

web/src/lib/__tests__/blueprint-engine.test.ts

@@ -0,0 +1,75 @@
+// C1 — the in-browser blueprint engine is pure and deterministic (no network).
+//
+// Run with: npm run test. These cover the local orchestrator the workspace uses on every chat
+// instruction, so the Details page mutates instantly and works fully offline.
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { apply, generate, generateCandidates } from "@/lib/blueprint-engine";
+
+describe("blueprint-engine.generate", () => {
+  it("builds a game blueprint for a Phaser idea", () => {
+    const d = generate("standard", "an 8-episode Phaser platformer on GitHub Pages");
+    assert.equal(d.candidate_id, "standard");
+    assert.ok(d.batches.length >= 6);
+    assert.ok(d.architecture.some((n) => /phaser/i.test(n.name)));
+    assert.ok(d.batches.every((b) => b.allowed_files.length && b.acceptance_criteria.length));
+  });
+
+  it("ramps minimal < standard < production", () => {
+    const idea = "A SaaS dashboard with auth";
+    const n = (id: string) => generate(id, idea).batches.length;
+    assert.ok(n("minimal") < n("standard"));
+    assert.ok(n("standard") < n("production"));
+  });
+
+  it("generateCandidates returns the three tiers", () => {
+    const cs = generateCandidates("a platformer game");
+    assert.deepEqual(cs.map((c) => c.id), ["minimal", "standard", "production"]);
+    assert.ok(cs.some((c) => c.recommended));
+  });
+});
+
+describe("blueprint-engine.apply (local orchestrator)", () => {
+  const base = () => generate("standard", "an 8-episode Phaser platformer");
+
+  it("adds a boss batch", () => {
+    const before = base();
+    const res = apply(before, "add a boss level");
+    assert.equal(res.data.batches.length, before.batches.length + 1);
+    assert.match(res.data.batches.at(-1)!.name, /boss/i);
+    assert.ok(res.updatedSections.includes("batches"));
+    // purity: the input is untouched
+    assert.equal(before.batches.length, base().batches.length);
+  });
+
+  it("reduces scope", () => {
+    const before = base();
+    const res = apply(before, "make this smaller");
+    assert.equal(res.data.batches.length, before.batches.length - 1);
+  });
+
+  it("splits a batch into two", () => {
+    const before = base();
+    const res = apply(before, "split batch 3 into two");
+    assert.equal(res.data.batches.length, before.batches.length + 1);
+    assert.ok(res.data.batches.some((b) => /part 1/.test(b.name)));
+    assert.ok(res.data.batches.some((b) => /part 2/.test(b.name)));
+    // batches stay renumbered batch-01..NN
+    res.data.batches.forEach((b, i) => assert.equal(b.id, `batch-${String(i + 1).padStart(2, "0")}`));
+  });
+
+  it("switches the stack (architecture + file plan)", () => {
+    const res = apply(generate("standard", "a web app"), "use FastAPI instead of Express");
+    assert.ok(res.updatedSections.includes("architecture"));
+    assert.ok(res.updatedSections.includes("filePlan"));
+    assert.ok(res.data.architecture.some((n) => /fastapi/i.test(n.description)));
+  });
+
+  it("adds an architecture component (worker/queue)", () => {
+    const res = apply(generate("minimal", "a web app"), "add a worker queue");
+    assert.ok(res.data.architecture.some((n) => /worker/i.test(n.name)));
+    assert.ok(res.updatedSections.includes("architecture"));
+  });
+});

web/src/lib/__tests__/blueprint-persistence.test.ts

@@ -0,0 +1,70 @@
+// C4 — localStorage-first persistence round-trips the workspace; C3 — AI refine is opt-in.
+//
+// Run with: npm run test. These prove a reload restores the workspace with no server, and that
+// the optional AI enhancement stays off (deterministic, no network) unless explicitly enabled.
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+
+import { generate } from "@/lib/blueprint-engine";
+import { clearWorkspace, loadWorkspace, saveWorkspace, workspaceKey } from "@/lib/blueprint-persistence";
+import { refineWithAI } from "@/lib/ai-refine";
+
+function installFakeWindow(): Map<string, string> {
+  const store = new Map<string, string>();
+  (globalThis as Record<string, unknown>).window = {
+    localStorage: {
+      getItem: (k: string) => (store.has(k) ? store.get(k)! : null),
+      setItem: (k: string, v: string) => void store.set(k, String(v)),
+      removeItem: (k: string) => void store.delete(k),
+    },
+  };
+  return store;
+}
+
+beforeEach(() => installFakeWindow());
+afterEach(() => { delete (globalThis as Record<string, unknown>).window; });
+
+describe("C4 persistence", () => {
+  it("save → load restores the workspace (reload with no server)", () => {
+    const idea = "an 8-episode Phaser platformer";
+    const key = workspaceKey(idea, "standard");
+    const data = generate("standard", idea);
+    data.chat_history = [{ id: "u1", role: "user", content: "add a boss level", timestamp: "" }];
+    saveWorkspace(key, data);
+
+    const restored = loadWorkspace(key);
+    assert.ok(restored);
+    assert.equal(restored!.candidate_id, "standard");
+    assert.equal(restored!.batches.length, data.batches.length);
+    assert.equal(restored!.chat_history[0].content, "add a boss level");
+  });
+
+  it("keys are stable per idea + candidate and isolated across them", () => {
+    assert.equal(workspaceKey("idea A", "standard"), workspaceKey("idea A", "standard"));
+    assert.notEqual(workspaceKey("idea A", "standard"), workspaceKey("idea B", "standard"));
+    assert.notEqual(workspaceKey("idea A", "standard"), workspaceKey("idea A", "minimal"));
+  });
+
+  it("clear removes the saved workspace", () => {
+    const key = workspaceKey("x", "standard");
+    saveWorkspace(key, generate("standard", "x"));
+    clearWorkspace(key);
+    assert.equal(loadWorkspace(key), null);
+  });
+
+  it("missing / corrupt entries load as null (never throw)", () => {
+    assert.equal(loadWorkspace(workspaceKey("never-saved", "standard")), null);
+    const ls = (globalThis as unknown as { window: { localStorage: Storage } }).window.localStorage;
+    ls.setItem(workspaceKey("bad", "standard"), "{not json");
+    assert.equal(loadWorkspace(workspaceKey("bad", "standard")), null);
+  });
+});
+
+describe("C3 AI refine (optional, fail-open)", () => {
+  it("returns null when assist is unavailable — deterministic result stands", async () => {
+    // No OllaBridge settings / no signed-in user in the test env → assist is off.
+    const out = await refineWithAI(generate("standard", "a web app"), "add audit logging");
+    assert.equal(out, null);
+  });
+});

web/src/lib/__tests__/offline-workspace.test.ts

@@ -0,0 +1,87 @@
+// C6 — Proof: the Blueprint workspace is fully offline.
+//
+// With the network blocked, generate → edit → persist → reload all succeed and the data path
+// makes ZERO requests. The capability probe degrades to {server:false} without throwing, so no
+// per-interaction request is ever attempted. This is the unit-level equivalent of an
+// airplane-mode browser e2e (the app has no Playwright harness).
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+
+import { apply, generate } from "@/lib/blueprint-engine";
+import { loadWorkspace, saveWorkspace, workspaceKey } from "@/lib/blueprint-persistence";
+import { getCapabilities, resetCapabilities } from "@/lib/capabilities";
+
+let fetchCalls = 0;
+const realFetch = globalThis.fetch;
+
+function installOfflineWindow(): void {
+  const store = new Map<string, string>();
+  (globalThis as Record<string, unknown>).window = {
+    localStorage: {
+      getItem: (k: string) => (store.has(k) ? store.get(k)! : null),
+      setItem: (k: string, v: string) => void store.set(k, String(v)),
+      removeItem: (k: string) => void store.delete(k),
+    },
+  };
+  // Network is blocked: every request rejects (like airplane mode / refused connection).
+  (globalThis as Record<string, unknown>).fetch = (..._args: unknown[]) => {
+    fetchCalls++;
+    return Promise.reject(new Error("ERR_NETWORK_BLOCKED"));
+  };
+}
+
+beforeEach(() => { fetchCalls = 0; resetCapabilities(); installOfflineWindow(); });
+afterEach(() => {
+  delete (globalThis as Record<string, unknown>).window;
+  (globalThis as Record<string, unknown>).fetch = realFetch;
+});
+
+describe("C6 — fully offline workspace", () => {
+  it("generate → edit → persist → reload, with ZERO network on the data path", () => {
+    const idea = "an 8-episode Phaser platformer on GitHub Pages";
+    const key = workspaceKey(idea, "standard");
+
+    // generate (local)
+    let data = generate("standard", idea);
+    const before = data.batches.length;
+
+    // edit (local engine) — add a boss
+    const res = apply(data, "add a boss level");
+    data = res.data;
+    assert.equal(data.batches.length, before + 1);
+    assert.match(data.batches.at(-1)!.name, /boss/i);
+
+    // persist (localStorage) + reload (new read)
+    saveWorkspace(key, data);
+    const reloaded = loadWorkspace(key);
+    assert.ok(reloaded);
+    assert.equal(reloaded!.batches.length, before + 1);
+    assert.match(reloaded!.batches.at(-1)!.name, /boss/i);
+
+    // the entire data path touched the network zero times
+    assert.equal(fetchCalls, 0);
+  });
+
+  it("capability probe degrades to {server:false} without throwing", async () => {
+    const cap = await getCapabilities({ timeoutMs: 50 });
+    assert.equal(cap.server, false);
+    assert.equal(fetchCalls, 1); // exactly one probe, caught — not per interaction
+    // cached: a second call does not probe again
+    const again = await getCapabilities({ timeoutMs: 50 });
+    assert.equal(again.server, false);
+    assert.equal(fetchCalls, 1);
+  });
+
+  it("a second session restores the same workspace from localStorage", () => {
+    const idea = "a SaaS dashboard with auth";
+    const key = workspaceKey(idea, "production");
+    const data = apply(generate("production", idea), "add audit logging").data;
+    saveWorkspace(key, data);
+
+    // "reload": a fresh read of the same key returns the identical plan
+    const restored = loadWorkspace(key);
+    assert.deepEqual(restored!.batches.map((b) => b.name), data.batches.map((b) => b.name));
+    assert.equal(fetchCalls, 0);
+  });
+});

web/src/lib/ai-refine.ts

@@ -0,0 +1,73 @@
+// C3 — Optional AI enhancement for the Blueprint workspace.
+//
+// After the in-browser engine has ALREADY applied a chat instruction (instant, governed), this
+// makes ONE provider-agnostic call (through OllaBridge, which can bridge to any model) to refine
+// only the EXPLANATION — `overview` / `designBrain` prose and a short `reply`. It is:
+//   • optional   — returns null when assist is off / no user (deterministic result stands)
+//   • bounded    — a hard timeout; a slow model never blocks the UI
+//   • fail-open  — any error/parse-failure returns null
+//   • safe       — it can never change architecture, batches, or files (governance unchanged)
+
+import { isOllaBridgeAssistAvailable, sendAIMessage } from "@/lib/ai-provider-manager";
+import type { BlueprintDetailsData } from "@/types/blueprint-state";
+
+export interface AIRefinement {
+  reply?: string;
+  overview?: string;
+  designBrain?: string;
+}
+
+const SYSTEM =
+  "You refine the EXPLANATION of a software blueprint after a change was applied. You may improve " +
+  "the 'overview' and 'designBrain' prose and write a short 'reply' confirming the change. You MUST " +
+  "NOT invent or change architecture, batches, files, or stack. Return ONLY compact JSON of the form " +
+  '{"reply":"...","overview":"...","designBrain":"..."} with no extra text.';
+
+export async function refineWithAI(
+  data: BlueprintDetailsData,
+  instruction: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<AIRefinement | null> {
+  if (!isOllaBridgeAssistAvailable()) return null;
+  const timeoutMs = opts.timeoutMs ?? 6000;
+  const user =
+    `Instruction just applied: ${instruction}\n` +
+    `Current overview: ${data.overview}\n` +
+    `Batches: ${data.batches.map((b) => b.name).join(", ")}\n` +
+    `Architecture: ${data.architecture.map((n) => n.name).join(", ")}`;
+  try {
+    const text = await withTimeout(
+      sendAIMessage([
+        { role: "system", content: SYSTEM },
+        { role: "user", content: user },
+      ]),
+      timeoutMs,
+    );
+    const json = extractJson(text);
+    if (!json) return null;
+    const out: AIRefinement = {};
+    if (typeof json.reply === "string" && json.reply.trim()) out.reply = json.reply.trim();
+    if (typeof json.overview === "string" && json.overview.trim()) out.overview = json.overview.trim();
+    if (typeof json.designBrain === "string" && json.designBrain.trim()) out.designBrain = json.designBrain.trim();
+    return Object.keys(out).length ? out : null;
+  } catch {
+    return null; // fail-open: the deterministic local result stands
+  }
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error("ai-refine timeout")), ms);
+    p.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+  });
+}
+
+function extractJson(text: string): Record<string, unknown> | null {
+  const m = text.match(/\{[\s\S]*\}/);
+  if (!m) return null;
+  try {
+    return JSON.parse(m[0]) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}

web/src/lib/ai-settings-store.ts

@@ -22,6 +22,7 @@ export function mergeAISettings(raw: unknown): MatrixAISettings {
   const mode = r.mode === "assisted" ? "assisted" : "deterministic";
   const authMode =
     ob.authMode === "api_key" || ob.authMode === "local-trust" ? ob.authMode : "pairing";
+  const md = (r.matrixDesigner ?? {}) as Record<string, unknown>;
   return {
     provider,
     mode,
@@ -33,9 +34,17 @@ export function mergeAISettings(raw: unknown): MatrixAISettings {
       pairToken: typeof ob.pairToken === "string" ? ob.pairToken : "",
       deviceId: typeof ob.deviceId === "string" ? ob.deviceId : "",
     },
+    matrixDesigner: {
+      enabled: md.enabled === true,
+    },
   };
 }
 
+// Convenience: is the optional Matrix Designer enhancement turned on?
+export function isMatrixDesignerEnabled(): boolean {
+  return getAISettings().matrixDesigner.enabled;
+}
+
 export function getAISettings(): MatrixAISettings {
   if (typeof window === "undefined") return { ...DEFAULT_AI_SETTINGS };
   const raw = window.localStorage.getItem(AI_SETTINGS_STORAGE_KEY);

web/src/lib/blueprint-client.ts

@@ -0,0 +1,116 @@
+// Optional server bridge for the Blueprint Details workspace.
+//
+// The workspace is driven entirely by the in-browser engine + store (C0/C1/C2) — these fetch
+// wrappers are the OPTIONAL enhancement path: when a control plane is configured they sync /
+// fetch real designer output, and on any failure they fall back to the local engine. Nothing on
+// the render path depends on them.
+
+import { apiBaseUrl } from "./api-client";
+import { authHeaders } from "./auth-token";
+import * as engine from "@/lib/blueprint-engine";
+
+export type {
+  ArchitectureNode,
+  BlueprintDetailsData,
+  DesignerBatch,
+  DesignerCandidate,
+  DesignerChatMessage,
+  FilePlanItem,
+} from "@/types/blueprint-state";
+
+import type { BlueprintDetailsData, DesignerCandidate } from "@/types/blueprint-state";
+
+// Local engine derivations re-exported for back-compat with existing callers.
+export const deriveLocalDetails = engine.generate;
+export const deriveLocalCandidates = engine.generateCandidates;
+
+/** The 3 blueprint cards. `useDesigner=false` (toggle off) / offline → local engine. */
+export async function fetchDesignerCandidates(
+  idea: string,
+  opts: { useDesigner?: boolean } = {},
+): Promise<DesignerCandidate[]> {
+  if (opts.useDesigner === false) return engine.generateCandidates(idea);
+  try {
+    const url = `${apiBaseUrl}/api/v1/blueprints/designer-candidates?idea=${encodeURIComponent(idea)}`;
+    const res = await fetch(url, { headers: { ...authHeaders() } });
+    if (!res.ok) throw new Error(`designer-candidates ${res.status}`);
+    const body = (await res.json()) as { candidates?: DesignerCandidate[] };
+    return body.candidates && body.candidates.length ? body.candidates : engine.generateCandidates(idea);
+  } catch {
+    return engine.generateCandidates(idea);
+  }
+}
+
+/** Optional: fetch real designer Details. Offline / toggle off → local engine. */
+export async function fetchBlueprintDetails(
+  candidateId: string,
+  idea: string,
+  opts: { useDesigner?: boolean } = {},
+): Promise<BlueprintDetailsData> {
+  if (opts.useDesigner === false) return engine.generate(candidateId, idea);
+  try {
+    const url = `${apiBaseUrl}/api/v1/blueprints/${candidateId}/details?idea=${encodeURIComponent(idea)}`;
+    const res = await fetch(url, { headers: { ...authHeaders() } });
+    if (!res.ok) throw new Error(`details ${res.status}`);
+    return (await res.json()) as BlueprintDetailsData;
+  } catch {
+    return engine.generate(candidateId, idea);
+  }
+}
+
+/** Optional server refinement; the workspace already applied the local engine result. */
+export async function sendBlueprintChat(
+  candidateId: string,
+  idea: string,
+  message: string,
+): Promise<{ reply: string; details: BlueprintDetailsData }> {
+  try {
+    const url = `${apiBaseUrl}/api/v1/blueprints/${candidateId}/chat`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...authHeaders() },
+      body: JSON.stringify({ idea, message }),
+    });
+    if (!res.ok) throw new Error(`chat ${res.status}`);
+    return (await res.json()) as { reply: string; details: BlueprintDetailsData };
+  } catch {
+    const res = engine.apply(engine.generate(candidateId, idea), message);
+    return { reply: res.reply, details: res.data };
+  }
+}
+
+export async function saveBlueprintDetails(
+  candidateId: string,
+  idea: string,
+  details: BlueprintDetailsData,
+  buildId?: string,
+): Promise<BlueprintDetailsData> {
+  try {
+    const url = `${apiBaseUrl}/api/v1/blueprints/${candidateId}/save`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...authHeaders() },
+      body: JSON.stringify({ idea, build_id: buildId, details }),
+    });
+    if (!res.ok) throw new Error(`save ${res.status}`);
+    return (await res.json()) as BlueprintDetailsData;
+  } catch {
+    return details; // offline: kept locally (localStorage persistence is C4)
+  }
+}
+
+/** Restore a previously-saved blueprint + chat for a build (owner-scoped). */
+export async function fetchSavedBlueprint(
+  candidateId: string,
+  buildId: string,
+): Promise<BlueprintDetailsData | null> {
+  try {
+    const url = `${apiBaseUrl}/api/v1/blueprints/${candidateId}/saved?build_id=${encodeURIComponent(buildId)}`;
+    const res = await fetch(url, { headers: { ...authHeaders() } });
+    if (!res.ok) throw new Error(`saved ${res.status}`);
+    const body = (await res.json()) as { found: boolean; details: BlueprintDetailsData | null };
+    return body.found ? body.details : null;
+  } catch {
+    return null;
+  }
+}

web/src/lib/blueprint-engine.ts

@@ -0,0 +1,336 @@
+// C1 — Browser blueprint-engine: deterministic, pure, no network.
+//
+// `generate(idea)` builds the initial blueprint; `apply(state, instruction)` is the local
+// orchestrator that mutates the plan from a chat instruction (add / reduce / split batches,
+// switch stack, add components) and returns the patched state + a reply + which sections
+// changed. This is the primary path — the LLM (C3) only *refines* this result, optionally.
+
+import {
+  type ArchitectureNode,
+  type BlueprintDetailsData,
+  type BlueprintSection,
+  type DesignerBatch,
+  type DesignerCandidate,
+  type FilePlanItem,
+  RMD_RULES,
+} from "@/types/blueprint-state";
+
+type Domain = "web-game" | "api" | "web-app";
+type Tier = { id: string; difficulty: string; scale: number };
+
+const TIERS: Tier[] = [
+  { id: "minimal", difficulty: "Easy", scale: 0.55 },
+  { id: "standard", difficulty: "Medium", scale: 1.0 },
+  { id: "production", difficulty: "Hard", scale: 1.6 },
+];
+
+// ---- generate -------------------------------------------------------------------------
+export function generate(candidateId: string, idea: string): BlueprintDetailsData {
+  const tier = TIERS.find((t) => t.id === candidateId) ?? TIERS[1];
+  const domain = inferDomain(idea);
+  const full = roadmap(domain);
+  const n = Math.max(3, Math.round(full.length * tier.scale));
+  const batches = n <= full.length ? full.slice(0, n) : full.concat(extra(full.length, n - full.length));
+  return {
+    candidate_id: candidateId,
+    overview: `This ${candidateId} blueprint builds ${idea.trim().slice(0, 120)}. Delivered in ordered, validated batches.`,
+    architecture: candidateId === "minimal" ? architecture(domain).slice(0, 2) : architecture(domain),
+    batches,
+    file_plan: filePlan(domain),
+    matrix_rules: RMD_RULES,
+    acceptance_criteria: ["builds and runs", "core flow works with tests", "Matrix validation approves the build"],
+    validation_plan: ["lint", "typecheck", "unit tests", "allowed-file check", "Matrix commit check"],
+    risks: ["external credentials may be required"],
+    assumptions: [domain === "web-game" ? "original assets only" : "auth required if data is sensitive"],
+    design_brain: `Client engine · ${batches.length} batches · ${candidateId}.`,
+    chat_history: [],
+  };
+}
+
+export function generateCandidates(idea: string): DesignerCandidate[] {
+  const domain = inferDomain(idea);
+  const stack = stackFor(domain);
+  const meta: [string, string, string, string, boolean][] = [
+    ["minimal", "Minimal", "Easy", "a weekend", false],
+    ["standard", "Standard", "Medium", "about one week", true],
+    ["production", "Production", "Hard", "about three weeks", false],
+  ];
+  return meta.map(([id, tier, difficulty, estimate, recommended]) => ({
+    id, tier, difficulty, estimate, recommended, stack,
+    title: `${tier} ${id === "standard" ? "Matrix Bundle" : "controlled blueprint"}`,
+    summary: `${recommended ? "Recommended " : ""}controlled blueprint for: ${idea.trim().slice(0, 90)}`,
+    file_count: generate(id, idea).batches.length * (id === "production" ? 7 : 5),
+  }));
+}
+
+// ---- apply — the local orchestrator ---------------------------------------------------
+export interface ApplyResult {
+  data: BlueprintDetailsData;
+  reply: string;
+  updatedSections: BlueprintSection[];
+}
+
+export function apply(state: BlueprintDetailsData, instruction: string): ApplyResult {
+  const text = instruction.trim();
+  const m = text.toLowerCase();
+  const data = clone(state);
+  const sections = new Set<BlueprintSection>();
+  let reply = "Noted. Save latest edits to keep this.";
+
+  const nextId = () => `batch-${String(data.batches.length + 1).padStart(2, "0")}`;
+
+  // 1) split a batch into two
+  if (/\bsplit\b/.test(m)) {
+    const idx = pickBatchIndex(data, m);
+    if (idx >= 0) {
+      const b = data.batches[idx];
+      const partB: DesignerBatch = {
+        ...clone(b), id: nextId(), name: `${b.name} (part 2)`, depends_on: [b.id],
+      };
+      data.batches[idx] = { ...b, name: `${b.name} (part 1)` };
+      data.batches.splice(idx + 1, 0, partB);
+      renumber(data);
+      sections.add("batches");
+      reply = `Split “${b.name}” into two batches. Review and Save latest edits.`;
+      return finish(data, sections, reply);
+    }
+  }
+
+  // 2) reduce / remove scope
+  if (/\b(reduce|smaller|simpler|remove|drop|trim)\b/.test(m)) {
+    if (data.batches.length > 3) {
+      const dropped = data.batches.pop()!;
+      sections.add("batches");
+      reply = `Reduced scope — removed “${dropped.name}”.`;
+    } else {
+      reply = "Already at the minimal batch set.";
+    }
+    return finish(data, sections, reply);
+  }
+
+  // 3) switch stack / framework  (architecture + file plan)
+  const stackHit = detectStack(m);
+  if (stackHit) {
+    applyStack(data, stackHit);
+    sections.add("architecture");
+    sections.add("filePlan");
+    reply = `Switched to ${stackHit.label}. Updated architecture and file plan.`;
+    return finish(data, sections, reply);
+  }
+
+  // 4) add an architecture component
+  const comp = detectComponent(m);
+  if (comp) {
+    if (!data.architecture.some((n) => n.name === comp.name)) {
+      data.architecture.push(comp);
+      sections.add("architecture");
+    }
+    // also add a batch to build it
+    data.batches.push(makeBatch(nextId(), comp.batchName, comp.allowed, text));
+    renumber(data);
+    sections.add("batches");
+    reply = `Added ${comp.name} (architecture + a build batch).`;
+    return finish(data, sections, reply);
+  }
+
+  // 5) add a feature / level / boss → a scoped batch
+  if (/\b(add|include|introduce|boss|level|enemy|feature|analytic|metric|audit|auth|dashboard|observab)\b/.test(m)) {
+    const name = featureName(m);
+    data.batches.push(makeBatch(nextId(), name, ["src/**"], text));
+    renumber(data);
+    sections.add("batches");
+    reply = `Added ${data.batches[data.batches.length - 1].id} — ${name}. Review and Save latest edits.`;
+    return finish(data, sections, reply);
+  }
+
+  return finish(data, sections, reply);
+}
+
+// ---- helpers --------------------------------------------------------------------------
+function finish(data: BlueprintDetailsData, sections: Set<BlueprintSection>, reply: string): ApplyResult {
+  if (sections.has("batches")) {
+    data.design_brain = `Client engine · ${data.batches.length} batches · ${data.candidate_id}.`;
+    sections.add("designBrain");
+  }
+  return { data, reply, updatedSections: [...sections] };
+}
+
+function makeBatch(id: string, name: string, allowed: string[], from: string): DesignerBatch {
+  return {
+    id, name, purpose: `Added from chat: ${from}`, tasks: [from],
+    allowed_files: allowed, depends_on: [], acceptance_criteria: ["feature works", "no runtime errors"],
+    validation_checks: ["unit tests"], must_not_change: [],
+  };
+}
+
+function renumber(data: BlueprintDetailsData): void {
+  data.batches.forEach((b, i) => { b.id = `batch-${String(i + 1).padStart(2, "0")}`; });
+}
+
+function pickBatchIndex(data: BlueprintDetailsData, m: string): number {
+  const num = m.match(/\b(\d{1,2})\b/);
+  if (num) {
+    const i = parseInt(num[1], 10) - 1;
+    if (i >= 0 && i < data.batches.length) return i;
+  }
+  return data.batches.length - 1;
+}
+
+function featureName(m: string): string {
+  if (/boss/.test(m)) return "Boss encounter";
+  if (/level/.test(m)) return "Extra level";
+  if (/analytic|metric/.test(m)) return "Analytics & metrics";
+  if (/audit/.test(m)) return "Audit logging";
+  if (/auth/.test(m)) return "Auth & access";
+  if (/dashboard/.test(m)) return "Admin dashboard";
+  if (/observab/.test(m)) return "Observability";
+  return "Refinement";
+}
+
+function detectStack(m: string): { label: string; nodes: ArchitectureNode[]; files: FilePlanItem[] } | null {
+  if (/next\.?js|nextjs/.test(m)) {
+    return { label: "Next.js", nodes: [{ name: "Web App", description: "Next.js", dependencies: [] }],
+      files: [{ path: "apps/web", description: "Next.js app" }] };
+  }
+  if (/fastapi/.test(m)) {
+    return { label: "FastAPI", nodes: [{ name: "API", description: "FastAPI", dependencies: ["Web App"] }],
+      files: [{ path: "services/api", description: "FastAPI service" }] };
+  }
+  if (/\bexpress\b|\bnode\b/.test(m) && /(use|switch|instead)/.test(m)) {
+    return { label: "Express", nodes: [{ name: "API", description: "Express", dependencies: ["Web App"] }],
+      files: [{ path: "services/api", description: "Express service" }] };
+  }
+  return null;
+}
+
+function applyStack(data: BlueprintDetailsData, hit: { nodes: ArchitectureNode[]; files: FilePlanItem[] }): void {
+  for (const node of hit.nodes) {
+    const i = data.architecture.findIndex((n) => n.name === node.name);
+    if (i >= 0) data.architecture[i] = node; else data.architecture.push(node);
+  }
+  for (const f of hit.files) {
+    const i = data.file_plan.findIndex((p) => p.path === f.path);
+    if (i >= 0) data.file_plan[i] = f; else data.file_plan.unshift(f);
+  }
+}
+
+function detectComponent(m: string): (ArchitectureNode & { batchName: string; allowed: string[] }) | null {
+  if (/worker|queue/.test(m)) {
+    return { name: "Worker / Queue", description: "Background jobs", dependencies: ["API"], batchName: "Worker & queue", allowed: ["services/worker/**"] };
+  }
+  if (/redis|cache/.test(m)) {
+    return { name: "Cache (Redis)", description: "Caching layer", dependencies: ["API"], batchName: "Caching layer", allowed: ["services/api/**"] };
+  }
+  if (/database|postgres|\bdb\b/.test(m) && /(add|use)/.test(m)) {
+    return { name: "Database", description: "Persistent storage", dependencies: ["API"], batchName: "Data model & migrations", allowed: ["db/**"] };
+  }
+  return null;
+}
+
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v)) as T;
+}
+
+// ---- domain knowledge -----------------------------------------------------------------
+function inferDomain(idea: string): Domain {
+  const s = idea.toLowerCase();
+  if (/(game|platformer|phaser|arcade|canvas)/.test(s)) return "web-game";
+  if (/(api|fastapi|service|endpoint)/.test(s)) return "api";
+  return "web-app";
+}
+
+function stackFor(domain: Domain): string[] {
+  return domain === "web-game" ? ["Phaser 3", "TypeScript", "Vite"] : ["Next.js", "FastAPI", "PostgreSQL", "Docker"];
+}
+
+function architecture(domain: Domain): ArchitectureNode[] {
+  if (domain === "web-game") {
+    return [
+      { name: "Web Client (Phaser)", description: "Canvas game", dependencies: [] },
+      { name: "Asset pipeline", description: "Original art", dependencies: ["Web Client (Phaser)"] },
+      { name: "Level engine", description: "Data-driven levels", dependencies: ["Web Client (Phaser)"] },
+      { name: "CI / Pages", description: "Build + deploy", dependencies: [] },
+    ];
+  }
+  return [
+    { name: "Web App", description: "Frontend", dependencies: [] },
+    { name: "API", description: "Business logic", dependencies: ["Web App"] },
+    { name: "Database", description: "Storage", dependencies: ["API"] },
+    { name: "Worker / Queue", description: "Background jobs", dependencies: ["API"] },
+    { name: "Admin Dashboard", description: "Ops & analytics", dependencies: ["Web App", "API"] },
+  ];
+}
+
+function filePlan(domain: Domain): FilePlanItem[] {
+  if (domain === "web-game") {
+    return [
+      { path: "src/scenes", description: "Boot/Preload/Game/…" },
+      { path: "src/levels", description: "level data + builder" },
+      { path: "src/entities", description: "Player, enemies, Coin" },
+      { path: "public/assets", description: "original art" },
+      { path: "README.md", description: "overview" },
+    ];
+  }
+  return [
+    { path: "apps/web", description: "Web app and dashboard" },
+    { path: "services/api", description: "API and business logic" },
+    { path: "services/worker", description: "Background jobs" },
+    { path: "packages/shared", description: "Shared types" },
+    { path: "db", description: "Migrations" },
+    { path: "README.md", description: "overview" },
+  ];
+}
+
+function roadmap(domain: Domain): DesignerBatch[] {
+  const spec: [string, string[]][] =
+    domain === "web-game"
+      ? [
+          ["Game foundation", ["vite.config.ts", "src/main.ts"]],
+          ["Asset pipeline", ["scripts/gen_assets.py", "public/assets/**"]],
+          ["Tilemap world", ["src/levels/**"]],
+          ["Player & controls", ["src/entities/Player.ts"]],
+          ["Enemies & power-ups", ["src/entities/**"]],
+          ["HUD & gate", ["src/ui/HUD.ts"]],
+          ["Campaign & boss", ["src/levels/episodes.ts"]],
+          ["Polish & release", [".github/workflows/deploy.yml"]],
+        ]
+      : [
+          ["Foundation", ["apps/web/**", "services/api/**"]],
+          ["Integrations", ["services/api/**"]],
+          ["Workflow & logic", ["services/api/**"]],
+          ["Admin & analytics", ["apps/web/**"]],
+          ["Hardening & deploy", ["docker-compose.yml", ".github/**"]],
+          ["Validation & release", ["tests/**"]],
+        ];
+  return spec.map(([name, allowed], i): DesignerBatch => ({
+    id: `batch-${String(i + 1).padStart(2, "0")}`,
+    name,
+    purpose: `${name}.`,
+    tasks: [name],
+    allowed_files: allowed,
+    depends_on: i > 0 ? [`batch-${String(i).padStart(2, "0")}`] : [],
+    acceptance_criteria: ["builds", "feature works", "no runtime errors"],
+    validation_checks: ["lint", "typecheck", "tests"],
+    must_not_change: [],
+  }));
+}
+
+function extra(start: number, count: number): DesignerBatch[] {
+  const names = ["Observability", "Performance pass", "Security review", "Docs & onboarding", "Accessibility"];
+  const out: DesignerBatch[] = [];
+  for (let k = 0; k < count; k++) {
+    const i = start + k + 1;
+    out.push({
+      id: `batch-${String(i).padStart(2, "0")}`,
+      name: names[k % names.length],
+      purpose: "Production hardening.",
+      tasks: ["hardening"],
+      allowed_files: ["**"],
+      depends_on: [`batch-${String(i - 1).padStart(2, "0")}`],
+      acceptance_criteria: ["meets the production bar"],
+      validation_checks: ["tests"],
+      must_not_change: [],
+    });
+  }
+  return out;
+}

web/src/lib/blueprint-persistence.ts

@@ -0,0 +1,50 @@
+// C4 — localStorage-first persistence for the Blueprint workspace.
+//
+// The workspace autosaves its single state object (which already embeds the chat history) to
+// localStorage on every edit, keyed per idea + candidate. On mount the store rehydrates from it,
+// so a reload restores the workspace with no server. All access is guarded + best-effort: a
+// quota error or private-mode block degrades silently to in-memory only.
+
+import type { BlueprintDetailsData } from "@/types/blueprint-state";
+
+const PREFIX = "matrix-builder:blueprint:v1";
+
+function hash(s: string): string {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+export function workspaceKey(idea: string, candidateId: string): string {
+  return `${PREFIX}:${hash(idea.trim())}:${candidateId}`;
+}
+
+export function saveWorkspace(key: string, data: BlueprintDetailsData): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(data));
+  } catch {
+    /* quota / private mode — keep working in memory */
+  }
+}
+
+export function loadWorkspace(key: string): BlueprintDetailsData | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) return null;
+    const data = JSON.parse(raw) as BlueprintDetailsData;
+    return data && Array.isArray(data.batches) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearWorkspace(key: string): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+    /* ignore */
+  }
+}

web/src/lib/blueprint-store.ts

@@ -0,0 +1,106 @@
+// C0 — Blueprint workspace store: one live state object, mutated in the browser.
+//
+// `useBlueprintWorkspace` is the single source of truth for the Details page. It generates the
+// initial blueprint and applies chat instructions entirely via `blueprint-engine` (no network),
+// so the workspace is instant and works fully offline. Two optional enhancements layer on top:
+//   • C4 persistence — the state autosaves to localStorage and rehydrates on reload (no server).
+//   • C3 AI refine   — one bounded, fail-open call may improve the explanation prose afterward.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import * as engine from "@/lib/blueprint-engine";
+import { refineWithAI } from "@/lib/ai-refine";
+import { loadWorkspace, saveWorkspace, workspaceKey } from "@/lib/blueprint-persistence";
+import type { BlueprintDetailsData, ChatMessage } from "@/types/blueprint-state";
+
+const now = () => new Date().toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+
+function messagesFrom(data: BlueprintDetailsData): ChatMessage[] {
+  return (data.chat_history ?? []).map((m, i) => ({ id: m.id || `h-${i}`, role: m.role, content: m.content }));
+}
+
+export interface BlueprintWorkspace {
+  data: BlueprintDetailsData;
+  messages: ChatMessage[];
+  dirty: boolean;
+  busy: boolean;
+  /** Apply a chat instruction locally (instant, no network) and patch the affected sections. */
+  applyInstruction: (text: string) => void;
+  /** Replace state with a refined version (optional AI/server enhancement). */
+  setData: (next: BlueprintDetailsData) => void;
+  markSaved: () => void;
+}
+
+export function useBlueprintWorkspace(candidateId: string, idea: string): BlueprintWorkspace {
+  const [data, setDataState] = useState<BlueprintDetailsData>(() => engine.generate(candidateId, idea));
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [dirty, setDirty] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  const dataRef = useRef(data); // latest state, so applyInstruction never reads a stale closure
+  dataRef.current = data;
+  const keyRef = useRef(workspaceKey(idea, candidateId));
+
+  // C4 — rehydrate from localStorage if present, else generate locally. No fetch on the render path.
+  useEffect(() => {
+    const key = workspaceKey(idea, candidateId);
+    keyRef.current = key;
+    const saved = loadWorkspace(key);
+    const next = saved ?? engine.generate(candidateId, idea);
+    dataRef.current = next;
+    setDataState(next);
+    setMessages(saved ? messagesFrom(saved) : []);
+    setDirty(false);
+    setBusy(false);
+  }, [candidateId, idea]);
+
+  const setData = useCallback((next: BlueprintDetailsData) => {
+    dataRef.current = next;
+    setDataState(next);
+    setMessages(messagesFrom(next));
+    saveWorkspace(keyRef.current, next);
+  }, []);
+
+  const applyInstruction = useCallback((text: string) => {
+    const clean = text.trim();
+    if (!clean || busy) return;
+    setMessages((m) => [...m, { id: `u-${Date.now()}`, role: "user", content: clean, time: now() }]);
+    setBusy(true);
+    // Defer a tick so the "thinking" affordance can paint — still zero network for the result.
+    window.setTimeout(() => {
+      const res = engine.apply(dataRef.current, clean);
+      const stamp = new Date().toISOString();
+      res.data.chat_history = [
+        ...(dataRef.current.chat_history ?? []),
+        { id: `uh-${Date.now()}`, role: "user", content: clean, timestamp: stamp },
+        { id: `bh-${Date.now()}`, role: "blueprint", content: res.reply, timestamp: stamp },
+      ];
+      dataRef.current = res.data;
+      setDataState(res.data);
+      setMessages((m) => [...m, { id: `b-${Date.now()}`, role: "blueprint", content: res.reply, time: now() }]);
+      setDirty(true);
+      setBusy(false);
+      saveWorkspace(keyRef.current, res.data); // C4 autosave
+
+      // C3 — optional, bounded, fail-open AI refinement of the explanation only.
+      void refineWithAI(res.data, clean)
+        .then((ref) => {
+          if (!ref) return;
+          const patched: BlueprintDetailsData = {
+            ...dataRef.current,
+            overview: ref.overview ?? dataRef.current.overview,
+            design_brain: ref.designBrain ?? dataRef.current.design_brain,
+          };
+          dataRef.current = patched;
+          setDataState(patched);
+          saveWorkspace(keyRef.current, patched);
+          if (ref.reply) setMessages((m) => [...m, { id: `r-${Date.now()}`, role: "blueprint", content: `✦ ${ref.reply}`, time: now() }]);
+        })
+        .catch(() => undefined);
+    }, 140);
+  }, [busy]);
+
+  const markSaved = useCallback(() => setDirty(false), []);
+
+  return { data, messages, dirty, busy, applyInstruction, setData, markSaved };
+}

web/src/lib/capabilities.ts

@@ -0,0 +1,45 @@
+// C5 — Capability probe: is a control plane actually reachable?
+//
+// The Blueprint workspace is fully client-side (C0–C4). The server is an OPTIONAL sync target:
+// callers gate every `/api/v1/blueprints/*` request behind `getCapabilities()`, so when no backend
+// is present (static hosting, offline) the app makes zero per-interaction requests and the UX is
+// identical. The probe runs at most once (cached), is timeout-bounded, and never throws.
+
+import { apiBaseUrl } from "@/lib/api-client";
+
+export interface Capabilities {
+  /** A control plane responded to /health — server sync/enhancement is available. */
+  server: boolean;
+}
+
+let cache: Capabilities | null = null;
+let inflight: Promise<Capabilities> | null = null;
+
+export async function getCapabilities(opts: { timeoutMs?: number } = {}): Promise<Capabilities> {
+  if (cache) return cache;
+  if (inflight) return inflight;
+  if (typeof window === "undefined" || typeof fetch === "undefined") return { server: false };
+
+  inflight = (async () => {
+    let server = false;
+    try {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 1500);
+      const res = await fetch(`${apiBaseUrl}/health`, { signal: ctrl.signal });
+      clearTimeout(t);
+      server = res.ok;
+    } catch {
+      server = false; // unreachable / blocked / refused — stay fully local
+    }
+    cache = { server };
+    inflight = null;
+    return cache;
+  })();
+  return inflight;
+}
+
+/** Test/runtime hook to forget the cached probe. */
+export function resetCapabilities(): void {
+  cache = null;
+  inflight = null;
+}

web/src/styles/matrix-builder.css

@@ -1492,3 +1492,190 @@ button,select,a{-webkit-tap-highlight-color:transparent;touch-action:manipulatio
 .mb-src-regen:hover{border-color:rgba(83,243,157,.45);color:#eafff4}
 .mb-src-regen svg{color:var(--grn-bright)}
 @media(max-width:640px){.mb-src-idea,.mb-src-edit{max-width:none;flex:1 1 100%;min-width:0}}
+
+/* ============================================================================
+   Blueprint Details — a calm, premium dark planning room (see BlueprintDetails)
+   ============================================================================ */
+/* Card secondary action: keep cards clean — Details is a quiet link, Choose stays primary. */
+.cand-actions{margin-top:6px;display:flex;align-items:center;gap:10px}
+.cand-actions .cand-choose{margin-top:0;flex:1}
+.cand-details{flex:none;background:transparent;border:1px solid var(--bd-light);color:var(--tx-muted);border-radius:11px;min-height:44px;padding:0 14px;font-weight:600;cursor:pointer;transition:.15s}
+.cand-details:hover{border-color:var(--grn);color:var(--grn-deep)}
+
+/* Full-bleed dark surface */
+.bd-surface{background:linear-gradient(165deg,var(--bg-dark-2),var(--bg-dark) 60%);min-height:calc(100vh - 60px);color:#dff1e6}
+.bd-page{max-width:1180px}
+.bd-crumb{display:flex;align-items:center;gap:8px;font-family:var(--mono);font-size:12px;color:#7fb8a0;margin-bottom:14px}
+.bd-crumb .bd-step{color:var(--grn-bright)}
+.bd-crumb .bd-sep{opacity:.4}
+.bd-crumb .bd-cur{color:#eafff4}
+.bd-head{margin-bottom:22px}
+.bd-h1{font-family:var(--serif);font-size:clamp(28px,4vw,40px);line-height:1.08;color:#fff;margin:0 0 10px;display:flex;align-items:center;gap:14px;flex-wrap:wrap}
+.bd-rec{font-family:var(--sans);font-size:12px;font-weight:700;color:var(--bg-dark);background:var(--grn-bright);border-radius:999px;padding:5px 11px}
+.bd-lede{color:#a9cbbb;font-size:16px;max-width:70ch;margin:0 0 14px}
+.bd-pills{display:flex;flex-wrap:wrap;gap:8px}
+.bd-page .mb-tag{background:rgba(255,255,255,.05);color:#cfe8db;border:1px solid rgba(120,200,160,.18)}
+.bd-page .mb-tag.n{background:rgba(255,255,255,.04);color:#9bb8aa}
+.bd-page .mb-tag.bd-ai{background:rgba(34,200,120,.16);color:var(--grn-bright);border-color:rgba(34,200,120,.35)}
+.bd-page .mb-tag.bd-lock{display:inline-flex;align-items:center;gap:5px}
+
+.bd-grid{display:grid;grid-template-columns:1.55fr 1fr;gap:20px;align-items:start}
+.bd-col{display:flex;flex-direction:column;gap:18px}
+.bd-card{background:rgba(255,255,255,.035);border:1px solid rgba(120,200,160,.16);border-radius:18px;padding:20px 22px;backdrop-filter:blur(6px)}
+.bd-card-h{display:flex;align-items:center;gap:9px;margin-bottom:14px}
+.bd-card-h svg{color:var(--grn-bright)}
+.bd-card-h h3{font-size:16px;font-weight:700;color:#fff;margin:0}
+.bd-card-sub{margin-left:auto;font-family:var(--mono);font-size:11px;color:#8aae9d}
+.bd-p{color:#bcd8c9;font-size:14.5px;margin:0 0 14px}
+.bd-ov,.bd-brain-grid{display:flex;flex-direction:column;gap:12px}
+.bd-ov>div,.bd-brain-grid>div{display:flex;flex-direction:column;gap:3px}
+.bd-ov-k{font-family:var(--mono);font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#7fb8a0}
+.bd-ov-v{color:#dbeee3;font-size:14px}
+
+/* Batches — thin, elegant ordered rows */
+.bd-batches{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:10px}
+.bd-batch{display:flex;gap:14px;padding:14px;border-radius:13px;background:rgba(0,0,0,.18);border:1px solid rgba(120,200,160,.10);border-left:2px solid var(--grn)}
+.bd-batch-n{font-family:var(--mono);font-size:13px;font-weight:700;color:var(--grn-bright);flex:none;width:26px;text-align:center;padding-top:1px}
+.bd-batch-body{flex:1;min-width:0}
+.bd-batch-top{display:flex;align-items:center;justify-content:space-between;gap:10px}
+.bd-batch-name{font-weight:700;color:#eafff4;font-size:14.5px}
+.bd-batch-status{font-family:var(--mono);font-size:10.5px;color:#86a99a;border:1px solid rgba(120,200,160,.18);border-radius:999px;padding:2px 8px;flex:none}
+.bd-batch-purpose{color:#a9cbbb;font-size:13.5px;margin:5px 0 8px}
+.bd-batch-meta{display:flex;flex-wrap:wrap;gap:6px}
+.bd-batch-tag{font-family:var(--mono);font-size:10.5px;color:#8fb3a4;background:rgba(255,255,255,.04);border:1px solid rgba(120,200,160,.12);border-radius:7px;padding:3px 7px}
+
+/* Design Brain */
+.bd-brain{border-color:rgba(138,99,210,.35);background:linear-gradient(180deg,rgba(138,99,210,.10),rgba(255,255,255,.03))}
+.bd-brain-ic{font-size:16px}
+
+/* Talk to blueprint */
+.bd-chat-sub{margin:-6px 0 12px}
+.bd-save{margin-left:auto;width:34px;height:34px;border-radius:9px;display:grid;place-items:center;background:rgba(34,200,120,.14);border:1px solid rgba(34,200,120,.3);color:var(--grn-bright);cursor:pointer;transition:.15s}
+.bd-save:hover{background:rgba(34,200,120,.24)}
+.bd-chat-log{display:flex;flex-direction:column;gap:10px;margin-bottom:12px;max-height:230px;overflow-y:auto}
+.bd-msg{display:flex;flex-direction:column;gap:3px;padding:10px 12px;border-radius:11px;background:rgba(0,0,0,.2)}
+.bd-msg.user{background:rgba(34,200,120,.10)}
+.bd-msg-role{font-family:var(--mono);font-size:10.5px;color:#8aae9d}
+.bd-msg-text{color:#dbeee3;font-size:14px}
+.bd-composer{display:flex;align-items:center;gap:8px;background:rgba(0,0,0,.25);border:1px solid rgba(120,200,160,.18);border-radius:13px;padding:6px 6px 6px 14px}
+.bd-composer:focus-within{border-color:var(--grn)}
+.bd-composer-input{flex:1;background:transparent;border:0;outline:0;color:#eafff4;font-size:14.5px;min-height:36px}
+.bd-composer-input::placeholder{color:#7c9a8c}
+.bd-composer-send{flex:none;width:38px;height:38px;border-radius:10px;display:grid;place-items:center;background:var(--grn);color:#fff;border:0;cursor:pointer;transition:.15s}
+.bd-composer-send:disabled{opacity:.4;cursor:default}
+
+/* Architecture nodes */
+.bd-arch{display:grid;grid-template-columns:1fr 1fr;gap:10px}
+.bd-arch-node{display:flex;flex-direction:column;gap:3px;padding:12px;border-radius:12px;background:rgba(0,0,0,.18);border:1px solid rgba(120,200,160,.16)}
+.bd-arch-ic{color:var(--grn-bright)}
+.bd-arch-label{font-weight:700;color:#eafff4;font-size:13.5px}
+.bd-arch-sub{font-family:var(--mono);font-size:10.5px;color:#88ab9c}
+
+/* File plan */
+.bd-files{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:9px}
+.bd-file{display:flex;flex-direction:column;gap:2px}
+.bd-file-path{font-family:var(--mono);font-size:12.5px;color:var(--grn-bright)}
+.bd-file-why{font-size:13px;color:#a9cbbb}
+
+/* Matrix rules */
+.bd-rules{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:11px}
+.bd-rules li{display:flex;align-items:center;gap:9px;color:#cfe8db;font-size:13.5px}
+.bd-rules svg{color:var(--grn-bright);flex:none}
+
+/* Actions */
+.bd-actions{display:flex;flex-direction:column;gap:10px;margin-top:4px}
+.bd-back{display:inline-flex;align-items:center;justify-content:center;gap:8px;min-height:46px;border-radius:12px;background:transparent;border:1px solid rgba(120,200,160,.22);color:#cfe8db;font-weight:600;cursor:pointer;transition:.15s}
+.bd-back:hover{border-color:var(--grn);color:#fff}
+.bd-choose{display:inline-flex;align-items:center;justify-content:center;gap:9px;min-height:52px;border-radius:13px;background:var(--grn);color:#fff;border:0;font-weight:700;font-size:15.5px;cursor:pointer;box-shadow:0 18px 40px -18px rgba(34,200,120,.8);transition:transform .15s,background .15s}
+.bd-choose:hover{transform:translateY(-1px);background:var(--grn-bright)}
+
+@media (max-width:880px){
+  .bd-grid{grid-template-columns:1fr}
+  .bd-arch{grid-template-columns:1fr 1fr}
+}
+
+/* Settings — Matrix Designer toggle badge */
+.md-badge{font-family:var(--mono);font-size:10px;font-weight:600;letter-spacing:.04em;text-transform:uppercase;color:var(--grn-deep);background:var(--grn-tint);border:1px solid rgba(18,138,82,.2);border-radius:999px;padding:2px 7px;margin-left:6px;vertical-align:middle}
+
+/* Blueprint Details — batch-06/07 polish (unsaved badge, dependency graph, busy) */
+.bd-unsaved{margin-left:auto;font-family:var(--mono);font-size:10px;font-weight:700;letter-spacing:.04em;text-transform:uppercase;color:#ffd27f;background:rgba(255,176,0,.14);border:1px solid rgba(255,176,0,.35);border-radius:999px;padding:2px 8px}
+.bd-chat .bd-card-h .bd-unsaved + .bd-save{margin-left:8px}
+.bd-save.on{background:rgba(34,200,120,.26);border-color:var(--grn)}
+.bd-depgraph{display:flex;flex-wrap:wrap;align-items:center;gap:4px}
+.bd-dep{display:inline-flex;align-items:center;gap:4px}
+.bd-dep-arrow{color:#6f9a88}
+.bd-dep-node{font-family:var(--mono);font-size:10.5px;color:var(--grn-bright);background:rgba(34,200,120,.10);border:1px solid rgba(34,200,160,.22);border-radius:6px;padding:1px 6px}
+.bd-typing{color:#8aae9d;font-style:italic}
+
+/* ============================================================================
+   Blueprint Details — image-exact redesign (sticky sidebar, calm Apple/Linear feel)
+   ============================================================================ */
+.bd-grid{align-items:start}
+.bd-aside{position:sticky;top:76px;align-self:start;padding-right:2px}
+
+/* Overview — narrative left, scope/quality/outcome right */
+.bd-ov-split{display:grid;grid-template-columns:1.5fr 1fr;gap:30px}
+.bd-ov-split .bd-p{margin:0}
+.bd-ov{display:flex;flex-direction:column;gap:16px}
+.bd-ov-scope{display:flex;flex-direction:column;gap:4px}
+.bd-ov-row{display:flex;gap:30px}
+.bd-ov-row>div{display:flex;flex-direction:column;gap:4px}
+@media (max-width:880px){ .bd-ov-split{grid-template-columns:1fr} }
+
+/* Build batches — thin rows, description inline, status pinned right */
+.bd-batch{align-items:center}
+.bd-batch-body{display:flex;flex-direction:column;gap:8px}
+.bd-batch-top{display:flex;align-items:baseline;gap:12px}
+.bd-batch-desc{color:#9bbcad;font-size:13px;font-weight:400}
+.bd-batch-status{margin-left:auto;display:inline-flex;align-items:center;gap:7px;flex:none;font-family:var(--mono);font-size:11px;color:#8fb3a4}
+.bd-status-dot{width:13px;height:13px;border-radius:50%;border:1.5px solid rgba(143,179,164,.5);position:relative}
+.bd-status-dot::after{content:"";position:absolute;left:3px;right:3px;top:5.5px;height:1.5px;background:rgba(143,179,164,.7)}
+
+/* Card "View details" link */
+.bd-card-link{margin-top:14px;display:inline-flex;align-items:center;gap:6px;background:none;border:0;color:var(--grn-bright);font-size:13px;font-weight:600;cursor:pointer;padding:0}
+.bd-card-link:hover{color:#fff}
+
+/* Architecture nodes — stacked title row + subtitle */
+.bd-arch-node{gap:6px}
+.bd-arch-top{display:flex;align-items:center;gap:8px}
+.bd-arch-ic{color:var(--grn-bright);display:grid;place-items:center}
+
+/* Compact sidebar Design Brain */
+.bd-brain-k{font-family:var(--mono);font-size:10.5px;letter-spacing:.08em;text-transform:uppercase;color:#7fb8a0}
+.bd-brain-intent{margin:6px 0 0;color:#dbeee3;font-size:13.5px;line-height:1.5}
+.bd-brain-note{margin:10px 0 0;color:#9bbcad;font-size:12.5px}
+
+/* Chat — tabs header */
+.bd-chat-head{display:flex;align-items:center;gap:12px;margin-bottom:14px}
+.bd-chat-tabs{display:flex;gap:18px}
+.bd-tab{background:none;border:0;color:#7c9a8c;font-weight:600;font-size:14px;cursor:pointer;padding:0 0 8px;border-bottom:2px solid transparent;margin-bottom:-1px}
+.bd-tab.on{color:#fff;border-bottom-color:var(--grn)}
+.bd-chat-empty{color:#7c9a8c;font-size:13.5px;margin:4px 0 0}
+
+/* Chat — messages with avatars (no bubbles, Claude/ChatGPT style) */
+.bd-chat-log{display:flex;flex-direction:column;gap:18px;margin-bottom:16px;max-height:340px;overflow-y:auto;padding-right:4px}
+.bd-msg{display:flex;gap:12px;align-items:flex-start;background:none;padding:0;border-radius:0}
+.bd-msg.user{background:none}
+.bd-msg-av{flex:none;width:28px;height:28px;border-radius:50%;display:grid;place-items:center;font-family:var(--mono);font-size:11px;font-weight:700;color:#dbeee3;background:rgba(255,255,255,.08);border:1px solid rgba(120,200,160,.2)}
+.bd-msg.blueprint .bd-msg-av{color:var(--grn-bright)}
+.bd-msg-body{display:flex;flex-direction:column;gap:4px;min-width:0}
+.bd-msg-head{display:flex;align-items:baseline;gap:9px}
+.bd-msg-role{font-weight:700;color:#eafff4;font-size:13.5px}
+.bd-msg-time{font-family:var(--mono);font-size:10.5px;color:#7c9a8c}
+.bd-msg-text{color:#c8e2d6;font-size:14px;line-height:1.5}
+
+/* Activity feed */
+.bd-activity{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:12px}
+.bd-activity-row{display:flex;align-items:center;gap:10px;color:#c8e2d6;font-size:13.5px}
+.bd-activity-dot{width:6px;height:6px;border-radius:50%;background:var(--grn-bright);flex:none}
+
+/* Composer — + button, ⌘↵ hint, send */
+.bd-composer{padding:8px 8px 8px 8px;gap:6px}
+.bd-composer-add{flex:none;width:38px;height:38px;border-radius:10px;display:grid;place-items:center;background:rgba(255,255,255,.05);border:1px solid rgba(120,200,160,.18);color:#cfe8db;cursor:pointer;transition:.15s}
+.bd-composer-add:hover{border-color:var(--grn);color:#fff}
+.bd-composer-input{padding-left:6px}
+.bd-kbd{flex:none;font-family:var(--mono);font-size:11px;color:#7c9a8c;background:rgba(255,255,255,.05);border:1px solid rgba(120,200,160,.16);border-radius:7px;padding:3px 8px}
+
+/* cascade fixes for the redesign */
+.bd-batch-status{border:0;padding:0;background:none;border-radius:0}
+.bd-msg-role{font-family:var(--sans)}

web/src/types/ai-settings.ts

@@ -23,10 +23,18 @@ export type OllaBridgeSettings = {
   deviceId: string;
 };
 
+// Optional enhancement: the "design brain". When enabled AND Internal AI (OllaBridge) assist is on,
+// Matrix Builder uses the AI to design the full batch plan + the coder prompts for the next stages.
+// Default OFF — it never changes the deterministic Matrix contract.
+export type MatrixDesignerSettings = {
+  enabled: boolean;
+};
+
 export type MatrixAISettings = {
   provider: AIProvider;
   mode: AIMode;
   ollabridge: OllaBridgeSettings;
+  matrixDesigner: MatrixDesignerSettings;
 };
 
 export const AI_SETTINGS_STORAGE_KEY = "matrix-builder:ai-settings:v1";
@@ -45,4 +53,7 @@ export const DEFAULT_AI_SETTINGS: MatrixAISettings = {
     pairToken: "",
     deviceId: "",
   },
+  matrixDesigner: {
+    enabled: false,
+  },
 };

web/src/types/blueprint-state.ts

@@ -0,0 +1,84 @@
+// C0 — Client state model for the Blueprint Details workspace.
+//
+// One state object is the single source of truth for the live workspace. It is produced and
+// mutated entirely in the browser by `blueprint-engine.ts` (no network on the render path);
+// the server and the LLM are optional progressive enhancements layered on top.
+
+export interface ArchitectureNode {
+  name: string;
+  description: string;
+  dependencies: string[];
+}
+export interface FilePlanItem {
+  path: string;
+  description: string;
+}
+export interface DesignerBatch {
+  id: string;
+  name: string;
+  purpose: string;
+  tasks: string[];
+  allowed_files: string[];
+  depends_on: string[];
+  acceptance_criteria: string[];
+  validation_checks: string[];
+  must_not_change: string[];
+}
+export interface DesignerChatMessage {
+  id: string;
+  role: "user" | "blueprint";
+  content: string;
+  timestamp: string;
+}
+export interface BlueprintDetailsData {
+  candidate_id: string;
+  overview: string;
+  architecture: ArchitectureNode[];
+  batches: DesignerBatch[];
+  file_plan: FilePlanItem[];
+  matrix_rules: string[];
+  acceptance_criteria: string[];
+  validation_plan: string[];
+  risks: string[];
+  assumptions: string[];
+  design_brain?: string | null;
+  chat_history: DesignerChatMessage[];
+}
+
+export interface DesignerCandidate {
+  id: string;
+  tier: string;
+  title: string;
+  summary: string;
+  file_count: number;
+  difficulty: string;
+  estimate: string;
+  stack: string[];
+  recommended: boolean;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: "user" | "blueprint";
+  content: string;
+  time?: string;
+}
+
+/** Which sections an engine `apply()` touched — lets the UI know what changed. */
+export type BlueprintSection = "overview" | "architecture" | "filePlan" | "batches" | "designBrain";
+
+/** The single source of truth for the live workspace (held by `useBlueprintWorkspace`). */
+export interface BlueprintWorkspaceState {
+  candidateId: string;
+  idea: string;
+  data: BlueprintDetailsData;
+  messages: ChatMessage[];
+  dirty: boolean;
+  busy: boolean;
+}
+
+export const RMD_RULES = [
+  "RMD-101: AI coders are workers, not architects.",
+  "RMD-103: Control files are protected.",
+  "RMD-111: Acceptance criteria are law.",
+];