ltcai 4.4.0 → 4.5.1

package/docs/V4_5_1_PRODUCT_REIMAGINING_REPORT.md

@@ -0,0 +1,61 @@
+# v4.5.1 Product Reimagining Report
+
+Release date: 2026-06-13
+
+## Objective
+
+v4.5.1 treats the previous desktop product surface as non-authoritative. The
+goal was not to polish the v4.5.0 recovery UI; it was to relaunch Lattice AI as
+a premium local-first Digital Brain while preserving all capabilities,
+workflows, data contracts, storage, FastAPI APIs, Tauri shell behavior, Brain
+Core, model runtimes, backup/restore, and portability.
+
+## Product Decision
+
+The product is now organized around six user-facing rooms:
+
+- Home: the living shape of what Lattice knows.
+- Ask: thinking with remembered context.
+- Add: files, folders, and pages entering memory.
+- Automate: supervised goals, runs, workflows, approvals, hooks, and tools.
+- Library: models, skills, marketplace, and tool connections.
+- Care: account, spaces, backups, devices, settings, and admin safety.
+
+Legacy hash routes still resolve into the SPA, but they no longer dictate the
+visible product model.
+
+## What Changed
+
+- Replaced the fixed left rail with compact desktop chrome and a centered
+  navigation dock.
+- Added a command palette and responsive mobile drawer.
+- Added an ambient brain canvas so the first viewport reads as a thinking
+  environment rather than a dashboard.
+- Replaced the first-run checklist with a first-session journey.
+- Reworked route labels and page hero copy across Brain, Ask, Capture, Act,
+  Library, and System.
+- Rebuilt global styling around calmer surfaces, fixed responsive type sizes,
+  and restrained accents.
+
+## What Was Preserved
+
+- FastAPI and generated OpenAPI client.
+- Tauri desktop shell and sidecar behavior.
+- `lattice_brain` package boundary.
+- StorageEngine, SQLite default, optional PostgreSQL scale mode.
+- Backup/restore and `.latticebrain` portability.
+- Model recommendation, prepare/load stream, and consent-gated downloads.
+- Knowledge graph, hybrid search, chat, capture, workflow, agent, system, and
+  admin APIs.
+
+## Self Review
+
+The redesigned first viewport immediately reads as a different product:
+Lattice branding, Home/Ask/Add/Automate/Library/Care navigation, first-session
+journey, and premium desktop chrome replace the old dashboard hierarchy.
+
+## Evidence
+
+- Desktop screenshot: `output/audits/v4.5.1-reimagining/screenshots/home-desktop.png`
+- Mobile screenshot: `output/audits/v4.5.1-reimagining/screenshots/home-mobile.png`
+- Walkthrough GIF: `output/audits/v4.5.1-reimagining/gifs/v4.5.1-reimagining-walkthrough.gif`

package/docs/V4_5_1_RC_ARTIFACTS.md

@@ -0,0 +1,44 @@
+# v4.5.1 RC Artifact Manifest
+
+Release date: 2026-06-13
+
+## Screenshots
+
+- `output/audits/v4.5.1-reimagining/screenshots/home-desktop.png`
+- `output/audits/v4.5.1-reimagining/screenshots/home-mobile.png`
+- `output/audits/v4.5.1-reimagining/screenshots/memory-map.png`
+- `output/audits/v4.5.1-reimagining/screenshots/library-models.png`
+
+## GIFs
+
+- `output/audits/v4.5.1-reimagining/gifs/v4.5.1-reimagining-walkthrough.gif`
+
+## Release Artifacts
+
+- `dist/ltcai-4.5.1-py3-none-any.whl`
+- `dist/ltcai-4.5.1.tar.gz`
+- `ltcai-4.5.1.tgz`
+- `dist/ltcai-4.5.1.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.1_aarch64.dmg`
+
+## SHA-256
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `dist/ltcai-4.5.1-py3-none-any.whl` | `3d5ce1a0a85f7aba1f78587cd7e4a66c63dd5c03ddde7cee57624ec3f487899b` |
+| `dist/ltcai-4.5.1.tar.gz` | `62f0e05ff32554cf599b76678de3136bc02e5af4775144e7347182eed0fb4675` |
+| `ltcai-4.5.1.tgz` | `e755f40f87484d8a6e3f6bc95f48f0f78e1d0fcde3af8b14c709cf7fa71b2e4b` |
+| `dist/ltcai-4.5.1.vsix` | `3badc5915dc31425fa383d5946f78e0914497aa9e523cb7fbdc81a295b8f4a2f` |
+| `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.1_aarch64.dmg` | `689ffc9553facf3987a5d57016dfd24fc3872f9c0810e28621f96b340ca38ce0` |
+
+## Validation
+
+`npm run release:validate` passed for the exact v4.5.1 artifact set. Historical
+files remain in `dist/` for prior releases, so all publish or upload steps must
+use exact v4.5.1 filenames only.
+
+## Notes
+
+The artifact list is exact-version only. Publishing remains out of scope for
+this RC unless the repository owner explicitly performs the manual registry
+publish steps.

