@arach/lattices 0.2.1 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arach Tchoupani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,66 +1,98 @@
 <picture>
-  <img alt="lattices" src="site/public/og.png" />
+  <img alt="lattices" src="apps/site/public/og.png" />
 </picture>
 
 # lattices
 
-macOS workspace manager. Menu bar app, CLI, and a WebSocket API
-so your AI agents can control the desktop.
+The agentic workspace manager for macOS.
 
-Window tiling, project discovery, workspace layers, on-screen OCR,
-and optionally tmux-powered persistent sessions. 30 RPC methods
-over WebSocket. One JSON config file.
+Lattices turns your Mac workspace into a coherent API, so agents can see and
+control windows, terminal sessions, screen text, and layouts. It also gives you
+an assistant to control that workspace in plain language.
+
+**[lattices.dev](https://lattices.dev)** · [Docs](https://lattices.dev/docs/overview) · [Download](https://github.com/arach/lattices/releases/latest)
 
 ## Install
 
+### Download the app
+
+Grab the signed DMG from the [latest release](https://github.com/arach/lattices/releases/latest):
+
+```sh
+# Or direct download:
+curl -LO https://github.com/arach/lattices/releases/latest/download/Lattices.dmg
+open Lattices.dmg
+```
+
+Drag **Lattices.app** into Applications. On first launch, a setup wizard
+walks you through granting Accessibility, Screen Recording, and choosing
+your project directory.
+
+### Install the CLI
+
 ```sh
 npm install -g @arach/lattices
 ```
 
-## Quick start
+Also published as `@lattices/cli` for existing installs. The CLI and app work
+independently — use either or both.
+
+### Build from source
 
 ```sh
-# Launch the menu bar app
-lattices app
+git clone https://github.com/arach/lattices.git
+cd lattices
 
-# Open the command palette from anywhere
-# Cmd+Shift+M
+# Install CLI dependencies
+npm install
+
+# Build/install/relaunch the dev app at the stable permission target
+./scripts/run.sh
 ```
 
-The app scans your projects, tiles windows, and gives you a command
-palette for everything. Add tmux if you want persistent terminal
-sessions:
+To build a signed, notarized DMG for distribution:
 
 ```sh
-brew install tmux
-cd my-project && lattices
+# Requires a Developer ID certificate and notarytool keychain profile
+./tools/release/build-dmg.sh
+
+# Create/update v<package.json version> and upload DMG assets
+./tools/release/ship.sh
 ```
 
-That creates a tmux session with Claude Code on the left and your
-dev server on the right. Detach, close your laptop, come back later,
-reattach. Everything is where you left it.
+See [Release](docs/release.md) for the CI and local maintainer workflows.
 
-## What it does
+## Quick start
 
-**Menu bar app** sits in your menu bar. Command palette, window tiling,
-project discovery, workspace layers, OCR, and the daemon API. Works
-with or without tmux.
+```sh
+# Show workspace status for the current directory
+lattices
 
-**CLI** for tiling, session management, OCR queries, and tab groups.
+# Launch the menu bar app
+lattices app
 
-**Daemon API** on `ws://127.0.0.1:9399`. 30 RPC methods and 5
-real-time events. Agents can discover projects, tile windows, launch
-sessions, switch layers, and read on-screen text.
+# Start or reattach a tmux session
+lattices start
 
-```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+# Open the command palette from anywhere
+# Cmd+Shift+M
+```
 
-const windows = await daemonCall('windows.list')
-await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
-await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+## Persistent terminal sessions
+
+Declare your dev environment in a `.lattices.json`: which panes, which
+commands, what layout. Lattices builds it, runs it, and keeps it alive.
+Close your laptop, reboot, come back a week later — your editor, dev
+server, and test runner are exactly where you left them.
+
+```sh
+cd my-project && lattices start
 ```
 
-## Configuration
+No config? It opens a shell in the project and, when it can, starts your
+detected dev command in a second pane.
+
+### Configuration
 
 Drop a `.lattices.json` in your project root:
 
@@ -68,100 +100,143 @@ Drop a `.lattices.json` in your project root:
 {
   "ensure": true,
   "panes": [
-    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "shell", "size": 60 },
     { "name": "server", "cmd": "pnpm dev" },
     { "name": "tests",  "cmd": "pnpm test --watch" }
   ]
 }
 ```
 
-Or skip it. Without a config, lattices reads your `package.json` and
-picks the right dev command automatically.
-
 ### Layouts
 
 ```
 2 panes              3+ panes
 
 ┌──────────┬───────┐ ┌──────────┬───────┐
-│  claude  │server │ │  claude  │server │
+│  shell   │server │ │  shell   │server │
 │  (60%)   │(40%)  │ │  (60%)   ├───────┤
 └──────────┴───────┘ │          │tests  │
                      └──────────┴───────┘
 ```
 
-## Workspace layers
+### Workspace layers
 
 Group projects into switchable contexts. `Cmd+Option+1` tiles your
-frontend and API side by side. `Cmd+Option+2` switches to the mobile
-stack. All sessions stay alive across switches.
+frontend and API side by side. `Cmd+Option+2` for the mobile stack.
+Sessions stay alive across switches.
 
-Configure in `~/.lattices/workspace.json`:
+### Tab groups
 
-```json
-{
-  "layers": [
-    {
-      "id": "web", "label": "Web",
-      "projects": [
-        { "path": "/Users/you/dev/frontend", "tile": "left" },
-        { "path": "/Users/you/dev/api", "tile": "right" }
-      ]
-    }
-  ]
-}
+Bundle related repos as tabs in one session. Each tab gets its own
+pane layout from its `.lattices.json`.
+
+```sh
+lattices group vox         # Launch iOS, macOS, Web, API as tabs
+lattices tab vox iOS       # Switch to the iOS tab
 ```
 
-## Tab groups
+## Window tiling and awareness
 
-Bundle related repos as tabs in one session. Each tab gets its own
-pane layout from its `.lattices.json`.
+A native menu bar app tracks every window across all your monitors.
+Tile with hotkeys, organize into switchable layers, snap to grids.
+
+It reads your windows too — extracting text from UI elements every
+60 seconds and running Vision OCR on background windows every 2 hours.
+Everything is searchable.
 
 ```sh
-lattices group talkie      # Launch iOS, macOS, Web, API as tabs
-lattices tab talkie iOS    # Switch to the iOS tab
+lattices scan                  # View current screen text
+lattices scan search "error"   # Search across all indexed text
+lattices scan recent           # Browse scan history
+lattices scan deep             # Trigger a Vision OCR scan now
 ```
 
-## Screen OCR
+## Voice commands (beta)
+
+Speak to control your workspace — tile windows, search, focus apps,
+and launch projects with natural language. Powered by
+[Vox](https://github.com/arach/vox) for transcription and
+local NLEmbedding for intent matching, with Claude fallback for
+ambiguous commands.
 
-The app reads text from visible windows using Apple Vision and indexes
-it with FTS5 full-text search. Agents can search for error messages,
-read terminal output, or find content across all your windows.
+Trigger with `Hyper+3` (configurable). Press Space to speak, Space to
+stop. The panel shows what was heard, the matched intent, extracted
+parameters, and execution results.
+
+## A programmable desktop
+
+The menu bar app runs a daemon with 35 RPC methods and 5 real-time
+events over WebSocket. Anything you can do from the app, an agent or
+script can do over the API.
 
 ```js
+import { daemonCall } from '@arach/lattices/daemon-client'
+
+// Search windows by content — title, app, session tags, OCR
+const results = await daemonCall('windows.search', { query: 'myproject' })
+
+// Launch and tile
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+
+// Read the screen
 await daemonCall('ocr.scan')
 const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
 ```
 
+Or from the CLI:
+
+```sh
+lattices search myproject           # Find windows by content
+lattices search myproject --deep    # Include terminal tab/process data
+lattices search myproject --all     # Same as --deep (all search sources)
+lattices place myproject left       # Search + focus + tile in one step
+```
+
+Claude Code skills, MCP servers, or your own scripts can drive your
+desktop the same way you do.
+
 ## CLI
 
 ```
-lattices                    Create or reattach to session
+lattices                    Show workspace status and common commands
+lattices start              Create or reattach to current project session
+lattices tmux               Alias for lattices start
 lattices init               Generate .lattices.json
 lattices ls                 List active sessions
 lattices kill [name]        Kill a session
+lattices search <query>     Search windows by title, app, session, OCR
+lattices search <q> --deep  Deep search: index + terminal inspection
+lattices search <q> --all   Same as --deep (all search sources)
+lattices place <query> [pos]  Deep search + focus + tile
+lattices focus <session>    Raise a session's window
 lattices tile <position>    Tile frontmost window
 lattices group [id]         Launch or attach a tab group
 lattices tab <group> [tab]  Switch tab within a group
-lattices ocr                View current OCR snapshot
-lattices ocr search <query> Search OCR history
+lattices scan               View current screen text
+lattices scan search <q>    Search indexed text
+lattices scan deep          Trigger Vision OCR now
 lattices app                Launch the menu bar app
 lattices help               Show help
 ```
 
 ## Requirements
 
-- macOS 13.0+
+- macOS 26.0+
 - Node.js 18+
 
 ### Optional
 
 - tmux for persistent terminal sessions (`brew install tmux`)
-- Swift 5.9+ to build the menu bar app from source
+- Swift 6.2 / Xcode 26+ to build the menu bar app from source
 
 ## Docs
 
-Full documentation at [lattices.dev/docs](https://lattices.dev/docs/overview).
+Full documentation at [lattices.dev/docs](https://lattices.dev/docs/overview), including:
+
+- [API reference](https://lattices.dev/docs/api) — all 35 daemon methods
+- [Layers](https://lattices.dev/docs/layers) — workspace layers and tab groups
+- [Voice commands](https://lattices.dev/docs/voice) — Vox integration
 
 ## License
 

package/apps/mac/Info.plist

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleIdentifier</key>
+    <string>dev.lattices.app</string>
+    <key>CFBundleName</key>
+    <string>Lattices</string>
+    <key>CFBundleDisplayName</key>
+    <string>Lattices</string>
+    <key>CFBundleExecutable</key>
+    <string>Lattices</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleURLTypes</key>
+    <array>
+        <dict>
+            <key>CFBundleURLName</key>
+            <string>dev.lattices.app</string>
+            <key>CFBundleURLSchemes</key>
+            <array>
+                <string>lattices</string>
+            </array>
+        </dict>
+    </array>
+    <key>CFBundleVersion</key>
+    <string>0.6.1</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.6.1</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>13.0</string>
+    <key>LSUIElement</key>
+    <true/>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Lattices uses the microphone for Hudson Voice dictation and voice commands.</string>
+    <key>NSSupportsAutomaticTermination</key>
+    <true/>
+</dict>
+</plist>

package/apps/mac/Lattices.app/Contents/Info.plist

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleIdentifier</key>
+    <string>dev.lattices.app</string>
+    <key>CFBundleName</key>
+    <string>Lattices</string>
+    <key>CFBundleDisplayName</key>
+    <string>Lattices</string>
+    <key>CFBundleExecutable</key>
+    <string>Lattices</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleURLTypes</key>
+    <array>
+        <dict>
+            <key>CFBundleURLName</key>
+            <string>dev.lattices.app</string>
+            <key>CFBundleURLSchemes</key>
+            <array>
+                <string>lattices</string>
+            </array>
+        </dict>
+    </array>
+    <key>CFBundleVersion</key>
+    <string>0.6.1</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.6.1</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>13.0</string>
+    <key>LSUIElement</key>
+    <true/>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Lattices uses the microphone for Hudson Voice dictation and voice commands.</string>
+    <key>NSSupportsAutomaticTermination</key>
+    <true/>
+</dict>
+</plist>

package/apps/mac/Lattices.app/Contents/Resources/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) |