@arach/lattices 0.1.0 → 0.2.0

package/docs/app.md

@@ -4,10 +4,8 @@ description: Command palette, window tiling, and session management
 order: 3
 ---
 
-# Menu Bar App
-
-The lattices menu bar app is a native macOS companion that lives in your
-menu bar and gives you quick access to all your lattices sessions.
+The lattices menu bar app sits in your menu bar and controls your
+workspace from there.
 
 ## Installation
 
@@ -94,15 +92,11 @@ 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, which creates
-  or reattaches to the session
-- **Sync** — runs `lattices sync` to reconcile panes to the config
-- **Restart** — runs `lattices restart <pane>` to kill and re-run a
-  specific pane's process
-- **Detach** — calls `tmux detach-client` directly
-- **Kill** — calls `tmux kill-session` directly
+The app calls the lattices CLI for session operations. Launch runs
+`lattices` 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.
 
 ## Window tiling
 
@@ -125,6 +119,9 @@ frontmost window.
 | Bottom Left  | Bottom-left quarter             |
 | Bottom Right | Bottom-right quarter            |
 | Maximize     | Full visible screen             |
+| Left Third   | Left third                      |
+| Center Third | Center third                    |
+| Right Third  | Right third                     |
 | Center       | 70% width, 80% height, centered |
 
 ## Space navigation
@@ -144,7 +141,7 @@ When a window is found and focused, the app flashes a green border
 highlight around it for ~1 second so you can spot it immediately.
 
 Grant Screen Recording and Accessibility permissions in System
-Settings > Privacy & Security for the best experience.
+Settings > Privacy & Security for all three paths to work.
 
 ## Settings
 
@@ -200,6 +197,57 @@ links to open the full `config.md` and `concepts.md` docs.
 can't be targeted. "frontmost" means tiling applies to whatever
 window is in front.
 
+## Screen OCR
+
+> See [Screen OCR](/docs/ocr) for full details on configuration, scanning,
+> search, and agent usage.
+
+The 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.
+
+### How it works
+
+1. Every 60 seconds, the app captures the top visible windows as images
+2. A SHA256 hash detects whether the window content has changed
+3. Changed windows are processed through `VNRecognizeTextRequest` (fast mode)
+4. Results are stored in `~/.lattices/ocr.db` with full-text indexing
+5. Entries older than 3 days are automatically purged
+
+### Desktop Inventory integration
+
+The Desktop Inventory view (Hyper+4) 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:
+
+| 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 scan (bypasses timer)     |
+
+```js
+import { daemonCall } from '@arach/lattices/daemon-client'
+
+// Find windows showing error messages
+const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
+
+// Read what's currently on screen
+const snapshot = await daemonCall('ocr.snapshot')
+```
+
+More in the [Daemon API reference](/docs/api#ocrsnapshot).
+
+### Requirements
+
+- **Screen Recording** permission — required to capture window images
+- Granted via System Settings > Privacy & Security > Screen Recording
+
 ## Daemon
 
 The menu bar app runs a WebSocket daemon on `ws://127.0.0.1:9399`.
@@ -215,7 +263,7 @@ lattices daemon status
 Or programmatically:
 
 ```js
-import { isDaemonRunning, daemonCall } from 'lattices/daemon-client'
+import { isDaemonRunning, daemonCall } from '@arach/lattices/daemon-client'
 
 if (await isDaemonRunning()) {
   const status = await daemonCall('daemon.status')
@@ -225,23 +273,22 @@ if (await isDaemonRunning()) {
 
 ### What it provides
 
-- **20 RPC methods** — read windows, sessions, projects, spaces, layers;
-  launch/kill/sync sessions; tile/focus/move windows; switch layers;
-  manage tab groups
-- **3 real-time events** — `windows.changed`, `tmux.changed`,
-  `layer.switched` — broadcast to all connected clients
-- **Window tracking** — the daemon monitors the desktop window list
-  and correlates windows to lattices sessions via title tags
-- **Space awareness** — knows which macOS Space each window is on
+- 30 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`,
+  `layer.switched`, `ocr.scanComplete`) broadcast to all connected clients.
+- Window tracking that monitors the desktop window list and correlates
+  windows to lattices sessions via title tags.
+- Space awareness, so it knows which macOS Space each window is on.
 
 ### Security
 
