@arach/lattices 0.2.1 → 0.6.1

package/docs/api.md

@@ -1,15 +1,15 @@
 ---
-title: Daemon API
+title: Agent API
 description: WebSocket API reference for programmatic control of lattices
 order: 5
 ---
 
-The lattices menu bar app runs a WebSocket daemon on `ws://127.0.0.1:9399`.
-30 RPC methods and 5 real-time events.
+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 daemon (it starts with the menu bar app):
+1. Launch the server (it starts with the menu bar app):
 
 ```bash
 lattices app
@@ -24,7 +24,7 @@ lattices daemon status
 3. Call a method from Node.js:
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 const windows = await daemonCall('windows.list')
 console.log(windows) // [{ wid, app, title, frame, ... }, ...]
@@ -83,14 +83,14 @@ lattices uses a JSON-RPC-style protocol over WebSocket on port **9399**.
 
 ### Connection lifecycle
 
-- The daemon starts when the menu bar app launches and stops when it quits.
+- 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 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.
+- 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
 
@@ -103,7 +103,7 @@ matching internally.
 Send an RPC call and await the response.
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 // Read-only
 const status = await daemonCall('daemon.status')
@@ -112,21 +112,24 @@ 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' })
+await daemonCall('window.place', {
+  session: 'myapp-a1b2c3',
+  placement: { kind: 'tile', value: 'left' }
+})
 
 // Custom timeout (default: 3000ms)
 await daemonCall('projects.scan', null, 10000)
 ```
 
 **Returns** the `result` field from the response.
-**Throws** if the daemon returns an error, the connection fails, or the timeout is reached.
+**Throws** if the server returns an error, the connection fails, or the timeout is reached.
 
 ### `isDaemonRunning()`
 
