@lattices/cli 0.3.0

package/docs/api.md

@@ -0,0 +1,924 @@
+---
+title: Agent API
+description: WebSocket API reference for programmatic control of lattices
+order: 5
+---
+
+The lattices menu bar app runs a WebSocket server on `ws://127.0.0.1:9399`.
+35+ RPC methods and 5 real-time events.
+
+## Quick start
+
+1. Launch the server (it starts with the menu bar app):
+
+```bash
+lattices app
+```
+
+2. Check that it's running:
+
+```bash
+lattices daemon status
+```
+
+3. Call a method from Node.js:
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+const windows = await daemonCall('windows.list')
+console.log(windows) // [{ wid, app, title, frame, ... }, ...]
+```
+
+Or from any language — it's a standard WebSocket:
+
+```bash
+# Plain websocat example
+echo '{"id":"1","method":"daemon.status"}' | websocat ws://127.0.0.1:9399
+```
+
+## Wire protocol
+
+lattices uses a JSON-RPC-style protocol over WebSocket on port **9399**.
+
+### Request
+
+```json
+{
+  "id": "unique-string",
+  "method": "windows.list",
+  "params": { "wid": 1234 }
+}
+```
+
+| Field    | Type    | Required | Description                          |
+|----------|---------|----------|--------------------------------------|
+| `id`     | string  | yes      | Caller-chosen ID, echoed in response |
+| `method` | string  | yes      | Method name (see below)              |
+| `params` | object  | no       | Method-specific parameters           |
+
+### Response
+
+```json
+{
+  "id": "unique-string",
+  "result": [ ... ],
+  "error": null
+}
+```
+
+| Field    | Type           | Description                                  |
+|----------|----------------|----------------------------------------------|
+| `id`     | string         | Echoed from request                          |
+| `result` | any \| null    | Method return value (null on error)          |
+| `error`  | string \| null | Error message (null on success)              |
+
+### Errors
+
+| 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 server 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 server restarts (e.g. after `lattices app restart`), existing
+  connections are dropped. Clients should reconnect and treat it as
+  stateless. There is no session resumption.
+
+## Node.js client
+
+lattices ships a zero-dependency WebSocket client that works with
+Node.js 18+. It handles connection, framing, and request/response
+matching internally.
+
+### `daemonCall(method, params?, timeoutMs?)`
+
+Send an RPC call and await the response.
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+// Read-only
+const status = await daemonCall('daemon.status')
+const windows = await daemonCall('windows.list')
+const win = await daemonCall('windows.get', { wid: 1234 })
+
+// Mutations
+await daemonCall('session.launch', { path: '/Users/you/dev/myapp' })
+await daemonCall('window.tile', { session: 'myapp-a1b2c3', position: 'left' })
+
+// Custom timeout (default: 3000ms)
+await daemonCall('projects.scan', null, 10000)
+```
+
+**Returns** the `result` field from the response.
+**Throws** if the server returns an error, the connection fails, or the timeout is reached.
+
+### `isDaemonRunning()`
+
+Check if the server is reachable.
+
+```js
+import { isDaemonRunning } from '@lattices/cli'
+
+if (await isDaemonRunning()) {
+  console.log('daemon is up')
+}
+```
+
+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 '@lattices/cli'
+
+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)
+}
+```
+
+---
+
+## System
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `daemon.status` | read | Health check and stats |
+| `api.schema` | read | Full API schema for self-discovery |
+| `diagnostics.list` | read | Recent diagnostic entries |
+
+#### `daemon.status`
+
+Health check and basic stats.
+
+**Params**: none
+
+**Returns**:
+
+```json
+{
+  "uptime": 3600.5,
+  "clientCount": 2,
+  "version": "1.0.0",
+  "windowCount": 12,
+  "tmuxSessionCount": 3
+}
+```
+
+#### `api.schema`
+
+Return the full API schema including version, models, and method definitions.
+Useful for agent self-discovery.
+
+**Params**: none
+
+#### `diagnostics.list`
+
+Return recent diagnostic log entries from the daemon.
+
+**Params**:
+
+| Field   | Type   | Required | Description                    |
+|---------|--------|----------|--------------------------------|
+| `limit` | number | no       | Max entries to return (default 50) |
+
+---
+
+## Windows & Spaces
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `windows.list` | read | All visible windows |
+| `windows.get` | read | Single window by ID |
+| `windows.search` | read | Search windows by query |
+| `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 |
+| `window.assignLayer` | write | Tag a window to a layer |
+| `window.removeLayer` | write | Remove a window's layer tag |
+| `window.layerMap` | read | All window→layer assignments |
+| `layout.distribute` | write | Distribute windows evenly |
+
+#### `windows.list`
+
+List all visible windows tracked by the desktop model.
+
+**Params**: none
+
+**Returns**: array of window objects:
+
+```json
+[
+  {
+    "wid": 1234,
+    "app": "Terminal",
+    "pid": 5678,
+    "title": "[lattices:myapp-a1b2c3] zsh",
+    "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
+    "spaceIds": [1],
+    "isOnScreen": true,
+    "latticesSession": "myapp-a1b2c3",
+    "layerTag": "web"
+  }
+]
+```
+
+The `latticesSession` field is present only on windows that belong to
+a lattices session (matched via the `[lattices:name]` title tag).
+
+The `layerTag` field is present when a window has been manually assigned
+to a layer via `window.assignLayer`.
+
+#### `windows.get`
+
+Get a single window by its CGWindowID.
+
+**Params**:
+
+| Field | Type   | Required | Description       |
+|-------|--------|----------|-------------------|
+| `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.
+
+#### `windows.search`
+
+Search windows by text query, including OCR content.
+
+**Params**:
+
+| Field   | Type   | Required | Description                    |
+|---------|--------|----------|--------------------------------|
+| `query` | string | yes      | Search query (matches title, app, OCR text) |
+| `ocr`   | boolean| no       | Include OCR text in search (default true) |
+| `limit` | number | no       | Max results (default 20)       |
+
+**Returns**: array of window objects matching the query.
+
+#### `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`) |
+
+#### `window.assignLayer`
+
+Manually tag a window to a layer. Tagged windows are raised and tiled
+when that layer activates, even if they aren't declared in `workspace.json`.
+
+**Params**:
+
+| Field   | Type   | Required | Description                    |
+|---------|--------|----------|--------------------------------|
+| `wid`   | number | yes      | CGWindowID                     |
+| `layer` | string | yes      | Layer ID to assign             |
+
+#### `window.removeLayer`
+
+Remove a window's layer tag.
+
+**Params**:
+
+| Field | Type   | Required | Description    |
+|-------|--------|----------|----------------|
+| `wid` | number | yes      | CGWindowID     |
+
+#### `window.layerMap`
+
+Return all current window→layer assignments.
+
+**Params**: none
+
+**Returns**:
+
+```json
+{
+  "1234": "web",
+  "5678": "mobile"
+}
+```
+
+Keys are CGWindowIDs (as strings), values are layer IDs.
+
+#### `layout.distribute`
+
+Distribute all visible lattices windows evenly across the screen.
+
+**Params**: none
+
+---
+
+## 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.
+
+**Params**: none
+
+**Returns**: array of session objects:
+
+```json
+[
+  {
+    "name": "myapp-a1b2c3",
+    "windowCount": 1,
+    "attached": true,
+    "panes": [
+      {
+        "id": "%0",
+        "windowIndex": 0,
+        "windowName": "main",
+        "title": "claude",
+        "currentCommand": "claude",
+        "pid": 9876,
+        "isActive": true
+      }
+    ]
+  }
+]
+```
+
+#### `tmux.inventory`
+
+List all tmux sessions including orphans (sessions not tracked by lattices).
+
+**Params**: none
+
+**Returns**:
+
+```json
+{
+  "all": [ ... ],
+  "orphans": [ ... ]
+}
+```
+
+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 & 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.
+
+**Params**: none
+
+**Returns**: array of project objects:
+
+```json
+[
+  {
+    "path": "/Users/you/dev/myapp",
+    "name": "myapp",
+    "sessionName": "myapp-a1b2c3",
+    "isRunning": true,
+    "hasConfig": true,
+    "paneCount": 2,
+    "paneNames": ["claude", "server"],
+    "devCommand": "pnpm dev",
+    "packageManager": "pnpm"
+  }
+]
+```
+
+`devCommand` and `packageManager` are present only when detected.
+
+#### `projects.scan`
+
+Trigger a re-scan of the project directory. Useful after cloning a new
+repo or adding a `.lattices.json` config.
+
+**Params**: none
+
+#### `layers.list`
+
+List configured workspace layers and the active index.
+
+**Params**: none
+
+**Returns**:
+
+```json
+{
+  "layers": [
+    { "id": "web", "label": "Web", "index": 0, "projectCount": 2 },
+    { "id": "mobile", "label": "Mobile", "index": 1, "projectCount": 2 }
+  ],
+  "active": 0
+}
+```
+
+Returns empty `layers` array if no workspace config is loaded.
+
+#### `layer.switch`
+
+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                    |
+|---------|--------|----------|--------------------------------|
+| `index` | number | no       | Layer index (0-based)          |
+| `name`  | string | no       | Layer ID or label              |
+
+Provide either `index` or `name`. If both are given, `name` takes priority.
+
+#### `group.launch`
+
+Launch a tab group session.
+
+**Params**:
+
+| Field | Type   | Required | Description      |
+|-------|--------|----------|------------------|
+| `id`  | string | yes      | Group ID         |
+
+**Errors**: `Not found` if the group ID doesn't match any configured group.
+
+#### `group.kill`
+
+Kill a tab group session.
+
+**Params**:
+
+| Field | Type   | Required | Description      |
+|-------|--------|----------|------------------|
+| `id`  | string | yes      | Group ID         |
+
+---
+
+## Processes & Terminals
+
+| 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 |
+
+#### `processes.list`
+
+List running processes relevant to development (editors, servers, build tools).
+
+**Params**:
+
+| Field     | Type   | Required | Description                        |
+|-----------|--------|----------|------------------------------------|
+| `command` | string | no       | Filter by command name substring   |
+
+**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"
+  }
+]
+```
+
+#### `processes.tree`
+
+Get the process tree rooted at a given PID.
+
+**Params**:
+
+| Field | Type   | Required | Description   |
+|-------|--------|----------|---------------|
+| `pid` | number | yes      | Root PID      |
+
+**Returns**: array of process objects (same shape as `processes.list`).
+
+#### `terminals.list`
+
+List all discovered terminal instances with their processes, tabs, and tmux associations.
+
+**Params**:
+
+| Field     | Type    | Required | Description                          |
+|-----------|---------|----------|--------------------------------------|
+| `refresh` | boolean | no       | Force-refresh the terminal tab cache |
+
+**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"
+  }
+]
+```
+
+#### `terminals.search`
+
+Search terminal instances by various criteria.
+
+**Params**:
+
+| 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**: filtered array of terminal instance objects (same shape as `terminals.list`).
+
+---
+
+## OCR
+
+| 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 |
+
+See [Screen OCR](/docs/ocr) for configuration, scan schedules, and storage details.
+
+#### `ocr.snapshot`
+
+Get the current in-memory OCR results for all visible windows.
+
+**Params**: none
+
+**Returns**: array of OCR result objects:
+
+```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
+  }
+]
+```
+
+#### `ocr.search`
+
+Full-text search across OCR history using SQLite FTS5.
+
+**Params**:
+
+| 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*`
+
+#### `ocr.history`
+
+Get the OCR timeline for a specific window, ordered by most recent first.
+
+**Params**:
+
+| Field   | Type   | Required | Description                |
+|---------|--------|----------|----------------------------|
+| `wid`   | number | yes      | CGWindowID                 |
+| `limit` | number | no       | Max results (default 50)   |
+
+#### `ocr.scan`
+
+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
+
+---
+
+## Events
+
+Events are pushed to all connected WebSocket clients when state changes.
+They have no `id` field — listen for messages with an `event` field.
+
+| 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 |
+
+#### `windows.changed`
+
+```json
+{ "event": "windows.changed", "data": { "windowCount": 12, "added": [1234], "removed": [5678] } }
+```
+
+#### `tmux.changed`
+
+```json
+{ "event": "tmux.changed", "data": { "sessionCount": 3, "sessions": ["myapp-a1b2c3"] } }
+```
+
+#### `layer.switched`
+
+```json
+{ "event": "layer.switched", "data": { "index": 1, "name": "mobile" } }
+```
+
+#### `ocr.scanComplete`
+
+```json
+{ "event": "ocr.scanComplete", "data": { "windowCount": 12, "totalBlocks": 342 } }
+```
+
+#### `processes.changed`
+
+```json
+{ "event": "processes.changed", "data": { "interestingCount": 5, "pids": [1234, 5678] } }
+```
+
+---
+
+## Agent integration
+
+### CLAUDE.md snippet
+
+Add this to your project's `CLAUDE.md` so any AI agent working in the
+project knows how to control the workspace:
+
+```markdown
+## Workspace Control
+
+This project uses lattices for workspace management. The daemon API
+is available at ws://127.0.0.1:9399.
+
+### Available commands
+- List windows: `daemonCall('windows.list')`
+- List sessions: `daemonCall('tmux.sessions')`
+- Launch a project: `daemonCall('session.launch', { path: '/absolute/path' })`
+- Tile a window: `daemonCall('window.tile', { session: 'name', position: 'left' })`
+- Switch layer: `daemonCall('layer.switch', { index: 0 })`
+- Switch layer by name: `daemonCall('layer.switch', { name: 'web' })`
+
+### Import
+\```js
+import { daemonCall } from '@lattices/cli'
+\```
+```
+
+### Multi-agent orchestration
+
+An orchestrator agent can set up the full workspace for sub-agents:
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+// Discover what's available
+const projects = await daemonCall('projects.list')
+
+// Launch the projects we need
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('session.launch', { path: '/Users/you/dev/api' })
+
+// Tile them side by side
+const sessions = await daemonCall('tmux.sessions')
+const fe = sessions.find(s => s.name.startsWith('frontend'))
+const api = sessions.find(s => s.name.startsWith('api'))
+
+await daemonCall('window.tile', { session: fe.name, position: 'left' })
+await daemonCall('window.tile', { session: api.name, position: 'right' })
+```
+
+### Reactive event pattern
+
+Subscribe to events to react to workspace changes:
+
+```js
+import WebSocket from 'ws'
+
+const ws = new WebSocket('ws://127.0.0.1:9399')
+
+ws.on('message', (raw) => {
+  const msg = JSON.parse(raw)
+
+  if (msg.event === 'tmux.changed') {
+    console.log('Sessions:', msg.data.sessions.join(', '))
+  }
+
+  if (msg.event === 'windows.changed') {
+    console.log('Windows:', msg.data.windowCount, 'total')
+  }
+
+  if (msg.event === 'layer.switched') {
+    console.log('Switched to layer', msg.data.index)
+  }
+})
+
+// You can also send RPC calls on the same connection
+ws.on('open', () => {
+  ws.send(JSON.stringify({ id: '1', method: 'daemon.status' }))
+})
+```
+
+### Health check before use
+
+Always verify the daemon is running before making calls:
+
+```js
+import { isDaemonRunning, daemonCall } from '@lattices/cli'
+
+if (!(await isDaemonRunning())) {
+  console.error('lattices daemon is not running — start it with: lattices app')
+  process.exit(1)
+}
+
+const status = await daemonCall('daemon.status')
+console.log(`Daemon up for ${Math.round(status.uptime)}s, tracking ${status.windowCount} windows`)
+```