@arach/lattices 0.2.0 → 0.6.1

package/docs/app.md

@@ -11,6 +11,7 @@ workspace from there.
 
 ```bash
 lattices app          # Build (or download) and launch
+lattices app update   # Download the latest release and relaunch
 lattices app build    # Rebuild from source
 lattices app restart  # Quit, rebuild, relaunch
 lattices app quit     # Stop the app
@@ -73,10 +74,32 @@ Available when `layers` are configured in `~/.lattices/workspace.json`
 | Command           | Description                              |
 |-------------------|------------------------------------------|
 | Settings          | Open preferences (terminal, scan root)   |
+| Update Lattices   | Download the latest release and relaunch |
 | Diagnostics       | View logs and debug info                 |
 | Refresh Projects  | Re-scan for .lattices.json configs        |
 | Quit Lattices      | Exit the menu bar app                    |
 
+## Overlay actors and HUDs
+
+Persistent overlay actors can be hidden or restored with **Hyper+B**. Apps can
+publish a static hover dashboard by exposing:
+
+```txt
+.lattices/hud/manifest.json
+```
+
+Register and publish one:
+
+```bash
+lattices hud register .lattices/hud/manifest.json --publish
+```
+
+The manifest points to a local `index.html`, optional icon, app activation
+target, HUD dimensions, and optional app-owned `sources` metadata for logs or
+state files. Lattices hosts the actor and loads the dashboard through a
+transparent `WKWebView`; the app owns the renderer and writes its own logs in
+the places it already uses.
+
 ## Project discovery
 
 The app scans a configurable root directory (up to 3 levels deep)
@@ -93,7 +116,7 @@ For each project found, the app reads:
 ## Session management
 
 The app calls the lattices CLI for session operations. Launch runs
-`lattices` in the project directory, Sync runs `lattices sync` to
+`lattices start` in the project directory, Sync runs `lattices sync` to
 reconcile panes, and Restart runs `lattices restart <pane>` to kill
 and re-run a pane's process. Detach and Kill call `tmux detach-client`
 and `tmux kill-session` directly.
@@ -143,10 +166,22 @@ highlight around it for ~1 second so you can spot it immediately.
 Grant Screen Recording and Accessibility permissions in System
 Settings > Privacy & Security for all three paths to work.
 
+## Voice commands
+
+> See [Voice Commands](/docs/voice) for the full guide.
+
+Press **Hyper+D** to open the voice command window. Hold **Option** to
+speak, release to stop. Lattices transcribes via Vox, matches to an
+intent, and executes. Built-in commands: find, show, open, tile, kill, scan.
+
+The provider-backed assistant can run in parallel, offering follow-up
+suggestions in the AI corner. Configure the provider and credentials in
+Settings > AI.
+
 ## Settings
 
 Open via the command palette or the gear icon in the main view.
-The settings window has three tabs:
+The settings window has five tabs:
 
 ### General
 
@@ -155,6 +190,8 @@ The settings window has three tabs:
 | Terminal   | Which terminal to use (auto-detected from installed) |
 | Mode       | `learning` or `auto` (see below)                     |
 | Scan Root  | Directory to scan for .lattices.json configs (type a path or click Browse) |
+| Updates    | Download the latest release and relaunch the app     |
+| Keyboard Remaps | Optional Caps Lock layer that maps hold to Hyper and tap to Escape |
 
 **Mode** controls how the app handles session interaction:
 
@@ -162,6 +199,44 @@ The settings window has three tabs:
   (helpful while getting used to tmux)
 - **Auto** — detaches sessions automatically (fewer prompts)
 
+### Keyboard Remaps
+
+**Keyboard remaps** are enabled by default for the laptop-friendly rule:
+
+- hold Caps Lock -> Hyper (`Control` + `Option` + `Shift` + `Command`)
+- tap Caps Lock -> Escape
+
+Rules live in `~/.lattices/keyboard-remaps.json`, and the Settings toggle
+can turn the layer off. Keyboard remaps require Accessibility permission
+because they use a local event tap.
+
+### Companion
+
+Shows the secure local bridge status, Mac bridge fingerprint, supported
+capability grants, and paired iPad or iPhone devices. The paired-device
+list shows each device fingerprint, last-seen time, and granted
+capabilities. You can refresh the list, revoke an individual device, or
+forget all trusted companions.
+
+The local companion bridge and trackpad proxy are off by default for
+privacy. Turn the bridge on in Settings > Companion, or open
+`lattices://companion/enable` to enable the bridge and jump straight to
+Companion settings. `lattices://companion/disable` turns it off again.
+
+The trackpad proxy toggle lives here. Paired devices still need the
+`input.trackpad` grant before they can send pointer events.
+
+### AI
+
+| Setting              | Default        | Description                              |
+|----------------------|----------------|------------------------------------------|
+| Assistant provider   | OpenAI Codex   | Provider used by in-app chat and provider-backed voice advice |
+| Pi runtime           | Auto-detected  | Runtime install/refresh controls for provider chat |
+| Provider credentials | Not set        | OAuth sign-in or local API-key storage for the selected provider |
+
+Shows assistant readiness, runtime availability, and selected-provider
+authentication state.
+
 ### Shortcuts
 
 Shows keyboard shortcut reference:
