@arach/lattices 0.2.0 → 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,37 +1,98 @@
 <picture>
-  <img alt="lattices" src="site/public/og.png" />
+  <img alt="lattices" src="apps/site/public/og.png" />
 </picture>
 
 # lattices
 
-Declarative tmux sessions for developers.
+The agentic workspace manager for macOS.
 
-One command to create a named tmux session with your tools running. Auto-detects your stack, fully configurable with `.lattices.json`, and a native macOS menu bar app.
+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
 ```
 
+Also published as `@lattices/cli` for existing installs. The CLI and app work
+independently — use either or both.
+
+### Build from source
+
+```sh
+git clone https://github.com/arach/lattices.git
+cd lattices
+
+# Install CLI dependencies
+npm install
+
+# Build/install/relaunch the dev app at the stable permission target
+./scripts/run.sh
+```
+
+To build a signed, notarized DMG for distribution:
+
+```sh
+# 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
+```
+
+See [Release](docs/release.md) for the CI and local maintainer workflows.
+
 ## Quick start
 
 ```sh
-cd my-project
+# Show workspace status for the current directory
 lattices
+
+# Launch the menu bar app
+lattices app
+
+# Start or reattach a tmux session
+lattices start
+
+# Open the command palette from anywhere
+# Cmd+Shift+M
 ```
 
-That's it. lattices creates a tmux session named after your project with Claude Code on the left and your dev server on the right. It detects your package manager and dev command automatically.
+## Persistent terminal sessions
 
-## How it works
+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.
 
-1. **Run `lattices`** in any project directory
-2. A named tmux session is created with configured panes
-3. Commands start running in each pane immediately
-4. Detach with `Ctrl+b d`, reattach by running `lattices` again
-5. Sessions persist in the background until you kill them
+```sh
+cd my-project && lattices start
+```
+
+No config? It opens a shell in the project and, when it can, starts your
+detected dev command in a second pane.
 
-## Configuration
+### Configuration
 
 Drop a `.lattices.json` in your project root:
 
@@ -39,118 +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" }
   ]
 }
 ```
 
-### Pane options
-
-| Field  | Description                              |
-|--------|------------------------------------------|
-| `name` | Label for the pane (for your reference)  |
-| `cmd`  | Command to run in the pane               |
-| `size` | Width % for the first pane (default: 60) |
-
-### Session options
-
-| Field     | Description                                                                 |
-|-----------|-----------------------------------------------------------------------------|
-| `ensure`  | Auto-restart exited commands on reattach                                    |
-| `prefill` | Type exited commands into panes on reattach without running (you hit Enter) |
-
 ### Layouts
 
 ```
-2 panes — side-by-side          3+ panes — main-vertical
+2 panes              3+ panes
 
-┌──────────┬─────────┐         ┌──────────┬─────────┐
-│  claude   │ server  │         │  claude   │ server  │
-│  (60%)   │ (40%)   │         │  (60%)   ├─────────┤
-└──────────┴─────────┘         │          │ tests   │
-                                └──────────┴─────────┘
+┌──────────┬───────┐ ┌──────────┬───────┐
+│  shell   │server │ │  shell   │server │
+│  (60%)   │(40%)  │ │  (60%)   ├───────┤
+└──────────┴───────┘ │          │tests  │
+                     └──────────┴───────┘
 ```
 
-## Auto-detection
+### Workspace layers
 
-Without a config file, lattices reads your `package.json` and picks the right command:
+Group projects into switchable contexts. `Cmd+Option+1` tiles your
+frontend and API side by side. `Cmd+Option+2` for the mobile stack.
+Sessions stay alive across switches.
 
-- Checks `scripts.dev`, `scripts.start`, `scripts.serve`, `scripts.watch`
-- Detects package manager from lock files (pnpm, bun, yarn, npm)
-- Falls back to a shell if no dev command is found
+### Tab groups
 
-## Menu bar app
+Bundle related repos as tabs in one session. Each tab gets its own
+pane layout from its `.lattices.json`.
 
-A macOS companion app for managing sessions without touching the terminal.
+```sh
+lattices group vox         # Launch iOS, macOS, Web, API as tabs
+lattices tab vox iOS       # Switch to the iOS tab
+```
+
+## Window tiling and awareness
+
+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 app          # Launch (builds from source or downloads binary)
-lattices app build    # Force rebuild from source
-lattices app quit     # Stop the menu bar app
+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
 ```
 
-Features:
-- See all projects and their session status at a glance
-- Launch, attach, or detach sessions with a click
-- **Command palette** (`Cmd+Shift+M`): Raycast-style launcher for all actions — fuzzy search, keyboard navigation, instant access to projects, window tiling, and settings
-- Auto-scans your project directories
-- Built with SwiftUI, runs natively on macOS
+## Voice commands (beta)
 
-The app tries to compile from source first (requires Xcode CLI tools), falling back to a pre-built arm64 binary from GitHub releases.
+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.
 
-## Tab groups
+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.
 
-Bundle related projects as tabs within a single terminal window.
-Configure in `~/.lattices/workspace.json`:
+## A programmable desktop
 
-```json
-{
-  "name": "my-setup",
-  "groups": [
-    {
-      "id": "talkie",
-      "label": "Talkie",
-      "tabs": [
-        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
-        { "path": "/Users/you/dev/talkie-web", "label": "Website" },
-        { "path": "/Users/you/dev/talkie-api", "label": "API" }
-      ]
-    }
-  ]
-}
+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' })
 ```
 
-Each tab gets its own tmux window with pane layout from its `.lattices.json`.
+Or from the CLI:
 
 ```sh
-lattices groups            # List groups with status
-lattices group talkie      # Launch or attach
-lattices tab talkie iOS    # Switch to a tab
+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
 ```
 
-Groups can also be referenced in [workspace layers](https://lattices.dev/docs/layers) to tile a whole group into a screen position.
+Claude Code skills, MCP servers, or your own scripts can drive your
+desktop the same way you do.
 
-## CLI reference
+## CLI
 
 ```
-lattices                    Create or reattach to a session for the current project
-lattices init               Generate a .lattices.json config
-lattices ls                 List active tmux sessions
-lattices kill [name]        Kill a session (defaults to current project)
-lattices group [id]         List tab groups or launch/attach a group
-lattices groups             List all tab groups with status
-lattices tab <group> [tab]  Switch tab within a group (by label or index)
-lattices app                Launch the menu bar companion app
+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 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
 
-- **tmux** — `brew install tmux`
-- **Node.js** 18+
-- **macOS** (the CLI is macOS-only, the menu bar app requires arm64)
+- macOS 26.0+
+- Node.js 18+
+
+### Optional
+
+- tmux for persistent terminal sessions (`brew install tmux`)
+- 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), 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) |