-Check if the daemon is reachable.
+Check if the server is reachable.
 
 ```js
-import { isDaemonRunning } from '@arach/lattices/daemon-client'
+import { isDaemonRunning } from '@lattices/cli'
 
 if (await isDaemonRunning()) {
   console.log('daemon is up')
@@ -135,12 +138,50 @@ if (await isDaemonRunning()) {
 
 Returns `true` if `daemon.status` responds within 1 second.
 
+## TypeScript SDK facade
+
+The CLI is a human/debug surface. Product code and agents should prefer the
+typed SDK facade, which validates params with Zod and calls the same daemon
+methods directly.
+
+```ts
+import { cua } from '@lattices/sdk'
+
+await cua.magicCursor({
+  app: 'Scout',
+  xRatio: 0.52,
+  yRatio: 0.91,
+  text: 'What are the most important docs in this project, and what would an agent say after reading them?',
+  treatment: 'execute',
+  trail: 'comet',
+  motion: 'rush',
+  trajectory: 'overshoot',
+  glow: 'halo',
+  idle: 'wiggle',
+  edge: 'ripple',
+})
+
+await cua.click({
+  app: 'Scout',
+  xRatio: 0.74,
+  yRatio: 0.95,
+  transport: 'ax',
+  axLabel: 'Send',
+  noFocus: true,
+  treatment: 'execute',
+})
+```
+
+`@lattices/cli/cua` exposes the same CUA module for CLI-adjacent scripts, but
+new app and agent code should use `@lattices/sdk` or `@lattices/sdk/cua` so the
+import names the product surface instead of the CLI package.
+
 ### Error handling
 
 `daemonCall` throws on errors — always wrap calls in try/catch:
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 try {
   await daemonCall('session.launch', { path: '/nonexistent' })
@@ -157,12 +198,707 @@ try {
 
 ---
 
+## Runs And Capture
+
+Runs are local executions that produce trace events and artifacts. Capture
+methods write into the Lattices run store under
+`~/Library/Application Support/Lattices/Runs/`.
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `runs.create` | write | Create a run record and artifact directory |
+| `runs.list` | read | List recent runs |
+| `runs.get` | read | Inspect one run, including artifacts and trace events |
+| `runs.artifacts` | read | List artifacts for one run |
+| `capture.screenshotWindow` | write | Capture a window screenshot as a run artifact |
+| `computer.prepare` | write | Resolve and optionally capture a terminal target without mutating it |
+| `computer.focusWindow` | write | Resolve, capture, focus, and verify a target window |
+| `computer.showCursor` | write | Show a visible cursor appearance and record it as a run |
+| `computer.launchApp` | write | Launch or focus a normal macOS app and record the run |
+| `computer.typeWindowText` | write | Type or paste into a normal app window, optionally after a click |
+| `computer.click` | write | Stage or execute a window-relative click target; prefers no-focus `AXPress` in auto/ax transport |
+| `computer.demoScout` | write | Scout warm-up run for memo/demo recording |
+| `computer.typeText` | write | Insert text into a safe terminal using the least intrusive transport |
+| `computer.demoTerminal` | write | Compatibility wrapper for a bounded terminal text action |
+
+#### `capture.screenshotWindow`
+
+Capture a window as a PNG artifact. If no target is provided, Lattices captures
+the frontmost non-Lattices window.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Target CGWindowID |
+| `session` | string | no | Target lattices session |
+| `app` | string | no | Target app name |
+| `title` | string | no | Optional title filter for `app`, or run title |
+| `runId` | string | no | Existing run to append to |
+| `source` | string | no | Calling surface label |
+| `filename` | string | no | Optional artifact filename |
+
+```js
+await daemonCall('capture.screenshotWindow', { source: 'agent' })
+
+await daemonCall('capture.screenshotWindow', {
+  session: 'frontend-a1b2c3',
+  filename: 'before-layout.png'
+})
+```
+
+CLI:
+
+```bash
+lattices capture window
+lattices runs
+lattices runs run_20260617-120000_a1b2c3
+lattices terminals
+lattices terminals --refresh
+lattices computer prepare --text "# hello" --treatment stage
+lattices computer focus-window --wid 7258 --treatment present
+lattices computer cursor --style marker --shape chevron --angle-deg -8 --label typing
+lattices computer launch-app Scout
+lattices computer scout --treatment present
+lattices computer scout "Draft memo text" --execute
+lattices computer type-window --app Scout --text "Draft memo text" --x-ratio .5 --y-ratio .86 --execute
+lattices computer click --app Scout --x-ratio .5 --y-ratio .86 --execute
+lattices cua click --app Scout --x-ratio .74 --y-ratio .95 --transport ax --ax-label Send --execute
+lattices computer type-text --text "# hello from lattices"
+lattices computer demo-terminal --dry-run
+```
+
+---
+
+#### Computer Action Treatments
+
+Computer-use endpoints accept a `treatment` field that controls how intrusive
+the action may be:
+
+| Treatment | Behavior |
+|-----------|----------|
+| `observe` | Resolve target and record a run, without focus or input |
+| `stage` | Resolve target and stage intent/artifacts, without focus or input |
+| `present` | Focus or present the target, without input |
+| `execute` | Perform the action after safety checks |
+
+The legacy `dryRun: true` flag maps to `stage`.
+
+#### `computer.prepare`
+
+Resolve and score terminal candidates for a future computer-use action. This is
+the least intrusive endpoint: by default it observes the target and captures an
+artifact, but it does not focus or type.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Specific terminal window id |
+| `tty` | string | no | Specific terminal TTY |
+| `app` | string | no | Preferred terminal app, such as `iTerm2` |
+| `text` | string | no | Text to stage in the run trace |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `capture` | bool | no | Capture target screenshot artifact. Defaults to `true` |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.prepare', {
+  text: '# review before typing',
+  treatment: 'stage'
+})
+```
+
+#### `computer.focusWindow`
+
+Resolve a target window, optionally capture it, focus it, and verify the focused
+window id. Use `treatment: 'observe'` or `stage` to plan without presenting.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Target window id |
+| `session` | string | no | Target lattices session |
+| `app` | string | no | Target app name |
+| `title` | string | no | Optional title substring for `app` |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `dryRun` | bool | no | Stage without focusing |
+| `capture` | bool | no | Capture before/after artifacts. Defaults to `true` |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.focusWindow', {
+  app: 'iTerm2',
+  treatment: 'present'
+})
+```
+
+#### `computer.showCursor`
+
+Resolve the current cursor location and show a visible cursor appearance. This
+is the cursor equivalent of a typing action: it records a run, cursor target,
+appearance parameters, and trace events. Use `observe` or `stage` to plan
+without showing anything.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `x` | double | no | Screen x coordinate. Defaults to current cursor |
+| `y` | double | no | Screen y coordinate. Defaults to current cursor |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `style` | string | no | `spotlight`, `pulse`, or `marker` |
+| `appearance` | string | no | Alias for `style` |
+| `shape` | string | no | Marker shape: `chevron`, `facet`, `shard`, `wedge`, `prism`, or `notch` |
+| `angleDeg` | double | no | Marker rotation in degrees. Positive rotates visually clockwise; default is `-8` for marker |
+| `size` | string | no | Marker size: `small`, `regular`, or `large`. Defaults to Settings |
+| `color` | string | no | `blue`, `green`, `amber`, `pink`, `red`, or `white` |
+| `durationMs` | int | no | Appearance duration in milliseconds |
+| `label` | string | no | Optional marker label |
+| `dryRun` | bool | no | Stage without showing |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.showCursor', {
+  style: 'marker',
+  shape: 'chevron',
+  angleDeg: -8,
+  size: 'regular',
+  color: 'white',
+  treatment: 'present'
+})
+```
+
+#### `computer.launchApp`
+
+Launch or focus a normal macOS app and record the result as a run. Use
+`dryRun: true` or `treatment: 'stage'` to plan without launching.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `app` | string | yes | App name, such as `Scout`, `Slack`, or `Notes` |
+| `bundleId` | string | no | Bundle identifier fallback for precise launch |
+| `path` | string | no | Explicit `.app` bundle path |
+| `title` | string | no | Optional title substring for app window selection |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `dryRun` | bool | no | Stage without launching |
+| `capture` | bool | no | Capture the launched app window. Defaults to `true` outside dry-run |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.launchApp', {
+  app: 'Scout',
+  treatment: 'present'
+})
+```
+
+#### `computer.typeWindowText`
+
+Focus a normal app window and insert text. If click coordinates are provided,
+Lattices clicks that target before typing. Coordinates can be absolute screen
+points (`x`, `y`) or ratios inside the target window (`xRatio`, `yRatio`).
+For window ratios, `0,0` is the top-left of the window and `1,1` is the
+bottom-right.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Target window id |
+| `app` | string | no | Target app name |
+| `title` | string | no | Optional title substring for app target |
+| `text` | string | yes | Text to insert |
+| `enter` | bool | no | Press Enter after typing. Defaults to `false` |
+| `send` | bool | no | Alias for `enter` in chat-style demos |
+| `x`, `y` | double | no | Absolute click point before typing |
+| `xRatio`, `yRatio` | double | no | Window-relative click point before typing |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `dryRun` | bool | no | Stage without typing |
+| `capture` | bool | no | Capture before/after artifacts. Defaults to `true` |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.typeWindowText', {
+  app: 'Scout',
+  text: 'Draft memo text',
+  xRatio: 0.5,
+  yRatio: 0.86,
+  treatment: 'execute'
+})
+```
+
+#### `computer.click`
+
+Stage or execute a click target. `stage` records the target without clicking.
+In `execute`, `transport: "auto"` prefers `AXPress` on the resolved accessibility
+button/control before falling back to a pointer click. Use `transport: "ax"` or
+`noFocus: true` when the action must not focus the app or move the hardware
+pointer. When a window target is provided, ratios are relative to that window.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Target window id |
+| `app` | string | no | Target app name |
+| `title` | string | no | Optional title substring for app target |
+| `x`, `y` | double | no | Absolute click point |
+| `xRatio`, `yRatio` | double | no | Window-relative click point |
+| `button` | string | no | `left` or `right`; defaults to `left` |
+| `transport` | string | no | `auto`, `ax`, or `pointer`; defaults to `auto` |
+| `axLabel` | string | no | Optional AX text/title hint, such as `Send` |
+| `noFocus` | bool | no | Require no-focus AX execution; disable pointer fallback |
+| `treatment` | string | no | `stage`, `present`, or `execute` |
+| `dryRun` | bool | no | Stage without clicking |
+| `capture` | bool | no | Capture before/after artifacts when targeting a window |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.click', {
+  app: 'Scout',
+  xRatio: 0.5,
+  yRatio: 0.86,
+  treatment: 'execute'
+})
+
+await daemonCall('computer.click', {
+  app: 'Scout',
+  xRatio: 0.74,
+  yRatio: 0.95,
+  transport: 'ax',
+  axLabel: 'Send',
+  noFocus: true,
+  treatment: 'execute'
+})
+```
+
+#### `computer.demoScout`
+
+Warm up a Scout memo/demo recording run. In `present` mode it launches or
+focuses Scout and records a run without typing. In `execute` mode it can click
+the likely composer area, type a draft, and optionally press Enter when
+`enter` or `send` is true. Dry-run/stage mode does not capture by default, so it
+works before Screen Recording permission is granted.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `app` | string | no | Scout app name override. Defaults to `Scout` |
+| `title` | string | no | Optional title substring for the Scout window |
+| `text` | string | no | Draft text to type in `execute` mode |
+| `enter` | bool | no | Press Enter after typing. Defaults to `false` |
+| `send` | bool | no | Alias for `enter` |
+| `click` | bool | no | Click the likely composer area before typing |
+| `xRatio`, `yRatio` | double | no | Composer click point; defaults to `0.5`, `0.86` |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `dryRun` | bool | no | Stage without launching or typing |
+| `capture` | bool | no | Capture before/after artifacts. Defaults to `true` outside dry-run |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.demoScout', { dryRun: true })
+
+await daemonCall('computer.demoScout', {
+  treatment: 'present',
+  capture: false
+})
+
+await daemonCall('computer.demoScout', {
+  text: 'Draft memo text',
+  treatment: 'execute',
+  send: false
+})
+```
+
+#### `computer.typeText`
+
+Resolve a terminal target and insert text after safety checks. Lattices prefers
+the least intrusive available transport: tmux pane input when a tmux pane is
+known, then target-pid key events/pasteboard insertion when window focus is
+required. Enter is never pressed unless `enter: true` is provided.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Specific terminal window id |
+| `tty` | string | no | Specific terminal TTY |
+| `app` | string | no | Preferred terminal app, such as `iTerm2` |
+| `text` | string | yes | Text to insert |
+| `enter` | bool | no | Press Enter after typing. Defaults to `false` |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `transport` | string | no | `auto`, `tmux`, or `pasteboard`. Defaults to `auto` |
+| `dryRun` | bool | no | Stage without typing |
+| `capture` | bool | no | Capture before/after artifacts. Defaults to `true` |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.typeText', {
+  text: '# hello from lattices',
+  transport: 'auto',
+  enter: false
+})
+```
+
+#### `computer.demoTerminal`
+
+Compatibility endpoint for the original terminal demo. It follows the same
+treatment, safety, capture, and transport rules as `computer.typeText`, but
+provides a default text payload when `text` is omitted.
+
+Run a bounded computer-use sequence against a terminal window:
+
+1. synthesize and score terminal candidates
+2. choose a safe shell-like terminal unless `wid` or `tty` is supplied
+3. capture a `before` screenshot artifact
+4. focus the terminal window
+5. insert text without pressing Enter by default
+6. capture an `after` screenshot artifact
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `wid` | uint32 | no | Specific terminal window id |
+| `tty` | string | no | Specific terminal TTY |
+| `app` | string | no | Preferred terminal app, such as `iTerm2` |
+| `text` | string | no | Text to insert |
+| `enter` | bool | no | Press Enter after typing. Defaults to `false` |
+| `treatment` | string | no | `observe`, `stage`, `present`, or `execute` |
+| `transport` | string | no | `auto`, `tmux`, or `pasteboard`. Defaults to `auto` |
+| `dryRun` | bool | no | Plan and capture without typing |
+| `capture` | bool | no | Capture before/after artifacts. Defaults to `true` |
+| `source` | string | no | Calling surface label |
+
+```js
+await daemonCall('computer.demoTerminal', { dryRun: true })
+
+await daemonCall('computer.demoTerminal', {
+  app: 'iTerm2',
+  text: '# hello from lattices',
+  enter: false
+})
+```
+
+---
+
+## Overlay UI
+
+The macOS app exposes a shared desktop overlay canvas for lightweight
+agent-visible UI. Use `overlay.publish` for transient passive visuals,
+and `overlay.actor.*` for persistent, movable actor surfaces.
+
+Persistent actors are useful for representing agents or processes on the
+desktop. Each actor has a stable `id`, can be moved independently through the
+API, dragged by the user, hidden/restored with **Hyper+B**, and closed with
+right-click. Click event callbacks and action surfaces are planned follow-on
+capabilities.
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `overlay.publish` | write | Publish a transient toast, label, highlight, or pet layer |
+| `overlay.clear` | write | Clear one overlay layer by id, or clear an owner namespace |
+| `overlay.actor.publish` | write | Create or update a persistent generative overlay actor |
+| `overlay.actor.moveTo` | write | Move an actor with app-owned easing |
+| `overlay.actor.hud` | write | Attach, update, or clear a hover web HUD for an actor |
+| `overlay.actor.visibility` | write | Show, hide, toggle, or inspect the sticky actor layer |
+
+#### `overlay.publish`
+
+Publish a transient layer on the screen overlay canvas.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `kind` | string | yes | `toast`, `label`, `highlight`, or `pet` |
+| `id` | string | no | Stable layer id; generated if omitted |
+| `text` | string | no | Toast/label text or pet message fallback |
+| `detail` | string | no | Secondary toast/label text |
+| `message` | string | no | Pet message |
+| `petId` | string | no | Bundled pet id from `apps/mac/Resources/Pets` |
+| `state` | string | no | Pet animation state |
+| `placement` | string | no | `top`, `bottom`, `center`, `cursor`, or `point` |
+| `x`, `y` | double | no | Screen-local point for `point` placement |
+| `w`, `h` | double | no | Highlight size |
+| `ttlMs` | int | no | Time to live in milliseconds |
+| `dismissible` | bool | no | Whether click-away dismissal removes the layer; defaults `true` |
+
+Example:
+
+```js
+await daemonCall('overlay.publish', {
+  kind: 'highlight',
+  x: 160,
+  y: 120,
+  w: 480,
+  h: 260,
+  text: 'Needs review',
+  style: 'warning',
+  ttlMs: 3000
+})
+```
+
+#### `overlay.actor.publish`
+
+Create or update a generative overlay actor. Actors default to persistent:
+omit `ttlMs` or pass `0`, and `dismissible` defaults to `false`.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | no | Stable actor id; generated if omitted |
+| `renderer` | string | no | `sprite` is currently supported |
+| `asset` | string | no | Bundled sprite asset id, such as `scout-ranger` |
+| `state` | string | no | Actor state or animation name |
+| `name` | string | no | Actor display name |
+| `message` | string | no | Attached message text |
+| `targetApp` | string | no | App name to activate when the actor is clicked |
+| `targetBundleId` | string | no | Bundle identifier to activate when the actor is clicked |
+| `targetAppPath` | string | no | `.app` bundle path to open when the actor is clicked |
+| `scale` | double | no | Actor scale multiplier |
+| `labelHidden` | bool | no | Hide the actor label/message |
+| `closeOnActivate` | bool | no | Remove the actor after activating its target app |
+| `hudUrl` | string | no | URL to render in a transparent hover HUD web view |
+| `hudHTML` | string | no | Inline HTML to render in a transparent hover HUD web view |
+| `hudWidth` | double | no | Hover HUD width |
+| `hudHeight` | double | no | Hover HUD height |
+| `hudReadAccess` | string | no | Local folder a file-backed HUD may read |
+| `placement` | string | no | `top`, `bottom`, `center`, `cursor`, or `point` |
+| `x`, `y` | double | no | Screen-local point for `point` placement |
+| `ttlMs` | int | no | Time to live; `0` means persistent |
+| `dismissible` | bool | no | Whether click-away dismissal removes the actor |
+
+Bundled sprite assets:
+
+| Asset | Notes |
+|-------|-------|
+| `assistant-spark` | Animated states include `idle`, `run_right`, `run_left`, `waving`, `jumping`, `failed`, `waiting`, `running`, and `review` |
+| `scout-ranger` | Bundled sprite asset with default frame fallback |
+
+Example:
+
+```js
+await daemonCall('overlay.actor.publish', {
+  id: 'agent-scout',
+  renderer: 'sprite',
+  asset: 'scout-ranger',
+  state: 'waiting',
+  name: 'Scout',
+  message: 'Waiting for feedback',
+  placement: 'point',
+  x: 640,
+  y: 320,
+  ttlMs: 0
+})
+```
+
+#### `overlay.actor.moveTo`
+
+Move an actor with app-owned animation. The app interpolates position and
+switches directional sprite states while moving.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Actor id |
+| `x`, `y` | double | yes | Target screen-local point |
+| `durationMs` | int | no | Animation duration |
+| `easing` | string | no | `linear`, `easeInOut`, or `spring` |
+
+Example:
+
+```js
+await daemonCall('overlay.actor.moveTo', {
+  id: 'agent-scout',
+  x: 820,
+  y: 280,
+  durationMs: 800,
+  easing: 'spring'
+})
+```
+
+#### `overlay.actor.hud`
+
+Attach a transparent, blurred hover HUD to an actor. The HUD is backed by a
+native `WKWebView`, so apps can point it at a local static HTML dashboard or,
+in development, a local URL.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Actor id |
+| `hudUrl` | string | no | URL or file path to render |
+| `hudHTML` | string | no | Inline HTML to render instead of a URL |
+| `hudTitle` | string | no | HUD title metadata |
+| `hudWidth` | double | no | HUD width |
+| `hudHeight` | double | no | HUD height |
+| `hudReadAccess` | string | no | Local folder a file-backed HUD may read |
+| `clear` | bool | no | Remove the actor HUD |
+
+Example:
+
+```js
+await daemonCall('overlay.actor.hud', {
+  id: 'switch-talkie',
+  hudUrl: '/Users/you/dev/talkie/.lattices/hud/index.html',
+  hudReadAccess: '/Users/you/Library/Application Support/Talkie/HUD',
+  hudWidth: 380,
+  hudHeight: 260
+})
+```
+
+#### `overlay.actor.visibility`
+
+Show, hide, toggle, or inspect the persistent actor layer without destroying
+the actors. This is the daemon equivalent of the app's **Hyper+B** shortcut.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | string | no | `show`, `hide`, `toggle`, or `status` |
+| `visible` | bool | no | Set layer visibility directly |
+| `hidden` | bool | no | Set layer hidden state directly |
+| `feedback` | bool | no | Show a short desktop feedback toast |
+
+Example:
+
+```js
+await daemonCall('overlay.actor.visibility', { action: 'toggle' })
+```
+
+### Static HUD Manifests
+
+Apps and projects can expose a local hover dashboard without running a web
+server by publishing a static bundle at:
+
+```txt
+.lattices/hud/
+  manifest.json
+  index.html
+  assets/
+```
+
+Minimal manifest:
+
+```json
+{
+  "version": 1,
+  "id": "talkie",
+  "name": "Talkie",
+  "bundleId": "com.usabletalkie.Talkie",
+  "icon": "./assets/icon.png",
+  "entry": "./index.html",
+  "readAccess": "~/Library/Application Support/Talkie/HUD",
+  "surface": { "width": 380, "height": 260 },
+  "actor": {
+    "labelHidden": true,
+    "click": "activateApp"
+  },
+  "sources": [
+    {
+      "path": "~/Library/Application Support/Talkie/HUD/activity.jsonl",
+      "format": "jsonl",
+      "schema": "talkie.activity.v1",
+      "presentation": "timeline"
+    }
+  ]
+}
+```
+
+The CLI resolves this manifest into `overlay.actor.publish` with a file-backed
+HUD URL. The macOS app loads `entry` through `WKWebView.loadFileURL`, allowing
+read access to the HUD folder by default, or to the manifest's `readAccess`
+folder when one is declared.
+
+`sources` is descriptive metadata for app-owned state, logs, or event streams.
+Lattices does not append to those logs. The app writes them in its normal
+runtime location, and the custom HUD renderer decides how to present them.
+
+Useful commands:
+
+```bash
+lattices hud register .lattices/hud/manifest.json --publish
+lattices hud publish talkie
+lattices hud sync
+lattices hud discover ~/dev --register
+```
+
+For packaged apps, keep the renderer files in the app bundle and point mutable
+sources at an app-owned folder such as `~/Library/Application Support/...`.
+
+---
+
 ## System
 
 | Method | Type | Description |
 |--------|------|-------------|
+| `deck.manifest` | read | Shared companion deck manifest |
+| `deck.snapshot` | read | Current companion deck runtime snapshot |
+| `deck.perform` | write | Perform a companion deck action |
 | `daemon.status` | read | Health check and stats |
 | `api.schema` | read | Full API schema for self-discovery |
+| `diagnostics.list` | read | Recent diagnostic entries |
+
+#### `deck.manifest`
+
+Return the shared `DeckKit` manifest exposed by the macOS app. This is
+the contract a future Lattices companion can consume to discover pages,
+capabilities, and security mode.
+
+**Params**: none
+
+#### `deck.snapshot`
+
+Return the current `DeckKit` runtime snapshot for the macOS host.
+
+**Params**: none
+
+**Returns**: a `DeckRuntimeSnapshot` object containing:
+
+- `voice`
+- `desktop`
+- `switcher`
+- `history`
+- `questions`
+
+#### `deck.perform`
+
+Perform a `DeckKit` action against the running macOS host and return a
+`DeckActionResult`.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `pageID` | string | no | Deck page ID |
+| `actionID` | string | yes | Deck action identifier |
+| `payload` | object | no | Deck action payload |
+
+Example:
+
+```json
+{
+  "id": "1",
+  "method": "deck.perform",
+  "params": {
+    "pageID": "layout",
+    "actionID": "layout.optimize",
+    "payload": {
+      "strategy": "balanced",
+      "region": "right"
+    }
+  }
+}
+```
 
 #### `daemon.status`
 
@@ -189,6 +925,84 @@ Useful for agent self-discovery.
 
 **Params**: none
 
+CLI shortcut:
+
+```bash
+lattices call api.schema
+```
+
+#### `diagnostics.list`
+
+Return recent diagnostic log entries from the daemon.
+
+**Params**:
+
+| Field   | Type   | Required | Description                    |
+|---------|--------|----------|--------------------------------|
+| `limit` | number | no       | Max entries to return (default 50) |
+
+---
+
+## Mouse & Input
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `mouse.find` | read | Show a sonar pulse at the current cursor |
+| `mouse.summon` | write | Move the cursor to a point or screen center |
+| `mouse.shortcuts.get` | read | Return the live mouse shortcut config |
+| `mouse.shortcuts.reload` | write | Reload `~/.lattices/mouse-shortcuts.json` without restarting |
+| `mouse.shortcuts.set` | write | Replace the full mouse shortcut config and activate it |
+| `mouse.shortcuts.upsert` | write | Create or replace one mouse shortcut rule and activate it |
+| `mouse.shortcuts.remove` | write | Remove one mouse shortcut rule and activate the new config |
+| `mouse.shortcuts.restoreDefaults` | write | Restore default mouse shortcuts |
+
+Mouse shortcut rules are data. Prefer `shortcut.send` for hotkeys an agent can
+define or change directly; do not add a named action unless the behavior cannot
+be expressed as data.
+
+Create or replace a gesture that sends Hyper+D:
+
+```js
+await daemonCall('mouse.shortcuts.upsert', {
+  rule: {
+    id: 'middle-up-voice',
+    enabled: true,
+    device: 'any',
+    trigger: { button: 'middle', kind: 'drag', direction: 'up' },
+    action: {
+      type: 'shortcut.send',
+      shortcut: {
+        key: 'd',
+        keyCode: 2,
+        modifiers: ['control', 'option', 'shift', 'command']
+      }
+    }
+  }
+})
+```
+
+If an agent edits `~/.lattices/mouse-shortcuts.json` itself, refresh the running
+app explicitly:
+
+```js
+await daemonCall('mouse.shortcuts.reload')
+```
+
+All write methods persist the config, checkpoint the previous version in
+`~/.lattices/mouse-shortcuts.history/`, and update the active event-tap snapshot
+immediately. No app restart is required.
+
+Supported action types:
+
+| Type | Purpose |
+|------|---------|
+| `shortcut.send` | Send a data-defined key or keyCode with modifiers |
+| `app.activate` | Activate an app by name |
+| `space.previous` | Switch to the previous macOS Space |
+| `space.next` | Switch to the next macOS Space |
+| `screenmap.toggle` | Open the Screen Map overview |
+| `dictation.start` | Legacy alias that presses the configured Voice Command hotkey |
+
 ---
 
 ## Windows & Spaces
@@ -197,11 +1011,17 @@ Useful for agent self-discovery.
 |--------|------|-------------|
 | `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.place` | write | Place a window or session using a typed placement spec |
+| `window.tile` | write | Compatibility wrapper for session tiling |
 | `window.focus` | write | Focus a window / switch Spaces |
 | `window.move` | write | Move a window to another Space |
-| `layout.distribute` | write | Distribute windows evenly |
+| `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 |
+| `space.optimize` | write | Optimize a set of windows using an explicit scope and strategy |
+| `layout.distribute` | write | Compatibility wrapper for visible-window balancing |
 
 #### `windows.list`
 