@@ -169,6 +244,14 @@ Shows keyboard shortcut reference:
 | Shortcut          | Action              |
 |-------------------|----------------------|
 | Cmd+Shift+M       | Open command palette |
+| Hyper+1            | Screen map           |
+| Hyper+2            | Window bezel         |
+| Hyper+3            | HUD                  |
+| Hyper+D            | Voice commands       |
+| Hyper+G            | Desktop inventory    |
+| Hyper+5            | Omni search          |
+| Hyper+6            | Cheat sheet          |
+| Hyper+B            | Hide/show persistent overlay actors |
 | Cmd+Option+1/2/3  | Switch workspace layer |
 | Ctrl+B  D         | Detach from session  |
 | Ctrl+B  X         | Kill current pane    |
@@ -216,13 +299,13 @@ Agents can use this to "see" what's on screen.
 
 ### Desktop Inventory integration
 
-The Desktop Inventory view (Hyper+4) uses OCR to make windows searchable
+The Desktop Inventory view (Hyper+G) uses OCR to make windows searchable
 by their content — not just by title or app name. When you type a search
 query, windows matching by OCR content show contextual snippets.
 
 ### API access
 
-Agents can query OCR data through four daemon endpoints:
+Agents can query OCR data through four API methods:
 
 | Method         | Description                                    |
 |----------------|------------------------------------------------|
@@ -232,7 +315,7 @@ Agents can query OCR data through four daemon endpoints:
 | `ocr.scan`     | Trigger an immediate scan (bypasses timer)     |
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 // Find windows showing error messages
 const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
@@ -241,16 +324,16 @@ const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
 const snapshot = await daemonCall('ocr.snapshot')
 ```
 
-More in the [Daemon API reference](/docs/api#ocrsnapshot).
+More in the [Agent API reference](/docs/api#ocrsnapshot).
 
 ### Requirements
 
 - **Screen Recording** permission — required to capture window images
 - Granted via System Settings > Privacy & Security > Screen Recording
 
-## Daemon
+## Agent API server
 
-The menu bar app runs a WebSocket daemon on `ws://127.0.0.1:9399`.
+The menu bar app runs a WebSocket server on `ws://127.0.0.1:9399`.
 It starts automatically when the app launches and stops when the app
 quits.
 
