@arach/lattices 0.1.0 → 0.2.1

package/docs/api.md

@@ -4,23 +4,8 @@ description: WebSocket API reference for programmatic control of lattices
 order: 5
 ---
 
-# Daemon API
-
 The lattices menu bar app runs a WebSocket daemon on `ws://127.0.0.1:9399`.
-It exposes 20 RPC methods and 3 real-time events — everything the app
-can do, agents and scripts can do too.
-
-## Who this is for
-
-- **AI coding agents** that need to discover projects, launch sessions,
-  tile windows, and switch contexts without human interaction
-- **Scripts and automation** — CI, dotfile bootstraps, workspace setup
-- **Custom tools** — build your own launcher, dashboard, or orchestrator
-
-> New to lattices? Start with the [Overview](/docs/overview) and
-> [Quickstart](/docs/quickstart). For the `.lattices.json` config format
-> and CLI commands, see [Configuration](/docs/config). For architecture
-> details, see [Concepts](/docs/concepts).
+30 RPC methods and 5 real-time events.
 
 ## Quick start
 
@@ -39,7 +24,7 @@ lattices daemon status
 3. Call a method from Node.js:
 
 ```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 const windows = await daemonCall('windows.list')
 console.log(windows) // [{ wid, app, title, frame, ... }, ...]
@@ -88,28 +73,25 @@ lattices uses a JSON-RPC-style protocol over WebSocket on port **9399**.
 | `result` | any \| null    | Method return value (null on error)          |
 | `error`  | string \| null | Error message (null on success)              |
 
-### Event (server-pushed)
-
-```json
-{
-  "event": "windows.changed",
-  "data": { ... }
-}
-```
-
-Events have no `id` — they are broadcast to all connected clients
-whenever state changes.
-
 ### Errors
 
-Three error types:
-
 | Error           | Meaning                              |
 |-----------------|--------------------------------------|
 | Unknown method  | The `method` string is not recognized |
 | Missing parameter | A required param was not provided   |
 | Not found       | The referenced resource doesn't exist |
 
+### Connection lifecycle
+
+- The daemon starts when the menu bar app launches and stops when it quits.
+- Connections are plain WebSocket. No handshake, no auth, no heartbeat.
+- The Node.js `daemonCall()` client opens a fresh connection per call and
+  closes it when the response arrives. For event subscriptions, hold the
+  connection open (see [Reactive event pattern](#agent-integration)).
+- If the daemon restarts (e.g. after `lattices app restart`), existing
+  connections are dropped. Clients should reconnect and treat the daemon
+  as stateless. There is no session resumption.
+
 ## Node.js client
 
 lattices ships a zero-dependency WebSocket client that works with
@@ -121,7 +103,7 @@ matching internally.
 Send an RPC call and await the response.
 
 ```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 // Read-only
 const status = await daemonCall('daemon.status')
@@ -132,7 +114,7 @@ const win = await daemonCall('windows.get', { wid: 1234 })
 await daemonCall('session.launch', { path: '/Users/you/dev/myapp' })
 await daemonCall('window.tile', { session: 'myapp-a1b2c3', position: 'left' })
 
-// Custom timeout (default: 5000ms)
+// Custom timeout (default: 3000ms)
 await daemonCall('projects.scan', null, 10000)
 ```
 
@@ -144,7 +126,7 @@ await daemonCall('projects.scan', null, 10000)
 Check if the daemon is reachable.
 
 ```js
