ltcai 4.3.3 → 4.5.1

package/README.md

@@ -7,12 +7,14 @@
 [![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.3.3 is a local-first Digital Brain desktop workspace.** It runs
+**Lattice AI v4.5.1 is a local-first Digital 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.3.3 release tree, which promotes the post-cleanup
-main branch after the v4.3.2 self-audit and independent dead-code/runtime audit.
+This README describes the v4.5.1 release-candidate tree, which preserves the
+v4.4.0 physical `lattice_brain` extraction and v4.5.0 capability recovery while
+reimagining the product surface from first principles: Home, Ask, Add,
+Automate, Library, and Care replace the prior dashboard-style presentation.
 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.
@@ -31,6 +33,13 @@ version, which can lag behind the GitHub Release.
   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.
+- First-run setup guides Make it yours -> Choose a space -> Meet your Mac ->
+  Pick a brain -> Install locally -> Try a question -> Set the pace -> Explore
+  memory.
+- 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 +49,7 @@ version, which can lag behind the GitHub Release.
 
 ### Desktop Startup
 
-The v4.3.3 DMG build launches a visible Tauri app, starts the FastAPI sidecar on
+The v4.5.1 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)
@@ -53,9 +62,8 @@ Evidence:
 ### Brain Graph
 
 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.
+and edges, then layers product controls for search, semantic grouping, focus
+neighborhoods, label modes, group collapse/expand, and importance filtering.
 
 ![Brain graph explorer](output/audits/v4.3.2-rc/screenshots/02-graph-explorer-before.png)
 
@@ -94,7 +102,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)
 
@@ -136,8 +147,11 @@ Archive evidence:
 - **Frontend**: React, TypeScript, Vite, TanStack Query, Zustand, Cytoscape.js,
   React Flow, Tailwind/shadcn-style primitives, generated OpenAPI client.
 - **Backend**: FastAPI on localhost is the source of truth for the UI.
-- **Brain Core**: independent Python package `lattice_brain`, imported by
-  FastAPI, CLI, tests, and future tools.
+- **Brain Core**: independent Python package `lattice_brain` (graph, memory,
+  context, conversations, ingestion, agent/hook runtime, workflow,
+  portability, storage) physically hosted in the package, imported by FastAPI,
+  CLI, tests, and future tools, and guaranteed by tests to never import
+  `latticeai`.
 - **Storage**: `StorageEngine` abstraction with SQLite default and optional
   PostgreSQL/pgvector scale mode.
 - **Portability**: encrypted `.latticebrain` archive plus backup/restore and
@@ -145,17 +159,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.3.3 architecture.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the detailed v4 architecture. v4.5.1
+does not redesign the v4.4.0 Brain Core extraction, StorageEngine, FastAPI,
+Tauri, backup/restore, or portability architecture.
 
 ## Installation And Release Artifacts
 
-Validated v4.3.3 artifacts are produced from the post-cleanup tree:
+Validated v4.5.1 RC artifacts are produced from the product-reimagining tree:
 
-- `dist/ltcai-4.3.3-py3-none-any.whl`
-- `dist/ltcai-4.3.3.tar.gz`
-- `ltcai-4.3.3.tgz`
-- `dist/ltcai-4.3.3.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_4.3.3_aarch64.dmg`
+- `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`
 
 For a public release, attach only those exact artifacts to the GitHub Release.
 Package-registry publishing is reserved for the owner.