@@ -221,7 +1041,8 @@ List all visible windows tracked by the desktop model.
     "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
     "spaceIds": [1],
     "isOnScreen": true,
-    "latticesSession": "myapp-a1b2c3"
+    "latticesSession": "myapp-a1b2c3",
+    "layerTag": "web"
   }
 ]
 ```
@@ -229,6 +1050,9 @@ 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).
 
+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.
@@ -242,6 +1066,56 @@ Get a single window by its 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 across title, app name, session tags, and OCR content. Returns results with `matchSource` indicating how the match was found, and `ocrSnippet` for OCR matches.
+
+**Params**:
+
+| Field   | Type   | Required | Description                    |
+|---------|--------|----------|--------------------------------|
+| `query` | string | yes      | Search query (matches title, app, session, OCR text) |
+| `ocr`   | boolean| no       | Include OCR text in search (default true) |
+| `limit` | number | no       | Max results (default 50)       |
+
+**Returns**: array of window objects with additional search fields:
+
+```json
+[
+  {
+    "wid": 265,
+    "app": "iTerm2",
+    "title": "✳ Claude Code",
+    "matchSource": "ocr",
+    "ocrSnippet": "…~/dev/vox StatusBarIconFolder…",
+    "frame": { "x": 688, "y": 3, "w": 1720, "h": 720 },
+    "isOnScreen": true
+  }
+]
+```
+
+`matchSource` values: `"title"`, `"app"`, `"session"`, `"ocr"`.
+
+**CLI usage**:
+
+```bash
+# Basic search (uses windows.search)
+lattices search vox
+
+# Deep search — adds terminal tab/process inspection for ranking
+lattices search vox --deep
+
+# Same as --deep (all search sources)
+lattices search vox --all
+
+# Pipeable output
+lattices search vox --wid
+lattices search vox --json
+
+# Search + focus + tile in one step
+lattices place vox right
+```
+
 #### `spaces.list`
 
 List macOS display spaces (virtual desktops).
@@ -264,20 +1138,55 @@ List macOS display spaces (virtual desktops).
 ]
 ```
 
