ltcai 11.9.0 → 12.1.0

package/docs/DEVELOPMENT.md

@@ -3,13 +3,16 @@
 > **Status: canonical** — current contributor guidance, kept in sync with the
 > current release.
 
-Current release: **11.9.0 — Working Order**.
+Current release: **12.1.0 — Fast Path**.
 
-This document is for contributors working on the local-first Digital Brain
-codebase. Product positioning and quick start stay in `README.md`; supported
-release history is 11.0.0 and later in `docs/CHANGELOG.md` and `RELEASE.md`
-(11.6.0 rebuilt the product server in Rust, so `SECURITY.md` supports only
-11.x).
+This document is the contributor onboarding path: how to boot the tree, where
+a change belongs, which gates will go red, and the house rules that keep the
+product honest. Product positioning and the five-minute first-run stay in
+[README.md](../README.md) and [ONBOARDING.md](ONBOARDING.md). Supported
+release history is 11.0.0 and later in [CHANGELOG.md](CHANGELOG.md) and
+[RELEASE.md](../RELEASE.md) (11.6.0 rebuilt the product server in Rust, so
+[SECURITY.md](../SECURITY.md) supports only 11.x). Open gaps toward v12.0.0
+live in [ROADMAP.md](ROADMAP.md) (reference, not canonical).
 
 ## Product Contract
 
@@ -18,8 +21,7 @@ across any AI model.
 
 Engineering work should preserve these boundaries:
 