package/docs/V4_5_1_UX_REPORT.md

@@ -0,0 +1,45 @@
+# v4.5.1 UX Report
+
+## UX Principle
+
+v4.5.1 designs for non-technical users who should understand what Lattice AI is,
+what to do next, how to add knowledge, how to use the brain, how to install a
+model, and how to automate work without reading the README.
+
+## Primary Flow
+
+The first-session journey is:
+
+1. Make it yours.
+2. Choose a space.
+3. Meet your Mac.
+4. Pick a brain.
+5. Install locally.
+6. Try a question.
+7. Set the pace.
+8. Explore memory.
+
+This replaces implementation-facing setup labels with user outcomes while still
+driving the same account, workspace, model recommendation, model setup, mode,
+and graph routes.
+
+## Screen Inventory Decision
+
+- Brain became Home, emphasizing the shape of work rather than a graph tool.
+- Capture became Add, emphasizing the act of feeding memory.
+- Act became Automate, emphasizing supervised work instead of an agent console.
+- System became Care, emphasizing trust, portability, and maintenance.
+- Ask and Library survived because their user intent is direct and legible.
+
+## Interaction Notes
+
+- Command palette remains available with Cmd/Ctrl+K.
+- Mode switching is visible as Calm, Deep, and Admin instead of Basic,
+  Advanced, and Admin in the first viewport.
+- Mobile navigation opens as a room chooser and preserves no-horizontal-overflow
+  behavior at 390px width.
+
+## Evidence
+
+- Playwright visual coverage: `tests/visual/v3.spec.js`
+- Screenshots: `output/audits/v4.5.1-reimagining/screenshots/`

package/docs/V4_5_1_VALIDATION_REPORT.md

@@ -0,0 +1,54 @@
+# v4.5.1 Validation Report
+
+Release date: 2026-06-13
+
+## Scope
+
+Validation covers the v4.5.1 product reimagining, version sync, frontend visual
+changes, release artifacts, and compatibility preservation.
+
+## Command Matrix
+
+| Check | Result |
+| --- | --- |
+| Python compile | PASS: `npm run check:python` compiled 775 modules |
+| Ruff | PASS: `node scripts/run_python.mjs -m ruff check .` |
+| Unit tests | PASS: `npm run test:unit` - 616 passed, 2 warnings |
+| Integration tests | PASS: `LTCAI_TEST_BASE_URL=http://127.0.0.1:4932 npm run test:integration` - 9 passed, 1 skipped |
+| Frontend lint | PASS: `npm run lint` |
+| TypeScript typecheck | PASS: `npm run typecheck` and `npm run typecheck:frontend` |
+| Playwright | PASS: `npm run test:visual` - 14 passed |
+| Tauri check/build | PASS: `npm run desktop:tauri:check`; PASS via `npm run release:artifacts` for the Tauri app and DMG build |
+| Release artifact validation | PASS: `npm run release:validate` |
+| Wheel smoke | PASS: `node scripts/run_python.mjs scripts/wheel_smoke.py --wheel dist/ltcai-4.5.1-py3-none-any.whl` |
+| npm pack dry-run | PASS: `npm pack --dry-run` |
+
+## Browser Evidence
+
+- Desktop screenshot: `output/audits/v4.5.1-reimagining/screenshots/home-desktop.png`
+- Mobile screenshot: `output/audits/v4.5.1-reimagining/screenshots/home-mobile.png`
+- Walkthrough GIF: `output/audits/v4.5.1-reimagining/gifs/v4.5.1-reimagining-walkthrough.gif`
+
+## RC Artifacts
+
+Expected exact-version artifacts:
+
+- `dist/ltcai-4.5.1-py3-none-any.whl`
+- `dist/ltcai-4.5.1.tar.gz`
+- `ltcai-4.5.1.tgz`
+- `dist/ltcai-4.5.1.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.1_aarch64.dmg`
+
+## Artifact Hashes
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `dist/ltcai-4.5.1-py3-none-any.whl` | `3d5ce1a0a85f7aba1f78587cd7e4a66c63dd5c03ddde7cee57624ec3f487899b` |
+| `dist/ltcai-4.5.1.tar.gz` | `62f0e05ff32554cf599b76678de3136bc02e5af4775144e7347182eed0fb4675` |
+| `ltcai-4.5.1.tgz` | `e755f40f87484d8a6e3f6bc95f48f0f78e1d0fcde3af8b14c709cf7fa71b2e4b` |
+| `dist/ltcai-4.5.1.vsix` | `3badc5915dc31425fa383d5946f78e0914497aa9e523cb7fbdc81a295b8f4a2f` |
+| `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.1_aarch64.dmg` | `689ffc9553facf3987a5d57016dfd24fc3872f9c0810e28621f96b340ca38ce0` |
+
+`npm run release:validate` confirmed all exact-version RC artifacts are present.
+It also warned that historical artifacts remain in `dist/`, so publish commands
+must continue to use explicit v4.5.1 filenames rather than a `dist/*` glob.

