latticesql 4.2.3 → 4.3.0

package/docs/assistant.md

@@ -233,13 +233,17 @@ workspace's Secrets object.
 
 ## Voice (optional)
 
-Set `OPENAI_API_KEY` (Whisper) or `ELEVENLABS_API_KEY` to enable the composer
-mic; choose the provider in the Assistant settings (also a machine-local user
-preference, not a workspace secret). When no microphone is available the mic
-button is shown disabled with a tooltip rather than erroring. **While a note is
-recording or transcribing, the composer is read-only** — it shows a
-"Listening… / Transcribing…" placeholder and the Send button is disabled — and
-the transcript is inserted when you stop.
+The composer's 🎙 mic dictates **on-device** — speech is transcribed in your
+browser by Whisper (WASM), so it needs no API key or setup and audio never leaves
+your machine. There is no voice-provider choice in the GUI; the mic is always
+shown when a microphone is available, and shown disabled with a tooltip when none
+is. **While a note is recording or transcribing, the composer is read-only** — it
+shows a "Listening… / Transcribing…" placeholder and the Send button is disabled —
+and the transcript is inserted when you stop.
+
+Keyed cloud transcription (`OPENAI_API_KEY` / Whisper or `ELEVENLABS_API_KEY`)
+remains available to **API** callers via `POST /api/assistant/transcribe` for
+backward compatibility; the GUI itself always dictates on-device.
 
 ## Cloud
 

package/docs/bugs/2026-06-23-connectors-tab-out-of-scope.md

@@ -0,0 +1,67 @@
+# Connectors settings tab rendered nothing (`fetchJson is not defined`)
+
+**Date:** 2026-06-23
+**Area:** GUI client script composition (`src/gui/app/modules/`)
+**Severity:** broken feature (the entire Connectors settings tab was non-functional)
+
+## Symptom
+
+Opening **Settings → Connectors** in the GUI highlighted the tab but left the
+drawer body showing whatever tab was previously open (e.g. the Lattice/Workspaces
+panel). The connectors panel never appeared. The browser console showed an
+uncaught `ReferenceError: fetchJson is not defined`.
+
+## Root cause
+
+The GUI client script (`appJs`) is composed by concatenating per-subsystem module
+strings in `src/gui/app/modules/index.ts` and inlining the result into a single
+`<script>` tag. The original modules' bodies execute inside a wrapper scope (an
+IIFE/`DOMContentLoaded` closure), so their top-level functions — `fetchJson`,
+`escapeHtml`, the `render*` panels, `selectDrawerTab` — are **scoped to the
+wrapper**, not attached to `window`.
+
+`connectorsSettingsJs` was appended as the **last** element of the composition
+array — _after_ the wrapper closes. That placed `renderConnectorsPanel` at true
+global scope. It was still reachable from `selectDrawerTab` (a wrapper-scoped
+function can call a global one), so clicking the tab invoked it — but its very
+first statement, `fetchJson('/api/connectors')`, referenced a name that only
+exists inside the wrapper. The `ReferenceError` was thrown synchronously, before
+the `.then`/`.catch` chain was attached and before `host.innerHTML` was written,
+so the drawer body was never updated and the tab silently showed stale content.
+
+Confirmed at runtime: `typeof window.renderConnectorsPanel === 'function'` while
+`typeof window.fetchJson === 'undefined'` — the panel function was the only one
+outside the wrapper.
+
+## Fix
+
+Move `connectorsSettingsJs` to sit **inside** the wrapper, next to `tableViewJs`
+(which defines `selectDrawerTab`, the dispatcher that calls it). Function
+declarations hoist within the wrapper, so `renderConnectorsPanel` can now see
+`fetchJson`/`escapeHtml`, and `selectDrawerTab` can still call it. No change to
+the panel code itself — purely a composition-order fix.
+
+## Why existing tests missed it
+
+`tests/unit/connectors-panel.test.ts` `eval`s `connectorsSettingsJs` in isolation
+with **stubbed** `fetchJson`/`escapeHtml`, so it exercises the panel's markup and
+button wiring but not the real composed-scope integration. The
+`app-js-composition` test only pins length + hash, not execution. Neither could
+observe the cross-module scope boundary.
+
+## Lessons
+
+- A module appended to the composition array is only correct if it lands on the
+  right side of the wrapper boundary. New client modules that depend on shared
+  helpers must be composed among the wrapped modules, not appended after them.
+- Isolated-`eval` unit tests with stubbed globals cannot catch cross-module scope
+  bugs. Browser-level coverage is required for "does this tab actually render."
+
+## Regression tests
+
+- `tests/e2e/connectors-settings.spec.ts` — opens the drawer on another tab,
+  clicks the Connectors tab, and asserts the connectors panel + Jira credential
+  form render with **no page error**. Verified to fail when the module is appended
+  last (the bug) and pass when it is composed inside the wrapper (the fix).
+- `tests/unit/app-js-composition.test.ts` — length/hash re-pinned after the
+  composition-order change.

