ltcai 4.3.0 → 4.3.3

package/README.md

@@ -1,338 +1,248 @@
-<div align="center">
-  <img src="docs/images/logo.svg" alt="Lattice AI" width="120" />
-
-  # Lattice AI
-
-  **A local-first Digital Brain Platform. Your Knowledge Graph is the durable asset; models just read it.**
-
-  Every source — files, folders, web pages, browser tabs — converges into one
-  Knowledge Graph on your own machine. Connect models, agents, and search to that
-  graph instead of placing your work inside any single model.
-</div>
-
-<div align="center">
-
-[![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](https://vsmarketplacebadges.dev/version-short/parktaesoo.ltcai.svg)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
-[![Open VSX](https://img.shields.io/open-vsx/v/parktaesoo/ltcai?label=Open%20VSX)](https://open-vsx.org/extension/parktaesoo/ltcai)
-[![GitHub release](https://img.shields.io/github/v/release/TaeSooPark-PTS/LatticeAI?label=GitHub%20release)](https://github.com/TaeSooPark-PTS/LatticeAI/releases)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
-[![VS Code extension](https://img.shields.io/badge/VS%20Code-extension-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
-
-</div>
-
-![Lattice AI — local-first AI workspace home](docs/assets/v3.4.0/home.png)
-
-> **Lattice AI is not a model-personalization system. It is a Digital Brain Platform.**
-> The Knowledge Graph is your durable asset. **Models are replaceable. Knowledge is durable.**
-
-It isn't another chat window, and it isn't a way to "fine-tune a model on you." The
-purpose of Lattice AI is to **connect models to your Knowledge Graph** — your digital
-brain — not to place you inside a model. AI reads your knowledge; you own it.
-
-- **Models are replaceable.** Swap MLX, Ollama, LM Studio, or a cloud LLM at will.
-- **Agents, RAG, and the UI are replaceable.** They are implementations, not the asset.
-- **Your Knowledge Graph is durable.** It outlives every model and is yours to export,
-  import, and back up locally — no cloud required.
-
-Local-first by default; cloud only when you choose. (The Vercel site is a
-landing/download/demo surface only — never the runtime. Lattice AI runs on your
-machine over local SQLite.)
-
-## Why install Lattice AI?
-
-Most AI tools only answer questions in a chat window. Lattice AI gives you a
-workspace around the work itself:
-
-- **Keep everything in one place** — files, notes, chats, and decisions live
-  together instead of scattered across tabs and apps.
-- **Turn documents into knowledge** — uploads and connected folders become
-  searchable, linked context you can reuse.
-- **Search the way you think** — fuse keyword, vector, and knowledge-graph
-  signals in a single query.
-- **Stay private and offline-capable** — run local models through MLX, Ollama, or
-  LM Studio; nothing leaves your machine unless you opt in.
-- **Use cloud models only when you choose** — bring an API key for cloud LLMs
-  when you want them, not by default.
-- **Inspect every agent run** — runs persist queued/running/final state, plans,
-  reviews, retries, cancellation, and replayable logs. With a loaded model the
-  v4 runner uses it; without one, deterministic simulation mode is explicitly
-  labeled and does not call a model.
-
-Lattice AI is not a clone of ChatGPT, Claude, Cursor, Obsidian, or Notion. It
-sits in a different place: a **workspace** that ties local/self-hosted AI, your
-files, project knowledge, hybrid search, local and optional cloud models, agents,
-and workflows together — and runs on your own hardware.
-
-## What can you do with it?
-
-- Build a private AI workspace for a project, scoped to your machine.
-- Chat with your local files, images, and workspace memory.
-- Upload documents — or connect a folder — and turn them into searchable knowledge.
-- Explore how files, decisions, conversations, and entities connect in a
-  Knowledge Graph.
-- Run local models through MLX, Ollama, or LM Studio, and use cloud LLMs only when
-  you want to.
-- Define agent workflows and replay their run records step by step, including
-  live tool execution, approval pauses, and cooperative cancellation.
-- Separate personal work from organization work.
-- Switch between Basic, Advanced, and Admin modes depending on your role.
+# Lattice AI
+
+[![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)
+[![Open VSX Version](https://img.shields.io/open-vsx/v/parktaesoo/ltcai?label=Open%20VSX)](https://open-vsx.org/extension/parktaesoo/ltcai)
+[![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Lattice AI v4.3.3 is a local-first Digital Brain desktop workspace.** It runs
+as a Tauri desktop app with a localhost FastAPI sidecar, stores the user's brain
+locally by default, and presents the Knowledge Graph as the durable asset.
+
+This README describes the v4.3.3 release tree, which promotes the post-cleanup
+main branch after the v4.3.2 self-audit and independent dead-code/runtime audit.
+External package registries are owner-published; the badges above link to
+package pages and may show the most recently published owner-controlled registry
+version, which can lag behind the GitHub Release.
+
+## What Was Verified
+
+- Desktop app starts and serves the React/Vite product shell from the FastAPI
+  sidecar.
+- Brain graph renders persisted local graph data with search, groups, focus,
+  filtering, and hybrid-search results.
+- Ask displays durable conversations, graph context, and honest unavailable
+  state when no model is loaded.
+- Capture uploads a document through `/upload/document` and shows indexed
+  documents from the backend.
+- Act exposes workflow create/run surfaces and agent runtime status without
+  presenting simulation as real success. When no LLM-backed model is loaded,
+  deterministic model-free agent simulation is reported honestly and does not call a model.
+- Library shows model/runtime availability honestly.
+- System exposes storage, backup health, archive, Brain Network, device
+  identity, and admin status through real APIs.
+- Backup, restore dry-run, archive verify, archive import dry-run, and
+  `.latticebrain` portability flows were exercised.
 
 ## Product Tour
 
-### Start from the workspace home
+### Desktop Startup
 
-![Lattice AI workspace home — readiness, model state, and retrieval status](docs/assets/v3.4.0/home.png)
+The v4.3.3 DMG build launches a visible Tauri app, starts the FastAPI sidecar on
+localhost, and shuts that sidecar down on normal macOS quit.
 
-The home view shows workspace readiness, model state, retrieval status, and the
-main entry points — derived from real local state, never placeholder counters.
+![Desktop startup and local sidecar](output/audits/v4.3.2-rc/screenshots/13-desktop-sidecar-startup.png)
 
-### Chat with files, images, and workspace context
+Evidence:
 
-![Lattice AI chat connected to files, graph context, and vision input](docs/assets/v3.4.0/chat.png)
+- Health log: `output/audits/v4.3.2-rc/logs/desktop-sidecar-health-after-shutdown-fix.json`
+- Shutdown log: `output/audits/v4.3.2-rc/logs/desktop-shutdown-after-fix.txt`
 
-Chat is wired to your files, graph context, memory, and model routing — including
-vision-capable image input by attach, drag-and-drop, or paste.
+### Brain Graph
 
-### Bring documents into the workspace
+Brain opens on the graph-first workspace. The graph uses real persisted nodes
+and edges from `/knowledge-graph/graph`, then layers product controls for search,
+semantic grouping, focus neighborhoods, label modes, group collapse/expand, and
+importance filtering.
 
-![Lattice AI files view — uploaded documents and connected folders](docs/assets/v3.4.0/files.png)
+![Brain graph explorer](output/audits/v4.3.2-rc/screenshots/02-graph-explorer-before.png)
 
-Uploads and connected folders become indexed workspace context, searchable from
-chat and hybrid search.
+![Graph product walkthrough](output/audits/v4.3.2-rc/gifs/graph-product-walkthrough.gif)
 
-### Understand knowledge visually
+### Ask
 
-![Lattice AI knowledge graph of files, decisions, conversations, and entities](docs/assets/v3.4.0/knowledge-graph.png)
+Ask uses backend conversation, model, and graph context APIs. In the audited
+state no model was loaded, so the UI showed a ready/unavailable state instead of
+fabricating an answer while still surfacing graph context from local data.
 
-The Knowledge Graph shows how files, decisions, conversations, and entities
-connect — context that stays useful even when you switch models.
+![Ask with graph context and no-model honesty](output/audits/v4.3.2-rc/screenshots/14-ask-context.png)
 
-### Inspect agent run records
+### Capture
 
-![Lattice AI agent run with roles, logs, review, and retry](docs/assets/v3.4.0/agent-run.png)
+Capture sends files through the backend upload/ingestion path and shows indexed
+documents returned by the backend. The screenshot below includes a note uploaded
+during release-prep evidence capture.
 
-The agent runner turns a goal into an inspectable, replayable run record — roles,
-logs, review, retry, and cancellation state — that you can read back step by
-step. Runs execute asynchronously and use the loaded model when one is available;
-otherwise they are labeled as simulation.
+![Capture document ingestion](output/audits/v4.3.2-rc/screenshots/15-capture-ingestion.png)
 
-### Extend with hooks and the local runtime
+Upload evidence: `output/audits/v4.3.2-rc/logs/readme-upload-note.json`
 
-![Lattice AI hooks dispatch with a recent-execution log](docs/assets/v3.4.0/hooks-dispatch.png)
+### Act
 
-![Lattice AI local agent status, handshake, and folder watching](docs/assets/v3.4.0/local-agent.png)
+Act exposes agents, workflows, approvals, hooks, and runtime status through
+existing backend APIs. The audited workflow path created a real workflow record;
+agent runtime simulation remains honestly unavailable as product success when no
+LLM-backed model is loaded.
 
-Advanced users wire lifecycle hooks into runs, tools, workflows, uploads, and
-indexing — and see the on-device local runtime's real status, handshake, and
-folder-watch activity.
+![Workflow create and run surfaces](output/audits/v4.3.2-rc/screenshots/09-workflow-create-run.png)
 
-## Install
+![Agent runtime status](output/audits/v4.3.2-rc/screenshots/10-agent-runtime-status.png)
 
-Install the local workspace:
+### Library
 
-```bash
-pip install ltcai
-```
+Library shows models, skills, MCP, and marketplace/configuration state with
+availability reported from runtime APIs. Optional model runtimes are not treated
+as loaded unless the runtime is actually available.
 
-Add Apple Silicon local model support:
+![Library model status](output/audits/v4.3.2-rc/screenshots/12-library-model-status.png)
 
-```bash
-pip install "ltcai[local]"
-```
+### System
 
-Install the npm CLI:
+System exposes account/workspace status, storage mode, backup health, archive
+operations, device identity, Brain Network, and admin hardening state. External
+integrations remain opt-in.
 
-```bash
-npm install -g ltcai
-```
+![System storage status](output/audits/v4.3.2-rc/screenshots/08-system-storage-status.png)
 
-Install the coding extension:
+![Brain Network and device identity](output/audits/v4.3.2-rc/screenshots/11-brain-network-device-identity.png)
 
-- [VS Code Marketplace: parktaesoo.ltcai](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
-- [Open VSX: parktaesoo.ltcai](https://open-vsx.org/extension/parktaesoo/ltcai)
-- [GitHub Releases](https://github.com/TaeSooPark-PTS/LatticeAI/releases)
+### Backup / Restore
 
-## Quick Start
+Backup and restore flows are backed by the knowledge-graph portability APIs.
+The retained v4.3.2 product audit exercised backup health, backup creation, restore dry-run, and
+archive restore surfaces.
 
-Start the workspace:
+![Brain backup and portability controls](output/audits/v4.3.2-rc/screenshots/06-brain-portability-backup.png)
 
-```bash
-LTCAI
-```
+### `.latticebrain` Portability
 
-Then open:
+The portable brain format is an encrypted `.latticebrain` archive. The audited
+System flow exercised archive export, inspect, verify, import dry-run, and
+restore dry-run/restore controls through FastAPI.
 
-```text
-http://127.0.0.1:4825/app
-```
+![System archive flows](output/audits/v4.3.2-rc/screenshots/07-system-archive-flows.png)
 
-Working from a development checkout:
+Archive evidence:
 
-```bash
-npm install
-npm run dev
-```
+- Create: `output/audits/v4.3.2-rc/logs/archive-create.json`
+- Verify: `output/audits/v4.3.2-rc/logs/archive-verify.json`
+- Import dry-run: `output/audits/v4.3.2-rc/logs/archive-import-dry-run.json`
 
-## Core Features
-
-- **Local-first workspace** — your data, models, and workspace state live on your
-  machine by default; cloud is opt-in.
-- **Files and connected folders** — upload documents or connect a local folder;
-  Lattice indexes them and watches connected folders for changes.
-- **Chat with workspace context** — conversations are grounded in your files,
-  knowledge graph, and memory, with vision-capable image input.
-- **Knowledge Graph** — files, images, notes, conversations, and decisions become
-  linked entities and relationships you can explore.
-- **Hybrid Search** — keyword, vector, and graph signals are fused into one ranked
-  result set.
-- **Local model support** — run multimodal models locally via MLX, Ollama, or LM
-  Studio, with hardware-aware recommendations and source disclosure.
-- **Optional cloud model routing** — add OpenAI-compatible or other cloud models
-  when you choose; model cards disclose origin, run mode, and internet use.
-- **Multi-agent workflows** — turn goals into runs with roles, handoffs, review,
-  retries, and replayable timelines.
-- **Skills, hooks, tools, and MCP** — extend the workspace with skills, lifecycle
-  hooks, a governed tool registry, and Model Context Protocol servers.
-- **Personal / Organization workspaces** — keep personal work separate from team
-  work with role-aware views.
-- **Basic / Advanced / Admin modes** — show only what each role needs, from core
-  workflows to agent tooling to administration.
-
-## Latest Release
-
-### v4.3.0 RC — Portability & Product Hardening
-
-- **Portable `.latticebrain` archives** — encrypted archives now include the
-  brain DB, blobs, workspace state, settings, signed bundles, storage metadata,
-  provenance, and public device identity metadata.
-- **Safe backup/restore flows** — archive inspect, verify, import, restore, and
-  restore dry-run are real API-backed operations; destructive restore requires
-  explicit admin confirmation.
-- **Migration safety** — live SQLite-to-Postgres migration creates and verifies
-  a pre-migration backup before copying data.
-- **Desktop hardening** — Tauri sidecar startup, status, restart, shutdown, and
-  loopback-only/default-off guards are hardened.
-- **Privacy audit surface** — token presence alone no longer enables Telegram or
-  external connectors; admin status reports storage, backup health, device
-  identity, permissions, and opt-in integration state.
-- **Release hardening** — exact-version validation covers wheel, sdist, npm tgz,
-  VSIX, and Tauri DMG artifacts.
-
-See [RELEASE_NOTES_v4.3.0.md](RELEASE_NOTES_v4.3.0.md),
-[docs/kg-schema.md](docs/kg-schema.md),
-[FEATURE_STATUS.md](FEATURE_STATUS.md).
-
-## How it works — every source converges into the graph
-
-As of v4.3.0, data sources flow through the brain ingestion pipeline into
-the Knowledge Graph — no source bypasses it, none becomes an isolated silo:
+## Architecture At A Glance
 
-```text
-source (file · folder · PDF · web URL · browser tab · text)
-  -> extraction -> normalization -> content hash (idempotent)
-  -> chunking -> entity detection -> relationship detection -> embedding
-  -> Knowledge Graph  (Source -[indexed_from]- content -[contains]- chunks)
-  -> RAG / agents / memory / hybrid search
-```
+- **Desktop shell**: Tauri 2 primary shell; Electron remains fallback-only.
+- **Frontend**: React, TypeScript, Vite, TanStack Query, Zustand, Cytoscape.js,
+  React Flow, Tailwind/shadcn-style primitives, generated OpenAPI client.
+- **Backend**: FastAPI on localhost is the source of truth for the UI.
+- **Brain Core**: independent Python package `lattice_brain`, imported by
+  FastAPI, CLI, tests, and future tools.
+- **Storage**: `StorageEngine` abstraction with SQLite default and optional
+  PostgreSQL/pgvector scale mode.
+- **Portability**: encrypted `.latticebrain` archive plus backup/restore and
+  migration tooling.
+- **Privacy**: local-first by default; cloud models, Telegram, Brain Network,
+  Docker, model downloads, and update checks require explicit opt-in paths.
 
-- **Every node is explainable.** Each ingested item carries provenance — where it
-  came from, when, how it was processed, whether it was embedded or linked.
-- **The graph is the asset.** Memory, search, and agents are views over it; models
-  read it. Swap a model and your knowledge is unchanged.
-- **Portable, no cloud.** Export/import the graph as JSON, or take a full local
-  binary backup (DB + blobs), encrypted `.latticebrain` archive, or explicit
-  SQLite-to-Postgres migration plan and restore it.
-- **Local-first protects the graph.** It lives in local SQLite on your machine.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the detailed v4.3.3 architecture.
 
-For the deeper design, see [ARCHITECTURE.md](ARCHITECTURE.md) and
-[docs/architecture.md](docs/architecture.md).
+## Installation And Release Artifacts
 
-## Documentation
+Validated v4.3.3 artifacts are produced from the post-cleanup tree:
 
-### Product and principles
+- `dist/ltcai-4.3.3-py3-none-any.whl`
+- `dist/ltcai-4.3.3.tar.gz`
+- `ltcai-4.3.3.tgz`
+- `dist/ltcai-4.3.3.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_4.3.3_aarch64.dmg`
 
-- [PROJECT_PRINCIPLES.md](PROJECT_PRINCIPLES.md) — product principles
-- [AI_PHILOSOPHY.md](AI_PHILOSOPHY.md) — how AI is used in the workspace
-- [MODEL_POLICY.md](MODEL_POLICY.md) — local model recommendation policy
+For a public release, attach only those exact artifacts to the GitHub Release.
+Package-registry publishing is reserved for the owner.
 
-### Architecture
+## Local Development
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — workspace, graph, pipeline, and model overview
-- [docs/architecture.md](docs/architecture.md) — full architecture reference
-- [docs/V4_3_PORTABILITY_ARCHITECTURE.md](docs/V4_3_PORTABILITY_ARCHITECTURE.md) — v4.3.0 portable brain archive architecture
-- [docs/V4_3_PRODUCT_HARDENING_REPORT.md](docs/V4_3_PRODUCT_HARDENING_REPORT.md) — v4.3.0 desktop/product hardening report
-- [docs/V4_3_PRIVACY_AUDIT.md](docs/V4_3_PRIVACY_AUDIT.md) — v4.3.0 privacy and local-first audit
-- [docs/V4_3_VALIDATION_REPORT.md](docs/V4_3_VALIDATION_REPORT.md) — v4.3.0 validation report
-- [docs/V4_2_BRAIN_CORE_ARCHITECTURE.md](docs/V4_2_BRAIN_CORE_ARCHITECTURE.md) — v4.2.0 Brain Core package and storage architecture
-- [docs/V4_2_STORAGE_MIGRATION_REPORT.md](docs/V4_2_STORAGE_MIGRATION_REPORT.md) — v4.2.0 storage migration and archive report
-- [docs/V4_2_VALIDATION_REPORT.md](docs/V4_2_VALIDATION_REPORT.md) — v4.2.0 validation report
-- [docs/V4_1_FRONTEND_ARCHITECTURE_REVIEW.md](docs/V4_1_FRONTEND_ARCHITECTURE_REVIEW.md) — v4.1.0 frontend and desktop architecture review
-- [docs/V4_1_FRONTEND_MIGRATION_REPORT.md](docs/V4_1_FRONTEND_MIGRATION_REPORT.md) — v4.1.0 capability migration report
-- [docs/V4_1_VALIDATION_REPORT.md](docs/V4_1_VALIDATION_REPORT.md) — v4.1.0 validation report
-- [docs/V3_BACKEND_ARCHITECTURE.md](docs/V3_BACKEND_ARCHITECTURE.md) — backend storage, search, and retrieval
+```bash
+npm install
+npm run dev
+```
 
-### Knowledge and retrieval
+Open the local app:
 
-- [KNOWLEDGE_GRAPH.md](KNOWLEDGE_GRAPH.md) — graph model and behavior
+```text
+http://127.0.0.1:4825/app
+```
 
-### Agents and workflows
+Build the release artifacts:
 
-- [docs/MULTI_AGENT_RUNTIME.md](docs/MULTI_AGENT_RUNTIME.md) — multi-agent workflow runtime
-- [docs/WORKFLOW_DESIGNER.md](docs/WORKFLOW_DESIGNER.md) — AI pipeline designer
+```bash
+npm run release:artifacts
+npm run release:validate
+```
 
-### Extensions
+Run the main validation set:
 
-- [docs/PLUGIN_SDK.md](docs/PLUGIN_SDK.md) — plugin SDK
+```bash
+npm run check:python
+node scripts/run_python.mjs -m ruff check .
+npm run lint
+npm run typecheck
+npm run test:unit
+LTCAI_TEST_BASE_URL=http://127.0.0.1:4932 npm run test:integration
+npm run test:visual
+npm run desktop:tauri:check
+node scripts/run_python.mjs scripts/wheel_smoke.py --wheel dist/ltcai-4.3.3-py3-none-any.whl
+npm pack --dry-run
+```
 
-### Releases
+## Known Limitations
 
-- [RELEASE_NOTES.md](RELEASE_NOTES.md) — current release notes
-- [RELEASE_NOTES_v4.3.0.md](RELEASE_NOTES_v4.3.0.md)
-- [RELEASE_NOTES_v4.2.0.md](RELEASE_NOTES_v4.2.0.md)
-- [RELEASE_NOTES_v4.1.0.md](RELEASE_NOTES_v4.1.0.md)
-- [RELEASE_NOTES_v4.0.1.md](RELEASE_NOTES_v4.0.1.md)
-- [RELEASE_NOTES_v4.0.0.md](RELEASE_NOTES_v4.0.0.md)
-- [RELEASE_NOTES_v3.6.0.md](RELEASE_NOTES_v3.6.0.md)
-- [RELEASE_NOTES_v3.5.0.md](RELEASE_NOTES_v3.5.0.md)
-- [RELEASE_NOTES_v3.4.1.md](RELEASE_NOTES_v3.4.1.md)
-- [RELEASE_NOTES_v3.4.0.md](RELEASE_NOTES_v3.4.0.md)
-- [CHANGELOG.md](CHANGELOG.md) and [docs/CHANGELOG.md](docs/CHANGELOG.md)
+- External package registries are owner-published and can lag behind the GitHub
+  Release.
+- PostgreSQL/pgvector is optional scale mode and is not required for default
+  local use.
+- Docker is never auto-started by default.
+- Model downloads and cloud model calls require explicit user action/consent.
+- Ask does not fabricate answers when no model is loaded.
+- Historical artifacts may remain in `dist/`; release uploads must use exact
+  v4.3.3 filenames.
 
 ## Release History
 
 | Version | Theme |
 | --- | --- |
-| **4.3.0** | Portability & Product Hardening RC — portable `.latticebrain` archives, confirmed restore/import, pre-migration backup verification, Tauri sidecar hardening, local-only/default-off integration guards, exact-version DMG validation |
-| **4.2.0** | Brain Core & Storage Rebuild — independent `lattice_brain` package, pluggable storage layer, sqlite-vec/pgvector capability reporting, explicit Postgres migration, consent-gated Docker setup, encrypted `.latticebrain` archives |
-| **4.1.0** | Frontend & Desktop Rebuild RC — React/Vite/OpenAPI desktop SPA, Tauri 2.0 primary shell, graph-first navigation, and legacy static frontend removal |
-| **4.0.1** | Digital Brain Platform maintenance — closes post-tag v4 gaps with durable async runs, stable identity/workspace state, full `/app` parity, and legacy UI retirement |
-| **4.0.0** | Digital Brain Platform — decomposed brain store, v2 write-mastered Knowledge Graph, durable memory/context, real workflow/agent foundations, signed brain exchange |
-| 3.6.0 | Knowledge Graph First — unified ingestion pipeline, formalized entity/relationship model, browser/web ingestion, local export/import/backup, provenance, KG as the primary surface |
-| 3.5.0 | Foundation stabilization & verification — OIDC verifier, trusted-proxy gating, runtime hook coverage, `tools/` package, reproducible artifacts |
-| 3.4.1 | Runtime completion — full hooks lifecycle, real Local Agent probes, Connect Folder and Folder Watch verified end-to-end |
-| 3.4.0 | Platform completion — hooks execution, uploads in Files, vision image input, agent run trigger, on-device Local Agent / Connect Folder / Folder Watch |
-| 3.3.1 | Visual product rebuild — rebuilt `/app` shell, Basic/Advanced/Admin navigation, refreshed design system |
-| **3.3.0** | Product quality & honesty release — evidence-based feature audit, single-source version truth, working document upload, documented design system |
-| 3.2.0 | Feature-complete platform — multi-agent collaboration, agent registry, marketplace + templates, workflow agents, long-term memory, skills/hooks/tool registries, MCP manager |
-| 3.1.0 | Mainline platform completion — native `/app` workflows, production embedding profiles, AgentRuntime/registries, hashed v3 assets |
-| 3.0.1 | Release-blocker remediation — provider-backed embeddings, unified AgentRuntime boundary, every v3 surface connected or clearly unavailable |
-| 3.0.0 | v3 local-first AI workspace platform — `/app`, Native Chat, Knowledge Graph, Vector Index, Hybrid Search, workspace modes |
-| 2.2.7 | Visual system stabilization — cohesive dark/light screens, crisp chat composer, dark graph canvas, Workspace OS polish |
-| 2.2.6 | Token-native CSS foundation |
-| 2.2.5 | Release hygiene hotfix — dark overlays, modal stack, cache-busting, favicon, and Telegram log masking |
-| 2.2.4 | Chat dark-mode completion |
-| 2.2.3 | Frontend stability and UX fixes |
-| 2.2.2 | Frontend QA stabilization — mobile nav, admin actions, overflow fixes, and expanded visual tests |
-| 2.2.1 | Frontend and UX overhaul for responsive workspace, themes, graph UX, admin reflow, and file attachment |
-| 2.2.0 | Multimodal-first Knowledge Graph and local model source disclosure |
-| 2.1.0 | Multi-agent workflow maturity |
-| 2.0.0 | AI pipeline, workflow, and plugin platform foundation |
-| 1.7.0 | Graph and collaboration |
-| 1.6.0 | Product experience deepening |
+| 4.3.3 | Dead-Code Cleanup Release: post-audit cleanup, architecture documentation correction, Vercel/static-docs readiness, README badge restoration, exact-current artifacts |
+| 4.3.2 | Product Polish & Graph UX Overhaul RC: evidence-based README, graph UX, structured product state, archive UX, desktop sidecar cleanup, publishing readiness |
+| 4.3.1 | End-User Audit Repair RC: desktop sidecar startup, npm clean install, default-off downloads, honest agent/workflow states |
+| 4.3.0 | Portability & Product Hardening RC: encrypted `.latticebrain` archives, backup/restore hardening, local-only startup guards |
+| 4.2.0 | Brain Core & Storage Rebuild: independent `lattice_brain`, StorageEngine abstraction, SQLite default, opt-in Postgres/pgvector |
+| 4.1.0 | Frontend & Desktop Rebuild: React/Vite SPA, Tauri shell, generated OpenAPI client |
+| 4.0.1 | Digital Brain maintenance: durable async runs, identity/workspace state, `/app` parity |
+| 4.0.0 | Digital Brain Platform foundation |
+| 3.0.0 | v3 local-first AI workspace platform |
+
+## Current Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - v4.3.3 architecture.
+- [FEATURE_STATUS.md](FEATURE_STATUS.md) - current feature status and historical
+  status ledger.
+- [RELEASE_NOTES.md](RELEASE_NOTES.md) - current release notes index.
+- [RELEASE_NOTES_v4.3.3.md](RELEASE_NOTES_v4.3.3.md) - v4.3.3 release notes.
+- [RELEASE.md](RELEASE.md) - release checklist and exact artifact guidance.
+- [SECURITY.md](SECURITY.md) - security posture.
+- [docs/CHANGELOG.md](docs/CHANGELOG.md) - changelog.
+- [docs/V4_3_2_DEADCODE_AUDIT_REPORT.md](docs/V4_3_2_DEADCODE_AUDIT_REPORT.md) - v4.3.3 cleanup basis.
+- [docs/V4_3_3_VALIDATION_REPORT.md](docs/V4_3_3_VALIDATION_REPORT.md) - v4.3.3 validation report.
+- [docs/V4_3_2_GRAPH_UX_REPORT.md](docs/V4_3_2_GRAPH_UX_REPORT.md) - graph UX report.
+- [docs/V4_3_2_PRODUCT_POLISH_REPORT.md](docs/V4_3_2_PRODUCT_POLISH_REPORT.md) - product polish report.
+- [docs/V4_3_2_SELF_AUDIT_REPORT.md](docs/V4_3_2_SELF_AUDIT_REPORT.md) - self-audit evidence.
+- [docs/V4_3_2_VALIDATION_REPORT.md](docs/V4_3_2_VALIDATION_REPORT.md) - RC validation report.
+- [docs/V4_3_2_DOCUMENTATION_CLEANUP_REPORT.md](docs/V4_3_2_DOCUMENTATION_CLEANUP_REPORT.md) - release-prep documentation cleanup report.
+- [docs/V4_3_2_GITHUB_VERCEL_CHECK_REPORT.md](docs/V4_3_2_GITHUB_VERCEL_CHECK_REPORT.md) - GitHub/Vercel readiness report.
+- [docs/V4_3_2_INDEPENDENT_AUDIT_PACKAGE.md](docs/V4_3_2_INDEPENDENT_AUDIT_PACKAGE.md) - package for an independent reviewer.
+- [docs/V4_3_2_DEADCODE_AUDIT_REPORT.md](docs/V4_3_2_DEADCODE_AUDIT_REPORT.md) - independent dead-code, architecture, and runtime audit.
+- [docs/V4_DIGITAL_BRAIN_RECOVERY.md](docs/V4_DIGITAL_BRAIN_RECOVERY.md) - transformation recovery file.
 
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).

package/bin/ltcai.js

@@ -60,9 +60,13 @@ function ensureManagedPython() {
 
   if (!canImport(managedPython, "fastapi")) {
     const requirements = path.join(root, "requirements.txt");
+    if (!fs.existsSync(requirements)) {
+      console.error(`[LTCAI] Missing ${requirements}. The npm package is incomplete and cannot start the Python server.`);
+      process.exit(1);
+    }
     console.log("[LTCAI] Installing Python dependencies. This can take a few minutes on first run.");
-    if (!runSync(managedPython, ["-m", "pip", "install", "--upgrade", "pip"])) return null;
-    if (!runSync(managedPython, ["-m", "pip", "install", "-r", requirements])) return null;
+    if (!runSync(managedPython, ["-m", "pip", "install", "--upgrade", "pip"])) process.exit(1);
+    if (!runSync(managedPython, ["-m", "pip", "install", "-r", requirements])) process.exit(1);
   }
 
   return managedPython;