@lattices/cli 0.3.0

package/docs/layers.md

@@ -0,0 +1,410 @@
+---
+title: Workspace Layers & Tab Groups
+description: Group projects into switchable layers and tabbed groups
+order: 4
+---
+
+Two ways to organize related projects in `~/.lattices/workspace.json`:
+
+- **Layers** — switchable contexts that focus and tile windows
+- **Tab groups** — related projects as tabs within a single terminal window
+
+Both features are configured in the same workspace config and
+work together.
+
+## Tab Groups
+
+Tab groups let you bundle related projects as tabs within a single
+terminal session (requires tmux). This is useful when you have a family
+of projects — like an iOS app, macOS app, website, and API — that
+you think of as one logical unit.
+
+### Configuration
+
+Add `groups` to `~/.lattices/workspace.json`:
+
+```json
+{
+  "name": "my-setup",
+  "groups": [
+    {
+      "id": "talkie",
+      "label": "Talkie",
+      "tabs": [
+        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
+        { "path": "/Users/you/dev/talkie-macos", "label": "macOS" },
+        { "path": "/Users/you/dev/talkie-web", "label": "Website" },
+        { "path": "/Users/you/dev/talkie-api", "label": "API" }
+      ]
+    }
+  ]
+}
+```
+
+Each tab's pane layout comes from its own `.lattices.json` — no changes
+to per-project configs.
+
+### How it works
+
+- Session name follows the pattern `lattices-group-<id>` (e.g. `lattices-group-talkie`)
+- 1 group = 1 tmux session. Each tab is a tmux window, and each window
+  gets its own panes from that project's `.lattices.json`
+- You can still launch projects independently: `cd talkie-ios && lattices`
+  creates its own standalone session as before
+
+### Tab group fields
+
+| Field          | Type     | Description                          |
+|----------------|----------|--------------------------------------|
+| `id`           | string   | Unique identifier for the group      |
+| `label`        | string   | Display name shown in the UI         |
+| `tabs`         | array    | List of tab definitions              |
+| `tabs[].path`  | string   | Absolute path to project directory   |
+| `tabs[].label` | string?  | Tab name (defaults to directory name) |
+
+### CLI commands
+
+```bash
+lattices groups             # List all groups with status
+lattices group <id>         # Launch or attach to a group
+lattices tab <group> [tab]  # Switch tab by label or index
+```
+
+Examples:
+
+```bash
+lattices group talkie       # Launch all Talkie tabs
+lattices tab talkie iOS     # Switch to the iOS tab
+lattices tab talkie 0       # Switch to first tab (by index)
+```
+
+### Menu bar app
+
+Tab groups appear above the project list in the menu bar panel.
+Each group row shows:
+
+- Status indicator (running/stopped)
+- Tab count badge
+- Expand/collapse to see individual tabs
+- Launch/Attach and Kill buttons
+- Per-tab "Go" buttons to switch and focus a specific tab
+
+The command palette also includes group commands:
+
+| Command                    | Description                            |
+|----------------------------|----------------------------------------|
+| Launch *group*             | Start the group session                |
+| Attach *group*             | Focus the running group session        |
+| *Group*: *Tab*             | Switch to a specific tab in a group    |
+| Kill *group* Group         | Terminate the group session            |
+
+## Layers
+
+Layers let you group projects into switchable contexts. Define two or
+three layers and switch between them. The target layer's windows come
+to the front and tile into position; the previous layer's windows fall
+behind.
+
+All tmux sessions stay alive across switches. Nothing is detached or
+killed. Layers only control which windows are focused.
+
+### Configuration
+
+Add `layers` to `~/.lattices/workspace.json`:
+
+```json
+{
+  "name": "my-setup",
+  "layers": [
+    {
+      "id": "web",
+      "label": "Web",
+      "projects": [
+        { "path": "/Users/you/dev/frontend", "tile": "left" },
+        { "path": "/Users/you/dev/api", "tile": "right" }
+      ]
+    },
+    {
+      "id": "mobile",
+      "label": "Mobile",
+      "projects": [
+        { "path": "/Users/you/dev/ios-app", "tile": "left" },
+        { "path": "/Users/you/dev/backend", "tile": "right" }
+      ]
+    }
+  ]
+}
+```
+
+### App windows in layers
+
+Layers aren't limited to terminal sessions. You can include any
+application window by using the `app`, `title`, `url`, and `launch`
+fields instead of `path`:
+
+```json
+{
+  "name": "hudson",
+  "layers": [
+    {
+      "id": "main",
+      "label": "Main",
+      "projects": [
+        { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
+        { "app": "Talkie", "tile": "top-right", "launch": "open -a Talkie" },
+        { "path": "/Users/you/dev/frontend", "tile": "bottom-right" }
+      ]
+    },
+    {
+      "id": "docs",
+      "label": "Docs",
+      "projects": [
+        { "app": "Google Chrome", "url": "https://docs.example.com", "tile": "left" },
+        { "app": "Notes", "title": "Sprint Notes", "tile": "right" }
+      ]
+    }
+  ]
+}
+```
+
+When switching to a layer, lattices matches windows by `app` name and
+optionally filters by `title` substring or `url` prefix. If `launch`
+is provided and no matching window is found, the command is executed
+to open the app.
+
+### Using groups in layers
+
+Layer projects can reference a tab group instead of a single path.
+This lets you tile a whole group into a screen position:
+
+```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" }
+      ]
+    }
+  ],
+  "layers": [
+    {
+      "id": "main",
+      "label": "Main",
+      "projects": [
+        { "group": "talkie", "tile": "top-left" },
+        { "path": "/Users/you/dev/design-system", "tile": "right" }
+      ]
+    }
+  ]
+}
+```
+
+When switching to this layer, lattices launches (or focuses) the
+"talkie" group session and tiles it to the top-left quarter, alongside
+the design-system project on the right.
+
+### Layer fields
+
+| Field             | Type     | Description                              |
+|-------------------|----------|------------------------------------------|
+| `name`            | string   | Workspace name (for your reference)      |
+| `layers`          | array    | List of layer definitions                |
+| `layers[].id`     | string   | Unique identifier (e.g. `"web"`)         |
+| `layers[].label`  | string   | Display name shown in the UI             |
+| `layers[].projects` | array  | Projects in this layer                   |
+| `projects[].path` | string?  | Absolute path to project directory       |
+| `projects[].group`| string?  | Group ID (alternative to `path`)         |
+| `projects[].app`  | string?  | Application name (for non-terminal windows) |
+| `projects[].title`| string?  | Window title substring to match          |
+| `projects[].url`  | string?  | URL prefix to match (browser windows)    |
+| `projects[].launch`| string? | Shell command to launch the app if not found |
+| `projects[].tile` | string?  | Tile position (optional, see below)      |
+
+Each project entry must have either `path`, `group`, or `app` — pick one.
+
+### Tile values
+
+Any tile position from the [config reference](/docs/config#tile-positions)
+works: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
+`bottom-left`, `bottom-right`, `left-third`, `center-third`,
+`right-third`, `maximize`, `center`.
+
+### Switching layers
+
+Four ways to switch:
+
+| Method               | How                                      |
+|----------------------|------------------------------------------|
+| **Hotkey**           | Cmd+Option+1, Cmd+Option+2, Cmd+Option+3... |
+| **Layer bar**        | Click a layer pill in the menu bar panel |
+| **Command palette**  | Search "Switch to Layer" in Cmd+Shift+M  |
+| **CLI**              | `lattices layer <name\|index>`           |
+
+When you switch to a layer:
+
+1. Each project's window is **raised and focused**
+2. App windows are matched by `app` / `title` / `url`
+3. If a project isn't running yet, it gets **launched** automatically
+4. Windows with a `tile` value are **tiled** to that position
+5. The previous layer's windows stay open behind the new ones
+
+The app remembers which layer was last active across restarts.
+
+### Named layer switching
+
+You can switch layers by name from the CLI:
+
+```bash
+lattices layer hudson     # Switch to the layer named "hudson"
+lattices layer 0          # Switch to the first layer (by index)
+```
+
+This is useful for scripting — you don't need to know the index,
+just the layer's `id` or `label`.
+
+### Window tagging
+
+You can manually assign any window to a layer, even if it's not
+declared in `workspace.json`. This is useful for ad-hoc windows
+that you want to move with a layer:
+
+```bash
+lattices window assign <wid> <layer>   # Tag a window to a layer
+lattices window map                    # Show all window→layer assignments
+```
+
+Tagged windows behave like declared ones — they're raised and tiled
+when their layer activates. Remove a tag by reassigning or with:
+
+```bash
+# Via the agent API
+await daemonCall('window.removeLayer', { wid: 1234 })
+```
+
+### Layer bezel
+
+When you switch layers via hotkey, a translucent HUD pill appears
+briefly at the top of the screen showing the new layer's name.
+This provides instant visual feedback without interrupting your flow.
+
+### Programmatic switching
+
+Agents and scripts can switch layers via the agent API:
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+// List available layers
+const { layers, active } = await daemonCall('layers.list')
+console.log(`Active: ${layers[active].label}`)
+
+// Switch to a layer by index
+await daemonCall('layer.switch', { index: 0 })
+
+// Switch to a layer by name
+await daemonCall('layer.switch', { name: 'hudson' })
+```
+
+The `layer.switch` call focuses and tiles all windows in the target
+layer, just like the hotkey or command palette. A `layer.switched`
+event is broadcast to all connected clients.
+
+More methods in the [Agent API reference](/docs/api).
+
+### Layer bar
+
+When a workspace config is loaded, a layer bar appears between the
+header and search field in the menu bar panel:
+
+```
+ lattices  2 sessions              [↔] [⟳]
+┌────────────────────────────────────────┐
+│  ● Web          ○ Mobile               │
+│  ⌥1             ⌥2                     │
+└────────────────────────────────────────┘
+ Search projects...
+```
+
+- Active layer: filled green dot
+- Inactive layers: dim outline dot
+- Hotkey hints shown below each label
+
+## Layout examples
+
+### Single project
+
+```json
+{
+  "projects": [
+    { "path": "/Users/you/dev/talkie" }
+  ]
+}
+```
+
+No `tile` — just focuses the window wherever it is.
+
+### Two-project split
+
+```json
+{
+  "projects": [
+    { "path": "/Users/you/dev/app", "tile": "left" },
+    { "path": "/Users/you/dev/api", "tile": "right" }
+  ]
+}
+```
+
+### Mixed: apps + terminals
+
+```json
+{
+  "projects": [
+    { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
+    { "path": "/Users/you/dev/api", "tile": "right" }
+  ]
+}
+```
+
+### Group + project
+
+```json
+{
+  "projects": [
+    { "group": "talkie", "tile": "left" },
+    { "path": "/Users/you/dev/api", "tile": "right" }
+  ]
+}
+```
+
+### Four quadrants
+
+```json
+{
+  "projects": [
+    { "path": "/Users/you/dev/frontend", "tile": "top-left" },
+    { "path": "/Users/you/dev/backend", "tile": "top-right" },
+    { "path": "/Users/you/dev/mobile", "tile": "bottom-left" },
+    { "path": "/Users/you/dev/infra", "tile": "bottom-right" }
+  ]
+}
+```
+
+## Tips
+
+- Projects don't need a `.lattices.json` config to be in a layer — any
+  directory path works. If the project has a config, lattices uses it; if
+  not, it opens a plain terminal in that directory.
+- App windows don't need any config at all — just specify `app` and
+  optionally `title` or `url` to match the right window.
+- You can have up to 9 layers (Cmd+Option+1 through Cmd+Option+9).
+- Edit `workspace.json` by hand — the app re-reads it on launch. Use
+  the Refresh Projects button or restart the app to pick up changes.
+- The `tile` field is optional. Omit it if you just want the window
+  focused without repositioning.
+- Tab groups and standalone projects can coexist in the same workspace.
+  Use groups for related project families, standalone paths for
+  individual projects.

package/docs/ocr.md

@@ -0,0 +1,185 @@
+---
+title: Screen OCR & Search
+description: Vision-powered screen reading with full-text search for agents
+order: 3.5
+---
+
+The menu bar app reads text from visible windows using Apple's Vision
+framework and stores results in a local SQLite database with FTS5
+full-text search. Agents can use this to "see" what's on screen.
+
+## Enabling OCR
+
+Open **Settings** (via command palette or gear icon) and toggle
+**Search & OCR** on. OCR is disabled by default.
+
+### Accuracy modes
+
+| Mode | Description |
+|------|-------------|
+| **Accurate** (default) | Higher quality recognition, slower processing |
+| **Fast** | Lower latency, reduced accuracy |
+
+Both modes use `VNRecognizeTextRequest` with language correction enabled.
+
+## How scanning works
+
+The app runs two scan schedules:
+
+| Schedule | Interval | Window limit | Purpose |
+|----------|----------|-------------|---------|
+| **Quick scan** | 60 seconds | Top 5 windows | Keep recent content fresh |
+| **Deep scan** | 2 hours | Up to 15 windows | Catch less-active windows |
+
+Both intervals and limits are configurable in Settings.
+
+### Change detection
+
+Before running OCR on a window, the app captures the window image and
+computes a SHA-256 hash of the pixel data. If the hash matches the
+previous scan, the cached result is reused. No Vision processing needed.
+
+This keeps CPU usage low when windows haven't changed. A 100ms throttle
+between windows further limits processing bursts.
+
+## Browsing results
+
+The **Recent Captures** section in Settings shows OCR results grouped by
+app. Each entry displays the window title, recognized text preview, and
+timestamp.
+
+## Searching
+
+### From the command palette
+
+The OmniSearch bar (Cmd+Shift+M) searches OCR content alongside windows,
+projects, and sessions. Matches show as "Screen Text" results with
+contextual snippets.
+
+### From the CLI
+
+```bash
+# View current OCR snapshot
+lattices ocr
+
+# Search OCR history
+lattices ocr search "error OR failed"
+
+# Trigger an immediate deep scan
+lattices ocr scan
+
+# View OCR history for a specific window ID
+lattices ocr history 12345
+```
+
+### From the agent API
+
+Agents can query OCR data through four API methods:
+
+| Method | Description |
+|--------|-------------|
+| `ocr.snapshot` | Current OCR results for all visible windows |
+| `ocr.search` | Full-text search across history (FTS5 syntax) |
+| `ocr.history` | Timeline of OCR results for a specific window |
+| `ocr.scan` | Trigger an immediate deep scan |
+
+#### `ocr.snapshot`
+
+Returns the latest OCR results for all on-screen windows.
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+const snapshot = await daemonCall('ocr.snapshot')
+// [{ wid, app, title, frame, fullText, blocks, timestamp }, ...]
+```
+
+Each result includes:
+- `wid` — window ID
+- `app` — application name
+- `title` — window title
+- `frame` — `{ x, y, w, h }` screen position
+- `fullText` — all recognized text concatenated
+- `blocks` — individual text blocks with `{ text, confidence, x, y, w, h }`
+- `timestamp` — Unix timestamp of the scan
+
+#### `ocr.search`
+
+Full-text search across OCR history using FTS5 query syntax.
+
+```js
+const results = await daemonCall('ocr.search', {
+  query: 'error OR failed',  // FTS5 query (required)
+  app: 'Terminal',            // filter by app name (optional)
+  limit: 50,                  // max results (optional, default 50)
+  live: false                 // search in-memory snapshot instead of history (optional)
+})
+// [{ id, wid, app, title, frame, fullText, snippet, timestamp }, ...]
+```
+
+The `snippet` field contains FTS5-highlighted text with `«` and `»`
+delimiters around matched terms.
+
+#### `ocr.history`
+
+Get the OCR content timeline for a specific window.
+
+```js
+const history = await daemonCall('ocr.history', {
+  wid: 12345,  // window ID (required)
+  limit: 50    // max results (optional, default 50)
+})
+```
+
+#### `ocr.scan`
+
+Trigger an immediate deep scan (all visible windows up to the deep limit).
+
+```js
+await daemonCall('ocr.scan')
+// { ok: true }
+```
+
+## Storage
+
+OCR data is stored in `~/.lattices/ocr.db`, a SQLite database in WAL
+(Write-Ahead Logging) mode for safe concurrent reads.
+
+The schema uses two tables:
+- `ocr_entry` — stores window ID, app, title, frame, full text, and timestamp
+- `ocr_fts` — FTS5 virtual table indexing `full_text`, `app`, and `title`
+
+Triggers keep the FTS index in sync with inserts, updates, and deletes.
+
+Entries older than 3 days are automatically deleted.
+
+## Agent usage
+
+A typical agent workflow: trigger a scan, then search for relevant content.
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+// Trigger a fresh scan
+await daemonCall('ocr.scan')
+
+// Search for compilation errors across all windows
+const errors = await daemonCall('ocr.search', { query: 'error OR warning' })
+
+for (const result of errors) {
+  console.log(`[${result.app}] ${result.title}`)
+  console.log(result.snippet)
+}
+
+// Read everything currently visible
+const snapshot = await daemonCall('ocr.snapshot')
+for (const win of snapshot) {
+  console.log(`${win.app}: ${win.fullText.slice(0, 200)}`)
+}
+```
+
+## Requirements
+
+- **Screen Recording** permission — required to capture window images
+- Grant via System Settings > Privacy & Security > Screen Recording
+- Add the lattices menu bar app to the allowed list

package/docs/overview.md

@@ -0,0 +1,94 @@
+---
+title: Overview
+description: What lattices is and who it's for
+order: 0
+---
+
+lattices is an agentic window manager for macOS. It provides a programmable
+workspace, smart layout management, and managed tmux sessions — all
+controllable from the CLI or a 35+-method agent API.
+
+## The problem
+
+I kept losing track of windows. Terminal here, dev server there, browser
+somewhere on the second monitor, three other projects buried under it all.
+Every morning I'd rebuild the same layout. Half my context-switching was
+just hunting for the right window.
+
+AI agents have it worse. They're stuck inside a single shell with no way
+to see what's on screen, arrange windows, or jump between projects.
+
+## The solution
+
+lattices addresses both sides with three layers:
+
+### Programmable workspace
+
+The CLI and agent API expose everything: query what's on screen, search
+window text, tile layouts, manage sessions. Claude Code skills, MCP servers,
+or your own scripts can drive your desktop the same way you do. Your
+workspace becomes infrastructure you can observe and control programmatically.
+
+### Smart layout manager
+
+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.
+
+### Managed tmux sessions
+
+We make tmux easy. Declare your dev environment in a `.lattices.json`:
+which panes, which commands, what layout. lattices builds it, runs it,
+and keeps it alive. Use your own terminal — sessions survive reboots
+and you can reattach anytime.
+
+## What's included
+
+| Component | Description |
+|-----------|-------------|
+| **CLI** | The `lattices` command. Tile windows, manage sessions, scan screen text, control the workspace from your terminal |
+| **Menu bar app** | Native macOS companion. Command palette, window tiling, project discovery, screen text indexing |
+| **Agent API** | WebSocket server on `ws://127.0.0.1:9399`. 35+ methods, 5 real-time events |
+| **Screen scanner** | Reads text from visible windows using Accessibility API (60s) and Apple Vision OCR (2h), indexes with FTS5 |
+| **Node.js client** | Zero-dependency `daemonCall()` helper for scripting |
+
+## Example
+
+```bash
+cd ~/my-project && lattices
+```
+
+Agents get the same control programmatically:
+
+```js
+import { daemonCall } from '@lattices/cli'
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+```
+
+## Who it's for
+
+- Developers who juggle multiple projects and want faster window management
+- People building AI agents that need to observe and control the desktop
+- Power users who work across multiple macOS Spaces
+- Anyone who wants persistent, auto-configured terminal sessions
+
+## Requirements
+
+- macOS 13.0+
+- Node.js 18+
+
+### Dev dependencies
+
+- Swift 5.9+ — only to build the menu bar app from source
+- tmux — needed for persistent terminal sessions (`brew install tmux`)
+
+## Next steps
+
+- [Quickstart](/docs/quickstart): install and run your first session in 2 minutes
+- [Configuration](/docs/config): `.lattices.json` format and CLI commands
+- [Screen scanning](/docs/ocr): AX text extraction, Vision OCR, and full-text search
+- [Concepts](/docs/concepts): architecture, glossary, and how it all works
+- [Agent API](/docs/api): RPC method reference for agents and scripts