ltcai 4.4.0 → 4.6.0

package/docs/V4_5_1_MODEL_EXPERIENCE_REPORT.md

@@ -0,0 +1,37 @@
+# v4.5.1 Model Experience Report
+
+## Goal
+
+Normal users should be able to install and use a local model without learning
+MLX, MLX-LM, MLX-VLM, Ollama, GGUF, or runtime internals.
+
+## Preserved Capability
+
+v4.5.1 keeps the v4.5.0 model recommendation and prepare/load stream:
+
+- Environment analysis.
+- Recommended model selection.
+- Explicit download/install consent.
+- Progress reporting.
+- Validation.
+- Load/ready state.
+- Compatibility recovery guidance.
+
+## Reimagined Presentation
+
+The model experience now sits under Library in the new product shell. The first
+session points users to "Pick a brain" and "Install locally" instead of runtime
+labels. Calm mode keeps implementation terms hidden while Deep/Admin retain
+diagnostics.
+
+## Non-Goals
+
+No model runtime behavior, download policy, local/cloud opt-in policy, or
+compatibility routing was changed in v4.5.1.
+
+## Evidence
+
+- Model UI: `frontend/src/pages/Library.tsx`
+- Model API client: `frontend/src/api/client.ts`
+- Related historical runtime report:
+  `docs/V4_5_0_MODEL_RUNTIME_UX_REPORT.md`

package/docs/V4_5_1_NAVIGATION_REPORT.md

@@ -0,0 +1,37 @@
+# v4.5.1 Navigation Report
+
+## New Navigation Model
+
+The primary navigation is now:
+
+- Home
+- Ask
+- Add
+- Automate
+- Library
+- Care
+
+This replaces the previous product taxonomy without removing compatibility
+routes. Existing paths such as `#/knowledge-graph`, `#/hybrid-search`,
+`#/files`, `#/agents`, `#/workspace-admin`, and admin aliases still route to
+the same capability modules.
+
+## Why This Model
+
+- Home is the user-facing Digital Brain entry point.
+- Ask is the clearest label for conversational work.
+- Add explains knowledge ingestion without technical vocabulary.
+- Automate explains agents/workflows as supervised outcomes.
+- Library remains clear for models, skills, and connections.
+- Care reframes account, backups, devices, and safety as maintenance.
+
+## Implementation
+
+- Route compatibility remains in `frontend/src/routes.ts`.
+- The visible dock and mobile drawer are implemented in `frontend/src/App.tsx`.
+- Visual tests now assert the new navigation labels and legacy route behavior.
+
+## Evidence
+
+- Tests: `tests/visual/v3.spec.js`
+- Code: `frontend/src/routes.ts`, `frontend/src/App.tsx`

package/docs/V4_5_1_ONBOARDING_REPORT.md

@@ -0,0 +1,29 @@
+# v4.5.1 Onboarding Report
+
+## Goal
+
+Onboarding should make the next action obvious to a first-time, non-technical
+user without documentation.
+
+## Reimagined Journey
+
+- Make it yours: account/profile setup.
+- Choose a space: personal or organization workspace selection.
+- Meet your Mac: environment analysis.
+- Pick a brain: model recommendation.
+- Install locally: consent-gated model/runtime setup.
+- Try a question: model validation through conversation.
+- Set the pace: Calm, Deep, or Admin mode.
+- Explore memory: open the knowledge map.
+
+## Behavior
+
+The journey reads real backend state from profile, workspace, models, and model
+recommendation APIs. The guide can be hidden through local storage, but no
+backend state is faked to mark setup complete.
+
+## Evidence
+
+- Primary component: `frontend/src/components/FirstRunGuide.tsx`
+- Desktop screenshot: `output/audits/v4.5.1-reimagining/screenshots/home-desktop.png`
+- Walkthrough GIF: `output/audits/v4.5.1-reimagining/gifs/v4.5.1-reimagining-walkthrough.gif`

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_6_0_LIVING_BRAIN_EXPERIENCE_REPORT.md