@@ -263,7 +346,7 @@ lattices daemon status
 Or programmatically:
 
 ```js
-import { isDaemonRunning, daemonCall } from '@arach/lattices/daemon-client'
+import { isDaemonRunning, daemonCall } from '@lattices/cli'
 
 if (await isDaemonRunning()) {
   const status = await daemonCall('daemon.status')
@@ -273,7 +356,7 @@ if (await isDaemonRunning()) {
 
 ### What it provides
 
-- 30 RPC methods for reading windows, sessions, projects, spaces, layers,
+- 35+ RPC methods for reading windows, sessions, projects, spaces, layers,
   processes, terminals, and OCR. Also launching/killing sessions, tiling
   windows, switching layers, and managing tab groups.
 - 5 real-time events (`windows.changed`, `tmux.changed`, `processes.changed`,
@@ -284,11 +367,11 @@ if (await isDaemonRunning()) {
 
 ### Security
 
-The daemon binds to localhost only (`127.0.0.1:9399`). Not accessible
+The server binds to localhost only (`127.0.0.1:9399`). Not accessible
 from the network. No authentication, so any local process can connect.
-This is intentional. It's for local automation, not remote access.
+This is intentional — it's for local automation, not remote access.
 
-Full method list in the [Daemon API reference](/docs/api).
+Full method list in the [Agent API reference](/docs/api).
 
 ## Diagnostics
 

package/docs/assistant-knowledge.md

@@ -0,0 +1,130 @@
+---
+type: Assistant Knowledge Base
+title: Lattices — Assistant Knowledge
+description: Orientation + capability map the in-app Workspace Assistant uses to explain Lattices and point to the right feature or doc
+audience: assistant
+---
+
+> You are reading the Workspace Assistant's knowledge base. It summarizes what
+> Lattices can do and links to the deeper docs. Treat the **structured context**
+> in your prompt (current settings, file paths, CLI commands) as ground truth for
+> *this user's* configuration; treat this file as ground truth for *how Lattices
+> works*. When a question goes deeper than this summary, name the relevant doc
+> (see [References](#references)) instead of guessing.
+
+## What Lattices is
+
+Lattices is an **agentic window manager for macOS** — a programmable workspace
+that pairs a native menu bar app with managed tmux sessions and a scriptable
+agent API. Three layers, one product:
+
+1. **Programmable workspace** — a CLI and a WebSocket agent API (`ws://127.0.0.1:9399`,
+   35+ methods, real-time events) that let scripts and AI agents observe and drive
+   the desktop the same way a person does.
+2. **Smart layout manager** — the menu bar app tracks every window across all
+   monitors: tiling, switchable layers, snap zones, and screen-text indexing.
+3. **Managed tmux sessions** — declare a dev environment in `.lattices.json`;
+   Lattices builds it, runs it, and keeps it alive across reboots.
+
+Requirements: macOS 26+, Node 18+; tmux only for session management.
+See [Overview](/docs/overview) and [Concepts](/docs/concepts).
+
+## Capability map
+
+Each area below is a one-paragraph summary plus the doc to cite for detail.
+
+### Window tiling & placement
+Snap windows to preset positions — halves, quarters, thirds, maximize, center —
+from the command palette or `lattices tile <position>`. There is also a grid
+placement primitive: compact `CxR:c,r` starts at 1 for command entry, while
+canonical `grid:CxR:c,r` starts at 0 for APIs. → [Tiling reference](/docs/tiling-reference), positions in [Configuration](/docs/config).
+
+### Workspace layers & tab groups
+Group projects into named **layers** you can switch between, and tab-group related
+windows. `workspace.json` layers launch/focus/tile projects. Studio layers are
+rule-backed live window sets persisted in `~/.lattices/layers.json`; their clauses
+support app/title/session exact, substring, regex, Space, visibility, and exclusion
+matches. → [Layers](/docs/layers).
+
+### Command palette & menu bar app
+The palette (**Cmd+Shift+M**) is the app's primary surface: launch projects, tile,
+sync, restart, open settings — all searchable. → [Menu Bar App](/docs/app).
+
+### tmux sessions (`.lattices.json`)
+Declare panes, commands, and layout per project. `lattices start` builds/attaches a
+persistent session named `<basename>-<hash>`; `lattices sync` reconciles a running
+session to its config. **Ensure** re-runs exited commands on reattach; **prefill**
+types them and waits. → [Concepts](/docs/concepts), [Configuration](/docs/config).
+
+### Screen OCR & search
+The app reads on-screen text via the Accessibility API (~60s) and Apple Vision OCR
+on background windows (~2h), indexing everything with FTS5. Search across titles,
+app names, session tags, and OCR with `lattices search <query>` (add `--deep` or
+`--all` to inspect terminal tabs by cwd). → [Screen OCR & Search](/docs/ocr).
+
+### Voice commands
+Natural-language voice control for window management ("put the browser on the
+right", "switch to the backend layer"). → [Voice Commands](/docs/voice).
+
+### Mouse gestures
+Hold a mouse button, draw a direction or shape, release — runs the matched action.
+Configured via `mouseGestures.enabled` plus `~/.lattices/mouse-shortcuts.json`.
+→ [Mouse Gestures](/docs/mouse-gestures).
+
+### Agent API & CLI
+Agents connect over WebSocket and get the same control as a person: list
+windows/projects, launch sessions, tile, switch layers, read screen text, and
+subscribe to events (`windows.changed`, `tmux.changed`, `layer.switched`).
+→ [Agent Guide](/docs/agents), [Agent API](/docs/api).
+
+### Project twins
+Pi-backed project "twins" for mediated, persistent agent execution scoped to a
+project. → [Project Twins](/docs/twins).
+
+## Key shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd+Shift+M** | Open the command palette |
+| `lattices tile <position>` | Tile the focused window (CLI) |
+| `lattices layer [name\|index]` | Switch workspace layer (CLI) |
+| **Ctrl+B** then `D` / `Z` / arrows | tmux: detach / zoom / move pane (inside a session) |
+
+Tiling and grid hotkeys are user-configurable — for the live set, point the user to
+Settings or the [Tiling reference](/docs/tiling-reference) rather than asserting one.
+
+## CLI quick reference
+
+`lattices` · `lattices init` · `lattices sync` · `lattices start` ·
+`lattices restart [pane]` · `lattices tile <position>` · `lattices group [id]` ·
+`lattices layer [name|index]` · `lattices windows --json` ·
+`lattices search <query> [--deep|--all] [--json] [--wid]` · `lattices place <query> [position]` ·
+`lattices app restart`. Full flags: [Configuration](/docs/config).
+
+## Config & file locations
+
+- **Per project:** `.lattices.json` in the project root (panes, commands, layout, ensure/prefill).
+- **User config (`~/.lattices/`):** `workspace.json`, `layers.json`, `mouse-shortcuts.json`,
+  `snap-zones.json`, `clusters.json`, `ocr.db`, `lattices.log`.
+- **Defaults domain:** `dev.lattices.app` (read/write app settings via `defaults`).
+
+The exact current values and paths for *this* machine arrive in your structured
+context — prefer those over the generic paths above when answering.
+
+## References
+
+| Topic | Doc |
+|-------|-----|
+| What it is / who it's for | [Overview](/docs/overview) |
+| Install & first run | [Quickstart](/docs/quickstart) |
+| Architecture, glossary, internals | [Concepts](/docs/concepts) |
+| `.lattices.json`, CLI, tile positions | [Configuration](/docs/config) |
+| Command palette, tiling, sessions | [Menu Bar App](/docs/app) |
+| Tiling & grid placement | [Tiling reference](/docs/tiling-reference) |
+| Layers & tab groups | [Layers](/docs/layers) |
+| Screen OCR & full-text search | [Screen OCR & Search](/docs/ocr) |
+| Voice control | [Voice Commands](/docs/voice) |
+| Mouse gestures | [Mouse Gestures](/docs/mouse-gestures) |
+| Agent contracts (voice/CLI/daemon) | [Agent Guide](/docs/agents) |
+| WebSocket RPC method reference | [Agent API](/docs/api) |
+| Project twins | [Project Twins](/docs/twins) |

package/docs/companion-deck.md

@@ -0,0 +1,209 @@
+# Companion Deck
+
+This document defines the first extraction boundary for the Lattices
+companion deck work.
+
+## Goals
+
+- Build the deck architecture in `lattices` first, without modifying
+  `talkie`.
+- Treat `talkie` as the donor and reference implementation, not the
+  place where the first shared abstraction is born.
+- Let `lattices` own Mac functionality.
+- Let `talkie` continue to own Talkie-specific flows.
+- Keep the transport and UI shell generic enough that both products can
+  embed the same deck later.
+
+## Product Ownership
+
+### Lattices owns
+
+- Voice agent control
+- Layout and screen state
+- Application, window, tab, and task switching
+- Session and layer switching
+- Desktop questions and agent follow-up
+- Action history and undo-oriented playback
+
+### Talkie owns
+
+- Dictation
+- Memo recording
+- Scratchpad and compose flows
+- Capture-specific flows
+- Talkie-branded deck pages and follow-up actions
+
+### Shared deck kit owns
+
+- Page model
+- Action model
+- Runtime snapshot model
+- Security mode model
+- App and task switcher model
+- History feed model
+- Generic host protocol
+
+## Security Modes
+
+The deck must support two security modes.
+
+### Standalone
+
+Used by a future standalone `Lattices Companion`.
+
+- Bonjour discovery
+- Local network only
+- No Tailscale or external relay dependency
+- QR or code-based pairing on top of the local network path
+- Per-device keypairs
+- Signed requests with nonce and timestamp protection
+- Local companion gateway with a reduced action surface
+
+### Embedded
+
+Used when the deck is embedded inside `talkie`.
+
+- Pairing, trust, transport, and signing are delegated to Talkie
+- Lattices focuses only on local functionality and state
+- The Lattices deck host does not need to own remote security in this mode
+
+## First Lattices Companion Scope
+
+The first iPad/iPhone companion for Lattices should focus on these pages:
+
+1. Voice
+2. Layout
+3. Switch
+4. History
+
+These pages cover the highest-value mobile control loops without pulling
+Talkie-specific concepts into the new product.
+
+## Module Plan
+
+### `swift/DeckKit`
+
+Cross-product contract incubated in the Lattices repo first.
+
+- Shared deck schema
+- Security mode model
+- Runtime snapshot model
+- Host protocol
+
+### `LatticesDeckHost`
+
+Mac-side adapter owned by Lattices.
+
+- Publishes deck pages and runtime state
+- Maps deck actions to the existing Lattices desktop APIs
+- Uses the existing desktop model, layout engine, switcher logic, and
+  voice agent surfaces
+
+### `Lattices Companion`
+
+Future iOS or iPadOS app that consumes `DeckKit` and the Lattices
+companion gateway.
+
+### `TalkieDeckHost`
+
+Future Talkie-side adapter that adds Talkie-only pages on top of the
+shared deck shell.
+
+## Current Lattices Milestone
+
+The first host-side integration now lives in the Lattices macOS app.
+
+- `swift/DeckKit` continues to own the shared manifest, snapshot,
+  action, and security contract.
+- `apps/mac/Sources/LatticesDeckHost.swift` is the first concrete Mac host.
+- The menu bar app daemon now exposes:
+  - `deck.manifest`
+  - `deck.snapshot`
+  - `deck.perform`
+
+That gives the future iPhone/iPad companion a stable local contract
+before transport and pairing are finalized.
+
+The current transport now runs as a local network bridge in the macOS
+app with Bonjour discovery on port `5287` (`LATS` on a phone keypad).
+Standalone mode now uses:
+
+- local Mac approval for first-time device pairing
+- per-device key agreement
+- signed requests with nonce and timestamp checks
+- encrypted deck payloads for snapshots, actions, and trackpad events
+- pairing-time capability grants, enforced again on every protected route
+
+The bridge still keeps `/health`, `/deck/manifest`, and pairing
+bootstrap lightweight so a new companion can connect and establish trust
+without an external relay or Tailscale dependency.
+
+## Reference Security Pattern
+
+The standalone bridge is the reference pattern we should share back to
+Talkie and Scout:
+
+1. Bonjour is discovery only. The TXT record exposes protocol version,
+   fingerprint, security mode, and coarse capabilities, but no project
+   names, sessions, commands, or tokens.
+2. Local-network control is opt-in. The bridge is disabled by default;
+   users enable it from Companion settings or the local
+   `lattices://companion/enable` deep link.
+3. Pairing is explicit Mac approval. A cryptographic handshake or public
+   key exchange proves key possession; it does not automatically grant
+   control.
+4. Trust is scoped. Pairing records store granted capabilities such as
+   `deck.read`, `deck.perform`, and `input.trackpad`.
+5. Every protected request is signed with a timestamp and nonce, then
+   checked for replay before the route runs.
+6. Sensitive payloads are encrypted with per-device key agreement and
+   route-bound additional authenticated data.
+7. Authorization happens after authentication. A trusted device still
+   needs the route's required capability before it can read state,
+   perform actions, or proxy input.
+
+That gives the family of apps one ergonomic model: discover nearby,
+pair once, reconnect quietly, and keep control surfaces capability
+scoped.
+
+## Initial Action Surface
+
+The first deck action IDs are intentionally small and map to existing
+desktop behavior:
+
+- `voice.toggle`
+- `voice.cancel`
+- `layout.activateLayer`
+- `layout.optimize`
+- `layout.placeFrontmost`
+- `switch.focusItem`
+- `history.undoLast`
+
+This keeps the first bridge focused on real Mac control loops instead
+of inventing a second execution stack.
+
+## Rollout Sequence
+
+1. Leave Talkie untouched and use it as the donor reference.
+2. Incubate `DeckKit` in `lattices`.
+3. Build a clean Lattices companion around `Voice`, `Layout`,
+   `Switch`, and `History`.
+4. Prove standalone local pairing and strong security for Lattices.
+5. Harden the deck contract.
+6. Retrofit the stabilized deck kit back into Talkie.
+
+Embedded mode remains a first-class constraint throughout the rollout.
+The standalone bridge must not leak into the shared deck contract in a
+way that would make Talkie embedding awkward later.
+
+## Vox
+
+Vox is the preferred voice dependency for the Lattices companion path.
+
+- Prefer direct embedding through `VoxCore` and `VoxEngine` for
+  in-process ASR and TTS inside Apple apps.
+- Keep `VoxBridge` available as an optional daemon-style path when a
+  shared runtime is more appropriate than direct embedding.
+- Keep the first contract in `DeckKit` voice-agnostic.
+- Let `LatticesDeckHost` decide whether voice is served by embedded Vox
+  or another local service surface.