package/docs/bugs/2026-06-24-cloud-pooler-exhaustion.md

@@ -0,0 +1,68 @@
+# Cloud queries fail under load with `EMAXCONNSESSION` (session-pooler exhaustion)
+
+**Date:** 2026-06-24
+**Area:** Postgres adapter / cloud connections (`src/db/postgres.ts`)
+**Severity:** queries fail under load on small-pool cloud projects
+
+## Symptom
+
+On a cloud (Supabase) workspace, a burst of activity — e.g. the assistant
+gathering data for a dashboard while the realtime broker is also running — caused
+queries to fail with:
+
+```
+(EMAXCONNSESSION) max clients reached in session mode — max clients are limited to pool_size: 15
+```
+
+The assistant, seeing failed tool queries, paraphrased this as a "rate limit."
+
+## Root cause
+
+The workspace connection string pointed at Supabase's **session-mode pooler**
+(`*.pooler.supabase.com:5432`), and the query pool connected there. In session
+mode, every pooled client holds one upstream connection for its entire lifetime.
+The app's footprint against that pooler was:
+
+- the query `pg.Pool` (default `max` 10), plus
+- the realtime broker's dedicated `LISTEN/NOTIFY` `pg.Client` (can't be pooled),
+  plus
+- transient connections during workspace open (peek / converge / bootstrap).
+
+Under a burst this exceeded the pooler's `pool_size` of 15. The visibility probe
+(`changeVisibleToActiveRole`, fired per change on the **entire** cloud via the
+global NOTIFY fan-out) competed for the same pool, amplifying the pressure.
+
+This is a capacity mismatch, not a transient — so backoff/retry is the wrong fix;
+it would just re-queue against a still-full pooler.
+
+## Fix
+
+Route the **query pool** through Supabase's **transaction-mode pooler** (port 6543) instead of the session pooler (5432). Transaction mode returns the upstream
+connection to the pool at COMMIT, multiplexing many clients over far fewer
+upstream slots. The adapter already holds no cross-statement session state (it
+re-executes SQL per call rather than caching server-side prepared statements;
+advisory locks are `_xact_` (transaction-scoped); `set_config(..., is_local=true)`
+is transaction-local; `SET search_path` appears only inside `SECURITY DEFINER`
+function bodies), so it is transaction-pooler-safe.
+
+The realtime broker keeps its **session-mode** connection — `LISTEN/NOTIFY`
+requires session mode, and it is a separate `pg.Client` not affected by the pool's
+URL.
+
+`toTransactionPoolerUrl()` does the rewrite surgically: only a Supabase pooler
+host on :5432 is bumped to :6543 (host:port only, never userinfo); direct,
+non-Supabase, already-:6543, and unparseable URLs are left untouched.
+`LATTICE_PG_SESSION_POOLER=1` forces the pool back onto session mode.
+
+## Lessons
+
+- `EMAXCONNSESSION` is the session pooler's client cap, not your `pg.Pool` `max`
+  — count the dedicated `LISTEN` client + transient open-time connections too.
+- Use the session pooler only for what needs it (LISTEN/NOTIFY); route ordinary
+  short queries through the transaction pooler.
+
+## Regression tests
+
+- `tests/unit/postgres-transaction-pooler.test.ts` — covers the rewrite
+  (Supabase :5432 → :6543, userinfo/db/query preserved) and the no-ops
+  (already-:6543, direct Supabase, non-Supabase, `:54321`, escape hatch).