package/docs/V4_5_1_VISUAL_DESIGN_REPORT.md

@@ -0,0 +1,30 @@
+# v4.5.1 Visual Design Report
+
+## Direction
+
+The visual language targets a calm premium desktop product rather than a
+developer/admin dashboard. The palette uses a carbon and warm-white base with
+jade, amber, violet, blue, and coral accents so the UI is not dominated by a
+single hue family.
+
+## System Changes
+
+- New sticky desktop chrome and centered dock.
+- Ambient brain canvas built from grid, line, and tile motifs.
+- Fixed responsive typography with media-query breakpoints, avoiding viewport
+  width font scaling.
+- Cards remain at 8px radius or less.
+- Shared buttons and badges were tightened for stable sizing and text fit.
+- Light theme retains the same hierarchy with warmer surfaces.
+
+## Accessibility And Layout
+
+- Primary navigation has an explicit `Primary navigation` label.
+- The command palette exposes a dialog label.
+- Mode switch has `Experience mode` semantics and pressed states.
+- Mobile layout was checked at 390x780 with zero horizontal overflow.
+
+## Evidence
+
+- Desktop visual pass: `output/audits/v4.5.1-reimagining/screenshots/home-desktop.png`
+- Mobile visual pass: `output/audits/v4.5.1-reimagining/screenshots/home-mobile.png`

package/docs/V4_DIGITAL_BRAIN_RECOVERY.md

@@ -5,21 +5,21 @@
 > completed analysis. **Update this file before ending any phase and before any
 > likely session/context/usage limit.**
 >
-> Last updated: 2026-06-13 — v4.3.3 Dead-Code Cleanup Release; Remaining Gaps remain empty
+> Last updated: 2026-06-13 — v4.5.1 Product Reimagining RC; Remaining Gaps remain empty
 
 ---
 
-## 0. RELEASE STATUS (v4.3.3)
-
-**v4.3.3 promotes the post-cleanup main tree after the independent dead-code,
-architecture, and runtime audit without redesigning the Digital Brain frontend,
-Brain Core, storage, or agent/workflow architecture.** Latest implementation
-milestone: v4.3.2 product polish plus post-audit cleanup, architecture
-documentation correction, Vercel/static-docs readiness, README badge
-restoration, and exact-current-main release artifacts.
-The v4.3.3 process creates a GitHub Release from locally validated artifacts.
-PyPI, npm Registry, VS Code Marketplace, Open VSX, and production deployments
-remain owner-only external publishing steps.
+## 0. RELEASE STATUS (v4.5.1)
+
+**v4.5.1 reimagines the desktop product surface after the v4.5.0 capability
+recovery without changing Brain Core, storage, API, model runtime, backup,
+portability, or agent/workflow behavior.** Current implementation milestone:
+new Home/Ask/Add/Automate/Library/Care navigation, compact desktop chrome,
+first-session journey, command palette, responsive mobile drawer, and refreshed
+Digital Brain visual system.
+The v4.5.1 RC process builds locally validated artifacts only. Tagging, GitHub
+Release creation, PyPI, npm Registry, VS Code Marketplace, Open VSX, and
+production deployments remain out of scope for this RC.
 Remaining implementation gaps: **none**.
 Owner-only blockers: pptx history rewrite (requires force-push/owner decision)
 and consent-gated production embedder provisioning (silent default download is
@@ -27,11 +27,11 @@ not permitted).
 
 ## Remaining Gaps
 