-#### `window.tile`
+#### `window.place`
 
-Tile a session's terminal window to a screen position.
+Canonical window placement mutation. Use this when an agent needs a
+single, typed placement contract across voice, CLI, and daemon clients.
 
 **Params**:
 
-| Field      | Type   | Required | Description                         |
-|------------|--------|----------|-------------------------------------|
-| `session`  | string | yes      | Session name                        |
-| `position` | string | yes      | Tile position (see below)           |
+| Field       | Type            | Required | Description                              |
+|-------------|-----------------|----------|------------------------------------------|
+| `wid`       | number          | no       | Target window ID                          |
+| `session`   | string          | no       | Target lattices session                   |
+| `app`       | string          | no       | Target app name                           |
+| `title`     | string          | no       | Optional title substring for app matching |
+| `display`   | number          | no       | Target display index                      |
+| `placement` | string \| object | yes     | Placement shorthand or typed object       |
+
+Target resolution priority is `wid` → `session` → `app/title` → frontmost window.
 
-**Positions**: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
+**Placement strings**: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
 `bottom-left`, `bottom-right`, `left-third`, `center-third`, `right-third`,
-`maximize`, `center`
+`top-third`, `middle-third`, `bottom-third`, `left-quarter`, `right-quarter`,
+`top-quarter`, `bottom-quarter`, `maximize`, `center`, `grid:CxR:C,R`, or
+compact `CxR:C,R`. The canonical `grid:` form is 0-indexed; the compact form is
+1-indexed for command entry.
+
+**Typed placement examples**:
+
+```json
+{ "kind": "tile", "value": "top-right" }
+{ "kind": "grid", "columns": 3, "rows": 2, "column": 2, "row": 0 }
+{ "kind": "fractions", "x": 0.5, "y": 0, "w": 0.5, "h": 1 }
+```
+
+**Returns**: execution receipt including resolved target, placement, and trace.
+
+#### `window.tile`
+
+Compatibility wrapper for `window.place` when the target is a lattices
+session window.
+
+**Params**:
+
+| Field      | Type   | Required | Description                             |
+|------------|--------|----------|-----------------------------------------|
+| `session`  | string | yes      | Session name                            |
+| `position` | string | yes      | Placement shorthand or grid syntax      |
+
+This method exists for compatibility. New integrations should prefer
+`window.place`.
 
 #### `window.focus`
 