package/docs/bugs/2026-06-24-html-author-model-entitlement.md

@@ -0,0 +1,77 @@
+# HTML/dashboard authoring fails for connected Claude subscriptions (hardcoded model not entitled)
+
+**Date:** 2026-06-24
+**Area:** GUI assistant — delegated HTML authoring (`src/gui/ai/html-author.ts`)
+**Severity:** broken feature (every `create_html_file` / `edit_html_file` failed for subscription auth)
+
+## Symptom
+
+Asking the assistant to build a dashboard ("Build me a dashboard that shows
+contract value by client") never produced a file. The chat would gather the data,
+say "Now I'll create the dashboard," then retry and stall. It failed on **both
+local (SQLite) and cloud (Postgres) workspaces**, which ruled out the database.
+On the cloud it was mislabeled as a "rate limit"; on local it just looped.
+
+## Root cause
+
+The chat assistant runs on `DEFAULT_MODEL` (`claude-haiku-4-5`). The HTML author
+**hardcoded a different model**, `claude-sonnet-4-6`, for the delegated authoring
+sub-call — using the **same resolved Claude auth** as the chat.
+
+When the user is connected via a Claude **subscription** ("Connect with Claude" /
+OAuth), the auth is entitled only to the models on that plan. This subscription
+had `claude-haiku-4-5` but **not** `claude-sonnet-4-6`. Anthropic surfaces a
+non-entitled model as a `429 rate_limit_error` on **every** call — even a
+one-token one — not as a 403/404. So every authoring sub-call 429'd instantly and
+no HTML file was ever produced. Because it's auth/model-based, it failed
+identically on local and cloud.
+
+Verified live over the real subscription auth:
+
+```
+haiku-4-5  : OK
+sonnet-4-6 : 429 rate_limit_error   (even max_tokens=16)
+```
+
+Backoff/retry could never fix this — the 429 is permanent for a non-entitled
+model, not transient.
+
+(Separately, the cloud data-gathering step hit Supabase session-pooler exhaustion
+— `EMAXCONNSESSION`, pool_size 15 — which is a distinct issue tracked on its own.)
+
+## Fix
+
+The author model must be one the resolved auth can actually call, and ideally the
+strongest such model. `htmlAuthorModelForAuth(auth)` picks by **auth kind**: a
+stronger model (`claude-sonnet-4-6`) for an Anthropic **API key** (entitled to all
+GA models — restoring the strong authoring the feature was designed around), and
+the **chat model** (`DEFAULT_MODEL`, proven entitled in-session) for an OAuth
+**subscription** (whose entitlements vary; a non-entitled model 429s every call).
+The authoring is still a focused, delegated sub-call (its own system prompt + a
+larger `maxTokens`) — it just never assumes a model the auth can't run.
+
+**Caveat — Haiku-only subscriptions.** Some "Connect with Claude" subscriptions
+entitle _only_ `claude-haiku-4-5` (verified: every Opus/Sonnet model 429s). On
+those, authoring uses Haiku and works, but Haiku is the weakest model and is not
+reliable for multi-step agentic editing (it returns valid HTML but may not honor
+the change, and may narrate an action without calling the tool). For dependable
+authoring/editing, use an Anthropic **API key** (Settings → Assistant → Advanced),
+which entitles the stronger model.
+
+## Lessons
+
+- Never hardcode a model for a sub-call that differs from the model the active
+  auth has already demonstrated it can use. A connected subscription's entitlement
+  is narrower than an API key's, and a non-entitled model returns `429
+rate_limit_error` (looks like a transient rate limit but is permanent).
+- A 429 that reproduces on a one-token request is an entitlement/permission
+  signal, not a load signal — do not back off; pick a usable model.
+
+## Regression tests
+
+- `tests/unit/gui-ai-html-author.test.ts` — asserts the authoring sub-call uses
+  `DEFAULT_MODEL` (the chat model) and explicitly **not** a hardcoded
+  `claude-sonnet-4-6`. (The prior test asserted the sonnet model — it encoded the
+  bug; it now guards against re-introducing a divergent, possibly-unentitled
+  model.) Verified live end-to-end: with the fix, `generateHtmlFile` returns a
+  valid HTML document over the same subscription that 429'd before.

package/docs/bugs/2026-06-25-chat-attached-files-not-connected.md

@@ -0,0 +1,64 @@
+# Chat message not connected to its attached files
+
+**Date:** 2026-06-25
+**Area:** GUI assistant composer (`src/gui/app/modules/create-database-wizard.ts`, `onboarding.ts`) + chat route (`src/gui/chat-routes.ts`)
+
+## Symptom
+
+A user attached three screenshots to a chat message ("analyze these screenshots")
+and the assistant replied that it did **not see any attached files** — even though
+the files were referenced in its context. The attachment and the message were
+disconnected: the assistant had no signal that those specific files belonged to
+this request.
+
+## Root cause
+
+The composer Send fired two independent, unordered actions:
+
+1. `sendStaged()` → `uploadFiles()` — a fire-and-forget ingest of the staged files.
+2. `sendChat(text)` — POST `/api/chat` with the message only.
+
+So the chat turn was sent **before** the files finished ingesting, and it carried
+**no reference** to them. Nothing told the assistant "these just-attached files are
+what the request is about." The earlier instinct — "send the images to the model as
+vision" — was the wrong fix: it only helps images, breaks on multiple/complex file
+types, and treats the symptom (analysis) rather than the cause (the message is not
+linked to the files the user added).
+
+## Fix
+
+Make the one composer Send a connected, ordered workflow that works for **any** file
+type and count, reusing the assistant's existing file-interaction tools:
+
+1. **Add the files first.** `uploadFiles()` now returns a promise resolving with
+   `[{id, name}]` for each ingested file. `submitComposer` awaits the ingest before
+   sending the chat (`opts.silent` suppresses the single-file open-the-record jump
+   when a message accompanies the upload).
+2. **Reference them in the turn.** `sendChat(text, attachedFiles)` includes the
+   ingested ids in the `/api/chat` body.
+3. **Connect server-side.** `buildAttachedFilesNote(db, attachedFiles)` grounds each
+   id against the **visible** files table (a stale/invented id is dropped, never
+   referenced) and prefixes a note — "the user just attached these files … read them
+   with your file tools and use them to do what the user asks" — to the model's turn
+   only. The persisted user message is unchanged; the dispatch/tools still see the
+   real message (so `ingest_url` is unaffected).
+
+The assistant then uses its existing tools (`get_row_context`, the `files` table,
+each file's extracted text/description) to act on exactly the attached files.
+
+## Lessons learned
+
+- A "send X to the model" reflex narrows a general problem to one data type. The
+  generic, scalable fix connected the message to the files via ids and let the
+  existing per-file capabilities do the rest.
+- Fire-and-forget + a dependent action is an ordering bug. Await the prerequisite
+  (ingest) before the dependent step (the chat turn) when one needs the other.
+- Ground model-facing references against the visible DB so the assistant never
+  receives an id it can't actually see.
+
+## Regression tests
+
+- `tests/unit/chat-attached-files.test.ts` — `buildAttachedFilesNote`: empty when
+  nothing is attached; names a single file (singular phrasing) with its id; names
+  multiple files (plural phrasing, the reported multi-screenshot case); drops
+  stale/invisible ids instead of inventing a reference.

package/docs/connectors.md

@@ -0,0 +1,166 @@
+# Connectors
+
+Connectors sync data from external systems into Lattice as **connected data
+types** — tables whose rows are ingested from a source rather than authored
+locally. They make external data first-class Lattice data: queryable, full-text
+searchable, rendered to context, linked on the graph, and ACL-scoped on a cloud.
+
+A _connector_ talks to one external product (a _toolkit_) and exposes its object
+types as connected data types. The built-in connector is **Jira**, which talks to
+Jira Cloud's REST + Agile APIs directly via [`jira.js`](https://github.com/MrRefactoring/jira.js)
+using your own Atlassian credentials — there is no broker service and no extra
+API key. Adding another source (Gmail, Slack, …) is a new `Connector`
+implementation, not changes to the core.
+
+> `jira.js` is an **optional dependency**. The package compiles and runs without
+> it; it is loaded lazily and a clear error is thrown only when the Jira connector
+> is actually used. Install it to use the connector: `npm install jira.js`.
+
+## Concepts
+
+| Concept                 | Meaning                                                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Connector**           | An implementation of the fetch/auth SPI (e.g. the Jira connector).                                                     |
+| **Toolkit**             | An external product a connector serves (e.g. `jira`).                                                                  |
+| **Connected data type** | A Lattice table with a `source` descriptor — its rows are synced from a toolkit model.                                 |
+| **Connector instance**  | A registered connection (`__lattice_connectors` row): which toolkit, the per-member connection handle, and sync state. |
+
+A connected table's **natural key is its primary key** (a stable external id), so
+re-syncs upsert idempotently. Every row carries connector lineage:
+`_source_connector_id` and `_source_model` (immutable) plus `_source_synced_at`.
+
+## Credentials
+
+The Jira connector authenticates as **you**, with an Atlassian **API token**
+(HTTP Basic auth: your account email + the token). Create one at
+<https://id.atlassian.com/manage-profile/security/api-tokens>. Lattice validates
+the credentials against Jira on connect (`GET /myself`) and stores them in the
+**machine-local encrypted credential store** — they never leave the machine
+except to call the Jira API directly, and they are never written to the registry,
+logs, or any rendered context.
+
+## Using the GUI
+
+Open **Settings → Connectors**, fill in your Jira **site URL**
+(`https://your-domain.atlassian.net`), **account email**, and **API token**, then
+**Connect**. The credentials are validated and the initial sync runs. Each
+connected toolkit shows its status + last-synced time with **Refresh** and
+**Disconnect** buttons, and connected data types get a "Connected" badge in the
+Objects list.
+
+## Quick start (programmatic)
+
+```typescript
+import {
+  JiraConnector,
+  createConnector,
+  syncConnector,
+  syncIfStale,
+  disconnectConnector,
+} from 'latticesql';
+
+const connector = new JiraConnector();
+
+// Validate + store the member's Atlassian credentials, returning a connection handle:
+const { connectionId, displayName } = await connector.connect({
+  site: 'https://your-domain.atlassian.net',
+  email: 'you@example.com',
+  apiToken: process.env.JIRA_API_TOKEN!,
+});
+
+const connectorId = await createConnector(db, {
+  connector: 'jira',
+  toolkit: 'jira',
+  displayName: displayName ?? 'jira',
+  connectionRef: connectionId,
+  connectedBy: 'user-123',
+});
+
+await syncConnector(db, connector, connectorId); // defines the tables + ingests
+```
+
+## Sync model
+
+- **`syncConnector(db, connector, connectorId)`** — full sync: paginated +
+  bounded fetch per model, idempotent upsert with lineage stamping, soft-delete
+  of rows that vanished from the source, and graph-edge derivation from FK
+  columns. Records the outcome on the connector; an external-sync failure is
+  re-thrown (never swallowed).
+- **`syncIfStale(db, connector, connectorId, maxAgeMs?)`** — no-op if the last
+  sync is within `maxAgeMs` (default 1 hour). Call it on app load.
+- **`syncStaleConnectors(db, connector, maxAgeMs?)`** — sync every stale
+  connector this implementation serves. The GUI calls this on load, so connected
+  data refreshes hourly **without a scheduler**. Manual refresh forces a sync.
+
+Reads done by the sync engine are bounded and column-projected — it never scans a
+full table to diff. Per-parent models iterate the parent's already-synced keys
+(comments are fetched per issue; sprints per board).
+
+## Disconnecting
+
+```typescript
+await disconnectConnector(db, connector, connectorId, { outputDir });
+```
+
+Soft-deletes every ingested row (children before parents), prunes rendered
+context files, marks the connector `disconnected` (use `{ mode: 'hard' }` to also
+remove the registry row), and drops the stored credentials. Soft-deleted rows
+drop out of the rendered context, full-text search, and the GUI listings (all of
+which filter `deleted_at IS NULL`), and their graph edges are removed — so the
+data is no longer available to the agent while remaining physically present and
+restorable.
+
+## Cloud ACL
+
+On a cloud (Postgres) workspace, the **owner** scopes connected data per member:
+
+```typescript
+await enableConnectorRls(db, connector, 'jira');
+```
+
+This enables Row-Level Security on the registry and the toolkit's connected
+tables and applies each type's default visibility — `private` (visible only to
+the connecting member) or `everyone` (shared with the team). It is a no-op on
+SQLite, a non-cloud Postgres, or for a non-owner role.
+
+Because each member connects with their own Atlassian credentials, the data a
+member syncs is already scoped to what they can see in the source — per-user
+auth, not a shared admin credential. Derived enrichment over connected rows
+inherits the source's visibility automatically: write it through
+`db.observe(table, pk, { changeKind: 'derived', sourceRef: [connectedRowId] })`,
+and the source-gated fold hides it from a viewer who can't see the source.
+
+## The Jira toolkit
+
+Connecting Jira creates six connected data types:
+
+| Table           | Natural key | Notes                                                         |
+| --------------- | ----------- | ------------------------------------------------------------- |
+| `jira_projects` | project key | FTS on name/description                                       |
+| `jira_issues`   | issue key   | FTS on summary/description; edges → project, assignee, sprint |
+| `jira_comments` | comment id  | fetched per issue; edges → issue, author                      |
+| `jira_users`    | account id  |                                                               |
+| `jira_boards`   | board id    | edge → project                                                |
+| `jira_sprints`  | sprint id   | fetched per board; edge → board                               |
+
+## Adding a connector
+
+Implement the `Connector` SPI and point the GUI/registry at it. The SPI is small:
+
+- `connector` / `toolkits()` / `models(toolkit)` — identity + the connected
+  `ConnectedModelDef`s (table schema, natural key, FK relations → graph edges).
+- `listChanges(toolkit, model, ctx)` — an async iterable of normalized
+  `ExternalRecord`s for one model, **paged and bounded** (per-parent models read
+  `ctx.parentKey`).
+- `disconnect(connectionRef)` — revoke / drop the stored connection.
+- `authorize` / `completeAuth` — for an OAuth-redirect source. A
+  credential-based connector (like Jira) instead exposes a `connect(creds)`
+  method that validates + stores the credentials and returns a connection handle;
+  the GUI route calls it when the connector supports it.
+
+The sync engine, graph wiring, teardown, and ACL all work from the model
+descriptors — no further code is required.
+
+```
+
+```