-The daemon binds to **localhost only** (`127.0.0.1:9399`). It is not
-accessible from the network. There is no authentication — any process
-on the same machine can connect. This is intentional: the daemon is
-designed for local automation, not remote access.
+The daemon 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.
 
-See the [Daemon API reference](/docs/api) for the full method list.
+Full method list in the [Daemon API reference](/docs/api).
 
 ## Diagnostics
 

package/docs/concepts.md

@@ -1,124 +1,51 @@
 ---
 title: Concepts
 description: Core ideas, glossary, and architecture of lattices
-order: 1
+order: 6
 ---
 
-# Concepts
-
-## What is lattices?
-
-lattices is a developer workspace launcher. It creates pre-configured
-terminal layouts for your projects using tmux, so you can go from
-"I want to work on X" to a full development environment in one click.
-
-It has two parts:
-
-1. **CLI** (`lattices`) — creates and manages tmux sessions from the terminal
-2. **Menu bar app** — a native macOS companion for launching, tiling,
-   and navigating sessions with a command palette
-
 ## Glossary
 
-### Daemon
-The lattices daemon is a WebSocket server (`ws://127.0.0.1:9399`) that
-runs inside the menu bar app. It exposes 20 RPC methods and 3 real-time
-events, giving scripts and AI agents full programmatic control over
-sessions, windows, layers, and projects. See the
-[API reference](/docs/api).
-
-### Agent
-Any program that calls the daemon API to control the workspace
-autonomously — an AI coding agent, a shell script, a CI pipeline,
-or a custom tool. Agents can discover projects, launch sessions, tile
-windows, switch layers, and react to real-time events without human
-interaction.
-
-### Session
-A tmux session is a persistent workspace that lives in the background.
-It survives terminal crashes, disconnects, and even closing your laptop.
-Think of it as a virtual desktop for a single project.
-
-### Pane
-A pane is a single terminal view inside a session. A typical lattices
-setup has two panes side by side — one running Claude Code and one
-running your dev server. You can have up to four or more.
-
-### Attach / Detach
-Attaching connects your terminal window to an existing session.
-Detaching disconnects your terminal but keeps the session alive.
-Your dev server keeps running, Claude keeps thinking — nothing is lost.
-
-### tmux
-tmux (terminal multiplexer) is the engine behind lattices. It manages
-sessions, panes, and layouts. lattices configures tmux for you so you
-don't need to learn tmux commands — but knowing a few shortcuts helps.
-
-### Multiplexer
-A program that lets you run multiple terminal sessions inside a single
-window and switch between them. tmux is the most popular one.
-
-### Sync / Reconcile
-Sync (`lattices sync`) brings a running session back in line with its
-declared config. It recreates missing panes, re-applies the layout,
-restores labels, and re-runs commands in idle panes. Useful when a pane
-was accidentally killed but you don't want to restart the whole session.
-
-### Ensure / Prefill
-Two modes for restoring exited commands when you reattach to a session:
-
-- **Ensure** — automatically re-runs the command (hands-free recovery)
-- **Prefill** — types the command into the pane but waits for you to
-  press Enter (manual confirmation)
-
-Set via `"ensure": true` or `"prefill": true` in `.lattices.json`.
-
-### Command Palette
-The menu bar app's primary interface, opened with **Cmd+Shift+M**.
-A searchable list of actions: launch/attach projects, tile windows,
-sync sessions, restart panes, open settings.
-
-### Window Tiling
-Both the CLI (`lattices tile`) and the menu bar app can snap terminal
-windows to preset screen positions (halves, quarters, maximize, center).
-Tiling uses AppleScript bounds and respects the menu bar and dock.
+| Term | Definition |
+|------|------------|
+| **Command Palette** | The menu bar app's primary interface (**Cmd+Shift+M**). Searchable list of actions: launch, tile, sync, restart, settings. |
+| **Window Tiling** | Snap terminal windows to preset screen positions (halves, quarters, thirds, maximize, center). Works from the CLI (`lattices tile`) or the command palette. |
+| **Daemon** | WebSocket server (`ws://127.0.0.1:9399`) inside the menu bar app. Exposes 30 RPC methods and 5 real-time events for programmatic control. See the [API reference](/docs/api). |
+| **Agent** | Any program that calls the daemon API autonomously — an AI coding agent, a shell script, a CI pipeline, or a custom tool. |
+| **Session** | A persistent tmux workspace that lives in the background. Survives terminal crashes, disconnects, and closing your laptop. One session per project. Requires tmux. |
+| **Pane** | A single terminal view inside a session. A typical setup has two panes side by side — Claude Code on the left, dev server on the right. Requires tmux. |
+| **Attach / Detach** | Attaching connects your terminal to an existing session. Detaching disconnects but keeps the session alive — your dev server keeps running, Claude keeps thinking. Requires tmux. |
+| **Sync / Reconcile** | `lattices sync` brings a running session back in line with its declared config — recreates missing panes, re-applies layout, restores labels, re-runs commands in idle panes. Requires tmux. |
+| **Ensure / Prefill** | Two modes for restoring exited commands on reattach. **Ensure** auto-reruns the command. **Prefill** types it but waits for you to press Enter. Set via `.lattices.json`. Requires tmux. |
+| **tmux** | Terminal multiplexer (optional). Provides persistent sessions, pane layouts, and command restoration. Install with `brew install tmux` if you want session management. |
 
 ## How it works
 
 1. You create a `.lattices.json` file in your project root (or run `lattices init`)