@@ -0,0 +1,58 @@
+# v4.6.0 Living Brain Experience Report
+
+## Goal
+
+v4.6.0 stops presenting Lattice AI as a graph product or dashboard. The
+first-run product flow is Login -> Environment Analysis -> Recommended Models
+-> Install & Load -> Brain. After setup, the Brain is the center of the desktop
+experience, and the graph is repositioned as an advanced layer for intentional
+relationship exploration.
+
+## Product Changes
+
+- First launch opens to a premium minimal Login screen only.
+- Setup runs as a full-screen guided sequence: friendly environment analysis,
+  short ranked model recommendations, and install/download/validate/load.
+- After model load, `/app` and `/app#/brain` open into Brain plus conversation.
+- The living Brain remains visible during primary conversation and reacts to
+  listening, recall, thinking, and active agent/workflow signals.
+- `/app#/ask` and `/app#/chat` remain compatible but route to the Brain
+  conversation.
+- Primary navigation is reduced to Brain, Memory, Files, Automations, Models,
+  and Settings.
+- Brain tabs now follow the product ladder: Brain, Memories, Knowledge,
+  Relationships, Graph, Care.
+- First-run setup no longer appears as dashboard cards above any app page; it
+  gates the app before the Brain opens.
+
+## Architecture
+
+- Added `frontend/src/components/LivingBrain.tsx` as the animated Brain
+  presence component.
+- Added `frontend/src/components/BrainConversation.tsx` to centralize chat
+  streaming, history, image attachment, model status, memory previews, and
+  Brain activity state.
+- Added `frontend/src/components/ProductFlow.tsx` to own Login, environment
+  analysis, recommendation, install/download/validate/load, and Brain entry.
+- Kept graph parsing, Cytoscape rendering, search, provenance, portability, and
+  archive APIs intact.
+- Kept FastAPI, Tauri, StorageEngine, Brain Core, backup/restore, and
+  portability unchanged.
+
+## Compatibility
+
+- Existing backend routes are unchanged.
+- Legacy hash routes continue to resolve through the SPA route alias table.
+- The advanced graph remains available at `/app#/knowledge-graph`.
+- The old Ask page imports the shared Brain conversation component to avoid
+  duplicate chat behavior.
+
+## Validation Scope
+
+The v4.6.0 work should be validated with:
+
+- frontend lint/typecheck/build
+- Python syntax validation
+- affected visual tests
+- unit tests covering version consistency and route compatibility
+- Tauri cargo check when the desktop toolchain is available

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.6.0 Living Brain Experience; 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.6.0)
+
+**v4.6.0 makes the Brain the product after the v4.5.1 product-shell reset
+without changing Brain Core, storage, API, model runtime, backup, portability,
+or agent/workflow behavior.** Current implementation milestone: Brain plus
+conversation is the home screen, the living Brain is always visible during the
+primary conversation experience, and graph exploration is preserved as the
+deepest intentional layer behind Memories, Knowledge, and Relationships.
+The v4.6.0 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 unless explicitly requested.
 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,12 @@ 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
-flows remain exposed through existing APIs, desktop sidecar behavior remains
-validated, and exact v4.3.3 release artifacts are the release target.
+None. v4.6.0 preserves the already-empty v4.3.2/v4.3.3/v4.5.0/v4.5.1 gap list
+and promotes the Living Brain tree: Brain conversation is primary, 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.6.0 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/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <meta name="color-scheme" content="dark light" />
-    <title>Lattice AI · Digital Brain</title>
+    <title>Lattice AI · Living Brain</title>
     <link rel="manifest" href="/manifest.json" />
     <link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32.png" />
     <script>
@@ -18,7 +18,7 @@
   </head>
   <body>
     <div id="root"></div>
-    <noscript>Lattice AI requires JavaScript for the local Digital Brain desktop shell.</noscript>
+    <noscript>Lattice AI requires JavaScript for the local Living Brain desktop shell.</noscript>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>