@@ -303,9 +1212,70 @@ Move a session's window to a different macOS Space.
 | `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.
+
+#### `space.optimize`
+
+Canonical space-balancing mutation. Use this when the goal is to make
+the current workspace coherent rather than placing one specific window.
+
+**Params**:
+
+| Field       | Type     | Required | Description                                         |
+|-------------|----------|----------|-----------------------------------------------------|
+| `scope`     | string   | no       | `visible`, `active-app`, `app`, or `selection`      |
+| `strategy`  | string   | no       | `balanced` or `mosaic`                              |
+| `app`       | string   | no       | App name for `app` scope                            |
+| `title`     | string   | no       | Optional title substring for app matching           |
+| `windowIds` | number[] | no       | Explicit window IDs for `selection` scope           |
+
+If `windowIds` is provided, scope is inferred as `selection`.
+If `app` is provided and `scope` is omitted, scope is inferred as `app`.
+
+**Returns**: execution receipt including resolved scope, strategy,
+affected window IDs, and trace.
+
 #### `layout.distribute`
 
-Distribute all visible lattices windows evenly across the screen.
+Compatibility wrapper for `space.optimize` with `scope=visible` and
+`strategy=balanced`.
 
 **Params**: none
 
@@ -440,7 +1410,8 @@ Restart a specific pane's process within a session.
 | `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 |