-2. lattices reads the config and creates a tmux session with your layout
-3. Each pane gets its command (claude, dev server, tests, etc.)
-4. The session persists in the background until you kill it
-5. You can attach/detach from any terminal at any time
-6. If `ensure` is enabled, exited commands auto-restart on reattach
+2. The menu bar app discovers the project and adds it to the command palette
+3. You can tile windows, switch layers, search via OCR, and use the daemon API
+4. With tmux installed, `lattices` also creates persistent terminal sessions:
+   - Each pane gets its command (claude, dev server, tests, etc.)
+   - The session persists in the background until you kill it
+   - You can attach/detach from any terminal at any time
+   - If `ensure` is enabled, exited commands auto-restart on reattach
 
 ## Architecture
 
-### Four-layer stack
-
-```
-┌─────────────────────────────┐
-│  AI Agents / Scripts        │  ← daemon API: 20 RPC methods, real-time events
-├─────────────────────────────┤
-│  Menu bar app (Swift/AppKit)│  ← GUI: command palette, tiling, project list
-├─────────────────────────────┤
-│  CLI (Node.js)              │  ← lattices, lattices sync, lattices restart ...
-├─────────────────────────────┤
-│  tmux                       │  ← session/pane lifecycle, layout, persistence
-└─────────────────────────────┘
-```
-
-- The **CLI** talks to tmux directly via `tmux` shell commands.
-- The **menu bar app** calls the CLI binary for session operations
-  (launch, sync, restart) and uses tmux directly for status checks
-  (has-session, list-panes). It also runs the **daemon** — a WebSocket
-  server on `ws://127.0.0.1:9399`.
-- **Agents and scripts** connect to the daemon over WebSocket and can
-  do everything the app and CLI can do: discover projects, launch
-  sessions, tile windows, switch layers, and subscribe to real-time
-  events.
-- All layers share the same session naming convention so they always
-  agree on which session belongs to which project.
+<img src="/architecture.svg" alt="lattices architecture diagram" style="margin: 2rem 0; max-width: 100%;" />
+
+- The menu bar app is the core. It provides the command palette,
+  window tiling, OCR, project discovery, and the daemon (a WebSocket
+  server on `ws://127.0.0.1:9399`). It works with or without tmux.
+- The CLI handles tiling, OCR queries, and (when tmux is installed)
+  session management via `tmux` shell commands.
+- Agents and scripts connect to the daemon over WebSocket. They can
+  do everything the app and CLI can do: discover projects, tile windows,
+  switch layers, read on-screen text, and subscribe to real-time events.
+- When tmux is installed, the app and CLI can also launch, sync, and
+  manage persistent terminal sessions. All layers share the same session
+  naming convention so they always agree on which session belongs to
+  which project.
 
 ### Session naming
 