package/docs/desktop.md

@@ -0,0 +1,75 @@
+# Lattice Desktop app
+
+A downloadable, double-click desktop build of the Lattice GUI — no terminal, no
+`npm install`. It runs the **exact same** GUI server as `lattice gui`, served into
+a native window, so there is only one GUI to maintain.
+
+## Install
+
+Download the installer for your OS from **[latticesql.com/install](https://latticesql.com/install)**:
+
+- **macOS** — `Lattice.dmg` (Apple silicon + Intel)
+- **Windows** — `Lattice.msi`
+
+The CLI path keeps working unchanged: `npm i -g latticesql && lattice gui`.
+
+> **Unsigned builds (current):** the v1 installers are not yet code-signed, so the
+> first launch shows an "unidentified developer" (macOS Gatekeeper) or "unknown
+> publisher" (Windows SmartScreen) prompt. Choose **Open anyway** / **Run anyway**.
+> Signed builds remove this step.
+
+## How it works
+
+The desktop app is built with [`deno desktop`](https://docs.deno.com/runtime/desktop/).
+It boots the standard `startGuiServer()` on a local port and points a native
+webview window at it — the webview talks to the local server exactly like a
+browser tab.
+
+- **Same version as the web GUI.** The app and its installer report the same
+  `latticesql` version the web GUI shows (one build constant; `deno.json`'s
+  version is kept in lockstep with `package.json` by `scripts/sync-desktop-version.mjs`).
+- **SQLite without native addons.** `better-sqlite3` is a native N-API addon that
+  cannot load under Deno, so the desktop build uses [`DenoSqliteAdapter`](../src/db/sqlite-deno.ts),
+  a drop-in adapter over the runtime's built-in `node:sqlite` `DatabaseSync`. The
+  npm/Node distribution is unchanged and still uses `better-sqlite3`.
+- **External links open in your browser.** A webview has no tabs/popups, so the
+  desktop shell routes `target="_blank"` links and `window.open()` to the system
+  default browser. "Connect with Claude" opens the provider page in your browser
+  while keeping the auth session local to the app.
+- **Upgrade-on-run.** On launch the app checks the release channel via
+  `Deno.autoUpdate()` and the `latest.json` manifest published with each release.
+- **Upgrade-on-install.** The download page always links the latest release, so a
+  fresh install is always current.
+
+## Build from source
+
+Requires a Deno **canary** build (`deno desktop` is canary-only for now):
+
+```bash
+deno upgrade canary
+npm ci
+
+# macOS .dmg → dist-desktop/Lattice.dmg
+npm run desktop:build:mac
+
+# Windows .msi → dist-desktop/Lattice.msi
+npm run desktop:build:win
+
+# Run the windowed app directly during development
+npm run desktop:dev
+```
+
+The app identity (name, bundle id, per-platform icons, update base URL) lives in
+[`deno.json`](../deno.json) under the `desktop` key.
+
+Releases are cut by the `Desktop Release` workflow on a `v*` tag: it builds both
+OSes, generates `latest.json`, and uploads the installers + manifest to the
+GitHub Release.
+
+## Limitations
+
+- **Image processing (`sharp`) and `sqlite-vec` acceleration are unavailable** in
+  the desktop build — both are native addons that do not load under Deno. Vector
+  search falls back to an in-process scan; image-dependent features are disabled.
+  Use the npm/Node build if you need them.
+- The build is large (it embeds its runtime + dependencies) and currently unsigned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latticesql",
-  "version": "4.2.3",
+  "version": "4.3.0",
   "description": "Persistent structured memory for AI agent systems — pluggable SQLite or Postgres backend, LLM context bridge",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/build-gui-assets.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src tests scripts",
     "lint:fix": "eslint src tests scripts --fix",
@@ -44,6 +44,11 @@
     "test:coverage": "vitest run --coverage",
     "test:e2e": "playwright test",
     "docs": "typedoc --out docs-generated src/index.ts",
+    "desktop:version:check": "node scripts/sync-desktop-version.mjs --check",
+    "test:deno": "deno test --no-check -A tests/deno/",
+    "desktop:dev": "npm run build && node scripts/sync-desktop-version.mjs && deno desktop --no-check --allow-all desktop/main.ts",
+    "desktop:build:mac": "npm run build && node scripts/sync-desktop-version.mjs && deno desktop --no-check --allow-env --allow-read --allow-write --allow-net --allow-run --allow-sys --allow-ffi --include dist/gui-assets --output dist-desktop/Lattice.dmg desktop/main.ts",
+    "desktop:build:win": "npm run build && node scripts/sync-desktop-version.mjs && deno desktop --no-check --allow-env --allow-read --allow-write --allow-net --allow-run --allow-sys --allow-ffi --include dist/gui-assets --output dist-desktop/Lattice.msi desktop/main.ts",
     "prepublishOnly": "npm run check:generic && npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
@@ -69,6 +74,7 @@
   "optionalDependencies": {
     "@aws-sdk/client-s3": "^3.1067.0",
     "exceljs": "^4.4.0",
+    "jira.js": "^5.3.1",
     "pg": "^8.11.0",
     "pgvector": "^0.2.0",
     "playwright": "^1.48.0",
@@ -77,6 +83,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
+    "@huggingface/transformers": "^4.2.0",
     "@playwright/test": "^1.48.0",
     "@types/better-sqlite3": "^7.6.12",
     "@types/jsdom": "^28.0.3",