ltcai 5.2.0 → 5.4.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,105 @@
 [![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.
+- Create consent-first Brain automation drafts for memory digests, project
+  reviews, and follow-up suggestions before any schedule is enabled.
+- 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 +146,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 +175,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 +186,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.4.0 Brain Automation Scheduler**:
+
+- Consent-first Brain automation recipes (Daily Memory Digest, Weekly Project Review,
+  Follow-up Radar) install from Automate page as reviewable disabled drafts.
+- TriggerService provides scheduler/brain-event triggers with dedup guards,
+  LATTICE_TZ support, consecutive failure degraded status, and explicit enabled:false
+  disarming.
+- lattice_brain/runtime dependency graph 정리 and entrypoint documentation added.
+- E2E scenarios for draft install + trigger execution with provenance.
+- All package/runtime/static versions synchronized to 5.4.0; PR #4 remote gates passed.
+
+Expected artifacts for 5.4.0 release must use exact filenames:
+
+- `dist/ltcai-5.4.0-py3-none-any.whl`
+- `dist/ltcai-5.4.0.tar.gz`
+- `ltcai-5.4.0.tgz`
+- `dist/ltcai-5.4.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_5.4.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.4.0 | Brain Automation Scheduler: consent-first recipe drafts (Daily/Weekly/Follow-up), TriggerService with dedup/LATTICE_TZ/degraded, runtime graph cleanup, E2E scenarios |
+| 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,68 @@
 The top entry is the current release-preparation target. Older entries are
 historical and may describe behavior as it existed at that release.
 
+## [5.4.0] - 2026-06-15
+
+> Brain Automation Scheduler. Consent-first recipe drafts (Daily Memory Digest,
+> Weekly Project Review, Follow-up Radar) install as disabled workflows.
+> Scheduler triggers (TriggerService) with dedup, LATTICE_TZ, degraded status,
+> and runtime graph cleanup.
+
+### Added
+- Consent-first Brain automation recipe drafts for Daily Memory Digest, Weekly
+  Project Review, and Follow-up Radar. Recipes install as disabled workflows so
+  users can inspect them before any scheduler or Brain-event trigger fires.
+
+### Changed
+- Workflow trigger scanning now treats explicit `enabled: false` trigger config
+  as disarmed while preserving legacy behavior for existing workflows that do
+  not include an `enabled` field.
+- The Automate page now surfaces Brain automation recipe cards with local-only,
+  review-before-run consent copy.
+- Recipe install UX: success feedback on "Create reviewable draft", install-time
+  button disabled to block duplicates clicks, and if same recipe draft already
+  exists (by metadata), button state changes + guide text instead of re-creating.
+- lattice_brain/runtime dependency/responsibility graph 정리 + 실제 진입점 매핑 문서화 (runtime/* 모듈 헤더 + app_factory 주석). AgentRuntime (lattice_brain facade) vs latticeai/core/agent (single-agent state/plan/transcript) 분리 명확화.
+- TriggerService 스케줄러 엣지케이스 보강: LATTICE_TZ env 지원 (describe() 노출), last_attempt_at + cooldown dedup 가드로 중복 실행 방지 (interval/brain_event), consecutive_failures + "degraded" status per-trigger 서페이싱.
+- A방향 E2E 시나리오 초안 brain_automation.py 에 작성 (draft install, dedup, consent-first, trigger fire with provenance, LATTICE_TZ, degraded, review flow, RunExecutor 경로).
+
+## Unreleased
+
+## [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 +84,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.