@@ -191,7 +207,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.3.3-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
 ```
 
@@ -205,12 +221,15 @@ npm pack --dry-run
 - Model downloads and cloud model calls require explicit user action/consent.
 - Ask does not fabricate answers when no model is loaded.
 - Historical artifacts may remain in `dist/`; release uploads must use exact
-  v4.3.3 filenames.
+  v4.5.1 filenames for this RC.
 
 ## Release History
 
 | Version | Theme |
 | --- | --- |
+| 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 |
 | 4.3.1 | End-User Audit Repair RC: desktop sidecar startup, npm clean install, default-off downloads, honest agent/workflow states |
@@ -223,16 +242,30 @@ npm pack --dry-run
 
 ## Current Documentation
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) - v4.3.3 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.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.
 - [SECURITY.md](SECURITY.md) - security posture.
 - [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_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,128 @@
 The top entry is the current release-preparation target. Older entries are
 historical and may describe behavior as it existed at that release.
 
+## [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
+> moves into the standalone `lattice_brain` package.
+
+### Changed
+
+- Physically moved the knowledge graph (schema, store, write/retrieval/
+  discovery/documents/ingest/projection/provenance mixins, identity, network,
+  curator) into `lattice_brain.graph`, and memory, context, conversations into
+  `lattice_brain` proper.
+- Physically moved the unified ingestion pipeline, hooks registry, multi-agent
+  orchestrator, agent runtime, workflow engine, and KG portability service into
+  `lattice_brain.ingestion`, `lattice_brain.runtime`, `lattice_brain.workflow`,
+  and `lattice_brain.portability`.
+- FastAPI app assembly, routers, and services now import `lattice_brain`
+  directly; `latticeai.brain.*` became deprecation shims and the moved
+  `latticeai.core.*`/`latticeai.services.*` paths became silent alias shims
+  with module identity preserved.
+- Synchronized all version copies to `4.4.0` and updated architecture/release
+  documentation to describe the physical extraction.
+
+### Added
+
+- `tests/unit/test_lattice_brain_isolation.py`: fails if `lattice_brain`
+  imports `latticeai` (import-hook enforced) and exercises the Brain Core
+  end-to-end (graph ingest/search, conversations, context, workflow, agent
+  runtime, encrypted archive round-trip) without FastAPI.
+- `lattice_brain.graph` and `lattice_brain.runtime` subpackages, shipped in the
+  wheel and covered by the wheel smoke check.
+
+### Fixed
+
+- The Brain Core boundary is no longer an import-path contract: importing
+  `lattice_brain` no longer pulls in `latticeai.brain`, and the package is
+  usable by CLI, tests, and future tools fully independently.
+
 ## [4.3.3] - 2026-06-13
 
 > Dead-Code Cleanup release after the independent audit cleanup on top of

package/docs/V4_4_0_EXTRACTION_REPORT.md

@@ -0,0 +1,239 @@
+# v4.4.0 Physical Extraction Report — `lattice_brain` Brain Engine
+
+Date: 2026-06-13
+Scope: complete physical extraction of the Brain Core implementation into the
+standalone `lattice_brain` package. The release flow attaches only validated
+v4.4.0 artifacts to GitHub; no external package registry publishing is part of
+this release step.
+
+## 1. Problem Before v4.4.0
+
+`lattice_brain` provided an import-path contract only. The graph, memory,
+context, conversation, and ingestion implementations physically lived under
+`latticeai/brain/` (and `latticeai/core/`, `latticeai/services/`) and were
+re-exported through `lattice_brain.*`. Importing `lattice_brain.store`
+actually executed `latticeai.brain.store`, so the Brain Core could not be
+used, tested, or distributed independently of the FastAPI product package.
+
+## 2. Dependency Graph
+
+### Before (v4.3.3)
+
+```
+lattice_brain.store/schema/retrieval/... (1-line re-exports)
+        │  imports
+        ▼
+latticeai.brain.* (physical implementation)
+        │  imports
+        ├─ latticeai.services.ingestion  (memory → IngestionItem)
+        │        └─ latticeai.core.hooks (dispatch_tool)
+        ├─ latticeai.core.graph_curator  (projection, lazy)
+        └─ kg_schema (root shim → lattice_brain.schema → latticeai.brain.schema)
+latticeai.services.agent_runtime → latticeai.core.multi_agent
+latticeai.services.kg_portability → lattice_brain.archive/storage (already clean)
+latticeai.core.workflow_engine    (stdlib only, hosted in latticeai)
+```
+
+Net effect: `import lattice_brain.store` pulled in `latticeai`.
+
+### After (v4.4.0)
+
+```
+latticeai (FastAPI app, routers, services, product backend)
+        │  imports (one direction only)
+        ▼
+lattice_brain (physical Brain Engine)
+  ├─ core, archive, embeddings, storage/        (already physical in v4.2+)
+  ├─ graph/   _kg_common, schema, store, write_master, retrieval, discovery,
+  │           documents, ingest, projection, provenance, identity, network,
+  │           curator
+  ├─ memory, context, conversations
+  ├─ ingestion                                   (uses .runtime.hooks)
+  ├─ runtime/ hooks, multi_agent, agent_runtime
+  ├─ workflow
+  └─ portability                                 (uses .archive/.storage/.graph.identity)
+```
+
+`lattice_brain` has zero `latticeai` imports — enforced by an import-hook test.
+External (third-party/optional) deps of the package: `cryptography`, `keyring`,
+`httpx`, `psycopg` (opt-in), `sqlite-vec` (opt-in), document parsers
+(`pdfplumber`, `python-docx`, `openpyxl`, `python-pptx`, `PIL`) — all already
+declared in `pyproject.toml`.
+
+## 3. Files Moved (physical, via `git mv`, history preserved)
+
+Knowledge graph → `lattice_brain/graph/`:
+
+| From | To |
+| --- | --- |
+| `latticeai/brain/_kg_common.py` | `lattice_brain/graph/_kg_common.py` |
+| `latticeai/brain/schema.py` | `lattice_brain/graph/schema.py` |
+| `latticeai/brain/store.py` | `lattice_brain/graph/store.py` |
+| `latticeai/brain/write_master.py` | `lattice_brain/graph/write_master.py` |
+| `latticeai/brain/retrieval.py` | `lattice_brain/graph/retrieval.py` |
+| `latticeai/brain/discovery.py` | `lattice_brain/graph/discovery.py` |
+| `latticeai/brain/documents.py` | `lattice_brain/graph/documents.py` |
+| `latticeai/brain/ingest.py` | `lattice_brain/graph/ingest.py` |
+| `latticeai/brain/projection.py` | `lattice_brain/graph/projection.py` |
+| `latticeai/brain/provenance.py` | `lattice_brain/graph/provenance.py` |
+| `latticeai/brain/identity.py` | `lattice_brain/graph/identity.py` |
+| `latticeai/brain/network.py` | `lattice_brain/graph/network.py` |
+| `latticeai/core/graph_curator.py` | `lattice_brain/graph/curator.py` |
+
+Memory / context / conversation:
+
+| From | To |
+| --- | --- |
+| `latticeai/brain/memory.py` | `lattice_brain/memory.py` |
+| `latticeai/brain/context.py` | `lattice_brain/context.py` |
+| `latticeai/brain/conversations.py` | `lattice_brain/conversations.py` |
+
+Ingestion / runtime / workflow / portability:
+
+| From | To |
+| --- | --- |
+| `latticeai/services/ingestion.py` | `lattice_brain/ingestion.py` |
+| `latticeai/core/hooks.py` | `lattice_brain/runtime/hooks.py` |
+| `latticeai/core/multi_agent.py` | `lattice_brain/runtime/multi_agent.py` |
+| `latticeai/services/agent_runtime.py` | `lattice_brain/runtime/agent_runtime.py` |
+| `latticeai/core/workflow_engine.py` | `lattice_brain/workflow.py` |
+| `latticeai/services/kg_portability.py` | `lattice_brain/portability.py` |
+
+19 files moved with history; 2 new subpackage `__init__.py` files
+(`lattice_brain/graph/`, `lattice_brain/runtime/`).
+
+Import edges rewritten inside moved code (the only source changes to the
+implementations):
+
+- `graph/_kg_common.py`: `latticeai.brain.schema` → `.schema`;
+  `lattice_brain.embeddings` → `..embeddings`
+- `graph/projection.py`: lazy `latticeai.core.graph_curator` → `.curator`
+- `graph/provenance.py`: lazy `kg_schema` → `.schema`
+- `graph/network.py`: `lattice_brain.identity` → `.identity`
+- `graph/store.py`: lazy `lattice_brain.storage` → `..storage`
+- `memory.py`: `latticeai.services.ingestion` → `.ingestion`
+- `ingestion.py`: `latticeai.core.hooks` → `.runtime.hooks`
+- `runtime/agent_runtime.py`: `latticeai.core.multi_agent` → `.multi_agent`
+- `portability.py`: absolute `lattice_brain.*` → relative; lazy identity →
+  `.graph.identity`
+- `runtime/hooks.py`: three `binding` metadata strings updated to the new
+  physical paths
+
+## 4. Re-Export Modules Deleted / Replaced
+
+Deleted (the old `lattice_brain → latticeai.brain` re-exports — the "fake
+extraction" layer):
+`lattice_brain/{_kg_common,schema,store,write_master,retrieval,discovery,documents,ingest,projection,provenance,network,identity}.py`
+
+Each path was recreated as an **internal alias shim** (`sys.modules[__name__] =
+lattice_brain.graph.<name>`), so old flat imports keep working with module
+identity preserved (the shim and the physical module are the same object —
+singletons, `isinstance`, and monkeypatching are unaffected). These alias the
+package to itself; nothing re-exports `latticeai` anymore.
+
+## 5. Compatibility Shims Kept (latticeai side)
+
+Deprecation shims (emit `DeprecationWarning`, alias the physical module):
+
+- `latticeai/brain/__init__.py` (re-exports the public surface from
+  `lattice_brain`)
+- `latticeai/brain/{store,schema,retrieval,discovery,documents,ingest,projection,provenance,write_master,network,identity,_kg_common,memory,context,conversations}.py`
+
+Silent alias shims (still-supported old paths):
+
+- `latticeai/core/hooks.py` → `lattice_brain.runtime.hooks`
+- `latticeai/core/multi_agent.py` → `lattice_brain.runtime.multi_agent`
+- `latticeai/core/workflow_engine.py` → `lattice_brain.workflow`
+- `latticeai/core/graph_curator.py` → `lattice_brain.graph.curator`
+- `latticeai/services/ingestion.py` → `lattice_brain.ingestion`
+- `latticeai/services/agent_runtime.py` → `lattice_brain.runtime.agent_runtime`
+- `latticeai/services/kg_portability.py` → `lattice_brain.portability`
+
+Root-level shims (`kg_schema.py`, `knowledge_graph.py`, …) continue to work
+unchanged through the flat `lattice_brain.*` paths.
+
+## 6. Consumers Updated to Import `lattice_brain` Directly
+
+`latticeai/app_factory.py`, `latticeai/core/{agent,agent_registry,builtin_hooks}.py`,
+`latticeai/api/{hooks,tools,computer_use,agents,browser,workflow_designer,chat,mcp}.py`,
+`latticeai/services/{platform_runtime,run_executor,upload_service}.py`,
+`p_reinforce.py`, `scripts/bump_version.py`, `scripts/wheel_smoke.py`, and all
+test modules now use the physical `lattice_brain` paths. Zero non-shim
+references to the old module locations remain.
+
+## 7. New Tests
+
+`tests/unit/test_lattice_brain_isolation.py`:
+
+1. **`test_lattice_brain_never_imports_latticeai`** — subprocess installs a
+   `sys.meta_path` finder that raises on any `latticeai` import, imports every
+   `lattice_brain` module via `pkgutil.walk_packages`, resolves every lazy
+   facade export, and asserts `latticeai` never entered `sys.modules`. This
+   test fails if `lattice_brain` ever imports `latticeai`.
+2. **`test_lattice_brain_usable_in_isolation`** — with the same import block
+   active and FastAPI never started: `BrainCore` construction, ingestion
+   pipeline → graph write, graph search, conversation store append/count,
+   context assembly, workflow engine run, agent runtime/hooks availability,
+   and an encrypted `.latticebrain` archive create → inspect → verify
+   round-trip.
+
+## 8. Packaging / Version Changes
+
+- `pyproject.toml`: packages now include `lattice_brain.graph` and
+  `lattice_brain.runtime`; version `4.4.0`.
+- `scripts/wheel_smoke.py`: import matrix extended with the new subpackages
+  and modules.
+- `scripts/bump_version.py`: `MULTI_AGENT_VERSION` target re-pointed to
+  `lattice_brain/runtime/multi_agent.py`.
+- All 13 synchronized version copies bumped to `4.4.0` via
+  `scripts/bump_version.py` (Python, npm, lockfiles, VSIX, Tauri, asset
+  manifest, runtime constants).
+- Docs updated: `ARCHITECTURE.md` (packaging note now describes the physical
+  layout and the isolation guarantee), `README.md` (Brain Core claim, history,
+  artifact names), `FEATURE_STATUS.md`, `SECURITY.md` (supported versions),
+  `RELEASE_NOTES.md`, `RELEASE_NOTES_v4.4.0.md`, `docs/CHANGELOG.md`,
+  `CHANGELOG.md` pointer.
+
+## 9. User Data and Behavior
+
+No storage schema, migration, archive format, or API change. The SQLite
+default engine, Postgres opt-in path, `.latticebrain` archive format, and
+backup/restore flows are byte-identical code, relocated. Old pickles are not
+used; module identity through shims keeps any dynamic lookups working.
+
+## 10. Validation Results
+
+Environment note: final release validation ran locally on macOS with Python
+3.12.13 (`LTCAI_PYTHON=/tmp/ltcai-v440-py312/bin/python`), Node 26.0.0,
+npm 11.12.1, Rust 1.96.0, Cargo 1.96.0, and Tauri CLI 2.0.0.
+
+| Check | Result |
+| --- | --- |
+| Python compile (`compileall` over `lattice_brain`, `latticeai`, `tests`, `tools`, `scripts`, root modules) | PASS |
+| `ruff check .` | PASS (no findings) |
+| Unit tests (`pytest tests/unit`) | **604 passed** (includes the 2 new isolation tests) |
+| Integration tests (`pytest tests/integration` against live uvicorn on localhost) | 9 passed, 1 skipped (live-Postgres test, opt-in by design) |
+| `lattice_brain` isolation tests | PASS (both) |
+| No `lattice_brain → latticeai` import test | PASS |
+| Graph/search/ingestion tests (`test_kg_*`, `test_ingestion_pipeline`, `test_browser_ingestion`, …) | PASS (within unit suite) |
+| Backup/restore + `.latticebrain` archive tests (`test_kg_portability`, archive round-trip in isolation test) | PASS |
+| Frontend lint (`npm run lint`) | PASS |
+| Frontend typecheck (`tsc --noEmit` + VS Code extension `tsc`) | PASS |
+| Playwright visual tests (`npx playwright test`) | **12 passed** |
+| Tauri check (`cargo check`) | PASS (existing transitive `block v0.1.6` future-incompat warning) |
+| Tauri DMG build (`npm run release:artifacts`) | PASS (`Lattice AI_4.4.0_aarch64.dmg`) |
+| Release artifact validation (`scripts/validate_release_artifacts.py 4.4.0 --require-vsix --require-tgz --require-dmg`) | PASS (warns about historical versions in `dist/`, as designed) |
+| Wheel smoke | PASS (29 wheel modules import from the wheel; `/health` returns `4.4.0`) |
+| `npm pack --dry-run` | PASS (315 files) |
+
+## 11. v4.4.0 Artifacts Built
+
+- `dist/ltcai-4.4.0-py3-none-any.whl` (contains `lattice_brain/graph/*`,
+  `lattice_brain/runtime/*`; verified by wheel content check + smoke)
+- `dist/ltcai-4.4.0.tar.gz`
+- `ltcai-4.4.0.tgz` (npm pack)
+- `dist/ltcai-4.4.0.vsix` (built via `scripts/build_vsix.mjs`)
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.4.0_aarch64.dmg`
+
+Per instructions: GitHub Release attachment uses only these exact validated
+v4.4.0 artifacts. External package registries are not published.

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`