ltcai 5.1.0 → 5.3.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,99 @@
+# Lattice AI Development
+
+This document is for contributors working on the local-first Digital Brain
+codebase. Product positioning and quick start stay in `README.md`; release
+history stays in `docs/CHANGELOG.md` and `RELEASE.md`.
+
+## Product Contract
+
+Lattice AI is a local-first Digital Brain that keeps your knowledge durable
+across any AI model.
+
+Engineering work should preserve these boundaries:
+
+- the Brain is the durable asset;
+- models are replaceable voices;
+- SQLite is the default local store;
+- PostgreSQL, Docker, cloud models, downloads, update checks, Telegram, and
+  Brain Network are opt-in;
+- import-only paths must not initialize MLX/GPU, write files, or make network
+  calls;
+- normal Brain use must stay separate from Admin/operator controls.
+
+## Local Setup
+
+```bash
+npm install
+npm run dev
+```
+
+The local app is served through the FastAPI sidecar at:
+
+```text
+http://127.0.0.1:4825/app
+```
+
+Apple Silicon local model extras:
+
+```bash
+pip install "ltcai[local]"
+```
+
+## Validation
+
+Run the smallest affected gate while iterating. Before committing broad runtime,
+API, UI, or release work, run:
+
+```bash
+npm run check:python
+node scripts/run_python.mjs -m ruff check .
+npm run lint
+npm run typecheck
+npm run test:unit
+npm run docs:check-links
+```
+
+Use these when the change touches the relevant surface:
+
+```bash
+npm run test:integration
+npm run test:visual
+npm run desktop:tauri:check
+npm run release:artifacts
+npm run release:validate
+```
+
+## Runtime Assembly
+
+`latticeai.app_factory` is the composition root. Keep it import-safe:
+
+- no MLX/GPU init at module import time;
+- no singleton construction at module import time;
+- no filesystem writes at module import time;
+- no external network calls at module import time.
+
+Runtime assembly seams live under `latticeai.runtime`:
+
+- `config_runtime.py` derives app config values from `Config`;
+- `security_runtime.py` applies trusted proxy/security-derived settings;
+- `brain_runtime.py` constructs Brain Core and conversation primitives.
+
+Future extraction should continue with router assembly, model runtime assembly,
+platform/hooks assembly, static asset serving, and lifespan/startup/shutdown.
+
+## Documentation Sync
+
+For user-facing, API, runtime, release, or packaging changes, check:
+
+- `README.md`
+- `ARCHITECTURE.md`
+- `FEATURE_STATUS.md`
+- `RELEASE.md`
+- `docs/CHANGELOG.md`
+- `SECURITY.md` when trust/security changes
+- `vscode-extension/README.md` when editor integration changes
+- `docs/LEGACY_COMPATIBILITY.md` when root compatibility files change
+
+Release/publish examples must use exact target-version filenames. Do not
+document wildcard upload commands such as `dist/*`.
+

package/docs/LEGACY_COMPATIBILITY.md