@@ -135,7 +62,7 @@ Both the CLI (Node.js `crypto.createHash`) and the app (Swift
 
 ### Window discovery via title tags
 
-When lattices creates a session, it sets the tmux option:
+When lattices creates a tmux session, it sets the tmux option:
 
 ```
 set-titles-string "[lattices:<session-name>] #{pane_title}"
@@ -164,7 +91,7 @@ It uses private SkyLight framework APIs loaded at runtime via `dlopen`:
 This is the same approach used by [Loop](https://github.com/MrKai77/Loop)
 and other macOS window managers.
 
-### Ensure/prefill restoration
+### Ensure/prefill restoration (requires tmux)
 
 When you run `lattices` (no arguments) and a session already exists:
 
@@ -176,35 +103,17 @@ When you run `lattices` (no arguments) and a session already exists:
    - **prefill**: sends the command without Enter (manual restart)
 4. Then it attaches to the session as normal
 
-## Agentic architecture
-
-lattices is designed for programmatic control. The daemon API gives
-agents the same capabilities as a human using the menu bar app:
-
-- **Discover** — list projects, sessions, windows, and Spaces
-- **Launch** — start sessions for any scanned project
-- **Arrange** — tile windows to screen positions, move between Spaces
-- **Monitor** — subscribe to `windows.changed`, `tmux.changed`, and
-  `layer.switched` events for real-time workspace awareness
-- **Recover** — sync sessions back to their declared config, restart
-  failed panes
-
-An orchestrator agent can set up an entire multi-project workspace in
-a few calls:
+## Agent control
 
-```js
-import { daemonCall } from 'lattices/daemon-client'
-
-await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
-await daemonCall('session.launch', { path: '/Users/you/dev/api' })
-
-const sessions = await daemonCall('tmux.sessions')
-await daemonCall('window.tile', { session: sessions[0].name, position: 'left' })
-await daemonCall('window.tile', { session: sessions[1].name, position: 'right' })
-```
+The daemon API gives agents the same control as a human using the
+menu bar app. An agent can list projects and windows, launch sessions,
+tile windows to screen positions, subscribe to real-time events
+(`windows.changed`, `tmux.changed`, `layer.switched`), and sync
+sessions back to their declared config.
 
-See the [Daemon API reference](/docs/api) for the full method list,
-event shapes, and integration patterns.
+A typical orchestrator sets up a multi-project workspace in a few
+`daemonCall()` invocations. See the [Daemon API reference](/docs/api)
+for the full method list and code examples.
 
 ## Key shortcuts (inside tmux)
 

package/docs/config.md

@@ -4,8 +4,6 @@ description: CLI commands, .lattices.json format, and tile positions
 order: 2
 ---
 
-# Configuration
-
 ## .lattices.json
 
 Place a `.lattices.json` file in your project root to define your
@@ -128,7 +126,7 @@ Run `lattices init` in your project directory to generate a starter
 |----------------------------|--------------------------------------------------|
 | `lattices`                   | Create or attach to session for current project   |
 | `lattices init`              | Generate .lattices.json config for this project     |
-| `lattices ls`                | List active tmux sessions                         |
+| `lattices ls`                | List active sessions (requires tmux)              |
 | `lattices kill [name]`       | Kill a session (defaults to current project)      |
 | `lattices sync`              | Reconcile session to match declared config        |
 | `lattices restart [pane]`    | Restart a pane's process (by name or index)       |
@@ -156,14 +154,14 @@ output:
 lattices windows --json
 ```
 
-Returns a JSON array of window objects to stdout — useful for piping
+Returns a JSON array of window objects to stdout, useful for piping
 into `jq` or consuming from scripts.
 
 ### Daemon responses
 
 All daemon API calls return JSON natively. If you need structured data
-from lattices, the daemon is the best path — no flags needed, no stdout
-parsing. See the [API reference](/docs/api).
+from lattices, the daemon is easier than parsing stdout. See the
+[API reference](/docs/api).
 
 ### Exit codes
 
@@ -225,10 +223,13 @@ screen position. Available positions:
 | `bottom-left`  | Bottom-left quarter         |
 | `bottom-right` | Bottom-right quarter        |
 | `maximize`     | Full screen (visible area)  |
+| `left-third`   | Left third                  |
+| `center-third` | Center third                |
+| `right-third`  | Right third                 |
 | `center`       | 70% width, 80% height, centered |
 
 Aliases: `left-half`/`left`, `right-half`/`right`, `top-half`/`top`,
 `bottom-half`/`bottom`, `max`/`maximize`.
 
-Tiling respects the menu bar and dock — it uses the visible desktop
+Tiling respects the menu bar and dock. It uses the visible desktop
 area, not the full screen.

package/docs/layers.md

@@ -4,8 +4,6 @@ description: Group projects into switchable layers and tabbed groups
 order: 4
 ---
 
-# Workspace Layers & Tab Groups
-
 Two ways to organize related projects in `~/.lattices/workspace.json`:
 
 - **Layers** — switchable contexts that focus and tile windows
@@ -16,8 +14,8 @@ work together.
 
 ## Tab Groups
 
-Tab groups let you bundle related projects as tabs (tmux windows)
-within a single tmux session. This is useful when you have a family
+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.
 
@@ -48,11 +46,11 @@ to per-project configs.
 
 ### How it works
 
-- **Session naming**: `lattices-group-<id>` (e.g. `lattices-group-talkie`)
-- **tmux mapping**: 1 group = 1 tmux session, each tab = 1 tmux window,
-  each window has its own panes from that project's `.lattices.json`
-- **Independent launch still works**: `cd talkie-ios && lattices` creates
-  its own standalone session as before
+- 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
 
@@ -102,14 +100,13 @@ The command palette also includes group commands:
 
 ## Layers
 
-Layers let you group projects into switchable contexts. Instead of
-juggling six terminal windows at once, define two or three layers and
-switch between them instantly — the target layer's windows come to the
-front and tile into position, while the previous layer's windows fall
+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.
+killed. Layers only control which windows are focused.
 
 ### Configuration
 
@@ -192,8 +189,9 @@ Each project entry must have either `path` or `group`, not both.
 ### Tile values
 
 Any tile position from the [config reference](/docs/config#tile-positions)
-works: `left`, `right`, `top-left`, `top-right`, `bottom-left`,
-`bottom-right`, `maximize`, `center`.
+works: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
+`bottom-left`, `bottom-right`, `left-third`, `center-third`,
+`right-third`, `maximize`, `center`.
 
 ### Switching layers
 
@@ -219,7 +217,7 @@ The app remembers which layer was last active across restarts.
 Agents and scripts can switch layers via the daemon API:
 
 ```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 // List available layers
 const { layers, active } = await daemonCall('layers.list')
@@ -233,7 +231,7 @@ 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.
 
-See the [Daemon API reference](/docs/api) for more methods.
+More methods in the [Daemon API reference](/docs/api).
 
 ### Layer bar