-import { isDaemonRunning } from 'lattices/daemon-client'
+import { isDaemonRunning } from '@arach/lattices/daemon-client'
 
 if (await isDaemonRunning()) {
   console.log('daemon is up')
@@ -153,11 +135,36 @@ if (await isDaemonRunning()) {
 
 Returns `true` if `daemon.status` responds within 1 second.
 
+### Error handling
+
+`daemonCall` throws on errors — always wrap calls in try/catch:
+
+```js
+import { daemonCall } from '@arach/lattices/daemon-client'
+
+try {
+  await daemonCall('session.launch', { path: '/nonexistent' })
+} catch (err) {
+  // err.message is one of:
+  //   "Not found"              — resource doesn't exist
+  //   "Missing parameter: ..." — required param missing
+  //   "Unknown method: ..."    — bad method name
+  //   "Daemon request timed out" — no response within timeout
+  //   ECONNREFUSED             — daemon not running
+  console.error('Daemon error:', err.message)
+}
+```
+
 ---
 
-## Read methods
+## System
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `daemon.status` | read | Health check and stats |
+| `api.schema` | read | Full API schema for self-discovery |
 
-### `daemon.status`
+#### `daemon.status`
 
 Health check and basic stats.
 
@@ -175,9 +182,28 @@ Health check and basic stats.
 }
 ```
 
+#### `api.schema`
+
+Return the full API schema including version, models, and method definitions.
+Useful for agent self-discovery.
+
+**Params**: none
+
 ---
 
-### `windows.list`
+## Windows & Spaces
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `windows.list` | read | All visible windows |
+| `windows.get` | read | Single window by ID |
+| `spaces.list` | read | macOS display spaces |
+| `window.tile` | write | Tile a window to a position |
+| `window.focus` | write | Focus a window / switch Spaces |
+| `window.move` | write | Move a window to another Space |
+| `layout.distribute` | write | Distribute windows evenly |
+
+#### `windows.list`
 
 List all visible windows tracked by the desktop model.
 
@@ -203,9 +229,7 @@ List all visible windows tracked by the desktop model.
 The `latticesSession` field is present only on windows that belong to
 a lattices session (matched via the `[lattices:name]` title tag).
 
----
-
-### `windows.get`
+#### `windows.get`
 
 Get a single window by its CGWindowID.
 
@@ -216,12 +240,92 @@ Get a single window by its CGWindowID.
 | `wid` | number | yes      | CGWindowID        |
 
 **Returns**: a single window object (same shape as `windows.list` items).
-
 **Errors**: `Not found` if the window ID doesn't exist.
 
+#### `spaces.list`
+
+List macOS display spaces (virtual desktops).
+
+**Params**: none
+
+**Returns**: array of display objects:
+
+```json
+[
+  {
+    "displayIndex": 0,
+    "displayId": "main",
+    "currentSpaceId": 1,
+    "spaces": [
+      { "id": 1, "index": 0, "display": 0, "isCurrent": true },
+      { "id": 2, "index": 1, "display": 0, "isCurrent": false }
+    ]
+  }
+]
+```
+
+#### `window.tile`
+
+Tile a session's terminal window to a screen position.
+
+**Params**:
+
+| Field      | Type   | Required | Description                         |
+|------------|--------|----------|-------------------------------------|
+| `session`  | string | yes      | Session name                        |
+| `position` | string | yes      | Tile position (see below)           |
+
+**Positions**: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
+`bottom-left`, `bottom-right`, `left-third`, `center-third`, `right-third`,
+`maximize`, `center`
+
+#### `window.focus`
+
+Focus a window — bring it to front and switch Spaces if needed.
+
+**Params** (one of):
+
+| Field     | Type   | Required | Description                     |
+|-----------|--------|----------|---------------------------------|
+| `wid`     | number | no       | CGWindowID (any window)         |
+| `session` | string | no       | Session name (lattices windows)  |
+
+Provide either `wid` or `session`. If `wid` is given, it takes priority.
+
+#### `window.move`
+
+Move a session's window to a different macOS Space.
+
+**Params**:
+
+| Field     | Type   | Required | Description                |
+|-----------|--------|----------|----------------------------|
+| `session` | string | yes      | Session name               |
+| `spaceId` | number | yes      | Target Space ID (from `spaces.list`) |
+
+#### `layout.distribute`
+
+Distribute all visible lattices windows evenly across the screen.
+
+**Params**: none
+
 ---
 
-### `tmux.sessions`
+## Sessions
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `tmux.sessions` | read | Lattices tmux sessions |
+| `tmux.inventory` | read | All sessions including orphans |
+| `session.launch` | write | Launch a project session |
+| `session.kill` | write | Kill a session |
+| `session.detach` | write | Detach clients from a session |
+| `session.sync` | write | Reconcile session to config |
+| `session.restart` | write | Restart a pane's process |
+
+All session methods require tmux to be installed.
+
+#### `tmux.sessions`
 
 List tmux sessions that belong to lattices.
 
@@ -250,9 +354,7 @@ List tmux sessions that belong to lattices.
 ]
 ```
 
----
-
-### `tmux.inventory`
+#### `tmux.inventory`
 
 List all tmux sessions including orphans (sessions not tracked by lattices).
 
@@ -269,9 +371,80 @@ List all tmux sessions including orphans (sessions not tracked by lattices).
 
 Both arrays contain session objects (same shape as `tmux.sessions`).
 
+#### `session.launch`
+
+Launch a new tmux session for a project. If a session already exists,
+it will be reattached. The project must be in the scanned project list —
+call `projects.list` to check, or `projects.scan` to refresh.
+
+**Params**:
+
+| Field  | Type   | Required | Description                      |
+|--------|--------|----------|----------------------------------|
+| `path` | string | yes      | Absolute path to project directory |
+
+**Returns**: `{ "ok": true }`
+**Errors**: `Not found` if the path isn't in the scanned project list.
+
+#### `session.kill`
+
+Kill a tmux session by name.
+
+**Params**:
+
+| Field  | Type   | Required | Description         |
+|--------|--------|----------|---------------------|
+| `name` | string | yes      | Session name        |
+
+#### `session.detach`
+
+Detach all clients from a session (keeps it running).
+
+**Params**:
+
+| Field  | Type   | Required | Description         |
+|--------|--------|----------|---------------------|
+| `name` | string | yes      | Session name        |
+
+#### `session.sync`
+
+Reconcile a running session to match its declared `.lattices.json` config.
+Recreates missing panes, re-applies layout, restores labels, re-runs
+commands in idle panes.
+
+**Params**:
+
+| Field  | Type   | Required | Description                      |
+|--------|--------|----------|----------------------------------|
+| `path` | string | yes      | Absolute path to project directory |
+
+**Errors**: `Not found` if the path isn't in the project list.
+
+#### `session.restart`
+
+Restart a specific pane's process within a session.
+
+**Params**:
+
+| Field  | Type   | Required | Description                      |
+|--------|--------|----------|----------------------------------|
+| `path` | string | yes      | Absolute path to project directory |
+| `pane` | string | no       | Pane name to restart (defaults to first pane) |
+
 ---
 
-### `projects.list`
+## Projects & Layers
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `projects.list` | read | Discovered projects |
+| `projects.scan` | write | Re-scan project directory |
+| `layers.list` | read | Workspace layers and active index |
+| `layer.switch` | write | Switch workspace layer |
+| `group.launch` | write | Launch a tab group |
+| `group.kill` | write | Kill a tab group |
+
+#### `projects.list`
 
 List all discovered projects.
 
@@ -297,33 +470,14 @@ List all discovered projects.
 
 `devCommand` and `packageManager` are present only when detected.
 
----
+#### `projects.scan`
 
-### `spaces.list`
-
-List macOS display spaces (virtual desktops).
+Trigger a re-scan of the project directory. Useful after cloning a new
+repo or adding a `.lattices.json` config.
 
 **Params**: none
 
-**Returns**: array of display objects:
-
-```json
-[
-  {
-    "displayIndex": 0,
-    "displayId": "main",
-    "currentSpaceId": 1,
-    "spaces": [
-      { "id": 1, "index": 0, "display": 0, "isCurrent": true },
-      { "id": 2, "index": 1, "display": 0, "isCurrent": false }
-    ]
-  }
-]
-```
-
----
-
-### `layers.list`
+#### `layers.list`
 
 List configured workspace layers and the active index.
 
@@ -343,203 +497,213 @@ List configured workspace layers and the active index.
 
 Returns empty `layers` array if no workspace config is loaded.
 
----
+#### `layer.switch`
 
-## Write methods
-
-### `session.launch`
-
-Launch a new tmux session for a project.
+Switch the active workspace layer. Focuses and tiles all windows in the
+target layer, launches any projects that aren't running yet, and posts
+a `layer.switched` event.
 
 **Params**:
 
-| Field  | Type   | Required | Description                      |
-|--------|--------|----------|----------------------------------|
-| `path` | string | yes      | Absolute path to project directory |
-
-**Returns**: `{ "ok": true }`
-
-**Errors**: `Not found` if the path isn't in the scanned project list.
-Run `projects.scan` first if needed.
-
-**Notes**: If a session already exists for this project, it will be
-reattached. The project must be in the scanned project list — call
-`projects.list` to check, or `projects.scan` to refresh.
-
----
+| Field   | Type   | Required | Description                    |
+|---------|--------|----------|--------------------------------|
+| `index` | number | yes      | Layer index (0-based)          |
 
-### `session.kill`
+#### `group.launch`
 
-Kill a tmux session by name.
+Launch a tab group session.
 
 **Params**:
 
-| Field  | Type   | Required | Description         |
-|--------|--------|----------|---------------------|
-| `name` | string | yes      | Session name        |
-
-**Returns**: `{ "ok": true }`
+| Field | Type   | Required | Description      |
+|-------|--------|----------|------------------|
+| `id`  | string | yes      | Group ID         |
 
----
+**Errors**: `Not found` if the group ID doesn't match any configured group.
 
-### `session.detach`
+#### `group.kill`
 
-Detach all clients from a session (keeps it running).
+Kill a tab group session.
 
 **Params**:
 
-| Field  | Type   | Required | Description         |
-|--------|--------|----------|---------------------|
-| `name` | string | yes      | Session name        |
-
-**Returns**: `{ "ok": true }`
+| Field | Type   | Required | Description      |
+|-------|--------|----------|------------------|
+| `id`  | string | yes      | Group ID         |
 
 ---
 
-### `session.sync`
+## Processes & Terminals
 
-Reconcile a running session to match its declared `.lattices.json` config.
-Recreates missing panes, re-applies layout, restores labels, re-runs
-commands in idle panes.
+| Method | Type | Description |
+|--------|------|-------------|
+| `processes.list` | read | Running developer processes |
+| `processes.tree` | read | Process tree from a PID |
+| `terminals.list` | read | Terminal instances with processes |
+| `terminals.search` | read | Search terminals by criteria |
 
-**Params**:
+#### `processes.list`
 
-| Field  | Type   | Required | Description                      |
-|--------|--------|----------|----------------------------------|
-| `path` | string | yes      | Absolute path to project directory |
-
-**Returns**: `{ "ok": true }`
-
-**Errors**: `Not found` if the path isn't in the project list.
-
----
-
-### `session.restart`
-
-Restart a specific pane's process within a session.
+List running processes relevant to development (editors, servers, build tools).
 
 **Params**:
 
-| Field  | Type   | Required | Description                      |
-|--------|--------|----------|----------------------------------|
-| `path` | string | yes      | Absolute path to project directory |
-| `pane` | string | no       | Pane name to restart (defaults to first pane) |
+| Field     | Type   | Required | Description                        |
+|-----------|--------|----------|------------------------------------|
+| `command` | string | no       | Filter by command name substring   |
 
-**Returns**: `{ "ok": true }`
-
-**Errors**: `Not found` if the path isn't in the project list.
+**Returns**: array of process objects:
 
----
+```json
+[
+  {
+    "pid": 1234,
+    "ppid": 567,
+    "command": "node",
+    "args": "server.js",
+    "cwd": "/Users/you/dev/myapp",
+    "tty": "/dev/ttys003",
+    "tmuxSession": "myapp-a1b2c3",
+    "tmuxPaneId": "%0"
+  }
+]
+```
 
-### `window.tile`
+#### `processes.tree`
 
-Tile a session's terminal window to a screen position.
+Get the process tree rooted at a given PID.
 
 **Params**:
 
-| Field      | Type   | Required | Description                         |
-|------------|--------|----------|-------------------------------------|
-| `session`  | string | yes      | Session name                        |
-| `position` | string | yes      | Tile position (see below)           |
-
-**Positions**: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
-`bottom-left`, `bottom-right`, `maximize`, `center`
-
-**Returns**: `{ "ok": true }`
-
----
+| Field | Type   | Required | Description   |
+|-------|--------|----------|---------------|
+| `pid` | number | yes      | Root PID      |
 
-### `window.focus`
+**Returns**: array of process objects (same shape as `processes.list`).
 
-Focus a window — bring it to front and switch Spaces if needed.
+#### `terminals.list`
 
-**Params** (one of):
+List all discovered terminal instances with their processes, tabs, and tmux associations.
 
-| Field     | Type   | Required | Description                     |
-|-----------|--------|----------|---------------------------------|
-| `wid`     | number | no       | CGWindowID (any window)         |
-| `session` | string | no       | Session name (lattices windows)  |
+**Params**:
 
-Provide either `wid` or `session`. If `wid` is given, it takes priority.
+| Field     | Type    | Required | Description                          |
+|-----------|---------|----------|--------------------------------------|
+| `refresh` | boolean | no       | Force-refresh the terminal tab cache |
 
-**Returns**: `{ "ok": true }` (with `wid` and `app` if focused by wid)
+**Returns**: array of terminal instance objects:
 
----
+```json
+[
+  {
+    "tty": "/dev/ttys003",
+    "app": "Terminal",
+    "windowIndex": 0,
+    "tabIndex": 0,
+    "isActiveTab": true,
+    "tabTitle": "myapp",
+    "processes": [ ... ],
+    "shellPid": 1234,
+    "cwd": "/Users/you/dev/myapp",
+    "tmuxSession": "myapp-a1b2c3",
+    "tmuxPaneId": "%0",
+    "hasClaude": true,
+    "displayName": "Terminal — myapp"
+  }
+]
+```
 
-### `window.move`
+#### `terminals.search`
 
-Move a session's window to a different macOS Space.
+Search terminal instances by various criteria.
 
 **Params**:
 
-| Field     | Type   | Required | Description                |
-|-----------|--------|----------|----------------------------|
-| `session` | string | yes      | Session name               |
-| `spaceId` | number | yes      | Target Space ID (from `spaces.list`) |
+| Field      | Type    | Required | Description                          |
+|------------|---------|----------|--------------------------------------|
+| `command`  | string  | no       | Filter by command name substring     |
+| `cwd`      | string  | no       | Filter by working directory substring |
+| `app`      | string  | no       | Filter by terminal app name          |
+| `session`  | string  | no       | Filter by tmux session name          |
+| `hasClaude`| boolean | no       | Filter to only Claude-running TTYs   |
 
-**Returns**: `{ "ok": true }`
+**Returns**: filtered array of terminal instance objects (same shape as `terminals.list`).
 
 ---
 
-### `layer.switch`
+## OCR
 
-Switch the active workspace layer.
+| Method | Type | Description |
+|--------|------|-------------|
+| `ocr.snapshot` | read | Current OCR results for all visible windows |
+| `ocr.search` | read | Full-text search across OCR history |
+| `ocr.history` | read | OCR timeline for a specific window |
+| `ocr.scan` | write | Trigger an immediate OCR scan |
 
-**Params**:
+See [Screen OCR](/docs/ocr) for configuration, scan schedules, and storage details.
 
-| Field   | Type   | Required | Description                    |
-|---------|--------|----------|--------------------------------|
-| `index` | number | yes      | Layer index (0-based)          |
+#### `ocr.snapshot`
 
-**Returns**: `{ "ok": true }`
-
-**Notes**: This focuses and tiles all windows in the target layer,
-launches any projects that aren't running yet, and posts a
-`layer.switched` event.
+Get the current in-memory OCR results for all visible windows.
 
----
+**Params**: none
 
-### `group.launch`
+**Returns**: array of OCR result objects:
 
-Launch a tab group session.
+```json
+[
+  {
+    "wid": 1234,
+    "app": "Terminal",
+    "title": "zsh",
+    "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
+    "fullText": "~/dev/myapp $ npm run dev\nready on port 3000",
+    "blocks": [
+      {
+        "text": "~/dev/myapp $ npm run dev",
+        "confidence": 0.95,
+        "x": 0.02, "y": 0.05, "w": 0.6, "h": 0.04
+      }
+    ],
+    "timestamp": 1709568000.0
+  }
+]
+```
 
-**Params**:
+#### `ocr.search`
 
-| Field | Type   | Required | Description      |
-|-------|--------|----------|------------------|
-| `id`  | string | yes      | Group ID         |
+Full-text search across OCR history using SQLite FTS5.
 
-**Returns**: `{ "ok": true }`
+**Params**:
 
-**Errors**: `Not found` if the group ID doesn't match any configured group.
+| Field   | Type    | Required | Description                              |
+|---------|---------|----------|------------------------------------------|
+| `query` | string  | yes      | FTS5 search query                        |
+| `app`   | string  | no       | Filter by application name               |
+| `limit` | number  | no       | Max results (default 50)                 |
+| `live`  | boolean | no       | Search live snapshot instead of history (default false) |
 
----
+**FTS5 query examples**: `error`, `"build failed"`, `error OR warning`, `npm AND dev`, `react*`
 
-### `group.kill`
+#### `ocr.history`
 
-Kill a tab group session.
+Get the OCR timeline for a specific window, ordered by most recent first.
 
 **Params**:
 
-| Field | Type   | Required | Description      |
-|-------|--------|----------|------------------|
-| `id`  | string | yes      | Group ID         |
-
-**Returns**: `{ "ok": true }`
-
-**Errors**: `Not found` if the group ID doesn't match any configured group.
-
----
+| Field   | Type   | Required | Description                |
+|---------|--------|----------|----------------------------|
+| `wid`   | number | yes      | CGWindowID                 |
+| `limit` | number | no       | Max results (default 50)   |
 
-### `projects.scan`
+#### `ocr.scan`
 
-Trigger a re-scan of the project directory. Useful after cloning a new
-repo or adding a `.lattices.json` config.
+Trigger an immediate OCR scan of all visible windows, bypassing the
+periodic timer. Results available via `ocr.snapshot` once complete;
+an `ocr.scanComplete` event is broadcast to all clients.
 
 **Params**: none
 
-**Returns**: `{ "ok": true }`
-
 ---
 
 ## Events
@@ -547,69 +711,47 @@ repo or adding a `.lattices.json` config.
 Events are pushed to all connected WebSocket clients when state changes.
 They have no `id` field — listen for messages with an `event` field.
 
-### `windows.changed`
+| Event | Trigger |
+|-------|---------|
+| `windows.changed` | Desktop window list changes |
+| `tmux.changed` | Sessions created, killed, or modified |
+| `layer.switched` | Active workspace layer changes |
+| `ocr.scanComplete` | OCR scan cycle finishes |
+| `processes.changed` | Developer processes start or stop |
 
-Fired when the desktop window list changes (windows opened, closed,
-moved, or resized).
+#### `windows.changed`
 
 ```json
-{
-  "event": "windows.changed",
-  "data": {
-    "windows": [ ... ],
-    "added": [1234],
-    "removed": [5678]
-  }
-}
+{ "event": "windows.changed", "data": { "windowCount": 12, "added": [1234], "removed": [5678] } }
 ```
 
-| Field     | Type     | Description                        |
-|-----------|----------|------------------------------------|
-| `windows` | array    | Full current window list           |
-| `added`   | number[] | Window IDs that appeared           |
-| `removed` | number[] | Window IDs that disappeared        |
+#### `tmux.changed`
 
----
-
-### `tmux.changed`
+```json
+{ "event": "tmux.changed", "data": { "sessionCount": 3, "sessions": ["myapp-a1b2c3"] } }
+```
 
-Fired when tmux sessions change (created, killed, panes added/removed).
+#### `layer.switched`
 
 ```json
-{
-  "event": "tmux.changed",
-  "data": {
-    "sessions": [ ... ]
-  }
-}
+{ "event": "layer.switched", "data": { "index": 1 } }
 ```
 
-| Field      | Type  | Description              |
-|------------|-------|--------------------------|
-| `sessions` | array | Full current session list |
+#### `ocr.scanComplete`
 
----
-
-### `layer.switched`
+```json
+{ "event": "ocr.scanComplete", "data": { "windowCount": 12, "totalBlocks": 342 } }
+```
 
-Fired when the active workspace layer changes.
+#### `processes.changed`
 
 ```json
-{
-  "event": "layer.switched",
-  "data": {
-    "index": 1
-  }
-}
+{ "event": "processes.changed", "data": { "interestingCount": 5, "pids": [1234, 5678] } }
 ```
 
-| Field   | Type   | Description                  |
-|---------|--------|------------------------------|
-| `index` | number | Index of the now-active layer |
-
 ---
 
-## Agent integration patterns
+## Agent integration
 
 ### CLAUDE.md snippet
 
@@ -631,7 +773,7 @@ is available at ws://127.0.0.1:9399.
 
 ### Import
 \```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 \```
 ```
 
@@ -640,7 +782,7 @@ import { daemonCall } from 'lattices/daemon-client'
 An orchestrator agent can set up the full workspace for sub-agents:
 
 ```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 // Discover what's available
 const projects = await daemonCall('projects.list')
@@ -660,10 +802,10 @@ await daemonCall('window.tile', { session: api.name, position: 'right' })
 
 ### Reactive event pattern
 
-Subscribe to events for real-time workspace awareness:
+Subscribe to events to react to workspace changes:
 
 ```js
-import WebSocket from 'ws' // or use the built-in client
+import WebSocket from 'ws'
 
 const ws = new WebSocket('ws://127.0.0.1:9399')
 
@@ -671,12 +813,11 @@ ws.on('message', (raw) => {
   const msg = JSON.parse(raw)
 
   if (msg.event === 'tmux.changed') {
-    console.log('Sessions changed:', msg.data.sessions.length, 'active')
+    console.log('Sessions:', msg.data.sessions.join(', '))
   }
 
   if (msg.event === 'windows.changed') {
-    const latticesWindows = msg.data.windows.filter(w => w.latticesSession)
-    console.log('Lattices windows:', latticesWindows.length)
+    console.log('Windows:', msg.data.windowCount, 'total')
   }
 
   if (msg.event === 'layer.switched') {
@@ -695,7 +836,7 @@ ws.on('open', () => {
 Always verify the daemon is running before making calls:
 
 ```js
-import { isDaemonRunning, daemonCall } from 'lattices/daemon-client'
+import { isDaemonRunning, daemonCall } from '@arach/lattices/daemon-client'
 
 if (!(await isDaemonRunning())) {
   console.error('lattices daemon is not running — start it with: lattices app')