+| `layer.activate` | write | Activate a workspace layer using an explicit mode |
+| `layer.switch` | write | Compatibility wrapper for launch-style layer activation |
 | `group.launch` | write | Launch a tab group |
 | `group.kill` | write | Kill a tab group |
 
@@ -497,17 +1468,33 @@ List configured workspace layers and the active index.
 
 Returns empty `layers` array if no workspace config is loaded.
 
-#### `layer.switch`
+#### `layer.activate`
 
-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.
+Canonical layer mutation. Use this when an agent wants an explicit
+activation mode instead of implicit "switch" behavior.
 
 **Params**:
 
-| Field   | Type   | Required | Description                    |
-|---------|--------|----------|--------------------------------|
-| `index` | number | yes      | Layer index (0-based)          |
+| Field   | Type   | Required | Description                                 |
+|---------|--------|----------|---------------------------------------------|
+| `index` | number | no       | Layer index (0-based)                       |
+| `name`  | string | no       | Layer ID or label                           |
+| `mode`  | string | no       | `launch`, `focus`, or `retile`              |
+
+Provide either `index` or `name`.
+
+**Modes**:
+
+- `launch` — bring up the layer, launching missing projects and retiling
+- `focus` — raise the layer's windows in place
+- `retile` — re-apply the layer layout without launch semantics
+
+**Returns**: execution receipt including resolved layer, mode, and trace.
+
+#### `layer.switch`
+
+Compatibility wrapper for `layer.activate` with `mode=launch`.
+It keeps the old semantics and still posts a `layer.switched` event.
 
 #### `group.launch`
 
