ltcai 4.4.0 → 4.6.0

package/README.md

@@ -7,12 +7,18 @@
 [![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-**Lattice AI v4.4.0 is a local-first Digital Brain desktop workspace.** It runs
+**Lattice AI v4.6.0 is a local-first Living Brain desktop workspace.** It runs
 as a Tauri desktop app with a localhost FastAPI sidecar, stores the user's brain
-locally by default, and presents the Knowledge Graph as the durable asset.
-
-This README describes the v4.4.0 release tree, which completes the physical
-extraction of the Brain Core into the standalone `lattice_brain` package.
+locally by default, and makes the Brain plus conversation the primary product
+experience.
+
+This README describes the v4.6.0 release-preparation tree, which preserves the
+v4.4.0 physical `lattice_brain` extraction, v4.5.0 capability recovery, and
+v4.5.1 product shell while repositioning the graph as a deep exploration layer.
+First launch now follows a Brain-first product flow: Login, friendly environment
+analysis, recommended models, guided install/download/validate/load, then the
+living Brain conversation. Memories, knowledge, relationships, and the advanced
+graph are progressively disclosed beneath the Brain.
 External package registries are owner-published; the badges above link to
 package pages and may show the most recently published owner-controlled registry
 version, which can lag behind the GitHub Release.
@@ -21,16 +27,27 @@ version, which can lag behind the GitHub Release.
 
 - Desktop app starts and serves the React/Vite product shell from the FastAPI
   sidecar.
-- Brain graph renders persisted local graph data with search, groups, focus,
-  filtering, and hybrid-search results.
-- Ask displays durable conversations, graph context, and honest unavailable
-  state when no model is loaded.
+- First launch opens to Login only, then guides environment analysis,
+  recommendations, install/download/validate/load, and finally the Brain.
+- After model loading, the home route opens to a living Brain presence plus
+  durable conversation, with the Brain always visible during the primary chat
+  flow.
+- The Brain presence reacts to conversation, recall, model readiness, and
+  agent/workflow activity with neural movement, memory pulses, and status
+  changes.
+- Memories, Knowledge, Relationships, and Graph are ordered as progressive
+  disclosure layers; the graph is no longer the product's first impression.
 - Capture uploads a document through `/upload/document` and shows indexed
   documents from the backend.
 - Act exposes workflow create/run surfaces and agent runtime status without
   presenting simulation as real success. When no LLM-backed model is loaded,
   deterministic model-free agent simulation is reported honestly and does not call a model.
-- Library shows model/runtime availability honestly.
+- Model setup recommends a short ranked list for the current computer instead
+  of exposing a catalog or runtime internals.
+- Gemma 4 MLX models are checked against their local `config.json` before load:
+  Gemma 4 12B `gemma4_unified` now shows **Runtime update needed** when the
+  installed MLX-VLM lacks `mlx_vlm.models.gemma4_unified`, while Gemma 4 26B
+  A4B stays on the working `gemma4` MLX-VLM path.
 - System exposes storage, backup health, archive, Brain Network, device
   identity, and admin status through real APIs.
 - Backup, restore dry-run, archive verify, archive import dry-run, and
@@ -40,7 +57,7 @@ version, which can lag behind the GitHub Release.
 
 ### Desktop Startup
 
-The v4.4.0 DMG build launches a visible Tauri app, starts the FastAPI sidecar on
+The v4.6.0 DMG build launches a visible Tauri app, starts the FastAPI sidecar on
 localhost, and shuts that sidecar down on normal macOS quit.
 
 ![Desktop startup and local sidecar](output/audits/v4.3.2-rc/screenshots/13-desktop-sidecar-startup.png)
@@ -50,24 +67,28 @@ Evidence:
 - Health log: `output/audits/v4.3.2-rc/logs/desktop-sidecar-health-after-shutdown-fix.json`
 - Shutdown log: `output/audits/v4.3.2-rc/logs/desktop-shutdown-after-fix.txt`
 
-### Brain Graph
+### Living Brain
+
+Brain opens on a living presence and conversation. The visual Brain is not a
+logo or static decoration: it changes state while the user types, when memories
+are recalled, while a response streams, and when agent/workflow activity is
+reported.
 
-Brain opens on the graph-first workspace. The graph uses real persisted nodes
-and edges from `/knowledge-graph/graph`, then layers product controls for search,
-semantic grouping, focus neighborhoods, label modes, group collapse/expand, and
-importance filtering.
+The advanced graph still exists, but it is intentionally opened from the Graph
+layer after the user moves through Brain, Memories, Knowledge, and
+Relationships.
 
 ![Brain graph explorer](output/audits/v4.3.2-rc/screenshots/02-graph-explorer-before.png)
 
 ![Graph product walkthrough](output/audits/v4.3.2-rc/gifs/graph-product-walkthrough.gif)
 
-### Ask
+### Conversation
 
-Ask uses backend conversation, model, and graph context APIs. In the audited
-state no model was loaded, so the UI showed a ready/unavailable state instead of
-fabricating an answer while still surfacing graph context from local data.
+Conversation uses backend conversation, model, and memory APIs. If no model is
+loaded, the UI shows a ready/unavailable state instead of fabricating an answer
+while still keeping nearby memory and source signals visible.
 
-![Ask with graph context and no-model honesty](output/audits/v4.3.2-rc/screenshots/14-ask-context.png)
+![Conversation with context and no-model honesty](output/audits/v4.3.2-rc/screenshots/14-ask-context.png)
 
 ### Capture
 
@@ -94,7 +115,10 @@ LLM-backed model is loaded.
 
 Library shows models, skills, MCP, and marketplace/configuration state with
 availability reported from runtime APIs. Optional model runtimes are not treated
-as loaded unless the runtime is actually available.
+as loaded unless the runtime is actually available. Model setup now follows the
+explicit Environment Analysis -> Recommended Models -> Install -> Download
+Progress -> Validate -> Load -> Ready path, with download/install consent kept
+visible.
 
 ![Library model status](output/audits/v4.3.2-rc/screenshots/12-library-model-status.png)
 
@@ -148,17 +172,19 @@ Archive evidence:
 - **Privacy**: local-first by default; cloud models, Telegram, Brain Network,
   Docker, model downloads, and update checks require explicit opt-in paths.
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) for the detailed v4.4.0 architecture.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the detailed v4 architecture. v4.6.0
+does not redesign the v4.4.0 Brain Core extraction, StorageEngine, FastAPI,
+Tauri, backup/restore, or portability architecture.
 
 ## Installation And Release Artifacts
 
-Validated v4.4.0 artifacts are produced from the extraction tree:
+Validated v4.6.0 artifacts are produced from the Living Brain tree:
 
-- `dist/ltcai-4.4.0-py3-none-any.whl`
-- `dist/ltcai-4.4.0.tar.gz`
-- `ltcai-4.4.0.tgz`
-- `dist/ltcai-4.4.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_4.4.0_aarch64.dmg`
+- `dist/ltcai-4.6.0-py3-none-any.whl`
+- `dist/ltcai-4.6.0.tar.gz`
+- `ltcai-4.6.0.tgz`
+- `dist/ltcai-4.6.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.6.0_aarch64.dmg`
 
 For a public release, attach only those exact artifacts to the GitHub Release.
 Package-registry publishing is reserved for the owner.
@@ -194,7 +220,7 @@ npm run test:unit
 LTCAI_TEST_BASE_URL=http://127.0.0.1:4932 npm run test:integration
 npm run test:visual
 npm run desktop:tauri:check
-node scripts/run_python.mjs scripts/wheel_smoke.py --wheel dist/ltcai-4.4.0-py3-none-any.whl
+node scripts/run_python.mjs scripts/wheel_smoke.py --wheel dist/ltcai-X.Y.Z-py3-none-any.whl
 npm pack --dry-run
 ```
 
@@ -206,14 +232,17 @@ npm pack --dry-run
   local use.
 - Docker is never auto-started by default.
 - Model downloads and cloud model calls require explicit user action/consent.
-- Ask does not fabricate answers when no model is loaded.
+- Conversation does not fabricate answers when no model is loaded.
 - Historical artifacts may remain in `dist/`; release uploads must use exact
-  v4.4.0 filenames.
+  v4.6.0 filenames for this release.
 
 ## Release History
 
 | Version | Theme |
 | --- | --- |
+| 4.6.0 | Living Brain Experience: made Brain plus conversation the home product, added an animated living Brain presence, and moved graph exploration to the deepest intentional layer |
+| 4.5.1 | Product Reimagining RC: replaced the desktop shell, navigation model, onboarding journey, first-viewport hierarchy, and visual system while preserving capabilities and local-first architecture |
+| 4.5.0 | Product Experience Recovery RC: restored first-run setup, workspace/model onboarding, explicit model install/download/validate/load flow, Gemma 4 runtime compatibility gating, Basic-mode polish, and graph discoverability |
 | 4.4.0 | Brain Engine Extraction: Brain Core physically moved into `lattice_brain` (graph/memory/context/conversation/ingestion/runtime/workflow/portability), latticeai paths reduced to compatibility shims, isolation tests guaranteeing no `latticeai` imports |
 | 4.3.3 | Dead-Code Cleanup Release: post-audit cleanup, architecture documentation correction, Vercel/static-docs readiness, README badge restoration, exact-current artifacts |
 | 4.3.2 | Product Polish & Graph UX Overhaul RC: evidence-based README, graph UX, structured product state, archive UX, desktop sidecar cleanup, publishing readiness |
@@ -227,10 +256,13 @@ npm pack --dry-run
 
 ## Current Documentation
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) - v4.4.0 architecture.
+- [ARCHITECTURE.md](ARCHITECTURE.md) - v4 architecture.
 - [FEATURE_STATUS.md](FEATURE_STATUS.md) - current feature status and historical
   status ledger.
 - [RELEASE_NOTES.md](RELEASE_NOTES.md) - current release notes index.
+- [RELEASE_NOTES_v4.6.0.md](RELEASE_NOTES_v4.6.0.md) - v4.6.0 Living Brain release notes.
+- [RELEASE_NOTES_v4.5.1.md](RELEASE_NOTES_v4.5.1.md) - v4.5.1 RC release notes.
+- [RELEASE_NOTES_v4.5.0.md](RELEASE_NOTES_v4.5.0.md) - v4.5.0 RC release notes.
 - [RELEASE_NOTES_v4.4.0.md](RELEASE_NOTES_v4.4.0.md) - v4.4.0 release notes.
 - [RELEASE_NOTES_v4.3.3.md](RELEASE_NOTES_v4.3.3.md) - v4.3.3 release notes.
 - [RELEASE.md](RELEASE.md) - release checklist and exact artifact guidance.
@@ -238,6 +270,18 @@ npm pack --dry-run
 - [docs/CHANGELOG.md](docs/CHANGELOG.md) - changelog.
 - [docs/V4_3_2_DEADCODE_AUDIT_REPORT.md](docs/V4_3_2_DEADCODE_AUDIT_REPORT.md) - v4.3.3 cleanup basis.
 - [docs/V4_3_3_VALIDATION_REPORT.md](docs/V4_3_3_VALIDATION_REPORT.md) - v4.3.3 validation report.
+- [docs/V4_5_0_PRODUCT_EXPERIENCE_RECOVERY_REPORT.md](docs/V4_5_0_PRODUCT_EXPERIENCE_RECOVERY_REPORT.md) - v4.5.0 product recovery report.
+- [docs/V4_5_0_VALIDATION_REPORT.md](docs/V4_5_0_VALIDATION_REPORT.md) - v4.5.0 validation report.
+- [docs/V4_5_1_PRODUCT_REIMAGINING_REPORT.md](docs/V4_5_1_PRODUCT_REIMAGINING_REPORT.md) - v4.5.1 product reimagining report.
+- [docs/V4_5_1_UX_REPORT.md](docs/V4_5_1_UX_REPORT.md) - v4.5.1 UX report.
+- [docs/V4_5_1_VISUAL_DESIGN_REPORT.md](docs/V4_5_1_VISUAL_DESIGN_REPORT.md) - v4.5.1 visual design report.
+- [docs/V4_5_1_NAVIGATION_REPORT.md](docs/V4_5_1_NAVIGATION_REPORT.md) - v4.5.1 navigation report.
+- [docs/V4_5_1_ONBOARDING_REPORT.md](docs/V4_5_1_ONBOARDING_REPORT.md) - v4.5.1 onboarding report.
+- [docs/V4_5_1_MODEL_EXPERIENCE_REPORT.md](docs/V4_5_1_MODEL_EXPERIENCE_REPORT.md) - v4.5.1 model experience report.
+- [docs/V4_5_1_GRAPH_EXPERIENCE_REPORT.md](docs/V4_5_1_GRAPH_EXPERIENCE_REPORT.md) - v4.5.1 graph experience report.
+- [docs/V4_5_1_VALIDATION_REPORT.md](docs/V4_5_1_VALIDATION_REPORT.md) - v4.5.1 validation report.
+- [docs/V4_5_1_RC_ARTIFACTS.md](docs/V4_5_1_RC_ARTIFACTS.md) - v4.5.1 screenshot, GIF, and RC artifact manifest.
+- [docs/V4_6_0_LIVING_BRAIN_EXPERIENCE_REPORT.md](docs/V4_6_0_LIVING_BRAIN_EXPERIENCE_REPORT.md) - v4.6.0 Living Brain design and validation notes.
 - [docs/V4_3_2_GRAPH_UX_REPORT.md](docs/V4_3_2_GRAPH_UX_REPORT.md) - graph UX report.
 - [docs/V4_3_2_PRODUCT_POLISH_REPORT.md](docs/V4_3_2_PRODUCT_POLISH_REPORT.md) - product polish report.
 - [docs/V4_3_2_SELF_AUDIT_REPORT.md](docs/V4_3_2_SELF_AUDIT_REPORT.md) - self-audit evidence.

package/docs/CHANGELOG.md

@@ -3,6 +3,134 @@
 The top entry is the current release-preparation target. Older entries are
 historical and may describe behavior as it existed at that release.
 
+## [4.6.0] - 2026-06-13
+
+> Living Brain Experience release after the v4.5.1 product shell reset.
+
+### Changed
+
+- Added the required first-launch product flow: Login -> Environment Analysis
+  -> Recommended Models -> Install & Load -> Brain.
+- Made Brain plus conversation the post-model-load `/app` and `/app#/brain`
+  experience.
+- Added an animated living Brain presence that reacts to listening, memory
+  recall, streaming/thinking, and agent/workflow activity.
+- Centralized chat streaming, model status, image attachment, conversation
+  history, and memory previews in a reusable Brain conversation component.
+- Reduced visible primary navigation to Brain, Memory, Files, Automations,
+  Models, and Settings;
+  `/ask` and `/chat` remain route-compatible aliases into Brain.
+- Reordered Brain layers as Brain -> Memories -> Knowledge -> Relationships ->
+  Graph, moving graph exploration to the deepest intentional layer.
+- Updated visual palette and copy so the product reads as a living digital
+  Brain rather than a graph tool or dashboard.
+- Removed the first-run dashboard/setup-card panel from the app shell; setup is
+  now a full-screen product sequence before the Brain opens.
+
+### Preserved
+
+- Brain Core, FastAPI APIs, Tauri shell, StorageEngine, backup/restore,
+  portability, model runtimes, graph/search/chat/capture/automation/system
+  workflows, and route aliases remain capability-compatible.
+
+### Validation
+
+- v4.6.0 validation scope is tracked in
+  `docs/V4_6_0_LIVING_BRAIN_EXPERIENCE_REPORT.md`.
+
+### Artifacts
+
+- `dist/ltcai-4.6.0-py3-none-any.whl`
+- `dist/ltcai-4.6.0.tar.gz`
+- `dist/ltcai-4.6.0.vsix`
+- `ltcai-4.6.0.tgz`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.6.0_aarch64.dmg`
+
+## [4.5.1] - 2026-06-13
+
+> Product Reimagining release candidate after the v4.5.0 capability recovery.
+
+### Changed
+
+- Replaced the desktop shell with a compact premium chrome, ambient brain
+  canvas, command palette, responsive mobile drawer, and six-room product model:
+  Home, Ask, Add, Automate, Library, Care.
+- Rewrote first-run onboarding as a non-technical journey: Make it yours ->
+  Choose a space -> Meet your Mac -> Pick a brain -> Install locally -> Try a
+  question -> Set the pace -> Explore memory.
+- Retained all compatibility hash routes while changing visible navigation,
+  information hierarchy, route labels, and page hero language.
+- Replaced the global visual system with a calmer Digital Brain palette,
+  fixed-size responsive typography, 8px-or-smaller card radii, and refined
+  shared controls.
+
+### Preserved
+
+- Brain Core, FastAPI APIs, Tauri shell, StorageEngine, backup/restore,
+  portability, model runtimes, graph/search/chat/capture/automation/system
+  workflows, and route aliases remain capability-compatible.
+
+### Validation
+
+- Full v4.5.1 RC validation is tracked in
+  `docs/V4_5_1_VALIDATION_REPORT.md`.
+
+### Artifacts
+
+- `dist/ltcai-4.5.1-py3-none-any.whl`
+- `dist/ltcai-4.5.1.tar.gz`
+- `dist/ltcai-4.5.1.vsix`
+- `ltcai-4.5.1.tgz`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.1_aarch64.dmg`
+
+## [4.5.0] - 2026-06-13
+
+> Product Experience Recovery release candidate after the v4.4.0 physical Brain
+> extraction.
+
+### Changed
+
+- Restored the first-run product journey in the desktop shell: Login ->
+  Workspace Selection -> Environment Analysis -> Model Recommendation -> Model
+  Installation -> Model Validation -> Mode Selection -> Brain Usage.
+- Reworked Library Models around the existing prepare/load stream so model setup
+  visibly moves through Environment Analysis, Recommended Models, Install,
+  Download Progress, Validate, Load, and Ready.
+- Basic mode now uses friendlier connected/needs-setup status language and
+  hides endpoint/module details in the Brain graph, model cards, and computer
+  readiness panels while preserving Advanced/Admin inspection detail.
+- Brain graph/search copy now emphasizes ideas, relationships, sources, focus,
+  filtering, and readability instead of backend endpoint implementation.
+
+### Fixed
+
+- Gemma 4 MLX routing now reads local model metadata before load. Gemma 4 12B
+  `gemma4_unified` shows **Runtime update needed** when installed MLX-VLM lacks
+  `mlx_vlm.models.gemma4_unified`; Gemma 4 26B A4B remains ready on the
+  standard `gemma4` MLX-VLM path.
+- Raw loader errors such as `No module named ...gemma4_unified` are converted
+  into actionable runtime-update guidance instead of marking the model ready or
+  routing it through an incompatible MLX-LM fallback.
+- Workspace selection now persists across reloads so the selected workspace is
+  used by API requests after restart.
+
+### Validation
+
+- Added unit coverage for Gemma 4 12B versus 26B runtime compatibility,
+  recommendation state, catalog routing, and the MLX-LM fallback guard.
+- Added Playwright coverage for first-run setup, model setup flow, Gemma
+  recovery guidance, and Basic graph developer-leakage prevention.
+- Full v4.5.0 RC validation is tracked in
+  `docs/V4_5_0_VALIDATION_REPORT.md`.
+
+### Artifacts
+
+- `dist/ltcai-4.5.0-py3-none-any.whl`
+- `dist/ltcai-4.5.0.tar.gz`
+- `dist/ltcai-4.5.0.vsix`
+- `ltcai-4.5.0.tgz`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.0_aarch64.dmg`
+
 ## [4.4.0] - 2026-06-13
 
 > Brain Engine Extraction release: the Brain Core implementation physically

package/docs/V4_5_0_GEMMA_RUNTIME_COMPATIBILITY_REPORT.md

@@ -0,0 +1,49 @@
+# v4.5.0 Gemma Runtime Compatibility Report
+
+Date: 2026-06-13
+
+## Regression
+
+Gemma 4 12B Instruct and Gemma 4 26B A4B were both presented as local Gemma 4
+models, but they do not enter the same loader path. The first real divergence is
+the local `config.json`: 12B declares `model_type: gemma4_unified`, while 26B
+A4B declares `model_type: gemma4`. Installed MLX-VLM 0.5.0 can load the 26B
+standard `gemma4` path, but it lacks `mlx_vlm.models.gemma4_unified`, and
+MLX-LM does not provide a `gemma4_unified` loader either.
+
+## Fix
+
+- `latticeai.core.model_compat` reads the local model metadata before load and
+  reports `runtime_update_needed` for 12B `gemma4_unified` when
+  `mlx_vlm.models.gemma4_unified` is absent.
+- `latticeai.models.router` keeps the v3 MLX-VLM path first and only retries
+  MLX-LM for standard Gemma 4 metadata. It does not route `gemma4_unified`
+  through the incompatible MLX-LM fallback.
+- `/models` preserves pulled/ready state for no-alias local MLX models, so 26B
+  A4B stays ready while 12B shows the honest runtime-update state.
+- Generic loader failures are converted into friendly recovery payloads without
+  hiding the root cause.
+- Recommendation classification marks the 12B MLX snapshot not recommended until
+  the installed runtime can load it, while the 26B A4B path remains recommended.
+
+## User Guidance
+
+The UI recommends:
+
+- update MLX-VLM to a version with `mlx_vlm.models.gemma4_unified`
+  (`mlx-vlm>=0.6.3`) before loading the 12B MLX snapshot,
+- use Gemma 4 26B A4B locally while the 12B runtime update is pending,
+- use Gemma 4 12B GGUF through Ollama, LM Studio, or llama.cpp as a local-server
+  alternative.
+
+## Tests
+
+- `tests/unit/test_model_compat.py`
+- `tests/unit/test_model_recommendation.py`
+- `tests/unit/test_mlx_router_gemma4_fallback.py`
+- `tests/unit/test_models_api_runtime_routing.py`
+- `tests/visual/v3.spec.js`
+
+## Evidence
+
+Screenshot: `output/audits/v4.5.0-rc/screenshots/03-gemma-runtime-recovery.png`

package/docs/V4_5_0_GRAPH_UX_REPORT.md

@@ -0,0 +1,34 @@
+# v4.5.0 Graph UX Report
+
+Date: 2026-06-13
+
+## Goal
+
+Improve discoverability, readability, focus, searching, and filtering without
+redesigning the graph architecture.
+
+## Changes
+
+- Graph copy now describes ideas, relationships, sources, and saved items
+  instead of backend endpoints.
+- Basic mode hides raw node IDs in the focus panel and shows connections/source
+  instead.
+- Search placeholder is product-oriented in Basic mode.
+- Brain search copy explains unified memory/graph/document search without
+  exposing endpoint mechanics.
+- Advanced/Admin retain structured inspection where useful.
+
+## Existing Capabilities Preserved
+
+- Cytoscape graph rendering
+- semantic groups
+- search
+- label modes
+- importance filter
+- focus neighborhoods
+- group collapse/expand
+- backend hybrid search
+
+## Evidence
+
+Screenshot: `output/audits/v4.5.0-rc/screenshots/04-graph-basic-focus.png`

package/docs/V4_5_0_MODEL_RUNTIME_UX_REPORT.md

@@ -0,0 +1,40 @@
+# v4.5.0 Model Runtime UX Report
+
+Date: 2026-06-13
+
+## Restored Flow
+
+Library Models now presents the intended model flow:
+
+1. Environment Analysis
+2. Recommended Models
+3. Install
+4. Download Progress
+5. Validate
+6. Load
+7. Ready
+
+## Implementation
+
+- Frontend uses the existing `/engines/prepare-model/stream` API for progress.
+- The consent checkbox is required before a setup action may install a runtime
+  or download model files.
+- Current model, top pick, computer readiness, and compatibility validation are
+  visible in one workflow.
+- Advanced/Admin modes show load IDs and engine details; Basic mode shows
+  product-level status and recovery.
+
+## Failure UX
+
+Runtime failures show:
+
+- a clear actionable state such as runtime update, repair, download, fallback,
+  or unsupported format,
+- friendly explanation,
+- recovery guidance,
+- alternatives,
+- no raw Python module exception in Basic mode.
+
+## Evidence
+
+Screenshot: `output/audits/v4.5.0-rc/screenshots/02-model-setup-flow.png`

package/docs/V4_5_0_ONBOARDING_REPORT.md

@@ -0,0 +1,31 @@
+# v4.5.0 Onboarding Report
+
+Date: 2026-06-13
+
+## Restored Surface
+
+The desktop shell now shows a first-run setup guide unless the user dismisses it
+locally. It is also discoverable from the command palette as First-run Setup.
+
+## Covered Steps
+
+- Login: opens System -> Account.
+- Workspace Selection: opens System -> Workspaces.
+- Environment Analysis: opens Library -> Models and uses model recommendation
+  data from `/models/recommendations`.
+- Model Recommendation: surfaces the top recommended local model.
+- Model Installation: keeps runtime install/model download consent visible.
+- Model Validation: shows compatibility profile results after load.
+- Mode Selection: links to System -> Settings and preserves Basic/Advanced/Admin.
+- Brain Usage: opens the graph-first Brain surface.
+
+## Privacy Behavior
+
+No external model download, runtime install, or cloud call starts from
+onboarding. Downloads and installs require the visible Library consent checkbox.
+
+## Evidence
+
+Primary screenshot: `output/audits/v4.5.0-rc/screenshots/01-first-run-setup.png`
+
+Walkthrough GIF: `output/audits/v4.5.0-rc/gifs/v4.5.0-first-run-walkthrough.gif`

package/docs/V4_5_0_PRODUCT_EXPERIENCE_RECOVERY_REPORT.md

@@ -0,0 +1,49 @@
+# v4.5.0 Product Experience Recovery Report
+
+Date: 2026-06-13
+
+## Scope
+
+v4.5.0 restores the product experience on `main` after v4.4.0. It does not
+redesign `lattice_brain`, StorageEngine, FastAPI, Tauri, backup/restore, or
+portability architecture.
+
+## Restored Journey
+
+Before v4.5.0, account, workspace, setup, environment analysis, model setup, and
+mode selection existed but were scattered inside System/Library surfaces.
+
+After v4.5.0, the first-run path is visible from the app shell:
+
+1. Login
+2. Workspace Selection
+3. Environment Analysis
+4. Model Recommendation
+5. Model Installation
+6. Model Validation
+7. Mode Selection
+8. Brain Usage
+
+## Product Changes
+
+- Added a first-run guide in the desktop app shell with direct actions for
+  account, workspace, model setup, mode choice, and Brain entry.
+- Persisted the selected workspace across reloads so the chosen workspace is
+  used by API requests after restart.
+- Reworked Library Models around the existing streamed prepare/load path.
+- Kept model downloads and runtime installs behind explicit consent.
+- Added Gemma 4 MLX runtime metadata checks so 12B `gemma4_unified` shows
+  runtime update guidance while 26B A4B remains ready on the working path.
+- Reduced Basic-mode developer leakage while keeping Advanced/Admin detail.
+- Updated graph/search copy for readability, focus, and source clarity.
+
+## Evidence
+
+- Screenshots: `output/audits/v4.5.0-rc/screenshots/`
+- GIFs: `output/audits/v4.5.0-rc/gifs/`
+- Validation: `docs/V4_5_0_VALIDATION_REPORT.md`
+
+## No-Redesign Confirmation
+
+No storage migrations, archive format changes, FastAPI architecture changes,
+Tauri shell redesign, or Brain Core extraction changes were introduced.

package/docs/V4_5_0_VALIDATION_REPORT.md

@@ -0,0 +1,60 @@
+# v4.5.0 Validation Report
+
+Date: 2026-06-13
+
+## Status
+
+Local RC validation passed on macOS using Python 3.12.13
+(`/tmp/ltcai-v450-py312/bin/python`).
+
+## Required Matrix
+
+| Check | Result |
+| --- | --- |
+| Python compile | PASS: `npm run check:python` |
+| Ruff | PASS: `python -m ruff check .` |
+| Unit tests | PASS: `npm run test:unit` (`607 passed`) |
+| Integration tests | PASS: `npm run test:integration` against a live local server (`9 passed`, `1 skipped`) |
+| `lattice_brain` isolation tests | PASS: `tests/unit/test_lattice_brain_isolation.py` |
+| no `lattice_brain` -> `latticeai` import test | PASS: isolation import guard |
+| graph/search/ingestion tests | PASS: focused graph, search, and ingestion suite (`79 passed`) |
+| backup/restore tests | PASS: `tests/unit/test_kg_portability.py`, `tests/unit/test_v42_brain_storage.py` |
+| `.latticebrain` archive tests | PASS: encrypted archive round trip, tamper rejection, dry-run restore |
+| frontend lint/typecheck | PASS: `npm run lint`, `npm run typecheck` |
+| Playwright | PASS: `npm run test:visual` (`14 passed`) |
+| Tauri cargo check | PASS: `npm run desktop:tauri:check` |
+| Tauri DMG build | PASS: `npm run release:artifacts` |
+| release artifact validation | PASS: `npm run release:validate` |
+| wheel smoke | PASS: `scripts/wheel_smoke.py --wheel dist/ltcai-4.5.0-py3-none-any.whl` |
+| npm pack dry-run | PASS: `npm pack --dry-run` |
+| onboarding/model/Gemma/first-run validation | PASS: Playwright coverage plus screenshots/GIF evidence |
+
+## Notes
+
+- The first integration run was executed without the live local server and
+  failed with connection-refused setup errors. It was rerun against
+  `http://127.0.0.1:8899` and passed.
+- The Postgres live migration integration test remains skipped unless the
+  dedicated Postgres fixture is available.
+- Vite reports the existing large frontend bundle warning during production
+  builds.
+- Tauri/Rust reports an upstream future-incompatibility warning for
+  `block v0.1.6`.
+- SHA-256 artifact hashes were captured after the final local artifact rebuild
+  so this report can be packaged without creating self-referential hash churn.
+
+## Evidence
+
+- Screenshots: `output/audits/v4.5.0-rc/screenshots/`
+- Walkthrough GIF: `output/audits/v4.5.0-rc/gifs/v4.5.0-first-run-walkthrough.gif`
+- Validated artifacts:
+  - `dist/ltcai-4.5.0-py3-none-any.whl`
+  - `dist/ltcai-4.5.0.tar.gz`
+  - `ltcai-4.5.0.tgz`
+  - `dist/ltcai-4.5.0.vsix`
+  - `src-tauri/target/release/bundle/dmg/Lattice AI_4.5.0_aarch64.dmg`
+
+## External Publishing
+
+No PyPI, npm Registry, VS Code Marketplace, or Open VSX publish command is part
+of this RC validation.

package/docs/V4_5_1_GRAPH_EXPERIENCE_REPORT.md

@@ -0,0 +1,33 @@
+# v4.5.1 Graph Experience Report
+
+## Goal
+
+Knowledge exploration should feel like using a Digital Brain, not inspecting a
+database viewer.
+
+## Reimagined Entry Point
+
+Brain is now presented as Home. The default tab is Today, with the map still one
+click away. The first-viewport language now explains that Lattice turns added
+material into a living memory map and keeps every answer tied to its source.
+
+## Preserved Capability
+
+- Cytoscape graph explorer.
+- Semantic groups.
+- Search, focus, label modes, group collapse, and importance filtering.
+- Provenance coverage.
+- Hybrid search.
+- Portability and backup controls.
+
+## Presentation Changes
+
+- Page copy avoids endpoint/framework language in Calm mode.
+- Graph remains real and API-backed.
+- Existing graph route aliases still open the map directly.
+
+## Evidence
+
+- Graph UI: `frontend/src/pages/Brain.tsx`
+- Visual test: `knowledge graph renders a Cytoscape canvas and provenance coverage`
+- Related historical report: `docs/V4_5_0_GRAPH_UX_REPORT.md`