@@ -0,0 +1,55 @@
+# Legacy Compatibility Map
+
+Lattice AI is moving toward a smaller, modular architecture centered on
+`lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.
+Some root-level modules remain packaged for compatibility with older imports,
+CLI entrypoints, or extension workflows. Their presence does not define the
+current architecture.
+
+## Current Policy
+
+- Keep compatibility shims while public imports or package entrypoints still
+  depend on them.
+- Prefer moving implementation into focused packages before removing a root
+  module.
+- Add deprecation notes before removal.
+- Avoid breaking package users during a minor release.
+- Do not silently remove rollback, backup, restore, or migration paths.
+
+## Root Module Map
+
+| Legacy root module | Current home / direction | Why it remains |
+| --- | --- | --- |
+| `knowledge_graph.py` | `lattice_brain.graph` / `lattice_brain.knowledge` | Compatibility for older graph imports and historical tooling |
+| `knowledge_graph_api.py` | `latticeai.api.memory`, `latticeai.api.search`, graph-related API routers | Compatibility for older API import paths |
+| `kg_schema.py` | `lattice_brain` storage/schema modules | Compatibility for graph schema references |
+| `auto_setup.py` | setup/model recommendation services | Compatibility for zero-config setup probes and historical auto-setup commands |
+| `llm_router.py` | `latticeai.models.router` | Compatibility for older local model routing imports |
+| `ltcai_cli.py` | package console entrypoint (`ltcai`) | Compatibility for the installed CLI contract |
+| `mcp_registry.py` | `latticeai.core.mcp_registry` and service-backed registries | Compatibility for MCP/skills lookup entrypoints |
+| `local_knowledge_api.py` | `lattice_brain.ingestion`, workspace capture APIs | Compatibility for local folder/file watcher flows |
+| `p_reinforce.py` | gardener/maintenance service direction | Compatibility for existing Brain gardening runtime hooks |
+| `telegram_bot.py` | opt-in integration package or disabled-by-default connector | Compatibility only; Telegram must remain opt-in |
+| `setup_wizard.py` | setup and model recommendation services | Compatibility for first-run recommendation calls |
+| `server.py` | lazy proxy to `latticeai.server_app` / `latticeai.app_factory` | Preserves historical `server.app` imports without import-time construction |
+
+## Packaging Notes
+
+`pyproject.toml` and `package.json` still include several root modules because
+older installed packages may import them directly. That is intentional for now.
+The long-term target is:
+
+- move implementation into `lattice_brain`, `latticeai.core`, `latticeai.models`,
+  `latticeai.services`, or `latticeai.api`;
+- leave thin shims with docstrings/deprecation warnings;
+- remove a shim only after tests prove no supported entrypoint relies on it.
+
+## Removal Checklist
+
+Before removing or excluding a legacy module:
+
+1. Search imports in the repository and generated package files.
+2. Add or update a compatibility test.
+3. Confirm the package still imports from a fresh non-repo working directory.
+4. Update `README.md`, `ARCHITECTURE.md`, `FEATURE_STATUS.md`, and this file.
+5. Run unit tests, package build, and wheel smoke validation.

package/docs/V4_1_VALIDATION_REPORT.md

@@ -43,5 +43,5 @@ FastAPI backend compatibility, release artifacts, and installed-wheel smoke.
   `block v0.1.6`; the current Tauri 2.0 build passes on Rust 1.96.
 - Release artifact validation warns that historical artifacts remain in
   `dist/`; this is expected and reinforces the rule to upload only exact
-  v4.1.0 filenames, never `dist/*`.
+  v4.1.0 filenames, never a wildcard from the `dist` directory.
 - No external registry publish was performed.

package/docs/V4_3_PRODUCT_HARDENING_REPORT.md

@@ -44,8 +44,8 @@ architecture.
 - Release artifact validation now checks the exact Tauri DMG path.
 - Release artifact build script cleans only target-version outputs before
   rebuilding.
-- Historical artifacts remain visible so `dist/*` upload mistakes are still
-  detectable.
+- Historical artifacts remain visible so wildcard upload mistakes from `dist`
+  are still detectable.
 
 ## Registry Policy
 

package/docs/V4_5_1_VALIDATION_REPORT.md

@@ -51,4 +51,5 @@ Expected exact-version artifacts:
 
 `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.
+must continue to use explicit v4.5.1 filenames rather than a wildcard from the
+`dist` directory.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-**Your private AI memory layer. Keep your knowledge. Switch any model.**
+**Lattice AI is a local-first Digital Brain that keeps your knowledge durable across any AI model.**
 
 **모델은 바꿔도, 내 지식은 남는 로컬 AI 브레인.**
 
@@ -26,7 +26,9 @@ Lattice AI is a local-first private AI memory layer. It keeps conversations,
 documents, decisions, relationships, and project history in a Brain that belongs
 to the user. Models can be local, cloud, current, or future. The Brain remains.
 
-The graph is real, but it is not the product identity. Users start with Brain
+The graph is real, but it is not the product identity. Product category is
+local-first Digital Brain; core capability is a private AI memory layer; UX
+metaphor is the Living Brain. Users start with Brain
 Chat, memory, topics, relationships, ownership, backup, and graph exploration.
 Advanced admin logs, roles, hooks, workflows, Telegram, Brain Network, Docker,
 Postgres, and plugin details stay outside the normal user flow.
@@ -51,4 +53,3 @@ Postgres, and plugin details stay outside the normal user flow.
 - Not a ChatGPT or Claude clone.
 
 Lattice AI is for people who want their knowledge to survive model changes.
-

package/frontend/src/components/FirstRunGuide.tsx

@@ -36,11 +36,11 @@ export function FirstRunGuide() {
   const readyProfile = compatProfiles.some((item) => item.chat_compatible || item.quality_status === "ok" || item.quality_status === "degraded");
 
   const steps = [
-    { label: "Make it yours", done: Boolean(profileData.email), icon: UserCircle, action: "account", detail: "Sign in or keep a local profile." },
+    { label: "Make it yours", done: Boolean(profileData.email), icon: UserCircle, action: "account", detail: "Choose the owner of this local AI Brain." },
     { label: "Choose a space", done: Boolean(registry.active_workspace || workspaceData.active_workspace), icon: Users, action: "workspace-admin", detail: "Decide where memories belong." },
-    { label: "Meet your Mac", done: recs.isSuccess, icon: Cpu, action: "models", detail: "Let Lattice inspect what can run locally." },
-    { label: "Pick a brain", done: Boolean(topPick || currentModel), icon: Library, action: "models", detail: "Use the recommended local model." },
-    { label: "Install locally", done: Boolean(currentModel || loadedModels.length), icon: Download, action: "models", detail: "Download only with explicit consent." },
+    { label: "Meet your Mac", done: recs.isSuccess, icon: Cpu, action: "models", detail: "See what local Brain experience this computer can support." },
+    { label: "Pick a voice", done: Boolean(topPick || currentModel), icon: Library, action: "models", detail: "Use the recommended model without rebuilding memory later." },
+    { label: "Install with consent", done: Boolean(currentModel || loadedModels.length), icon: Download, action: "models", detail: "Download only after an explicit click." },
     { label: "Talk to Brain", done: Boolean(readyProfile || currentModel || loadedModels.length), icon: PlayCircle, action: "chat", detail: "Confirm the model can answer." },
     { label: "Set the pace", done: Boolean(mode), icon: SlidersHorizontal, action: "settings", detail: "Stay Calm or switch deeper." },
     { label: "Explore deeply", done: true, icon: Layers3, action: "knowledge-graph", detail: "Open advanced relationships." },
@@ -55,7 +55,7 @@ export function FirstRunGuide() {
         <div className="page-kicker"><CheckCircle2 className="h-4 w-4" /> First 10 minutes</div>
         <h2>Build your living Brain without guessing.</h2>
         <p>
-          Start with a space, let Lattice recommend a private local model, then add the first pieces of knowledge.
+          Start with a local Brain, let Lattice recommend a model voice, then add the first pieces of durable knowledge.
           Every step keeps the next action visible.
         </p>
         <div className="arrival-actions">

package/frontend/src/components/ProductFlow.tsx

@@ -531,7 +531,7 @@ function buildDetectedFacts(analysis: FlowAnalysis | null) {
     {
       label: "Computer",
       value: appleSilicon ? "Apple Silicon Mac" : friendlyOs(profile.os),
-      detail: "Ready for local AI workspace use",
+      detail: "Ready for local Digital Brain use",
     },
     {
       label: "Memory",

package/frontend/src/i18n.ts

@@ -13,11 +13,11 @@ export const COPY: Record<Language, TextMap> = {
     "language.ko": "한국어",
     "language.en": "English",
     "brain.level": "단계",
-    "brain.depth.1": "Living Brain",
-    "brain.depth.2": "Memory Layer",
-    "brain.depth.3": "Knowledge Layer",
-    "brain.depth.4": "Relationship Layer",
-    "brain.depth.5": "Knowledge Graph",
+    "brain.depth.1": "지금 기억",
+    "brain.depth.2": "오래된 기억",
+    "brain.depth.3": "주제",
+    "brain.depth.4": "관계",
+    "brain.depth.5": "전체 지식 그래프",
     "brain.view.memories": "기억 보기",
     "brain.view.topics": "주제 보기",
     "brain.view.relationships": "관계 보기",
@@ -29,11 +29,11 @@ export const COPY: Record<Language, TextMap> = {
     "brain.private": "개인 소유",
     "brain.admin": "관리자 콘솔",
     "brain.empty.kicker": "내 오래가는 기억",
-    "brain.empty.title": "잊으면 안 되는 일부터 말해 주세요.",
-    "brain.empty.body": "문서, 대화, 프로젝트, 결정이 Brain에 쌓이고 나중에 주제와 관계로 다시 보입니다.",
-    "brain.prompt.remember": "이 결정을 기억해줘: ",
-    "brain.prompt.know": "내가 이미 알고 있는 것은? ",
-    "brain.prompt.plan": "이 프로젝트 맥락을 계획으로 바꿔줘: ",
+    "brain.empty.title": "잊으면 안 되는 맥락부터 말해 주세요.",
+    "brain.empty.body": "문서, 대화, 프로젝트, 결정이 이 컴퓨터의 Brain에 쌓이고 나중에 주제와 관계로 다시 보입니다.",
+    "brain.prompt.remember": "이 프로젝트 목표를 기억해줘: ",
+    "brain.prompt.know": "이 문서를 내 Brain에 넣고 요약해줘: ",
+    "brain.prompt.plan": "지난 결정들을 나중에 찾을 수 있게 정리해줘: ",
     "brain.placeholder": "Brain에게 말하기...",
     "brain.image": "이미지",
     "brain.unavailable": "지금은 답할 수 없음",
@@ -75,16 +75,16 @@ export const COPY: Record<Language, TextMap> = {
     "admin.kicker": "분리된 관리자 작업공간",
     "admin.title": "Admin Console",
     "admin.body": "사용자, 로그, 보안, Brain 상태는 일반 사용자 화면과 분리됩니다.",
-    "flow.shell": "내 로컬 Brain 만들기",
-    "flow.login.title": "내 Brain을 시작합니다.",
-    "flow.login.body": "모델은 바뀔 수 있지만, 내 문서와 대화, 결정, 기억은 사라지면 안 됩니다. Lattice는 이 지식을 내가 소유하는 개인 Brain으로 모읍니다.",
+    "flow.shell": "내 로컬 AI 브레인 만들기",
+    "flow.login.title": "내 AI 브레인의 주인을 정합니다.",
+    "flow.login.body": "Lattice AI는 모델이 바뀌어도 내 지식과 맥락을 보존하는 로컬 우선 AI 브레인입니다. 대화와 기억은 기본적으로 이 컴퓨터에 저장됩니다.",
     "flow.name": "이름",
     "flow.email": "이메일",
     "flow.password": "비밀번호",
     "flow.password.placeholder": "로컬 Brain 비밀번호",
     "flow.login.busy": "Brain 여는 중...",
     "flow.login.submit": "내 Brain 시작하기",
-    "flow.login.note": "기존 Brain과 다른 이메일이면 새로 만들지 않고 먼저 확인합니다.",
+    "flow.login.note": "이 프로필은 내 AI 브레인의 주인입니다. 기존 Brain과 다른 이메일이면 새로 만들지 않고 먼저 확인합니다.",
     "flow.login.missing": "이름과 이메일, 비밀번호를 입력하면 기존 Brain을 안전하게 확인합니다.",
     "flow.login.otherEmail": "이 컴퓨터의 기존 Brain과 다른 이메일입니다. 오타인지 확인해 주세요.",
     "flow.login.wrongPassword": "기존 Brain 이메일은 맞지만 비밀번호가 다릅니다. 비밀번호를 다시 확인해 주세요.",
@@ -95,21 +95,21 @@ export const COPY: Record<Language, TextMap> = {
     "flow.promise.model.v": "모델은 목소리이고, 자산은 Brain입니다.",
     "flow.promise.ownership.k": "사용자 소유",
     "flow.promise.ownership.v": "백업, 복원, 이동이 가능합니다.",
-    "flow.analysis.title": "이 컴퓨터를 확인합니다.",
-    "flow.analysis.body": "Brain이 클라우드에 의존하지 않고 이 컴퓨터에서 편하게 돌아갈 수 있는지 확인합니다.",
+    "flow.analysis.title": "이 컴퓨터에서 가능한 경험을 확인합니다.",
+    "flow.analysis.body": "스펙 점수가 아니라, 이 Mac에서 어떤 로컬 AI 브레인 경험이 편한지 알려드립니다. 클라우드 모델은 선택 사항입니다.",
     "flow.analysis.finding": "가장 편한 설정을 찾는 중...",
     "flow.analysis.ready": "추천 모델을 바로 시작할 수 있게 준비했습니다.",
     "flow.analysis.wait": "잠시만 기다리면 자동으로 정리됩니다.",
     "flow.analysis.error": "Lattice가 이 컴퓨터를 끝까지 확인하지 못했습니다. 그래도 안전한 기본값으로 계속할 수 있습니다.",
     "flow.analysis.continue": "추천 모델 보기",
-    "flow.recommend.title": "추천 모델로 시작하세요.",
-    "flow.recommend.body": "모델은 Brain의 현재 목소리입니다. 나중에 바꿔도 기억과 지식은 그대로 남습니다.",
+    "flow.recommend.title": "추천대로 시작하세요.",
+    "flow.recommend.body": "모델은 Brain의 현재 목소리입니다. 가장 안전한 추천, 더 빠른 모델, 더 강한 모델만 먼저 보여드립니다.",
     "flow.recommend.primary": "추천대로 시작하기",
     "flow.recommend.unsupported": "이 컴퓨터에서 추가 확인이 필요합니다",
     "flow.recommend.back": "뒤로",
     "flow.recommend.hint": "잘 모르겠다면 추천대로 시작하면 됩니다.",
     "flow.install.title": "모델을 설치하고 시작합니다.",
-    "flow.install.body": "이 모델이 Brain의 로컬 목소리가 됩니다. 다운로드, 확인, 로드는 사용자가 누른 뒤에만 진행됩니다.",
+    "flow.install.body": "이 모델이 Brain의 로컬 목소리가 됩니다. 다운로드할 때만 인터넷이 필요하고, 실행은 내 컴퓨터에서 진행됩니다.",
     "flow.install.wait": "Brain이 사용할 모델을 기다리고 있습니다.",
     "flow.install.prepare": "Brain 준비 중입니다.",
     "flow.install.done": "Brain이 준비되었습니다.",
@@ -119,18 +119,18 @@ export const COPY: Record<Language, TextMap> = {
     "flow.install.start": "다운로드하고 시작하기",
     "flow.install.busy": "모델 준비 중...",
     "flow.install.enter": "Brain으로 들어가기",
-    "flow.install.local": "모든 작업은 이 컴퓨터에서 진행됩니다.",
+    "flow.install.local": "모델 다운로드와 외부 통신은 사용자가 시작할 때만 진행됩니다.",
   },
   en: {
     "language.label": "Language",
     "language.ko": "한국어",
     "language.en": "English",
     "brain.level": "Level",
-    "brain.depth.1": "Living Brain",
-    "brain.depth.2": "Memory Layer",
-    "brain.depth.3": "Knowledge Layer",
-    "brain.depth.4": "Relationship Layer",
-    "brain.depth.5": "Knowledge Graph",
+    "brain.depth.1": "Now memory",
+    "brain.depth.2": "Older memory",
+    "brain.depth.3": "Topics",
+    "brain.depth.4": "Relationships",
+    "brain.depth.5": "Full knowledge graph",
     "brain.view.memories": "Memories",
     "brain.view.topics": "Topics",
     "brain.view.relationships": "Relationships",
@@ -142,11 +142,11 @@ export const COPY: Record<Language, TextMap> = {
     "brain.private": "Private",
     "brain.admin": "Admin Console",
     "brain.empty.kicker": "Durable memory",
-    "brain.empty.title": "Start with what should not be forgotten.",
-    "brain.empty.body": "Documents, conversations, projects, and decisions accumulate in your Brain, then reappear as topics and relationships.",
-    "brain.prompt.remember": "Remember this decision: ",
-    "brain.prompt.know": "What do I already know about ",
-    "brain.prompt.plan": "Turn this project context into a plan: ",
+    "brain.empty.title": "Start with context that should not be forgotten.",
+    "brain.empty.body": "Documents, conversations, projects, and decisions accumulate in the Brain on this computer, then reappear as topics and relationships.",
+    "brain.prompt.remember": "Remember this project goal: ",
+    "brain.prompt.know": "Put this document into my Brain and summarize it: ",
+    "brain.prompt.plan": "Organize past decisions so I can find them later: ",
     "brain.placeholder": "Talk to your Brain...",
     "brain.image": "Image",
     "brain.unavailable": "Unavailable",
@@ -188,16 +188,16 @@ export const COPY: Record<Language, TextMap> = {
     "admin.kicker": "Separate admin workspace",
     "admin.title": "Admin Console",
     "admin.body": "Users, logs, security, and Brain health stay out of the normal user experience.",
-    "flow.shell": "Create your local Brain",
-    "flow.login.title": "Start your Brain.",
-    "flow.login.body": "Models can change, but your documents, conversations, decisions, and memories should stay yours. Lattice gathers them into a personal Brain you control.",
+    "flow.shell": "Create your local AI Brain",
+    "flow.login.title": "Choose the owner of your AI Brain.",
+    "flow.login.body": "Lattice AI is a local-first Digital Brain that keeps your knowledge durable across any AI model. Conversations and memories are stored on this computer by default.",
     "flow.name": "Name",
     "flow.email": "Email",
     "flow.password": "Password",
     "flow.password.placeholder": "Local Brain password",
     "flow.login.busy": "Opening Brain...",
     "flow.login.submit": "Start my Brain",
-    "flow.login.note": "If the email differs from this computer's Brain, Lattice checks before creating anything new.",
+    "flow.login.note": "This profile owns your AI Brain. If the email differs from this computer's Brain, Lattice checks before creating anything new.",
     "flow.login.missing": "Enter your name, email, and password so Lattice can safely check your Brain.",
     "flow.login.otherEmail": "This email differs from the Brain on this computer. Please check for a typo.",
     "flow.login.wrongPassword": "The email matches this Brain, but the password is different. Please check it again.",
@@ -208,21 +208,21 @@ export const COPY: Record<Language, TextMap> = {
     "flow.promise.model.v": "The model is the voice; the Brain is the asset.",
     "flow.promise.ownership.k": "User owned",
     "flow.promise.ownership.v": "Back up, restore, and move it.",
-    "flow.analysis.title": "Checking this computer.",
-    "flow.analysis.body": "Lattice checks whether your Brain can run comfortably on this computer without depending on the cloud.",
+    "flow.analysis.title": "Checking what this computer can do.",
+    "flow.analysis.body": "This is not a spec test. Lattice explains what local AI Brain experience this Mac can support. Cloud models remain optional.",
     "flow.analysis.finding": "Finding the easiest setup...",
     "flow.analysis.ready": "Your recommended model is ready to start.",
     "flow.analysis.wait": "This will be summarized automatically in a moment.",
     "flow.analysis.error": "Lattice could not finish checking this computer. You can still continue with a safe default.",
     "flow.analysis.continue": "View recommended models",
-    "flow.recommend.title": "Start with the recommended model.",
-    "flow.recommend.body": "The model is your Brain's current voice. You can change it later without losing memory or knowledge.",
+    "flow.recommend.title": "Start with the recommendation.",
+    "flow.recommend.body": "The model is your Brain's current voice. You see the safest recommendation, a faster model, and a stronger model first.",
     "flow.recommend.primary": "Start with recommendation",
     "flow.recommend.unsupported": "This computer needs one more check",
     "flow.recommend.back": "Back",
     "flow.recommend.hint": "If unsure, start with the recommendation.",
     "flow.install.title": "Install the model and start.",
-    "flow.install.body": "This model becomes your Brain's local voice. Download, validation, and loading begin only after you choose to start.",
+    "flow.install.body": "This model becomes your Brain's local voice. Internet is needed only for download; execution happens on this computer.",
     "flow.install.wait": "Waiting for the model your Brain will use.",
     "flow.install.prepare": "Preparing your Brain.",
     "flow.install.done": "Your Brain is ready.",
@@ -232,7 +232,7 @@ export const COPY: Record<Language, TextMap> = {
     "flow.install.start": "Download and start",
     "flow.install.busy": "Preparing model...",
     "flow.install.enter": "Enter Brain",
-    "flow.install.local": "Everything runs on this computer.",
+    "flow.install.local": "Downloads and external communication start only when you choose them.",
   },
 };
 

package/frontend/src/pages/Library.tsx

@@ -30,8 +30,8 @@ export function LibraryPage({ initialTab }: { initialTab?: string }) {
     <div className="space-y-5">
       <header className="page-hero">
         <div className="page-kicker"><Boxes className="h-4 w-4" /> Library</div>
-        <h1 className="page-title">Choose what powers Lattice.</h1>
-        <p className="page-copy">Pick a private local model, add skills, and connect tools without learning runtime internals.</p>
+        <h1 className="page-title">Choose your Brain's voice.</h1>
+        <p className="page-copy">Start with a short local model recommendation. Your Brain and memories stay durable when you switch later.</p>
       </header>
       <Tabs tabs={visibleTabs} value={tab} onChange={(id) => setTab(id as LibraryTab)} />
       {tab === "models" ? <ModelsPanel /> : null}
@@ -103,7 +103,7 @@ function ModelsPanel() {
   return (
     <div className="grid gap-4 xl:grid-cols-[1.2fr_0.8fr]">
       <div className="space-y-4">
-        <DataPanel title="Guided model setup" description="Analyze this Mac, recommend a model, install only with consent, validate it, then load it." result={recs.data}>
+        <DataPanel title="Guided model setup" description="Lattice recommends a small set first, explains internet/download needs, and keeps every model download behind consent." result={recs.data}>
           {(data) => {
             const recommendation = (data as Record<string, unknown>).recommendations as Record<string, unknown> | undefined;
             const profile = (data as Record<string, unknown>).profile as Record<string, unknown> | undefined;
@@ -134,7 +134,7 @@ function ModelsPanel() {
                 <label className="flex items-start gap-2 rounded-lg border border-border bg-background/55 p-3 text-sm leading-6">
                   <input className="mt-1" type="checkbox" checked={consent} onChange={(event) => setConsent(event.target.checked)} />
                   <span>
-                    Allow Lattice to install a missing local model component or download model files for this action.
+                    Allow Lattice to install a missing local model component or download model files for this action. Download uses the internet; running the model stays local.
                   </span>
                 </label>
                 {latestProgress ? (
@@ -151,15 +151,22 @@ function ModelsPanel() {
             );
           }}
         </DataPanel>
-        <DataPanel title="Recommended models" result={models.data}>
+        <DataPanel title={mode === "basic" ? "Recommended models" : "Recommended and advanced models"} result={models.data}>
         {(data) => (
           <div className="grid gap-2">
-            {(catalog.length ? catalog : asArray<Record<string, unknown>>((data as Record<string, unknown>).loaded)).slice(0, 14).map((model, index) => {
+            {(catalog.length ? catalog : asArray<Record<string, unknown>>((data as Record<string, unknown>).loaded)).slice(0, mode === "basic" ? 3 : 14).map((model, index) => {
               const id = String(model.id || model.model_id || model.name || index);
               const loaded = asArray<string>((data as Record<string, unknown>).loaded).includes(id) || (data as Record<string, unknown>).current === id || model.state === "loaded";
               const loadId = String(model.recommended_load_id || id);
               const engine = String(model.recommended_engine || model.engine || "");
               const recommendation = recommendationById.get(id) || recommendationById.get(loadId) || {};
+              const modelVerification = asRecord(model.verification);
+              const recommendationVerification = asRecord(recommendation.verification);
+              const modelHardware = asRecord(model.hardware);
+              const recommendationHardware = asRecord(recommendation.hardware);
+              const hardwareNote = modelHardware.notes || recommendationHardware.notes || (modelHardware.recommended_ram_gb ? `~${modelHardware.recommended_ram_gb}GB RAM rec` : "");
+              const safetyNotes = model.safety_notes || recommendation.safety_notes;
+              const licenseText = model.license || recommendation.license;
               const compatibility = (model.runtime_compatibility || recommendation.runtime_compatibility || {}) as Record<string, unknown>;
               const fallbackAvailable = String(compatibility.status || "") === "fallback_available";
               const unsupported = model.load_status === "unsupported" || compatibility.supported === false;
@@ -171,12 +178,16 @@ function ModelsPanel() {
               const actionLabel = String(compatibility.action || loadStatus.replace(/_/g, " "));
               const badgeLabel = unsupported && mode === "basic" ? "needs attention" : unsupported ? actionLabel : loadStatus;
               const canPrepare = loadAvailable || downloadRequired;
+              const downloadSize = model.download_size || model.estimated_size || recommendation.download_size || recommendation.estimated_size || model.size || recommendation.size;
+              const maker = model.provider || recommendation.provider || model.organization || recommendation.organization;
               return (
                 <div key={id} className="grid gap-3 rounded-lg border border-border bg-background/55 p-4 md:grid-cols-[1fr_auto]">
                   <div className="min-w-0">
                     <div className="flex flex-wrap items-center gap-2">
                         <div className="text-base font-semibold">{String(model.name || id)}</div>
-                      {topPick?.id === id ? <Badge variant="success">recommended</Badge> : null}
+                      {topPick?.id === id || model.recommended_default ? <Badge variant="success">recommended</Badge> : null}
+                      {String(model.modality || recommendation.modality || "").includes("multi") || String(model.modality || "") === "multimodal" ? <Badge variant="muted">multimodal</Badge> : null}
+                      {modelVerification.verified || recommendationVerification.verified ? <Badge variant="success" title="HF verified (config+tokenizer present)">✓ HF</Badge> : null}
                     </div>
                     <div className="mt-1 text-sm text-muted-foreground">
                       {mode === "basic"
@@ -186,6 +197,16 @@ function ModelsPanel() {
                         ].filter(Boolean).map(String).join(" · ")
                         : [model.family || recommendation.family || "local", model.size || recommendation.size].filter(Boolean).map(String).join(" · ")}
                     </div>
+                    {(model.hardware || recommendation.hardware) ? (
+                      <div className="mt-1 text-[11px] text-muted-foreground/80">
+                        {String(hardwareNote)}
+                      </div>
+                    ) : null}
+                    <div className="mt-2 flex flex-wrap gap-1 text-[11px] text-muted-foreground">
+                      <Badge variant="muted">{downloadRequired ? `Download: ${String(downloadSize || "required")}` : "No download needed now"}</Badge>
+                      <Badge variant="muted">{downloadRequired ? "Internet only during download" : "Runs locally when loaded"}</Badge>
+                      {maker ? <Badge variant="muted">{String(maker)}</Badge> : null}
+                    </div>
                     {unsupported ? (
                       <div className="mt-3 rounded-lg border border-amber-500/30 bg-amber-500/10 p-3 text-sm">
                         <div className="font-medium">{mode === "basic" ? "Needs attention before loading" : actionLabel}</div>
@@ -198,8 +219,15 @@ function ModelsPanel() {
                       </div>
                     ) : !loaded && !loadAvailable ? <div className="mt-1 text-xs text-muted-foreground">{unavailableReason}</div> : null}
                     {mode !== "basic" ? (
-                      <div className="mt-2 text-xs text-muted-foreground">
-                        {runtimeLabel} · {loadId}
+                      <div className="mt-2 space-y-1 text-xs text-muted-foreground">
+                        <div>
+                          {runtimeLabel} · {loadId}
+                          {model.load_strategy || recommendation.load_strategy ? ` · ${String(model.load_strategy || recommendation.load_strategy)}` : ""}
+                          {modelVerification.notes ? ` · ${String(modelVerification.notes).slice(0,60)}` : ""}
+                        </div>
+                        {safetyNotes || licenseText ? (
+                          <div>{[licenseText ? `License: ${String(licenseText)}` : "", safetyNotes ? String(safetyNotes) : ""].filter(Boolean).join(" · ")}</div>
+                        ) : null}
                       </div>
                     ) : null}
                     {unsupported || fallbackAvailable ? <AlternativeModels compatibility={compatibility} /> : null}
@@ -221,6 +249,11 @@ function ModelsPanel() {
                 </div>
               );
             })}
+            {mode === "basic" && catalog.length > 3 ? (
+              <div className="rounded-lg border border-border bg-background/55 p-3 text-sm text-muted-foreground">
+                Showing the safest short list. Switch to Advanced for the full registry, runtime details, licenses, and safety notes.
+              </div>
+            ) : null}
           </div>
         )}
         </DataPanel>
@@ -277,6 +310,10 @@ function ModelRecovery({ error }: { error: Record<string, unknown> }) {
   );
 }
 
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
 function SkillsPanel() {
   const qc = useQueryClient();
   const skills = useQuery({ queryKey: ["skills"], queryFn: latticeApi.skills });

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "5.1.0"
+__version__ = "5.3.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/archive.py

@@ -14,6 +14,7 @@ import io
 import json
 import os
 import shutil
+import sqlite3
 import tempfile
 import zipfile
 from dataclasses import dataclass
@@ -111,6 +112,16 @@ def _sqlite_siblings(db_path: Path) -> tuple[Path, Path, Path]:
     return (db_path, Path(str(db_path) + "-wal"), Path(str(db_path) + "-shm"))
 
 
+def _checkpoint_sqlite(db_path: Path) -> None:
+    if not db_path.exists():
+        return
+    try:
+        with sqlite3.connect(str(db_path)) as conn:
+            conn.execute("PRAGMA wal_checkpoint(FULL)")
+    except sqlite3.Error:
+        return
+
+
 def _restore_sibling(path: Path, backup: Path) -> None:
     if backup.exists():
         shutil.copy2(backup, path)
@@ -124,6 +135,7 @@ def _replace_sqlite_atomically(src: Path, dest: Path, backup_dir: Path) -> None:
     shutil.copyfile(src, tmp)
     backups: dict[Path, Path] = {}
     try:
+        _checkpoint_sqlite(dest)
         for sibling in _sqlite_siblings(dest):
             if sibling.exists():
                 backup = backup_dir / sibling.name