-- the Brain is the durable asset;
-- models are replaceable voices;
+- the Brain is the durable asset; models are replaceable voices;
 - SQLite is the live local Brain store;
 - Docker, cloud models, downloads, update checks and Brain Network are opt-in
   (the PostgreSQL scale/migration tooling and the Telegram bridge left the tree
@@ -28,34 +30,128 @@ Engineering work should preserve these boundaries:
   calls;
 - normal Brain use must stay separate from Admin/operator controls.
 
-## Local Setup
+## 10-minute quickstart
+
+Need Python 3.11+, Node, and a Rust toolchain (`cargo`). The product is
+`lattice-host`; Python is the 20-route compute worker it supervises.
 
 ```bash
-npm install
-npm start
+git clone <this-repo>
+cd "Lattice AI"          # or whatever the directory is named
+
+python3 -m venv .venv
+.venv/bin/pip install -U pip
+.venv/bin/pip install -e ".[dev]"
+
+npm ci
+npm start                # product. If PATH has a stale global LTCAI: node bin/ltcai.js
 ```
 
-`npm start` (or `bin/ltcai.js` / the `LTCAI` binary) is the product: it
-boots `lattice-host` and serves the SPA at:
+Then open:
 
 ```text
 http://127.0.0.1:4825/app
 ```
 
-`npm run dev` is **not** the product. It starts the 19-route Python AI
-worker with `--reload` (`latticeai.cli.entrypoint`). Use it when iterating
-on worker compute seams, not to serve the app.
+The first screen is the wake step: language switcher (한국어 / English), the
+Living Brain, and the Korean headline **「내 지식이 살아나는 Brain을 시작하세요.」**
+with the primary **「Brain 지금 깨우기」**. An existing local Brain can skip
+into the home canvas.
 
-Apple Silicon local model extras:
+Apple Silicon local-model extras (MLX), only if you will load a model:
 
 ```bash
-pip install "ltcai[local]"
+.venv/bin/pip install -e ".[local]"
 ```
 
-## Validation
+### `npm start` vs `npm run dev`
+
+| command | what it actually is | what you get |
+| --- | --- | --- |
+| `npm start` | the `LTCAI` bin → [`bin/ltcai.js`](../bin/ltcai.js) | **the product**: `lattice-host` on `127.0.0.1:4825`, supervising the worker, serving the SPA at `/app` |
+| `node bin/ltcai.js` | the same bin, called directly | same product; use this if a stale global `LTCAI` is on `PATH` |
+| `npm run dev` | `node scripts/run_python.mjs -m latticeai.cli.entrypoint --reload` | **not the product**. The 20-route worker with uvicorn `--reload`. Prints `Lattice AI worker on http://127.0.0.1:4825`. There is no SPA. |
+
+`scripts/run_python.mjs` prefers `.venv/bin/python`. `bin/ltcai.js` prefers
+`LTCAI_PYTHON`, then a managed `~/.ltcai/npm-python`, then `.venv`. Pin the
+worker interpreter with `LTCAI_PYTHON` when both exist.
+
+`bin/ltcai.js` looks for the host at `LATTICEAI_HOST_BIN` / `LTCAI_HOST`, then
+`rust/target/release/lattice-host`, then `rust/target/debug/lattice-host`. If
+none exist it runs `cargo build -p lattice-host` (debug). A stale
+`rust/target/release/lattice-host` wins over a current debug binary — pin or
+rebuild (`cargo build -p lattice-host --release`) if `-V` is not 12.1.0.
+
+Do not run `npm start` and `npm run dev` on the same port. The worker
+entrypoint defaults to `LATTICEAI_PORT` or **4825**, the same port as the
+product. Iterate on worker compute with
+`LATTICEAI_PORT=4835 npm run dev` (and `--no-spawn` / a pinned worker port on
+the host if you are pairing them).
+
+## The map — 어디에 무엇을
+
+Two crate-local maps are the contract. This table is the index; they are the
+detail. Read the matching `mod.rs` before adding a file.
+
+- [`rust/lattice-agent/ARCHITECTURE.md`](../rust/lattice-agent/ARCHITECTURE.md)
+  — `kernel/` decides; `parse/` `content/` `tools/` never import the kernel;
+  `surface/` carries HTTP; `prompts/` fills a blank. Arrows point down only.
+- [`rust/lattice-platform/ARCHITECTURE.md`](../rust/lattice-platform/ARCHITECTURE.md)
+  — this crate **offers**. It does not decide whether a run is allowed
+  (`lattice-agent` kernel) and it does not own what is true (`lattice-core`).
+
+```text
+lattice-host            one door — mounts every family
+  lattice-platform      what the product offers
+      workspaceos/      place, people, dials, workspace_os.json
+      toolsurface/      MCP, tools, plugins, agents, computer-use
+      governance/       review, proposals, automation, workflows, hooks
+      knowledge/        export/import/backup, network, boundary, voice
+      modelops/         catalog, recommendations, setup
+      adminops/         audit, security dashboard, funnel
+      shell/            SPA + 308 redirects
+  lattice-agent         may it run, and what does it do
+  lattice-core          what is true — GraphWriter is the only graph writer
+  lattice-retrieval     search, memory, chronicle, command, evidence
+  lattice-ingest        files, folders, browser capture
+  lattice-jobs          embed drain + index API
+  lattice-chat          POST /chat
+  lattice-auth          who is this
+Python worker           compute only — 19 allowlisted routes
+frontend/src            SPA
+```
+
+Compatibility re-exports at each crate's `src/lib.rs` keep the pre-v12 paths
+working for *consumers*. New code inside a crate uses the real path
+(`crate::kernel::state`, `crate::adminops::admin`).
+
+| 할 일 | 어디에 | 하지 말 것 |
+| --- | --- | --- |
+| **새 제품 API 라우트** | The `lattice-platform` domain that names the subject (`workspaceos/`, `toolsurface/`, `governance/`, `knowledge/`, `modelops/`, `adminops/`). One module owns one family: `MOUNTED: &[(&str, &str)]` + `router(state)`, then mount the factory in [`rust/lattice-host/src/gateway/product.rs`](../rust/lattice-host/src/gateway/product.rs). A **page shell** is a 308 in `shell/ui_redirects`, not a second handler — except `GET /plugins/sdk` (it carries `require_user`, so it is `toolsurface::plugins`). | Do not put retrieval/search/chronicle in platform — that is `lattice-retrieval`. Ingest doors are `lattice-ingest`. Chat is `lattice-chat`. Index drain is `lattice-jobs`. Identity is `lattice-auth`. Agent-loop HTTP is `lattice-agent` `surface/`. A handler here that re-derives "is this allowed" has forked `lattice_agent::kernel::permission`. A module that opens the graph has become a second writer. |
+| **에이전트 툴 추가** | A tool that runs *inside an agent turn* goes in `lattice-agent` `tools/`, in the file named for what it *touches*: `files` (workspace), `vault` (Brain/Obsidian), `shell` (subprocesses), `desktop` (OS actuation), `render` (document creators), `scaffold` (templates), `local` (paths outside the workspace). Add the name to `tools::host::MUTATING_TOOLS` or `RENDER_TOOLS` and the arm to the dispatcher in [`tools/host.rs`](../rust/lattice-agent/src/tools/host.rs). `is_native` follows from those tables. Every path resolves through `tools::sandbox::Workspace::resolve`; every write passes `content::sanitize::sanitize_write_content`. HTTP exposure of an existing capability is `lattice-platform` `toolsurface/tools/` plus `tools::governance_for` — not a second implementation. | Do not add a permission check in the handler — the kernel already said yes. Do not `std::fs` a raw path. Do not put a read-only compute handler here; those stay on the worker (`POST /agent/tool`). Pointer tools (`computer_*` click/move/type/…) stay on the worker on purpose. |
+| **파싱 러그 추가** | `lattice-agent` `parse/action.rs` (or `parse/channel.rs` for a new model-family frame). Append it to the ordered chain — cheapest and most literal first — and **name it in the returned `repairs` list**. CPython primitives (`pyjson`, `pyliteral`, `pyshlex`, `pystr`) are pinned by [`rust/fixtures/agent/`](../rust/fixtures/agent/FROZEN.md). New answers that Python never gave live under **new keys** (see [`agent_loop/FROZEN.md`](../rust/fixtures/agent_loop/FROZEN.md) `*_extended`). | A silent repair is a bug. Never supply a tool name, path, or argument the model did not write. Do not put a decision here (that is `kernel/`) or file-body salvage (that is `content/`). Do not rewrite a frozen row in place. |
+| **새 워커 계산** | Compute only — embed, parse, extract, render, ASR, LLM. Add the handler next to its family (`latticeai/api/worker_compute.py` for the `/worker/*` seams, or `WORKER_ROUTES` / `WORKER_SEAM_ROUTES` in [`latticeai/runtime/build_phases/worker_profile.py`](../latticeai/runtime/build_phases/worker_profile.py) if it is a model/engine door). Append `(method, path)` to the matching tuple. Regenerate the committed projection: `.venv/bin/python scripts/gen_worker_allowlist_fixture.py`. `tests/unit/test_worker_allowlist.py` pins the file; `lattice-host` `include_str!`s [`rust/fixtures/worker_allowlist.json`](../rust/fixtures/worker_allowlist.json). There are **19** routes. Anything not native and not on that list is `404`. | Do not add a worker route for a product feature. The worker stores nothing — no graph, no sessions, no files. `latticeai.app_factory.build_context` is the **worker** composition root (`create_worker_app`); it is not the product. Import of `latticeai.app_factory` must stay free of MLX/GPU init, singleton construction, filesystem writes, and network calls. |
+| **프론트 화면 / 패널** | Route screens in `frontend/src/pages/` (`Brain`, `Capture`, `Chronicle`, `Act`, `Library`, `System`). Feature panels in `frontend/src/features/<area>/`. Shared chrome in `frontend/src/components/`. Hash routes and aliases in `frontend/src/routes.ts`. Copy in `frontend/src/i18n/`: one namespace module calls `registerCopy` (`shell` is eager; `brain`, `workspace`, `onboarding`, `chronicle` register from the lazy route). Author Korean first; ship the English pair in the same module. `t()` falls back to `COPY.ko`. Colors from [`frontend/src/styles/tokens.css`](../frontend/src/styles/tokens.css) as `hsl(var(--token))`; surface rules in the narrowest file under `frontend/src/styles/experience/`. Brain behavior belongs in `useBrainChat` / `useBrainHistory` / `useBrainIngestion` / `useBrainProof`. Failed `ApiResult` stays an unavailable/error state. Colocate a Vitest file; the floor is 100% `all: true`. | No user-facing English/Korean literals in TSX (`scripts/check_i18n_literals.mjs`). Do not import a namespace you do not register (`check:i18n-namespaces`). Do not add a competing shell rule to `styles.css`. Do not put runtime metrics or admin tools on the default first screen. Regenerate `frontend/src/api/openapi.ts` with `npm run frontend:openapi` when a contract changes — do not edit it by hand. |
+| **지식 그래프 쓰기** | [`lattice_core::graph_write::GraphWriter`](../rust/lattice-core/src/graph_write/mod.rs) only. Public doors: `open` / `with_parts`; ingest `ingest_file` / `ingest_content` / `ingest_message` / `ingest_event`; vectors `write_vectors` / `write_vectors_with` / `rebuild_vector_index`; curation `curate` / `curate_scan` / `curate_noise` / promotions / `mark_superseded`; documents `delete_document_tree` / `delete_node` / `set_node_sensitivity` / `stamp_node_validity` / `set_local_source_watch` / `remove_local_source` / `upsert_nodes` / `upsert_edges`; provenance `record_ingestion` / `import_graph_data`. Production `open()` stamps `"personal"` when a write omits a workspace. Chunks, concepts, triples and embeddings arrive as *data* on the request types — the writer never calls a model. | Do not open `knowledge_graph.sqlite` for writing from another crate. Do not go through the retired `/worker/graph/mutate`. `with_parts` leaves `default_workspace` unset so frozen goldens keep their legacy-null rows — that constructor is for parity, not the product. |
+| **검증 / 골든** | Each family has a `FROZEN.md` stating what wrote it and that it must not be regenerated. **Agent kernel** — [`rust/fixtures/agent/`](../rust/fixtures/agent/FROZEN.md), `lattice-agent` `tests/parity.rs`. **Agent loop** — [`rust/fixtures/agent_loop/`](../rust/fixtures/agent_loop/FROZEN.md), `tests/agent_loop.rs`. **Retrieval / embeddings** — [`rust/fixtures/golden/`](../rust/fixtures/golden/FROZEN.md), `lattice-retrieval` + `lattice-core` `tests/golden_embeddings.rs`. **Graph writes** — [`rust/fixtures/graph_write/`](../rust/fixtures/graph_write/FROZEN.md). **Chunking** — [`rust/fixtures/chunking/`](../rust/fixtures/chunking/FROZEN.md), `lattice-ingest`. **HTTP replay** — [`rust/fixtures/http/`](../rust/fixtures/http/FROZEN.md). Python worker: `npm run test:unit`. SPA: `npm run test:frontend`. Visual: `npm run test:visual`. Integration starts its own loopback host with disposable HOME/data and refuses non-loopback URLs (`npm run test:integration`). | Frozen expected values are inviolable. If the port disagrees, **the port changed** — fix the port. A deliberate new answer goes under a **new key** (or a new file) and is named as not-parity; do not edit a row in place. Do not resurrect a deleted generator to "refresh" a golden. |
+
+A new gate or verdict goes in `lattice-agent` `kernel/` and fails **closed**:
+unknown is a refusal, an unreachable verifier is `NEEDS_REVIEW`, a policy-less
+tool is its most dangerous plausible class. Gate order is pinned by the agent
+goldens; reordering is a behaviour change.
+
+A new built-in prompt goes in `prompts/mod.rs` as a constant plus the test that
+feeds it through the real parser. A caller-supplied prompt always wins.
+
+`workspace_os.json` has exactly one writer:
+`workspaceos::workspace::store::WorkspaceOsStore`. Governance's
+`GovernanceState` is a facade over the same `Arc`. Audit lines go through
+`adminops::admin::append_audit_event` only.
+
+## The gates
 
-Run the smallest affected gate while iterating. Before committing broad runtime,
-API, UI, or release work, run:
+Run the smallest affected gate while iterating. Before committing broad
+runtime, API, UI, or release work:
 
 ```bash
 npm run lint
@@ -63,125 +159,177 @@ npm run typecheck
 npm run test:frontend
 npm run test:unit
 npm run docs:check-links
+npm run rust:lint          # fmt --check + clippy -D warnings
+npm run rust:test
 ```
 
-`npm run lint` is **ten** gates since 11.8.0, in order: `lint:python`
-(ruff + mypy), `lint:visual`, `lint:frontend`, `frontend:openapi:check`,
-`check_i18n_literals.mjs`, `check:i18n-namespaces`, `check:bundle`,
-`check:server-i18n`, `check_release_evidence_bound.mjs`, and
-`check:max-file-lines`. Three left in 11.8.0: `check:python` (ruff already
-parses every file on every CI test leg), `check:legacy-debt` (the mjs mirror had
-drifted from the Python test that states the same rule — the Python test is
-authoritative), and the extension tests, which CI now invokes directly on the
-3.11 + ubuntu leg.
-
-Coverage floors are not symmetrical, and the difference is deliberate rather
-than an oversight: **Python is a line-coverage floor of 90**
-(`[tool.coverage.report] fail_under = 90`, branch measurement off) and the
-frontend still pins **100% on all four vitest metrics**. Run
-`npm run test:coverage` / `npm run test:frontend:coverage` to see either.
-
 Use these when the change touches the relevant surface:
 
 ```bash
 npm run test:integration
 npm run test:visual
+npm run test:coverage
+npm run test:frontend:coverage
 npm run desktop:tauri:check
 npm run release:evidence
 npm run release:artifacts
 npm run release:validate
 ```
 
-Run `npm run build:assets` before `npm run release:evidence`. The capture command
-reads the current package version, writes only to `output/release/vX.Y.Z/`, and
-requires Playwright Chromium plus `ffmpeg` for the checked-in GIF/WebM evidence.
-
-`npm run test:integration` starts its own loopback server with disposable HOME,
-data, Brain, agent, XDG, temp, SQLite, and vault paths. It refuses non-loopback
-external base URLs so validation cannot mutate a developer's real local Brain.
-
-Regenerate committed API artifacts with `npm run frontend:openapi`; CI and
-`npm run lint` fail when either `frontend/openapi.json` or
-`frontend/src/api/openapi.ts` differs from a fresh isolated export.
-
-## Frontend Experience Ownership
-
-`frontend/src/styles/tokens.css` owns React color tokens and
-`frontend/src/styles/experience.css` imports the focused shell, conversation,
-graph, capture, and responsive layers under `frontend/src/styles/experience/`.
-Keep ownership in the narrowest surface file; do not add another competing
-shell or composer rule to `styles.css`.
-
-Brain behavior belongs in the focused `useBrainChat`, `useBrainHistory`,
-`useBrainIngestion`, and `useBrainProof` hooks. Translation namespaces live in
-`frontend/src/i18n/`. Failed `ApiResult` values must remain unavailable/error
-states rather than being normalized to healthy empty data, and affected paths
-must have Vitest coverage.
-
-Default mode should expose user tasks and outcomes. Runtime metrics, registry
-identifiers, pipeline controls, and administrator tools belong in progressive
-disclosure or advanced/admin mode. New navigation and tabs must preserve
-keyboard access, visible focus, mobile safe areas, and reduced-motion behavior.
-
-## 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` as typed stages:
-
-- `config_runtime.py` derives immutable app config values from `Config`;
-- `security_runtime.py` applies trusted proxy/security-derived settings;
-- `brain_runtime.py` constructs Brain Core and conversation primitives;
-- model, platform, and router stages receive explicit dependencies and return
-  typed bundles rather than ambient `locals()` maps.
-
-The module-level `server_app` compatibility surface is an explicit allowlist.
-Model services use injected state, and HTTP exceptions belong at the API
-boundary. Readiness tests should reject forbidden patterns instead of treating
-symbol presence alone as architectural completion.
-
-Future extraction should continue with AgentRuntime, ToolRegistry, config,
-server decomposition, and Knowledge Graph stabilization in that order when
-architectural debt is present.
-
-## Runtime Hook Coverage
-
-Knowledge Graph ingestion paths must continue to pass through the shared
-pre-tool/post-tool lifecycle:
-
-- browser `read-url` ingestion dispatches `tool.kg_ingest.*` events;
-- browser `ingest-current-tab` ingestion dispatches the same lifecycle;
-- the native ingest door in `lattice-ingest` (writing through `graph_write`)
-  remains the single ingestion boundary behind those routes.
-
-## Documentation Sync
+### `npm run lint` — ten members, in this order
+
+1. `lint:python` — `ruff check .` then `mypy`. Fix ruff locally (`ruff check --fix`) before arguing with the rule; mypy errors name the module under `latticeai/` or `lattice_brain/`.
+2. `lint:visual` — `node --check` on every `tests/visual/*.js`, `*.cjs`, and `tests/visual/mock_server/*.cjs`. A syntax error in a screenshot spec fails here, not in Playwright.
+3. `lint:frontend` — `scripts/lint_frontend.mjs`: `tsc --noEmit` plus static checks over `frontend/` and `static/app`.
+4. `frontend:openapi:check` — `frontend/openapi.json` and `frontend/src/api/openapi.ts` must match a fresh isolated export. Fix: `npm run frontend:openapi` and commit both artifacts.
+5. `scripts/check_i18n_literals.mjs` — no user-facing string literals in `frontend/src` TS/TSX. Move the words into the matching `frontend/src/i18n/` namespace (both `ko` and `en`).
+6. `check:i18n-namespaces` — a lazy chunk may only read keys whose namespace it imports. Import the namespace module from the route, do not reach into a sibling dictionary.
+7. `check:bundle` — initial JS gzip closure stays under 150 KiB. Heavy UI belongs behind `React.lazy`. Do not raise the budget to hide a sync import.
+8. `check:server-i18n` — routers listed in `scripts/check_server_i18n.mjs` must raise through `http_error` / `translate`, never a quoted `detail=`. Adding a name to `LOCALIZED` is how a migration is declared finished. Today it locks 4 worker routers and reports 2 unclaimed (`health`, `search`).
+9. `scripts/check_release_evidence_bound.mjs` — see the binding paragraph below.
+10. `check:max-file-lines` — see the line-limit paragraph below.
+
+Three things left the local chain in 11.8.0 and must not be "restored" as
+habits: `check:python` (ruff already parses every file on every CI test leg),
+`check:legacy-debt` (the Python test is authoritative), and the extension
+tests (CI invokes them directly on the 3.11 + ubuntu leg). See
+[CI_AND_RELEASE_GATES.md](CI_AND_RELEASE_GATES.md).
+
+### Coverage floors
+
+The floors are not symmetrical, and that is deliberate. Python
+(`[tool.coverage.report] fail_under = 90` in `pyproject.toml`) is a
+**line-coverage** floor; branch measurement is off. Run
+`npm run test:coverage`. A red report is uncovered product lines in
+`latticeai/` or `lattice_brain/` — add a unit test, do not lower the floor
+and do not hide the line with `pragma: no cover` unless the exclusion is
+reasoned. The frontend (`vitest.config.ts`) pins **100% on statements,
+branches, functions, and lines** with `all: true`, so an untested new module
+is in the denominator. Run `npm run test:frontend:coverage`. A file that
+vanishes from the text reporter is fully covered; confirm with
+`--coverage.reporter=json-summary`. `frontend/src/i18n/**`,
+`frontend/src/api/openapi.ts`, and `frontend/src/main.tsx` are excluded on
+purpose.
+
+### Max-file-lines (1,000)
+
+`scripts/check_max_file_lines.mjs` fails any git-tracked
+`*.py *.ts *.tsx *.js *.mjs *.cjs *.css *.rs` over 1,000 lines, tests
+included. It exists because a 10k-line CSS file and twenty-seven other
+oversize modules landed before anyone noticed — long files burn review and
+conflict on every feature. Split by cohesion, not at line 1,000. Exempt only
+generated paths (`frontend/src/api/openapi.ts`, `static/app/`,
+`static/vendor/`, `src-tauri/gen/`). A new exemption for a hand-written file
+is not a fix.
+
+### Clippy `-D warnings`
+
+`npm run rust:lint` is `cargo fmt --all -- --check` then
+`cargo clippy --workspace --all-targets -- -D warnings` inside `rust/`. CI
+runs the same. The workspace no longer carries blanket `#![allow]`. Fix the
+diagnostic at the source; do not re-allow it. Format drift is `cargo fmt`
+in `rust/`.
+
+### Docs gates
+
+`npm run docs:check-links` is two scripts:
+`scripts/check_markdown_links.mjs` (README plus one hop of README-linked
+Markdown) and `scripts/check_doc_status.mjs` (every relative link under the
+root canonical docs and `docs/**`). A red line is a broken relative path —
+fix the href or put the file where the href says. Canonical docs (this one
+included) must carry `Current release: **12.1.0 — …**` matching
+`package.json`; do not bump that marker here ahead of the release lane.
+`npm run docs:check-current` is the release-set version pin
+([`scripts/check_current_release_docs.mjs`](../scripts/check_current_release_docs.mjs)).
+Reference docs ([ROADMAP.md](ROADMAP.md), this file's siblings with
+`Status: reference`) are not held to the version marker. Historical
+changelog entries that mention old versions stay.
+
+### Release-evidence binding
+
+`scripts/check_release_evidence_bound.mjs` (lint member 9) checks that
+`output/release/v12.1.0/SCREENSHOT_INDEX.md` still names the live
+`static/app/asset-manifest.json` digest and the visual mock-server
+fingerprint. It exists so a later `npm run build:assets` cannot ship
+screenshots of an older UI, and so a mock-server edit cannot leave the
+evidence describing a panel the tree no longer produces. Fix: run
+`npm run build:assets` then `npm run release:evidence` (needs Playwright
+Chromium and `ffmpeg`); the capture writes only to
+`output/release/vX.Y.Z/`. `LTCAI_SKIP_RELEASE_EVIDENCE_BOUND=1` is the
+capture script's own hatch, not a commit-time escape.
+
+## House rules
+
+**Honesty.** A stub is a stub. A capability that cannot complete surfaces
+`unavailable` / `skipped` / `simulation` / `awaiting_approval` with a reason
+— never a fabricated success, score, or record. A remaining `—` in
+[FEATURE_STATUS.md](../FEATURE_STATUS.md) or
+[SURFACE_PARITY.md](SURFACE_PARITY.md) states why it is a design boundary.
+Do not write "Current" over a surface that 404s. See
+[PROJECT_PRINCIPLES.md](../PROJECT_PRINCIPLES.md).
+
+**Fail-closed verification is law.** An unverifiable agent outcome is
+`NEEDS_REVIEW`, not success. An unknown permission case is a refusal. A
+policy-less tool takes its most dangerous plausible class. The worker
+allowlist answers `404` for everything it does not name. Graph scope errors
+do not silently widen. Change-proposal approval whose base SHA no longer
+matches is a **409**, never a merge and never a silent overwrite. Additive
+creates may run with minimal friction; mutations and deletions of existing
+user files are staged as review proposals (`change_proposal`) and applied
+exactly as reviewed.
+
+**Korean UX is the default.** Author product copy in Korean first; ship the
+English pair in the same `registerCopy` table. `t()` falls back to
+`COPY.ko`. The first-run `LanguageChooser` is on every onboarding step.
+Do not leave an English literal on a path a Korean reader will see — the
+i18n gates exist to catch that, and the remaining English API `detail`
+strings are a named gap in [ROADMAP.md](ROADMAP.md), not a style.
+
+**Tokens-only CSS.** React color lives in `frontend/src/styles/tokens.css`
+and is consumed as `hsl(var(--token))`. No hex on a themed surface. Put a
+new rule in the narrowest `frontend/src/styles/experience/` file. Do not
+add another competing shell or composer rule to `styles.css`. No glass —
+the 11.7.0 elevation ladder is the vocabulary.
+
+**Workspace `null` = personal.** `DEFAULT_WORKSPACE_ID` is `"personal"`.
+Reads treat a NULL or blank `workspace_id` as personal visibility.
+Production `GraphWriter::open` stamps `"personal"` when a write omits a
+workspace. A request that names two different workspaces (header vs.
+query/body) is 403. Do not invent a second default string, and do not
+treat NULL as "visible to every tenant".
+
+## 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
+- [README.md](../README.md)
+- [ARCHITECTURE.md](../ARCHITECTURE.md)
+- [FEATURE_STATUS.md](../FEATURE_STATUS.md)
+- [RELEASE.md](../RELEASE.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [SECURITY.md](../SECURITY.md) when trust/security changes
+- [vscode-extension/README.md](../vscode-extension/README.md) when editor
+  integration changes
+- [LEGACY_COMPATIBILITY.md](LEGACY_COMPATIBILITY.md) when root compatibility
+  files change
+- this file, when the contributor path or the map changes
+- [ROADMAP.md](ROADMAP.md), when a named gap closes or a new honest leftover
+  appears
+
+The release-docs lane owns README / ARCHITECTURE / FEATURE_STATUS version
+bumps. Do not move this file's `Current release` marker off 12.1.0 ahead of
+that lane.
 
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
 
-For 11.9.0 release work, exact artifacts are:
+For 12.1.0 release work, exact artifacts are:
 
-- `dist/ltcai-11.9.0-py3-none-any.whl`
-- `dist/ltcai-11.9.0.tar.gz`
-- `ltcai-11.9.0.tgz`
-- `dist/ltcai-11.9.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_11.9.0_aarch64.dmg`
+- `dist/ltcai-12.1.0-py3-none-any.whl`
+- `dist/ltcai-12.1.0.tar.gz`
+- `ltcai-12.1.0.tgz`
+- `dist/ltcai-12.1.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_12.1.0_aarch64.dmg`
 
 The dmg is ad-hoc signed (effectively unsigned); `npm run release:validate`
 checks the names and presence, not a Developer ID signature.

package/docs/ENTERPRISE.md

@@ -22,7 +22,7 @@ boundary honest (Community is never crippled to upsell Enterprise).
 ## The extension seam
 
 The seam moved to Rust with the product server in 11.6.0 and now lives in
-[`rust/lattice-platform/src/admin/enterprise.rs`](../rust/lattice-platform/src/admin/enterprise.rs):
+[`rust/lattice-platform/src/adminops/admin/enterprise.rs`](../rust/lattice-platform/src/adminops/admin/enterprise.rs):
 
 - `Edition` — `community` (default) or `enterprise`.
 - `EnterpriseCapability` — the enum of reserved capabilities (below).

package/docs/MULTI_AGENT_RUNTIME.md

@@ -3,14 +3,14 @@
 The Multi-Agent Runtime is the **orchestration layer** introduced in v2.0.0 and
 operationalized in v2.2.0. It sits
 *above* the single-agent state machine, which since 11.6.0 is the Rust loop
-orchestrator ([`lattice_agent::agentloop`](../rust/lattice-agent/src/agentloop/mod.rs))
+orchestrator ([`lattice_agent::agentloop`](../rust/lattice-agent/src/kernel/agentloop/mod.rs))
 and coordinates a pipeline of named **roles** that hand off work to one another,
 retry on a failing review, and emit a fully observable, replayable timeline.
 
-- **Source of truth:** `rust/lattice-platform/src/agents.rs` (the orchestration
-  routes) over `rust/lattice-agent/src/agentloop/` (the state machine)
+- **Source of truth:** `rust/lattice-platform/src/toolsurface/agents/mod.rs` (the orchestration
+  routes) over `rust/lattice-agent/src/kernel/agentloop/` (the state machine)
 - **HTTP surface:** the `agents` family, mounted by `lattice-platform`
-- **Persistence:** `rust/lattice-platform/src/review_queue.rs` — the same
+- **Persistence:** `rust/lattice-platform/src/governance/review_queue.rs` — the same
   `workspace_os.json` document the Review Center reads
 
 > **Moved in 11.6.0.** The Python modules this page used to name

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **11.9.0 — Working Order**.
+Current release: **12.1.0 — Fast Path**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind
@@ -11,7 +11,9 @@ read the docs first.
 
 1. Wake the Brain and confirm the local owner profile.
 2. Let Lattice inspect local model/runtime readiness (`/setup/scan` is a
-   real probe; brew/pip items stay manual).
+   real probe). Since 12.0.0 a listed brew/pip/uv item can be installed
+   from here, one item at a time and only when the user says so — the
+   default is still to show the command rather than run it.
 3. Pick the recommended Brain voice (`/models/recommendations` probes RAM
    and the worker catalog) or skip model loading.
 4. Add one source: upload a file, choose and scan a folder, save a note, or
@@ -32,7 +34,15 @@ read the docs first.
 - Empty states suggest one concrete next action without claiming proof that does
   not exist yet.
 - Core-service failures show an unavailable/error state and recovery guidance;
-  they are never presented as an empty or healthy Brain.
+  they are never presented as an empty or healthy Brain. Since 12.0.0 every
+  route and every heavy panel sits inside an error boundary with a 다시 시도
+  action, so one failing panel costs its own card rather than the screen.
+- The first source can be added on any model the machine can hold: the agent
+  profile is measured on load, and a model that cannot emit a tool call is
+  guided through numbered choices instead of failing the run.
+- Re-scanning a folder that has not changed is nearly free, so re-indexing is
+  a safe habit rather than a cost. A file deleted from disk keeps its memory
+  until the user confirms the 「삭제된 파일 정리」 action.
 - Upload, note, browser, and message ingestion all converge through the unified
   ingestion pipeline when it is available.
 - Workspace-scoped content must not leak or overwrite another workspace's graph

package/docs/OPERATIONS.md

@@ -1,4 +1,4 @@
-# Lattice AI — Operations Guide (v11.9.0)
+# Lattice AI — Operations Guide (v12.1.0)
 
 > **Status: canonical** — kept in sync with the current release. Storage layout
 > below reflects the SQLite live Brain store and workspace scoping, not the
@@ -29,9 +29,18 @@ tar -czf ltcai-backup-$(date +%Y%m%d).tar.gz ~/.ltcai ~/ltcai-agent
 tar -xzf ltcai-backup-YYYYMMDD.tar.gz -C ~
 ```
 
-인앱 복원(`.latticebrain` / `VACUUM INTO` 스냅샷)은 원자적입니다. **오래
-떠 있는 프로세스에서 복원하면 커넥션이 재활용되기 전까지 복원 전
-바이트를 줄 수 있습니다.** 복원 뒤에는 호스트를 재시작하십시오.
+인앱 복원(`.latticebrain` / `VACUUM INTO` 스냅샷)은 원자적이고, **v12.0.0
+부터 즉시 반영됩니다 — 복원 뒤 재시작이 필요 없습니다.** 스토어가
+세대(generation) 에폭을 들고 있어서, 복원이 에폭을 올리면 이전 세대에서
+열린 풀 커넥션은 다음 체크아웃에서 낡은 것으로 판정되어 닫히고, 그다음
+읽기는 복원된 바이트를 봅니다. 11.9.0까지의 완화책이던 "복원 후 재시작"
+절차는 더 이상 필요하지 않습니다.
+
+삭제된 파일 정리는 별개의 확인된 동작입니다: `POST
+/api/ingestion/folder/prune`가 `confirm` 없이는 dry-run(무엇이 지워질지와
+노드/엣지/청크/벡터 수)이고, `confirm`이 있을 때만 문서 서브트리를
+`delete_document_tree`로 제거합니다. 어느 경로도 디스크의 파일을 지우지
+않습니다.
 
 ### 2.3 히스토리만 초기화
 ```bash

package/docs/REALTIME_COLLABORATION.md

@@ -5,7 +5,7 @@ Realtime Collaboration is the subsystem that gives a Lattice AI workspace a live
 workspace-scoped execution observability for agents, handoffs, reviews,
 workflows, plugins, retries, and failures. It is delivered over Server-Sent
 Events (SSE) by an in-process pub/sub bus, the
-[`RealtimeBus`](../rust/lattice-platform/src/realtime.rs), native since 11.6.0.
+[`RealtimeBus`](../rust/lattice-platform/src/workspaceos/realtime.rs), native since 11.6.0.
 
 The design goal is to surface "what is happening in the workspace right now"
 (workspaces created, graphs indexed, agents and workflows run, plugins enabled,