@@ -589,7 +1576,7 @@ List all discovered terminal instances with their processes, tabs, and tmux asso
 
 | Field     | Type    | Required | Description                          |
 |-----------|---------|----------|--------------------------------------|
-| `refresh` | boolean | no       | Force-refresh the terminal tab cache |
+| `refresh` | boolean | no       | Explicitly refresh terminal-tab metadata through terminal app scripting |
 
 **Returns**: array of terminal instance objects:
 
@@ -734,7 +1721,7 @@ They have no `id` field — listen for messages with an `event` field.
 #### `layer.switched`
 
 ```json
-{ "event": "layer.switched", "data": { "index": 1 } }
+{ "event": "layer.switched", "data": { "index": 1, "name": "mobile" } }
 ```
 
 #### `ocr.scanComplete`
@@ -764,16 +1751,23 @@ project knows how to control the workspace:
 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')`
+### Search (find windows)
+- Search by content: `daemonCall('windows.search', { query: 'myproject' })`
+  Returns windows with `matchSource` ("title", "app", "session", "ocr") and `ocrSnippet`
+- Search terminals: `daemonCall('terminals.search', {})` — tabs, cwds, processes
+- CLI: `lattices search myproject`, `lattices search myproject --deep`, or `lattices search myproject --all` (same as `--deep`)
+
+### Actions
+- Focus a window: `daemonCall('window.focus', { wid: 1234 })`
+- Place a window: `daemonCall('window.place', { session: 'name', placement: 'left' })`
 - 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 })`
+- Activate a layer: `daemonCall('layer.activate', { name: 'web', mode: 'launch' })`
+- Optimize the workspace: `daemonCall('space.optimize', { scope: 'visible', strategy: 'balanced' })`
+- CLI: `lattices place myproject left` (search + focus + tile in one step)
 
 ### Import
 \```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 \```
 ```
 
@@ -782,7 +1776,7 @@ import { daemonCall } from '@arach/lattices/daemon-client'
 An orchestrator agent can set up the full workspace for sub-agents:
 
 ```js
-import { daemonCall } from '@arach/lattices/daemon-client'
+import { daemonCall } from '@lattices/cli'
 
 // Discover what's available
 const projects = await daemonCall('projects.list')
@@ -796,8 +1790,8 @@ 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' })
+await daemonCall('window.place', { session: fe.name, placement: 'left' })
+await daemonCall('window.place', { session: api.name, placement: 'right' })
 ```
 
 ### Reactive event pattern
@@ -836,7 +1830,7 @@ ws.on('open', () => {
 Always verify the daemon is running before making calls:
 
 ```js
-import { isDaemonRunning, daemonCall } from '@arach/lattices/daemon-client'
+import { isDaemonRunning, daemonCall } from '@lattices/cli'
 
 if (!(await isDaemonRunning())) {
   console.error('lattices daemon is not running — start it with: lattices app')