ltcai 5.2.0 → 5.3.0

package/README.md

@@ -1,5 +1,18 @@
 # Lattice AI
 
+**Lattice AI is a local-first Digital Brain that keeps your knowledge durable across any AI model.**
+
+**Lattice AI는 모델이 바뀌어도 내 지식과 맥락을 보존하는 로컬 우선 AI 브레인입니다.**
+
+Your model is the voice you use today. Your Brain is the asset you keep.
+Lattice AI preserves conversations, documents, decisions, project context,
+relationships, and workflows on your computer by default. Cloud models, model
+downloads, update checks, and other external communication happen only after
+explicit consent.
+
+It is not a ChatGPT clone, a model launcher, a graph database, or a note app.
+It is a private AI memory layer wrapped in a Living Brain experience.
+
 [![PyPI Version](https://img.shields.io/pypi/v/ltcai?label=PyPI)](https://pypi.org/project/ltcai/)
 [![npm Version](https://img.shields.io/npm/v/ltcai?label=npm)](https://www.npmjs.com/package/ltcai)
 [![VS Code Marketplace Version](https://vsmarketplacebadges.dev/version-short/parktaesoo.ltcai.svg)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
@@ -7,146 +20,103 @@
 [![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)
 
-**Your private AI memory layer. Keep your knowledge. Switch any model.**
+## Why You Need It
 
-**모델은 바꿔도, 내 지식은 남는 로컬 AI 브레인.**
+You need Lattice AI when:
 
-Lattice AI is a local-first Digital Brain for your conversations, documents,
-decisions, project history, relationships, and workflows. It is not a ChatGPT
-clone, a model launcher, a graph database, or a note app. The model is the voice
-you use today. The Brain is the durable asset you keep.
+- you ask different AI models about the same project and lose the context each time;
+- your decisions are scattered across chats, notes, PDFs, folders, and tools;
+- you want to switch models without rebuilding memory from zero;
+- you want your AI Brain to stay on your computer by default;
+- you want backup, restore, inspect, and export paths for your Brain.
 
-Use Lattice AI when you want to:
+이런 사람에게 필요합니다:
 
-- remember project decisions across weeks or months and see the source later;
-- preserve context when switching between local, cloud, or future models;
-- connect documents, conversations, files, notes, and decisions into one Brain;
-- export, backup, inspect, verify, and move the Brain as an encrypted
-  `.latticebrain` archive;
-- avoid cloud lock-in and keep knowledge local by default;
-- get an honest unavailable state instead of a fake answer when no model or
-  evidence is available.
+- 매번 AI를 바꿀 때마다 프로젝트 맥락을 다시 설명하는 사람
+- 문서, 대화, 결정, 파일이 여기저기 흩어져 있는 사람
+- 내 지식을 특정 AI 서비스 안에 묶어두고 싶지 않은 사람
+- 로컬에 저장되는 개인 AI 브레인을 원하는 사람
 
-By default, Lattice binds to localhost, stores the Brain on your machine, keeps
-model downloads and cloud calls behind explicit consent, and separates normal
-Brain use from the Admin Console. Korean and English UI copy share the same
-underlying Brain, so language preference changes the interface, not your data.
+## What You Can Do
 
-External package registries are owner-published and can lag behind this GitHub
-Release. Release uploads must use the exact v5.2.0 artifact filenames below.
+- Chat with a Brain that remembers useful context instead of treating every
+  session as disposable.
+- Add documents, local folders, notes, screenshots, and conversations with
+  source-aware memory.
+- See recent memories, older memories, topics, relationships, and the full
+  knowledge graph when you want deeper structure.
+- Use a recommended local model without learning model internals first.
+- Keep advanced controls, audit logs, roles, and retention in a separate Admin
+  surface.
+- Export or back up your Brain as an encrypted `.latticebrain` archive.
 
-**5.2.0 major update**: Structured model capability registry + automated HF
-verification (scripts/verify_hf_model_registry.py) + expanded modern multimodal
-candidates. User-facing recommendations are narrowed to current load-ready
-families; registry-only candidates stay visible for verification transparency
-until config/tokenizer/load readiness is confirmed. Frontend now shows verified
-status, modality badges, hardware fit notes, and explicit download/load
-strategies before consent. See RELEASE.md and docs/CHANGELOG.md.
+## One-Minute Flow
+
+1. Launch the app.
+2. Create or open a local profile.
+3. Let Lattice explain what this computer can run.
+4. Start with the recommended model, or skip and choose later.
+5. Talk to your Brain.
+6. Watch memories, topics, relationships, and graph structure emerge from real use.
+7. Back up, inspect, export, or restore the Brain when you need ownership actions.
 
 ## Living Brain Flow
 
 ### 1. Login
 
-First launch opens to Login only. The local profile is the beginning of the
-Brain, not a dashboard, graph, or setup grid. The first screen frames Lattice as
-a durable knowledge home where models are replaceable and ownership stays with
-the user. v5.2.0 adds a transparent verified model registry, load-ready catalog,
-and workspace-scoped marketplace install state.
+Choose the owner of the Brain. The profile is not a SaaS account by default; it
+is the local identity for the knowledge you keep.
 
-![Login](output/release/v5.2.0/screenshots/01-login.png)
+![Login](output/release/v5.3.0/screenshots/01-login.png)
 
 ### 2. Environment Analysis
 
-Lattice reads the machine locally and summarizes what kind of Brain this
-computer can support.
+See what kind of local AI experience this computer can support before choosing a
+model.
 
-![Environment Analysis](output/release/v5.2.0/screenshots/02-environment-analysis.png)
+![Environment Analysis](output/release/v5.3.0/screenshots/02-environment-analysis.png)
 
 ### 3. Recommended Models
 
-The model step is a short recommendation list. It avoids catalog noise and keeps
-runtime/install details behind clear user consent. Users who do not know which
-model to choose can start with the recommended model in one click.
+Start with a short list: safest recommendation, faster model, stronger model.
+Advanced details stay available without overwhelming first-time users.
 
-![Recommended Models](output/release/v5.2.0/screenshots/03-recommended-models.png)
+![Recommended Models](output/release/v5.3.0/screenshots/03-recommended-models.png)
 
 ### 4. Install And Load
 
-The install screen keeps consent visible and shows install, download, validate,
-and load progress. No model download or runtime install starts silently, and the
-screen explains that large downloads may take minutes without inventing fake ETA
-data.
+Download and load only after consent. Lattice explains model size, local
+execution, and network use before work starts.
 
-![Install and Load](output/release/v5.2.0/screenshots/04-install-load-progress.png)
+![Install and Load](output/release/v5.3.0/screenshots/04-install-load-progress.png)
 
 ### 5. Brain Chat
 
-After setup, the home experience is the living Brain plus conversation. The Brain
-stays present while the user types, recalls context, and receives responses. The
-home now includes a compact Brain overview for recent memories, older memories,
-and major topics, plus saved-to-memory feedback after chat.
+Talk normally. Useful decisions and context become memory, then appear later as
+topics, relationships, and graph structure.
 
-![Brain Chat Home](output/release/v5.2.0/screenshots/05-brain-chat-home.png)
+![Brain Chat Home](output/release/v5.3.0/screenshots/05-brain-chat-home.png)
 
 ## Brain Depths
 
-The user travels inward through the Brain. Each depth keeps conversation nearby
-while revealing more structure.
+The user travels inward from everyday memory to deeper structure:
 
-| Depth | Experience | Evidence |
+| Level | User name | What the user gets |
 | --- | --- | --- |
-| Level 1 | Living Brain presence | ![Living Brain Level 1](output/release/v5.2.0/screenshots/06-living-brain-level-1.png) |
-| Level 2 | Memory Layer | ![Memory Layer](output/release/v5.2.0/screenshots/07-memory-layer.png) |
-| Level 3 | Knowledge Layer | ![Knowledge Layer](output/release/v5.2.0/screenshots/08-knowledge-layer.png) |
-| Level 4 | Relationship Layer | ![Relationship Layer](output/release/v5.2.0/screenshots/09-relationship-layer.png) |
-| Level 5 | Knowledge Graph with nodes, edges, search, and focus detail | ![Knowledge Graph Layer](output/release/v5.2.0/screenshots/10-knowledge-graph-layer.png) |
+| Level 1 | Now memory | The living Brain presence and current conversation context |
+| Level 2 | Older memory | Durable memories with source-aware recall |
+| Level 3 | Topics | Recurring themes across chats and documents |
+| Level 4 | Relationships | How decisions, people, files, and ideas connect |
+| Level 5 | Full knowledge graph | Nodes, edges, search, and focused detail for advanced exploration |
 
 Walkthrough:
 
-![v5.2.0 Living Brain walkthrough](output/release/v5.2.0/gifs/v5.2.0-living-brain-walkthrough.gif)
-
-Model setup status evidence:
-
-![Model setup status](output/release/v5.2.0/screenshots/11-model-setup-status.png)
-
-Separate admin console evidence:
-
-![Admin Console](output/release/v5.2.0/screenshots/12-admin-console.png)
+![v5.3.0 Living Brain walkthrough](output/release/v5.3.0/gifs/v5.3.0-living-brain-walkthrough.gif)
 
 Screenshot index and capture notes:
-[output/release/v5.2.0/SCREENSHOT_INDEX.md](output/release/v5.2.0/SCREENSHOT_INDEX.md)
-
-## Architecture At A Glance
+[output/release/v5.3.0/SCREENSHOT_INDEX.md](output/release/v5.3.0/SCREENSHOT_INDEX.md)
 
-- **Desktop shell**: Tauri 2 is the release desktop shell and starts the
-  localhost sidecar.
-- **Frontend**: React, TypeScript, Vite, TanStack Query, Zustand, Cytoscape.js,
-  React Flow, Tailwind/shadcn-style primitives, and generated OpenAPI types.
-- **Backend**: FastAPI on localhost is the UI source of truth.
-- **Brain Core**: independent `lattice_brain` package for graph, memory,
-  context, conversations, ingestion, runtime, workflow, storage, and
-  portability. Isolation tests prevent `lattice_brain` from importing
-  `latticeai`.
-- **Storage**: `StorageEngine` abstraction with SQLite default and optional
-  PostgreSQL/pgvector scale mode.
-- **Portability**: encrypted `.latticebrain` archives plus backup, restore,
-  inspect, verify, import dry-run, and confirmed restore/import flows. The
-  Brain home keeps conversation first and surfaces the everyday "Care for my
-  Brain" ownership path as a collapsed control with export, backup, archive,
-  inspect, and restore preview actions while keeping destructive confirmed
-  restore in Settings. Restore operations create pre-restore backups and roll
-  back failed DB/blob swaps so the current Brain is not left half-restored.
-- **Privacy**: local-first and private-first by default. Cloud models, Telegram,
-  Brain Network, Docker/Postgres setup, model downloads, and update checks are
-  opt-in paths.
-- **Admin separation**: user chat and Brain ownership stay in the main Brain
-  surface; user directory, audit logs, security events, policies, and index
-  rebuild controls live under the separate `#/admin` console. Admin history,
-  audit, stats, and sensitivity reads honor the active workspace when present.
-
-See [ARCHITECTURE.md](ARCHITECTURE.md) for the detailed v5.2.0 architecture.
-
-## Installation
+## Install
 
 Run from Python:
 
@@ -174,19 +144,27 @@ Apple Silicon local model extras:
 pip install "ltcai[local]"
 ```
 
-## Release Artifacts
-
-Validated 5.2.0 artifacts (current release):
+## Architecture At A Glance
 
-- `dist/ltcai-5.2.0-py3-none-any.whl`
-- `dist/ltcai-5.2.0.tar.gz`
-- `ltcai-5.2.0.tgz`
-- `dist/ltcai-5.2.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_5.2.0_aarch64.dmg`
+- **Product category**: local-first Digital Brain.
+- **Core capability**: private AI memory layer for conversations, documents,
+  decisions, relationships, workflows, and project context.
+- **UX metaphor**: Living Brain.
+- **Desktop shell**: Tauri 2 starts a localhost sidecar.
+- **Frontend**: React, TypeScript, Vite, TanStack Query, Zustand, Cytoscape.js,
+  React Flow, and generated OpenAPI types.
+- **Backend**: FastAPI on localhost is the UI source of truth.
+- **Brain Core**: independent `lattice_brain` package for graph, memory,
+  context, conversations, ingestion, runtime, workflow, storage, and portability.
+- **Storage**: SQLite default; PostgreSQL/pgvector is optional scale mode.
+- **Portability**: encrypted `.latticebrain` archives plus backup, restore,
+  inspect, verify, import dry-run, and confirmed restore/import flows.
+- **Trust boundary**: local-first by default; cloud calls, downloads, Telegram,
+  Brain Network, Docker/Postgres setup, and update checks are opt-in.
+- **Admin separation**: normal Brain use stays separate from users, audit logs,
+  policies, security events, retention, and index rebuilds.
 
-Attach only those exact files to the GitHub Release. Do not upload a wildcard
-from the `dist` directory. Historical artifact references in release history are
-intentionally preserved.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the current architecture.
 
 ## Local Development
 
@@ -195,13 +173,6 @@ npm install
 npm run dev
 ```
 
-Build and validate release artifacts:
-
-```bash
-npm run release:artifacts
-npm run release:validate
-```
-
 Main validation set:
 
 ```bash
@@ -213,66 +184,73 @@ npm run test:unit
 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-5.2.0-py3-none-any.whl
-npm pack --dry-run
 npm run docs:check-links
 ```
 
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
+
+## Current Release Preparation
+
+The current development target is **5.3.0 Product Clarity and Runtime Cleanup**:
+
+- README and first-run copy are organized around the local-first Digital Brain.
+- Product descriptions are aligned across package metadata, architecture docs,
+  feature status, release notes, and extension metadata.
+- Release artifacts and exact filenames are kept in the release section instead
+  of interrupting the product introduction.
+- `app_factory.py` is being thinned by moving config, security, and Brain runtime
+  assembly seams into `latticeai.runtime`.
+- Legacy root modules are documented in
+  [docs/LEGACY_COMPATIBILITY.md](docs/LEGACY_COMPATIBILITY.md).
+
+Expected artifacts for a future 5.3.0 release must use exact filenames:
+
+- `dist/ltcai-5.3.0-py3-none-any.whl`
+- `dist/ltcai-5.3.0.tar.gz`
+- `ltcai-5.3.0.tgz`
+- `dist/ltcai-5.3.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_5.3.0_aarch64.dmg`
+
+Do not upload `dist/*`. Package registry publishing remains owner-run.
+
 ## Known Limitations
 
-- External package registries are owner-published and can lag behind the GitHub
-  Release.
-- PostgreSQL/pgvector is optional scale mode. SQLite is the default local brain.
-- Docker, model downloads, cloud model calls, Telegram, Brain Network, and
-  update checks require explicit user action.
+- External package registries are owner-published and can lag behind GitHub.
+- PostgreSQL/pgvector is optional scale mode. SQLite is the default local Brain.
+- Docker, model downloads, cloud model calls, Telegram, Brain Network, and update
+  checks require explicit user action.
 - Conversation does not fabricate answers when no model is loaded.
-- Agent/workflow simulation without a loaded LLM is deterministic and does not call a model.
-  It is labeled as LLM-free/model-free rather than presented as autonomous model
-  success.
-- Historical artifacts can remain in `dist/`; uploads must use exact target version (e.g. 5.2.0)
-  filenames.
+- Agent/workflow simulation without a loaded LLM is deterministic and does not
+  call a model; it is labeled as LLM-free/model-free rather than presented as
+  autonomous model success.
 
 ## Release History
 
 | Version | Theme |
 | --- | --- |
-| 5.1.0 | Product Trust & Clarity Release: clarifies the private AI memory-layer promise, hardens CSP/secret/auto-read/download gates, adds trust/privacy docs, and refreshes v5.1.0 evidence |
-| 5.0.0 | Multilingual Brain Foundation Release: adds persisted Korean/English language choice across first-run onboarding, Brain home, graph exploration, and Admin Console while preserving the v4 runtime foundations |
-| 4.7.2 | Intuitive Brain UX Release: safer login, one-click recommended setup, direct Brain views, memory-save feedback, and exact v4.7.2 artifacts |
-| 4.7.0 | Admin Separation Release: added the separate Admin Console for users/logs/security/Brain operations, refreshed screenshots/GIFs, synchronized release docs, and built exact v4.7.0 artifacts |
-| 4.6.1 | Living Brain Release Refresh: publishable version bump after v4.6.0 PyPI immutability, refreshed README/screenshots/GIFs, synchronized release docs, and exact v4.6.1 artifacts |
-| 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 |
-
-## Current Documentation
-
-- [ARCHITECTURE.md](ARCHITECTURE.md) - v5.2.0 architecture.
-- [docs/WHY_LATTICE.md](docs/WHY_LATTICE.md) - why Lattice AI exists.
+| 5.3.0 | Product Clarity and Runtime Cleanup: user-first README/onboarding, unified Digital Brain identity, legacy compatibility map, and app factory runtime seams |
+| 5.2.0 | User-Focused Model Transformation: structured model capability registry, HF verification transparency, model recommendation UX, and workspace-scoped marketplace state |
+| 5.1.0 | Product Trust & Clarity Release: clarifies the private AI memory-layer promise, hardens CSP/secret/auto-read/download gates, adds trust/privacy docs, and refreshes evidence |
+| 5.0.0 | Multilingual Brain Foundation Release: adds persisted Korean/English language choice across first-run onboarding, Brain home, graph exploration, and Admin Console |
+| 4.7.2 | Intuitive Brain UX Release: safer login, one-click recommended setup, direct Brain views, memory-save feedback, and exact artifacts |
+| 4.7.0 | Admin Separation Release: adds the separate Admin Console for users/logs/security/Brain operations |
+| 4.6.1 | Living Brain Release Refresh: publishable version bump after v4.6.0 PyPI immutability |
+| 4.6.0 | Living Brain Experience: made Brain plus conversation the home product |
+| 4.5.1 | Product Reimagining RC: reset shell, navigation, onboarding, and visual system |
+| 4.5.0 | Product Experience Recovery RC: restored first-run setup, workspace/model onboarding, and graph discoverability |
+
+## Documentation
+
+- [docs/WHY_LATTICE.md](docs/WHY_LATTICE.md) - product philosophy.
 - [docs/TRUST_MODEL.md](docs/TRUST_MODEL.md) - local-first trust model.
 - [PRIVACY.md](PRIVACY.md) - privacy and external communication policy.
-- [docs/PRODUCT_DIRECTION_REVIEW.md](docs/PRODUCT_DIRECTION_REVIEW.md) -
-  Brain-first product direction review.
-- [FEATURE_STATUS.md](FEATURE_STATUS.md) - current feature status and historical
-  status ledger.
-- [RELEASE_NOTES.md](RELEASE_NOTES.md) - release notes index.
-- [RELEASE.md](RELEASE.md) - current v5.2.0 release notes and historical release history.
-- [RELEASE_NOTES_v5.2.0.md](RELEASE_NOTES_v5.2.0.md) - v5.2.0 user-focused model transformation release notes.
-- [RELEASE_NOTES_v5.0.0.md](RELEASE_NOTES_v5.0.0.md) - v5.0.0 multilingual foundation history.
-- [RELEASE_NOTES_v4.7.2.md](RELEASE_NOTES_v4.7.2.md) - v4.7.2 intuitive Brain UX history.
-- [RELEASE_NOTES_v4.7.1.md](RELEASE_NOTES_v4.7.1.md) - v4.7.1 admin operations history.
-- [RELEASE_NOTES_v4.7.0.md](RELEASE_NOTES_v4.7.0.md) - v4.7.0 admin separation history.
-- [RELEASE_NOTES_v4.6.1.md](RELEASE_NOTES_v4.6.1.md) - v4.6.1 release refresh history.
-- [RELEASE_NOTES_v4.6.0.md](RELEASE_NOTES_v4.6.0.md) - v4.6.0 Living Brain history.
-- [RELEASE_NOTES_v4.5.1.md](RELEASE_NOTES_v4.5.1.md) - v4.5.1 product reimagining history.
-- [RELEASE_NOTES_v4.5.0.md](RELEASE_NOTES_v4.5.0.md) - v4.5.0 product recovery history.
-- [RELEASE.md](RELEASE.md) - release checklist and exact artifact guidance.
+- [ARCHITECTURE.md](ARCHITECTURE.md) - current technical architecture.
+- [FEATURE_STATUS.md](FEATURE_STATUS.md) - current feature status and known limitations.
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - developer workflow.
+- [docs/LEGACY_COMPATIBILITY.md](docs/LEGACY_COMPATIBILITY.md) - root legacy shim map.
+- [RELEASE.md](RELEASE.md) - release guide and current release notes.
+- [docs/CHANGELOG.md](docs/CHANGELOG.md) - historical changes.
 - [SECURITY.md](SECURITY.md) - security posture.
-- [docs/CHANGELOG.md](docs/CHANGELOG.md) - changelog.
-- [docs/V4_7_1_ADMIN_OPERATIONS_REPORT.md](docs/V4_7_1_ADMIN_OPERATIONS_REPORT.md) - v4.7.1 admin operations history.
-- [docs/V4_7_0_ADMIN_SEPARATION_REPORT.md](docs/V4_7_0_ADMIN_SEPARATION_REPORT.md) - v4.7.0 admin separation history.
-- [docs/V4_6_1_RELEASE_REFRESH_REPORT.md](docs/V4_6_1_RELEASE_REFRESH_REPORT.md) - v4.6.1 release refresh report.
-- [docs/V4_6_0_LIVING_BRAIN_EXPERIENCE_REPORT.md](docs/V4_6_0_LIVING_BRAIN_EXPERIENCE_REPORT.md) - v4.6.0 Living Brain design notes.
 
 ## License
 

package/docs/CHANGELOG.md

@@ -3,6 +3,41 @@
 The top entry is the current release-preparation target. Older entries are
 historical and may describe behavior as it existed at that release.
 
+## [5.3.0] - 2026-06-14
+
+> Product Clarity and Runtime Cleanup. Lattice AI is now presented consistently
+> as a local-first Digital Brain that keeps user knowledge durable across any AI
+> model, while the first runtime extraction seams move out of `app_factory.py`.
+
+### Added
+- `docs/DEVELOPMENT.md` for contributor setup, validation gates, runtime
+  assembly expectations, and documentation sync rules.
+- `docs/LEGACY_COMPATIBILITY.md` to explain root compatibility modules, their
+  current homes, why they remain packaged, and the safe removal checklist.
+- v5.3.0 release evidence index and copied screenshot/GIF paths under
+  `output/release/v5.3.0/`.
+
+### Changed
+- Reorganized README around product identity, user need, user actions,
+  one-minute flow, screenshots, installation, architecture, and release
+  preparation. Release artifacts no longer interrupt the first screen.
+- Unified public descriptions in README, package metadata, pyproject, feature
+  status, architecture, release notes, and VS Code extension docs.
+- Improved onboarding and model setup copy around local ownership, explicit
+  consent, model-as-voice, Brain-as-asset, and what happens before download/load.
+- Simplified Basic model setup to a shorter recommendation set while Advanced
+  keeps hardware, verification, load strategy, license, and safety detail.
+- Moved config, security, and Brain runtime builders from `latticeai.app_factory`
+  into `latticeai.runtime` modules while preserving lazy import compatibility.
+- Bumped synchronized package/runtime/static versions to `5.3.0`.
+
+### Preserved
+- No package registry publishing automation.
+- Local-first defaults and explicit consent gates for downloads, cloud calls,
+  Telegram, Brain Network, Docker/Postgres setup, and update checks.
+- `server_app.__getattr__` lazy compatibility and app factory import side-effect
+  boundaries.
+
 ## [5.2.0] - 2026-06-14
 
 > Lattice AI 5.2.0 — Aggressive User-Focused Model Transformation. Transparent
@@ -22,6 +57,7 @@ historical and may describe behavior as it existed at that release.
 - `model_recommendation.py` `_classify_one` now forwards 5.2 fields (hf_repo, verification, hardware, load_strategy, license, safety, recommended_default).
 - `verification.verified` and verified-model API lists now require HF presence plus config and tokenizer hints, with weights-hint detail exposed separately, so the UI badge matches the actual load-readiness contract.
 - Marketplace template installs now keep registry entries scoped per workspace, and `/marketplace/templates/registry` returns only the authorized workspace scope.
+- SQLite restore now checkpoints WAL state before taking the pre-restore backup, keeping failed blob restores rollback-safe on Linux/Python 3.12 CI and local builds.
 - Backend model APIs return rich fields; frontend can render verified badges, modality, hardware notes, strategies.
 - Library.tsx (ModelsPanel): added "multimodal" + "✓ HF" verified badges, recommended_default support, hardware notes line, load_strategy plus license/safety notes in advanced detail, updated guided setup copy for transparency and consent.
 - All registry HF ids confirmed present via HF API on 2026-06-14; 15/16 expose config/tokenizer hints, Pixtral remains available-but-not-local-load-verified, and large models are flagged with explicit limitations.

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/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.
-