-None. v4.3.3 preserves the already-empty v4.3.2 gap list and promotes the
-post-cleanup tree: Brain graph exploration remains real and API-backed, raw
-product JSON dumps remain replaced with readable state, archive import/restore
+None. v4.5.1 preserves the already-empty v4.3.2/v4.3.3/v4.5.0 gap list and
+promotes the product-reimagining tree: Brain graph exploration remains real and
+API-backed, readable product state remains in place, archive import/restore
 flows remain exposed through existing APIs, desktop sidecar behavior remains
-validated, and exact v4.3.3 release artifacts are the release target.
+validated, and exact v4.5.1 RC artifacts are the validation target.
 Owner-only blockers above are intentionally not implementation gaps.
 
 ## 1. Program Charter (from the user's v4.0.0 directive)

package/docs/architecture.md

@@ -88,13 +88,17 @@ work on them.
 
 Local recommended models must be multimodal. The v2.2 local model workflow policy is:
 
-- macOS Apple Silicon: MLX-VLM first
+- macOS Apple Silicon: MLX-VLM first, with MLX-LM retained as a Gemma 4 text
+  fallback only for standard Gemma 4 metadata. Gemma 4 12B `gemma4_unified`
+  requires an MLX-VLM runtime that includes `mlx_vlm.models.gemma4_unified`.
 - Windows: llama.cpp multimodal path, with LM Studio as a user-friendly option
 - Linux: llama.cpp or vLLM multimodal path depending on GPU support
 - Ollama: kept as an option, not the default priority
 
-The removed path is the old text-only MLX-LM recommendation route. Low-spec
-machines use smaller or quantized multimodal models.
+The removed path is the old text-only MLX-LM recommendation lane for ordinary
+model selection. MLX-LM remains available as a targeted recovery path for
+standard Gemma 4 metadata, but it is not used for `gemma4_unified`.
+Low-spec machines use smaller or quantized multimodal models.
 
 ## Model Source Disclosure
 
@@ -140,7 +144,7 @@ Basic mode and advanced mode have the same feature access.
 | `latticeai/services/model_catalog.py` | Multimodal model catalog, source metadata, aliases |
 | `latticeai/services/model_recommendation.py` | Hardware-aware multimodal recommendation |
 | `latticeai/services/model_runtime.py` | Download, load, server, and model workflow orchestration |
-| `llm_router.py` | MLX-VLM and OpenAI-compatible model routing |
+| `llm_router.py` | MLX-VLM/MLX-LM and OpenAI-compatible model routing |
 | `knowledge_graph.py` | Graph storage, extraction, local folder knowledge graph context |
 | `latticeai/core/context_builder.py` | Graph context for generation |
 | `latticeai/core/workspace_os.py` | Workspace state, timeline, snapshots, durable context |

package/frontend/src/App.tsx

@@ -1,10 +1,11 @@
 import * as React from "react";
 import { useQuery } from "@tanstack/react-query";
-import { Command, Menu, Moon, Search, Sun, X } from "lucide-react";
+import { BrainCircuit, CheckCircle2, Command, Menu, Moon, Search, Sparkles, Sun, X } from "lucide-react";
 import { latticeApi } from "@/api/client";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
-import { useAppStore } from "@/store/appStore";
+import { FirstRunGuide } from "@/components/FirstRunGuide";
+import { useAppStore, WorkspaceMode } from "@/store/appStore";
 import { commandRoutes, go, parseHash, primaryRoutes, PrimaryRoute } from "@/routes";
 import { BrainPage } from "@/pages/Brain";
 import { AskPage } from "@/pages/Ask";
@@ -14,6 +15,12 @@ import { LibraryPage } from "@/pages/Library";
 import { SystemPage } from "@/pages/System";
 import { cn } from "@/lib/utils";
 
+const modes: Array<{ id: WorkspaceMode; label: string }> = [
+  { id: "basic", label: "Calm" },
+  { id: "advanced", label: "Deep" },
+  { id: "admin", label: "Admin" },
+];
+
 function useRoute() {
   const [route, setRoute] = React.useState(parseHash);
   React.useEffect(() => {
@@ -33,9 +40,26 @@ function Page({ primary, tab }: { primary: PrimaryRoute; tab?: string }) {
   return <BrainPage initialTab={tab} />;
 }
 
+function AmbientBrain() {
+  return (
+    <div className="ambient-brain" aria-hidden="true">
+      <span className="signal-line signal-line-a" />
+      <span className="signal-line signal-line-b" />
+      <span className="signal-line signal-line-c" />
+      <span className="signal-tile signal-tile-a" />
+      <span className="signal-tile signal-tile-b" />
+      <span className="signal-tile signal-tile-c" />
+    </div>
+  );
+}
+
 function CommandPalette({ open, onClose }: { open: boolean; onClose: () => void }) {
   const [query, setQuery] = React.useState("");
-  const matches = commandRoutes.filter((route) => route.label.toLowerCase().includes(query.toLowerCase()) || route.key.includes(query.toLowerCase()));
+  const normalized = query.trim().toLowerCase();
+  const matches = commandRoutes.filter((route) => (
+    route.label.toLowerCase().includes(normalized) || route.key.includes(normalized)
+  ));
+
   React.useEffect(() => {
     if (!open) return;
     const onKey = (event: KeyboardEvent) => {
@@ -44,16 +68,17 @@ function CommandPalette({ open, onClose }: { open: boolean; onClose: () => void
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
   }, [open, onClose]);
+
   if (!open) return null;
   return (
-    <div className="fixed inset-0 z-50 bg-background/80 p-4 backdrop-blur-sm" role="dialog" aria-modal="true">
-      <div className="mx-auto mt-16 max-w-xl rounded-lg border border-border bg-card shadow-xl">
-        <div className="flex items-center gap-2 border-b border-border p-3">
+    <div className="command-scrim" role="dialog" aria-modal="true" aria-label="Lattice command palette">
+      <div className="command-panel">
+        <div className="command-search">
           <Search className="h-4 w-4 text-muted-foreground" />
-          <Input value={query} onChange={(e) => setQuery(e.target.value)} autoFocus placeholder="Jump to a capability" />
-          <Button variant="ghost" size="icon" onClick={onClose}><X className="h-4 w-4" /></Button>
+          <Input value={query} onChange={(event) => setQuery(event.target.value)} autoFocus placeholder="Jump to anything in Lattice" />
+          <Button variant="ghost" size="icon" onClick={onClose} aria-label="Close command palette"><X className="h-4 w-4" /></Button>
         </div>
-        <div className="max-h-96 overflow-auto p-2">
+        <div className="command-list soft-scrollbar">
           {matches.map((route) => {
             const Icon = route.icon;
             return (
@@ -63,10 +88,13 @@ function CommandPalette({ open, onClose }: { open: boolean; onClose: () => void
                   go(route.key);
                   onClose();
                 }}
-                className="flex w-full items-center gap-3 rounded-md px-3 py-2 text-left text-sm hover:bg-muted"
+                className="command-row"
               >
-                <Icon className="h-4 w-4 text-primary" />
-                {route.label}
+                <span className="command-icon"><Icon className="h-4 w-4" /></span>
+                <span>
+                  <span className="block text-sm font-semibold">{route.label}</span>
+                  <span className="block text-xs text-muted-foreground">Open {route.key.replace(/[-/]/g, " ")}</span>
+                </span>
               </button>
             );
           })}
@@ -76,6 +104,48 @@ function CommandPalette({ open, onClose }: { open: boolean; onClose: () => void
   );
 }
 
+function PrimaryDock({ active, onNavigate }: { active: PrimaryRoute; onNavigate?: () => void }) {
+  return (
+    <nav className="primary-dock" aria-label="Primary navigation">
+      {primaryRoutes.map((item) => {
+        const Icon = item.icon;
+        const selected = active === item.id;
+        return (
+          <button
+            key={item.id}
+            className={cn("dock-button", selected && "is-active")}
+            onClick={() => {
+              go(item.id);
+              onNavigate?.();
+            }}
+            aria-current={selected ? "page" : undefined}
+          >
+            <Icon className="h-4 w-4" />
+            <span>{item.label}</span>
+          </button>
+        );
+      })}
+    </nav>
+  );
+}
+
+function ModeSwitch({ mode, setMode }: { mode: WorkspaceMode; setMode: (mode: WorkspaceMode) => void }) {
+  return (
+    <div className="mode-switch" aria-label="Experience mode">
+      {modes.map((item) => (
+        <button
+          key={item.id}
+          className={cn(mode === item.id && "is-active")}
+          onClick={() => setMode(item.id)}
+          aria-pressed={mode === item.id}
+        >
+          {item.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
 export default function App() {
   const route = useRoute();
   const { theme, setTheme, mode, setMode } = useAppStore();
@@ -93,6 +163,7 @@ export default function App() {
   React.useEffect(() => {
     document.documentElement.dataset.theme = theme;
   }, [theme]);
+
   React.useEffect(() => {
     const onKey = (event: KeyboardEvent) => {
       if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
@@ -105,94 +176,84 @@ export default function App() {
   }, []);
 
   const healthData = (health.data?.data || {}) as Record<string, unknown>;
-  const appVersion = typeof healthData.version === "string" ? healthData.version : null;
+  const workspaceData = (workspace.data?.data || {}) as Record<string, unknown>;
   const desktopData = (desktop.data?.data || {}) as Record<string, unknown>;
-  const desktopError = typeof desktopData.last_error === "string" ? desktopData.last_error : desktop.data?.error;
-
-  const rail = (
-    <aside className="flex h-full w-64 shrink-0 flex-col border-r border-border bg-card">
-      <div className="flex h-16 items-center gap-3 border-b border-border px-4">
-        <div className="grid h-9 w-9 place-items-center rounded-md bg-primary text-primary-foreground font-bold">LA</div>
-        <div>
-          <div className="font-semibold">Lattice AI</div>
-          <div className="text-xs text-muted-foreground">Digital Brain Desktop</div>
-        </div>
-      </div>
-      <nav className="flex-1 space-y-1 overflow-auto p-3">
-        {primaryRoutes.map((item) => {
-          const Icon = item.icon;
-          const active = route.primary === item.id;
-          return (
-            <button
-              key={item.id}
-              onClick={() => {
-                go(item.id);
-                setDrawer(false);
-              }}
-              className={cn(
-                "flex min-h-14 w-full items-center gap-3 rounded-md px-3 py-2 text-left transition",
-                active ? "bg-primary/14 text-foreground" : "text-muted-foreground hover:bg-muted hover:text-foreground",
-              )}
-            >
-              <Icon className="h-5 w-5" />
-              <span>
-                <span className="block text-sm font-medium">{item.label}</span>
-                <span className="block text-xs">{item.description}</span>
-              </span>
-            </button>
-          );
-        })}
-      </nav>
-      <div className="border-t border-border p-3 text-xs text-muted-foreground">
-        <div>Server: {health.data?.ok ? "online" : "unavailable"}</div>
-        {window.__TAURI_INTERNALS__ ? (
-          <div>Sidecar: {desktopData.running ? "running" : desktopError ? `unavailable (${desktopError})` : "starting"}</div>
-        ) : null}
-        <div>Workspace: {String((workspace.data?.data as Record<string, unknown>)?.active_workspace || "local")}</div>
-      </div>
-    </aside>
-  );
+  const appVersion = typeof healthData.version === "string" ? healthData.version : null;
+  const activeRoute = primaryRoutes.find((item) => item.id === route.primary);
+  const workspaceName = String(workspaceData.active_workspace || "Personal space");
+  const backendReady = Boolean(health.data?.ok);
+  const desktopReady = !window.__TAURI_INTERNALS__ || Boolean(desktopData.running);
 
   return (
-    <div className="min-h-screen bg-background text-foreground">
+    <div className="app-backdrop min-h-screen text-foreground">
+      <AmbientBrain />
       <CommandPalette open={palette} onClose={() => setPalette(false)} />
-      <div className="hidden lg:fixed lg:inset-y-0 lg:left-0 lg:block">{rail}</div>
+
+      <header className="app-chrome">
+        <div className="brand-lockup">
+          <button className="mobile-menu" onClick={() => setDrawer(true)} aria-label="Open navigation"><Menu className="h-5 w-5" /></button>
+          <button className="brand-mark" onClick={() => go("brain")} aria-label="Open Lattice home">
+            <BrainCircuit className="h-5 w-5" />
+          </button>
+          <div className="brand-copy">
+            <div className="brand-name">Lattice</div>
+            <div className="brand-subtitle">Digital Brain</div>
+          </div>
+        </div>
+
+        <div className="desktop-dock">
+          <PrimaryDock active={route.primary} />
+        </div>
+
+        <div className="chrome-actions">
+          <button className="status-chip" onClick={() => go("settings")}>
+            <span className={cn("status-light", backendReady && desktopReady ? "is-ready" : "is-waiting")} />
+            <span>{backendReady && desktopReady ? "Ready" : "Starting"}</span>
+          </button>
+          <Button variant="outline" onClick={() => setPalette(true)}><Command className="h-4 w-4" /> Find</Button>
+          <Button variant="outline" size="icon" onClick={() => setTheme(theme === "dark" ? "light" : "dark")} aria-label="Toggle theme">
+            {theme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
+          </Button>
+        </div>
+      </header>
+
       {drawer ? (
-        <div className="fixed inset-0 z-40 lg:hidden">
-          <button className="absolute inset-0 bg-background/70" aria-label="Close navigation" onClick={() => setDrawer(false)} />
-          <div className="relative h-full">{rail}</div>
+        <div className="mobile-drawer">
+          <button className="drawer-scrim" aria-label="Close navigation" onClick={() => setDrawer(false)} />
+          <div className="drawer-panel">
+            <div className="drawer-header">
+              <div>
+                <div className="font-semibold">Lattice</div>
+                <div className="text-xs text-muted-foreground">Choose a room</div>
+              </div>
+              <Button variant="ghost" size="icon" onClick={() => setDrawer(false)} aria-label="Close navigation"><X className="h-4 w-4" /></Button>
+            </div>
+            <PrimaryDock active={route.primary} onNavigate={() => setDrawer(false)} />
+          </div>
         </div>
       ) : null}
-      <div className="lg:pl-64">
-        <header className="sticky top-0 z-30 flex h-16 items-center justify-between gap-3 border-b border-border bg-background/95 px-4 backdrop-blur">
-          <div className="flex min-w-0 items-center gap-2">
-            <Button variant="ghost" size="icon" className="lg:hidden" onClick={() => setDrawer(true)}><Menu className="h-5 w-5" /></Button>
-            <div className="min-w-0">
-              <div className="truncate text-sm text-muted-foreground">{appVersion ? `v${appVersion}` : "Version unavailable"}</div>
-              <div className="truncate font-medium">{primaryRoutes.find((item) => item.id === route.primary)?.label}</div>
-            </div>
+
+      <main className="page-shell">
+        <section className="workspace-ribbon" aria-label="Current workspace">
+          <div className="min-w-0">
+            <div className="ribbon-kicker"><Sparkles className="h-4 w-4" /> {activeRoute?.label || "Home"}</div>
+            <h1>{activeRoute?.description || "A calm place to think with your knowledge."}</h1>
           </div>
-          <div className="flex items-center gap-2">
-            <Button variant="outline" onClick={() => setPalette(true)}><Command className="h-4 w-4" /> Search</Button>
-            <select
-              value={mode}
-              onChange={(e) => setMode(e.target.value as "basic" | "advanced" | "admin")}
-              className="h-9 rounded-md border border-border bg-background px-2 text-sm"
-              aria-label="Workspace mode"
-            >
-              <option value="basic">Basic</option>
-              <option value="advanced">Advanced</option>
-              <option value="admin">Admin</option>
-            </select>
-            <Button variant="outline" size="icon" onClick={() => setTheme(theme === "dark" ? "light" : "dark")} aria-label="Toggle theme">
-              {theme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
-            </Button>
+          <div className="ribbon-meta">
+            <div className="meta-card">
+              <CheckCircle2 className="h-4 w-4 text-primary" />
+              <span>{workspaceName}</span>
+            </div>
+            <div className="meta-card">
+              <span>{appVersion ? `v${appVersion}` : "Version checking"}</span>
+            </div>
+            <ModeSwitch mode={mode} setMode={setMode} />
           </div>
-        </header>
-        <main className="p-4 lg:p-6">
-          <Page primary={route.primary} tab={route.tab} />
-        </main>
-      </div>
+        </section>
+
+        <FirstRunGuide />
+        <Page primary={route.primary} tab={route.tab} />
+      </main>
     </div>
   );
 }