@lattices/cli 0.6.0 → 0.6.1

package/docs/assistant-knowledge.md

@@ -0,0 +1,130 @@
+---
+type: Assistant Knowledge Base
+title: Lattices — Assistant Knowledge
+description: Orientation + capability map the in-app Workspace Assistant uses to explain Lattices and point to the right feature or doc
+audience: assistant
+---
+
+> You are reading the Workspace Assistant's knowledge base. It summarizes what
+> Lattices can do and links to the deeper docs. Treat the **structured context**
+> in your prompt (current settings, file paths, CLI commands) as ground truth for
+> *this user's* configuration; treat this file as ground truth for *how Lattices
+> works*. When a question goes deeper than this summary, name the relevant doc
+> (see [References](#references)) instead of guessing.
+
+## What Lattices is
+
+Lattices is an **agentic window manager for macOS** — a programmable workspace
+that pairs a native menu bar app with managed tmux sessions and a scriptable
+agent API. Three layers, one product:
+
+1. **Programmable workspace** — a CLI and a WebSocket agent API (`ws://127.0.0.1:9399`,
+   35+ methods, real-time events) that let scripts and AI agents observe and drive
+   the desktop the same way a person does.
+2. **Smart layout manager** — the menu bar app tracks every window across all
+   monitors: tiling, switchable layers, snap zones, and screen-text indexing.
+3. **Managed tmux sessions** — declare a dev environment in `.lattices.json`;
+   Lattices builds it, runs it, and keeps it alive across reboots.
+
+Requirements: macOS 26+, Node 18+; tmux only for session management.
+See [Overview](/docs/overview) and [Concepts](/docs/concepts).
+
+## Capability map
+
+Each area below is a one-paragraph summary plus the doc to cite for detail.
+
+### Window tiling & placement
+Snap windows to preset positions — halves, quarters, thirds, maximize, center —
+from the command palette or `lattices tile <position>`. There is also a grid
+placement primitive: compact `CxR:c,r` starts at 1 for command entry, while
+canonical `grid:CxR:c,r` starts at 0 for APIs. → [Tiling reference](/docs/tiling-reference), positions in [Configuration](/docs/config).
+
+### Workspace layers & tab groups
+Group projects into named **layers** you can switch between, and tab-group related
+windows. `workspace.json` layers launch/focus/tile projects. Studio layers are
+rule-backed live window sets persisted in `~/.lattices/layers.json`; their clauses
+support app/title/session exact, substring, regex, Space, visibility, and exclusion
+matches. → [Layers](/docs/layers).
+
+### Command palette & menu bar app
+The palette (**Cmd+Shift+M**) is the app's primary surface: launch projects, tile,
+sync, restart, open settings — all searchable. → [Menu Bar App](/docs/app).
+
+### tmux sessions (`.lattices.json`)
+Declare panes, commands, and layout per project. `lattices start` builds/attaches a
+persistent session named `<basename>-<hash>`; `lattices sync` reconciles a running
+session to its config. **Ensure** re-runs exited commands on reattach; **prefill**
+types them and waits. → [Concepts](/docs/concepts), [Configuration](/docs/config).
+
+### Screen OCR & search
+The app reads on-screen text via the Accessibility API (~60s) and Apple Vision OCR
+on background windows (~2h), indexing everything with FTS5. Search across titles,
+app names, session tags, and OCR with `lattices search <query>` (add `--deep` or
+`--all` to inspect terminal tabs by cwd). → [Screen OCR & Search](/docs/ocr).
+
+### Voice commands
+Natural-language voice control for window management ("put the browser on the
+right", "switch to the backend layer"). → [Voice Commands](/docs/voice).
+
+### Mouse gestures
+Hold a mouse button, draw a direction or shape, release — runs the matched action.
+Configured via `mouseGestures.enabled` plus `~/.lattices/mouse-shortcuts.json`.
+→ [Mouse Gestures](/docs/mouse-gestures).
+
+### Agent API & CLI
+Agents connect over WebSocket and get the same control as a person: list
+windows/projects, launch sessions, tile, switch layers, read screen text, and
+subscribe to events (`windows.changed`, `tmux.changed`, `layer.switched`).
+→ [Agent Guide](/docs/agents), [Agent API](/docs/api).
+
+### Project twins
+Pi-backed project "twins" for mediated, persistent agent execution scoped to a
+project. → [Project Twins](/docs/twins).
+
+## Key shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd+Shift+M** | Open the command palette |
+| `lattices tile <position>` | Tile the focused window (CLI) |
+| `lattices layer [name\|index]` | Switch workspace layer (CLI) |
+| **Ctrl+B** then `D` / `Z` / arrows | tmux: detach / zoom / move pane (inside a session) |
+
+Tiling and grid hotkeys are user-configurable — for the live set, point the user to
+Settings or the [Tiling reference](/docs/tiling-reference) rather than asserting one.
+
+## CLI quick reference
+
+`lattices` · `lattices init` · `lattices sync` · `lattices start` ·
+`lattices restart [pane]` · `lattices tile <position>` · `lattices group [id]` ·
+`lattices layer [name|index]` · `lattices windows --json` ·
+`lattices search <query> [--deep|--all] [--json] [--wid]` · `lattices place <query> [position]` ·
+`lattices app restart`. Full flags: [Configuration](/docs/config).
+
+## Config & file locations
+
+- **Per project:** `.lattices.json` in the project root (panes, commands, layout, ensure/prefill).
+- **User config (`~/.lattices/`):** `workspace.json`, `layers.json`, `mouse-shortcuts.json`,
+  `snap-zones.json`, `clusters.json`, `ocr.db`, `lattices.log`.
+- **Defaults domain:** `dev.lattices.app` (read/write app settings via `defaults`).
+
+The exact current values and paths for *this* machine arrive in your structured
+context — prefer those over the generic paths above when answering.
+
+## References
+
+| Topic | Doc |
+|-------|-----|
+| What it is / who it's for | [Overview](/docs/overview) |
+| Install & first run | [Quickstart](/docs/quickstart) |
+| Architecture, glossary, internals | [Concepts](/docs/concepts) |
+| `.lattices.json`, CLI, tile positions | [Configuration](/docs/config) |
+| Command palette, tiling, sessions | [Menu Bar App](/docs/app) |
+| Tiling & grid placement | [Tiling reference](/docs/tiling-reference) |
+| Layers & tab groups | [Layers](/docs/layers) |
+| Screen OCR & full-text search | [Screen OCR & Search](/docs/ocr) |
+| Voice control | [Voice Commands](/docs/voice) |
+| Mouse gestures | [Mouse Gestures](/docs/mouse-gestures) |
+| Agent contracts (voice/CLI/daemon) | [Agent Guide](/docs/agents) |
+| WebSocket RPC method reference | [Agent API](/docs/api) |
+| Project twins | [Project Twins](/docs/twins) |

package/docs/config.md

@@ -152,6 +152,7 @@ Run `lattices init` in your project directory to generate a starter
 | `lattices hud sync`          | Publish all registered HUD actors                 |
 | `lattices search <query>`      | Search windows by title, app, session, OCR       |
 | `lattices search <q> --deep`   | Deep search: index + live terminal inspection    |
+| `lattices search <q> --all`    | Same as `--deep` (all search sources)            |
 | `lattices search <q> --wid`    | Print matching window IDs only (pipeable)        |
 | `lattices place <query> [pos]` | Deep search + focus + tile (default: bottom-right)|
 | `lattices focus <session>`   | Focus a session's window and switch Spaces        |
@@ -281,6 +282,10 @@ Aliases: `left-half`/`left`, `right-half`/`right`, `top-half`/`top`,
 Tiling respects the menu bar and dock. It uses the visible desktop
 area, not the full screen.
 
+For arbitrary cells, use compact `CxR:c,r` with 1-indexed coordinates
+from the top-left, or canonical `grid:CxR:c,r` with 0-indexed coordinates.
+Example: `lattices tile 4x4:1,2`.
+
 ### Smart app tiling
 
 Use `lattices tile family` when you want lattices to arrange a whole

package/docs/hyperspace-grid-snappiness.md

@@ -0,0 +1,210 @@
+# Hyper+G in-place grid — snappiness & satisfaction brief
+
+Context: `relayoutGroup()` already switched from sequential `RealWindowAnimator.setFrameRobust`
+to `WindowTiler.batchMoveAndRaiseWindows` (SLS freeze + one AX pass/app), with UI refresh
+deferred and a tap on commit. This is the "make it even better" pass.
+
+Code anchors:
+- Grid path: `WindowMotionMode.swift:1100 relayoutGroup()` → `:1138 distributeGroup()` (G = keycode 5, `:833`)
+- Batch move: `WindowTiler.swift:1753 batchMoveAndRaiseWindows` (freeze `:1767`, AX enum `:1776`, activate `:1818`, unfreeze `:1825`)
+- Sound: `DiagnosticLog.swift:162 AppFeedback.playTap`
+- Optional anim: `RealWindowAnimator.swift` (Timer 60fps, 0.28s — NOT on the batch path)
+- Chrome flash: `WindowTiler.swift:54 WindowHighlight.flash` (single-window only)
+- No haptics anywhere in the codebase yet → green field.
+
+---
+
+## The governing principle
+
+Perceived latency is bound to the **earliest** feedback the brain receives, not the moment
+pixels finish moving. The AX move is 40–120ms of work we can't fully erase. So the play is:
+**acknowledge on key-down (haptic + sound + overlay), move under cover, let the windows catch
+up.** Every quick win below is a variant of "fire feedback before the slow thing finishes."
+
+---
+
+## Quick wins (ship this week, low risk)
+
+### Q1 — Haptic on key-down (biggest bang, ~10 lines)
+There is zero haptic feedback today. `NSHapticFeedbackManager.defaultPerformer.perform(.alignment, performanceTime: .now)`
+is *exactly* the Loop/Magnet "snap" feel on trackpad/Force Touch. Fire it the instant `G` is
+matched in `keyDown` (`:833`), **before** `distributeGroup()` runs. Costs nothing, lands on the
+keypress, and the windows snapping ~80ms later reads as "instant + tactile."
+
+### Q2 — Decouple + pre-warm the tap sound
+`playTap` does `DispatchQueue.main.async { stop(); play() }`. Three problems:
+- the async hop delays the sound ~1 runloop turn past the keypress,
+- `stop()` then `play()` adds a tiny dead gap,
+- NSSound's *first* play in a session stutters (codec spin-up).
+
+Fixes: (a) prime the sound once on motion-mode entry by playing `tap.wav` at volume 0; (b) fire
+it synchronously on key-down (same site as the haptic), not after the move; (c) consider a
+prepared `AVAudioPlayer` (`prepareToPlay()`) or `AudioServicesPlaySystemSound` for sub-frame
+latency. Net: the *thunk* and the *tap* (haptic) coincide with the keypress, not the landing.
+
+### Q3 — Shrink the SLS freeze window
+`batchMoveAndRaiseWindows` does the slow `kAXWindowsAttribute` enumeration **inside** the
+`SLSDisableUpdate` freeze (`:1776`). The screen is frozen while we do AX queries. Resolve the
+AX elements *before* the freeze, freeze only around the set-frame writes, unfreeze immediately.
+Bonus: `relayoutGroup` already resolves each element via `recordOriginal`'s `ax(for: m)` (`:1113`)
+and then the batch path re-resolves the whole window list — pass the resolved elements in and
+skip the second AX pass entirely. Shorter freeze = less black-flash, snappier reveal.
+
+### Q4 — Stop activating every app
+`batchMoveAndRaiseWindows` calls `app.activate()` once per pid (`:1818`). With windows from N
+apps that's N activations → focus churn, Space flicker, and the overlay can lose key. AX
+`kAXRaiseAction` (already issued at `:1806`) reorders without activating. Activate **only** the
+app that should end up frontmost (the last-picked / aimed window), once. Raise the rest.
+
+### Q5 — Overlay "snap-pop" on the selection chrome
+The real move is a teleport, so add the *sense* of motion in the cheap overlay layer (no AX
+cost). When the grid lands, give each selection border a tiny scale overshoot (1.0→1.04→1.0,
+~120ms, Core Animation) + a one-shot green edge flash converging on the slot. This is the
+Arc/Raycast "it clicked into place" pop. Overlay-only, runs off the AX path, can't add input
+latency.
+
+---
+
+## Bigger bets (more design, higher ceiling)
+
+### B1 — Ghost-slot anticipation (kills perceived latency outright)
+On `G`, **instantly** paint the target grid as outlined ghost slots (you already compute
+`balancedGrid` rects → `tileFrame`). Animate the slots filling (or the picked windows' chrome
+sliding toward their slots) over ~140ms while the real `batchMove` runs underneath. The user
+sees motion begin on the same frame as the keypress; the real windows arrive under the
+animation. This fully decouples felt-speed from AX latency and is the single highest-ceiling
+change. The ghost overlay is also the natural home for Q5's pop.
+
+### B2 — Precompute on selection, commit = pure writes
+Every pluck/unpluck currently recomputes `balancedGrid` + `tileFrame` and re-resolves AX. Cache
+(a) the AX element per picked wid and (b) the target frame map, updated incrementally as the
+selection changes. By the time `G` fires, commit is nothing but the frozen set-frame loop —
+nothing to compute, nothing to resolve, minimal freeze.
+
+### B3 — Staggered cascade fill (the "deliberate fast" feel)
+Real windows must move simultaneously (per-window AX animation = jank — see "avoid"). But the
+*overlay* tiles/borders can land on a micro-stagger in reading order (~10–14ms/cell). The eye
+reads a fast left-to-right cascade as more intentional and premium than a flat simultaneous
+snap, while the actual work stays a single batch. Pure overlay timing.
+
+---
+
+## What to avoid (these ADD latency or jank)
+
+- **Don't animate many real windows via per-tick AX writes.** `RealWindowAnimator`'s 0.28s
+  Timer loop is fine for one window; across a group it's 60fps × N AX position+size writes —
+  AX is slow and serializes, so it stutters and feels *slower* than a clean teleport. Keep the
+  batch teleport; animate the overlay, not the windows.
+- **Don't do AX enumeration / `DesktopModel.poll()` inside the freeze or on the commit path.**
+  Poll/rebuild are already deferred (`refreshAfterGridMove`, `:1125`) — keep it that way; don't
+  let new chrome work creep back onto the hot path.
+- **Don't async-dispatch or `stop()`-then-`play()` the commit sound** (see Q2) — both push the
+  thunk past the keypress.
+- **Don't `app.activate()` per app** (Q4) — multi-app activation is the main source of flicker
+  and overlay focus loss.
+- **Avoid Timer-driven overlay animation.** Use Core Animation / `CADisplayLink`; `Timer` at
+  1/60 drifts and can hitch under load.
+- **Don't add dwell.** `WindowHighlight.flash` defaults to a 0.9s dwell + 0.3s fade — fine for a
+  one-shot locate, wrong for a snap pop. Snap feedback wants ~120–180ms total. Long fades read
+  as lag, not polish.
+
+---
+
+## Recommended ship order
+
+1. **Q1 + Q2** together — one small change at the `G` key site: haptic + synchronous pre-warmed
+   sound on key-down. Instant tactile upgrade, ~20 lines, no risk.
+2. **Q3 + Q4** — tighten `batchMoveAndRaiseWindows` (pre-resolve AX, shorter freeze, single
+   activate). Real latency reduction.
+3. **Q5** — overlay snap-pop on the chrome. First "ooh" moment.
+4. **B1** — ghost-slot anticipation once Q5's overlay exists to build on. This is the headliner.
+
+---
+
+## Implementation sketches
+
+### Sketch 1 — Haptic + tactile commit on key-down (Q1+Q2)
+At `WindowMotionMode.swift:833`, before dispatching the grid:
+```swift
+case 5: // G
+    if exposed { gatherInPlace() }
+    else {
+        AppFeedback.shared.commitTactile()   // haptic + sound, synchronous, NOW
+        distributeGroup()                     // remove the playTapSound() from relayoutGroup
+    }
+    return
+```
+New in `AppFeedback`:
+```swift
+func warmUp() {                       // call on motion-mode entry
+    tapSound?.volume = 0; tapSound?.play(); tapSound?.stop(); tapSound?.volume = 1
+}
+func commitTactile() {                // called on the keypress, on main
+    NSHapticFeedbackManager.defaultPerformer.perform(.alignment, performanceTime: .now)
+    tapSound?.currentTime = 0
+    tapSound?.play()                  // no async hop, no stop() gap
+}
+```
+Remove `AppFeedback.shared.playTapSound()` from `relayoutGroup()` (`:1120`) so the feedback is
+owned by the keypress, not the move completion.
+
+### Sketch 2 — Pre-resolved, minimal-freeze batch (Q3+Q4)
+New overload that trusts caller-resolved elements and freezes only the writes:
+```swift
+static func batchSetFrames(_ moves: [(el: AXUIElement, pid: Int32, frame: CGRect, raise: Bool)],
+                           frontmostPid: Int32?) {
+    // app -> enhanced-UI off, BEFORE freeze
+    let pids = Set(moves.map(\.pid))
+    let appRefs = Dictionary(uniqueKeysWithValues: pids.map { ($0, AXUIElementCreateApplication($0)) })
+    appRefs.values.forEach { AXUIElementSetAttributeValue($0, "AXEnhancedUserInterface" as CFString, false as CFTypeRef) }
+
+    let cid = _SLSMainConnectionID?()
+    if let cid { _ = _SLSDisableUpdate?(cid) }          // freeze ONLY the writes
+    for m in moves {
+        setFrameTriplet(m.el, m.frame)                  // size→pos→size
+        if m.raise { AXUIElementPerformAction(m.el, kAXRaiseAction as CFString) }
+    }
+    if let cid { _ = _SLSReenableUpdate?(cid) }         // unfreeze immediately
+
+    appRefs.values.forEach { AXUIElementSetAttributeValue($0, "AXEnhancedUserInterface" as CFString, true as CFTypeRef) }
+    if let frontmostPid { NSRunningApplication(processIdentifier: frontmostPid)?.activate() }  // ONE activate
+}
+```
+`relayoutGroup` already has `el` in hand from `recordOriginal` — collect it into `moves` and
+call this; no second `kAXWindows` enumeration, freeze shrinks to just the set-frame loop.
+
+### Sketch 3 — Overlay snap-pop on selection chrome (Q5)
+On grid landing, per slot, run a layer animation on the existing selection border view (overlay,
+not the window):
+```swift
+let pop = CAKeyframeAnimation(keyPath: "transform.scale")
+pop.values = [1.0, 1.045, 1.0]; pop.keyTimes = [0, 0.45, 1]
+pop.duration = 0.13; pop.timingFunction = CAMediaTimingFunction(name: .easeOut)
+borderLayer.add(pop, forKey: "snapPop")
+// + a one-shot edge tint that fades over the same 0.13s
+```
+No dwell, no AX. Fire it from `refreshAfterGridMove` (`:1125`) so it rides the deferred turn.
+
+### Sketch 4 — Ghost-slot anticipation (B1)
+On `G`, before the move, draw target slots in the motion overlay and animate the picked windows'
+*chrome* (or ghost rects) from current → slot, while `batchSetFrames` runs underneath:
+```swift
+func previewGrid(_ rects: [CGRect]) {     // rects already from balancedGrid → tileFrame
+    for (i, r) in rects.enumerated() {
+        let slot = ghostLayer(at: currentChromeFrame(i))
+        slot.frame = currentChromeFrame(i)
+        CATransaction.begin()
+        CATransaction.setAnimationDuration(0.14)
+        slot.frame = r                      // slides to target as the real window teleports under it
+        CATransaction.commit()
+    }
+}
+```
+Sequence: keypress → `commitTactile()` (Sketch 1) + `previewGrid()` same frame → `batchSetFrames()`
+→ ghosts fade as real windows land → `refreshAfterGridMove`. Felt latency ≈ 0; the move hides
+under 140ms of overlay motion.
+
+### Sketch 5 — Staggered cascade (B3, optional flourish)
+In `previewGrid`/snap-pop, offset each cell's animation `beginTime` by `index * 0.012` in
+row-major order. Overlay-only; the real batch stays simultaneous. Toggle behind a setting if you
+want a "calm" vs "playful" feel.

package/docs/layers.md

@@ -315,6 +315,59 @@ event is broadcast to all connected clients.
 
 More methods in the [Agent API reference](/docs/api).
 
+## Rule-backed Studio layers
+
+Studio layers are live window rules stored in `~/.lattices/layers.json`.
+They are separate from `workspace.json` launch-and-tile layers: Studio
+layers do not launch projects. They resolve matching desktop windows,
+then recall or scope those windows in Studio and Screen Map.
+
+Each layer has a `match` array. A window joins the layer when it matches
+any clause in that array. Inside one clause, every present positive field
+must match, and every clause in `not` must fail.
+
+```json
+[
+  {
+    "id": "review",
+    "name": "Review",
+    "match": [
+      {
+        "appEquals": "Google Chrome",
+        "titleRegex": "(GitHub|Pull Request)",
+        "not": [
+          { "titleContains": "Actions" }
+        ]
+      },
+      {
+        "sessionContains": "lattices",
+        "isOnScreen": true
+      }
+    ]
+  }
+]
+```
+
+Supported clause fields:
+
+| Field | Match |
+|-------|-------|
+| `app` | App name contains this string |
+| `appEquals` | App name exactly equals this string |
+| `appRegex` | App name matches this regular expression |
+| `titleContains` | Window title contains this string |
+| `titleEquals` | Window title exactly equals this string |
+| `titleRegex` | Window title matches this regular expression |
+| `session` | Parsed lattices tmux session exactly equals this string |
+| `sessionContains` | Parsed lattices tmux session contains this string |
+| `isOnScreen` | Window is, or is not, visible on the current Space |
+| `spaceId` | Window belongs to this macOS Space id |
+| `not` | Exclusion clauses; any match rejects the window |
+
+`app` and `titleContains` are the original substring fields, so older
+`layers.json` files continue to work. New layers created from plucked
+windows use `appEquals` by default to avoid accidental substring matches.
+
 ### Layer bar
 
 When a workspace config is loaded, a layer bar appears between the

package/docs/mouse-gestures.md

@@ -12,8 +12,9 @@ Mouse gestures are a user-level shortcut system for the macOS app. Hold a
 configured mouse button, draw a direction or shape, then release to run the
 matched action.
 
-The app code owns the recognizer, action dispatcher, and JSON schema. Your
-actual gesture mappings live in:
+The app code owns the recognizer, action dispatcher, and JSON schema. The
+gesture mappings are data, so agents can define or change hotkeys without
+adding a named action in Swift. Your actual gesture mappings live in:
 
 ```bash
 ~/.lattices/mouse-shortcuts.json
@@ -36,6 +37,16 @@ Do not add personal shortcuts by changing `MouseGestureConfig.swift`. Add them
 to the user JSON file instead. The Settings UI can open that file from
 **Settings -> Shortcuts -> Mouse Gestures -> Configure...**.
 
+Agents should usually write these rules through the daemon:
+
+```js
+await daemonCall('mouse.shortcuts.upsert', { rule })
+```
+
+The daemon persists the rule, snapshots the old config, and refreshes the
+running app immediately. If a tool edits `~/.lattices/mouse-shortcuts.json`
+directly, call `mouse.shortcuts.reload` afterward; no app restart is required.
+
 ## Lightweight History
 
 Lattices keeps local snapshots of your mouse shortcut config before risky
@@ -100,6 +111,32 @@ The circle recognizer is intentionally generous: it looks for broad circular
 motion, a reasonably closed path, and enough turn coverage rather than a
 geometrically perfect circle.
 
+## Default: Dictation Gesture
+
+New default configs use a plain shortcut action for dictation. The middle-button
+up gesture sends the Lattices voice command hotkey, currently Hyper+D:
+
+```json
+{
+  "id": "dictation",
+  "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"]
+    }
+  }
+}
+```
+
 ## Default: Screenshot Area Gesture
 
 New default configs include a back-button circle gesture for the macOS
@@ -139,7 +176,7 @@ Supported action types include:
 | `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` | Start dictation |
+| `dictation.start` | Legacy compatibility alias that presses the configured Voice Command hotkey |
 | `shortcut.send` | Send a keyboard shortcut |
 | `app.activate` | Activate an app by name |
 

package/docs/ocr.md

@@ -65,6 +65,9 @@ lattices search "error"
 # Deep search — also inspects terminal tabs and processes
 lattices search "myproject" --deep
 
+# Same as --deep (all search sources)
+lattices search "myproject" --all
+
 # Search + focus + tile the top result
 lattices place "myproject" left
 

package/docs/prompts/hands-off-system.md

@@ -62,6 +62,11 @@ User: "put my terminals in a grid on the right"
 {"actions": [{"intent": "distribute", "slots": {"app": "iTerm2", "region": "right"}}], "spoken": "Gridding your terminals on the right half."}
 ```
 
+User: "put chrome in the top-right cell of a 4x4 grid"
+```json
+{"actions": [{"intent": "tile_window", "slots": {"wid": 12345, "position": "grid:4x4:3,0"}}], "spoken": "Chrome to the top-right of a 4×4."}
+```
+
 User: "organize my chrome windows on the left"
 ```json
 {"actions": [{"intent": "distribute", "slots": {"app": "Google Chrome", "region": "left"}}], "spoken": "Arranging your Chrome windows on the left."}
@@ -174,8 +179,11 @@ Grid-based tiling. Every position is a cell in a cols×rows grid.
 **3x2 (sixths):** top-left-third, top-center-third, top-right-third, bottom-left-third, bottom-center-third, bottom-right-third
 **4x1 (fourths):** first-fourth, second-fourth, third-fourth, last-fourth
 **4x2 (eighths):** top-first-fourth, top-second-fourth, top-third-fourth, top-last-fourth, bottom-first-fourth, bottom-second-fourth, bottom-third-fourth, bottom-last-fourth
+**4x4 (sixteenths):** no named cells — address them directly with `grid:4x4:C,R` (top-left `grid:4x4:0,0`, top-right `grid:4x4:3,0`, bottom-left `grid:4x4:0,3`, bottom-right `grid:4x4:3,3`, near-center `grid:4x4:1,1`)
+
+For arbitrary grids, use the syntax `grid:CxR:C,R` where C=columns, R=rows, then col,row (0-indexed). Example: `grid:5x3:2,1` = center cell of a 5×3 grid; `grid:4x4:3,0` = top-right of a 4×4 (each cell a sixteenth of the screen).
 
-For arbitrary grids, use the syntax `grid:CxR:C,R` where C=columns, R=rows, then col,row (0-indexed). Example: `grid:5x3:2,1` = center cell of a 5×3 grid.
+To span a window across a rectangular block of cells, address two inclusive corners: `grid:CxR:c0,r0-c1,r1`. Example: `grid:4x4:0,0-1,1` = the top-left 2×2 block (a quarter) of a 4×4 grid; `grid:4x4:0,0-3,1` = the top half. Order doesn't matter — the corners are normalized.
 
 When the user says "quarter" they mean a 2×2 cell (top-left, top-right, etc.), not a 4×1 fourth.
 When they say "third" they usually mean a 3×1 column, but "top third" means the 3×2 row.

package/docs/proposals/LAT-006-followup-gaps.md

@@ -0,0 +1,103 @@
+# LAT-006 Follow-up: Next Use Cases & Gaps (Load / Voice / Type / Click)
+
+Assessment date: 2026-06-17. Scope: current working tree on `main` (uncommitted LAT-006
+runs/capture/computer-use slice). Focus: root-cause product/API shape, not workarounds.
+
+## What exists today (grounded)
+
+A real **observe → act → capture → trace** layer landed (LAT-006 Phase 2 + a computer-use
+extension), wired end to end:
+
+- **Daemon** (`apps/mac/Sources/Core/Daemon/LatticesApi.swift`):
+  - `runs.create | runs.list | runs.get | runs.artifacts`
+  - `capture.screenshotWindow`
+  - `computer.prepare | computer.focusWindow | computer.typeText | computer.showCursor | computer.demoTerminal`
+  - `settings.cursorAppearance.get | .set`
+- **Controllers**: `Core/Actions/ComputerUseController.swift`, `Core/Capture/CaptureController.swift`,
+  `Core/Runs/RunStore.swift` + `RunModels.swift` (persists to `~/Library/Application Support/Lattices/Runs/`, `runs.json` index).
+- **CLI** (`bin/lattices.ts`): `lattices computer|capture|runs|terminals`.
+- **Palette** (`PaletteCommand.swift`): "Screenshot Current Window", "Review Runs" under a new `.run` category → `ScreenMapWindowController.showPage(.runs)` + `RunsReviewView.swift`.
+- **Safety model**: `ComputerTreatment` = observe/stage/present/execute. Typing only targets
+  scored *safe* terminals (avoids claude/codex/vim, requires idle shell for Enter), with a transport
+  ladder: tmux `send-keys` → iTerm session `write text` → pasteboard/key-events (active tab only).
+
+This is a strong foundation. The gaps below are about **shape**, not patching.
+
+## Gaps by focus area (root-cause)
+
+### 1. Loading apps — not a first-class, composable operation
+App/project launch lives only inside the voice `launch` intent → `session.launch`
+(`Intents/LaunchIntent.swift`), with a brittle fallback (capitalize first letter, `NSWorkspace`
+name match; no bundle-id resolution). Root cause: **there is no `apps.launch` daemon verb and no
+"wait until window exists" precondition.** So launching can't be wrapped as a Run, can't be composed
+with capture/type/click, and the computer-use layer can't open a target app before acting on it.
+→ Add `apps.launch` (name/bundleId/project) returning a `RunSession` with surfaces, plus a shared
+`waitForWindow` primitive that `computer.focusWindow/typeText/click` reuse as a precondition.
+
+### 2. Voice/talk flows — the new capabilities are invisible to voice
+`IntentEngine.swift` vocabulary stops at workspace control: tile_window, focus, launch,
+switch_layer, search, list_*, distribute, create_layer, kill, scan, swap, hide, highlight,
+move_to_display, find_mouse, summon_mouse, undo. Root cause: **none of `computer.*`, `capture.*`,
+or `runs.*` is registered as an intent.** Voice can move/observe windows but cannot drive the proof
+loop (screenshot, type, review a run). The slot/dispatch plumbing already exists, so this is additive.
+→ Register `screenshot` → `capture.screenshotWindow`; `type` → `computer.typeText` (default
+`treatment=stage`, require explicit confirm before execute — matches the HandsOff "don't act on
+questions" preference); `show_cursor`/`click` → cursor/click methods; `review_run` → runs page.
+
+### 3. Typing — solid, but terminal-only
+Strongest area. The transport ladder + safety scoring is the right shape. Root-cause limits:
+- Typing targets **terminals exclusively** (`TerminalCandidate` / `ProcessModel.synthesizeTerminals`).
+  There is no "type into the focused text field of app X" (browser URL bar, native field).
+- The pasteboard path saves/restores the clipboard but requires the tab already active; iTerm is
+  explicitly excluded from the keyboard transport, so non-tmux iTerm has no fallback.
+→ Add an AX-based `computer.typeInto` that resolves the focused element / a target text field, keeping
+the terminal path as the specialized *safe* case. This generalizes typing without weakening the
+terminal safety model.
+
+### 4. Clicking around — the verb does not exist
+**There is no click action.** `computer.showCursor` only renders a visual marker; it posts no mouse
+event. The only `CGEvent` mouse code (`Core/Input/MouseGestureController.swift`) *recognizes* gestures
+— it does not synthesize targeted clicks. So the "act" half of the loop for non-terminal targets
+(buttons, links, menu items) is entirely missing. This is the single biggest missing primitive.
+→ Add `computer.click` (+ `computer.moveCursor`) that resolves a target (coordinate, AX element, or
+window+role) and posts left/right down/up via `CGEvent`, wrapped in a Run with before/after capture,
+gated by the same treatment model (observe/stage/present/execute).
+
+### 5. Cross-cutting: the proof loop is open at both ends
+- **Recording not implemented.** Proposal lists `capture.recordWindow/recordRegion` + an AppKit
+  `--recording-probe` (Phase 3); only screenshots exist (`WindowCapture` uses `SCStream` for stills).
+  Also missing: `runs.start`, `runs.stop`.
+- **No verify step.** `typeText` captures before/after screenshots but never asserts the text landed.
+  An OCR/AX diff (reusing the existing `ocr.search`) would close observe → act → **verify** and feed
+  LAT-005 receipts.
+
+## Suggested implementation order (highest leverage first)
+
+1. **`computer.click` + `computer.moveCursor`** — fills the only missing computer-use verb; reuse
+   treatment model + Run wrapper + before/after capture.
+2. **Voice intents over existing `computer.*`/`capture.*`/`runs.*`** — additive, low risk; stage-by-default
+   for any execute, explicit confirm gate.
+3. **`apps.launch` (Run-wrapped) + `waitForWindow` precondition** — unblocks "load app, then act".
+4. **`computer.typeInto` (AX focused-element)** — generalize typing beyond terminals.
+5. **LAT-006 Phase 3 recording probe + `runs.stop`**, then an **OCR/AX verify** step on type/click runs.
+
+## Testing steps
+
+- CLI dogfood (per project convention — test via `lattices`, not raw daemon):
+  `lattices computer prepare`, `lattices computer type --text "ls" --dry-run`, `lattices capture window`,
+  `lattices runs list`, `lattices runs <id> --json`.
+- Treatment matrix: observe/stage/present/execute each produce a Run with correct artifacts and never
+  over-act (stage/observe must not focus or type).
+- Safety regression: `computer.typeText` refuses claude/codex/vim targets; refuses Enter on non-idle shells.
+- Click (new): coordinate click + AX-element click on a known button → before/after artifacts in the run
+  dir; assert no click when `treatment != execute`.
+- Voice: "screenshot this window" / "type ls in my terminal" resolve to the right daemon method; execute
+  paths require confirm.
+- Persistence: confirm `~/Library/Application Support/Lattices/Runs/` + `runs.json` survive an app restart.
+
+## Owner / next move
+
+This is an answer, not a handoff — no other agent needs waking. The clearest single next step that
+unblocks the most use cases is **`computer.click`** (closes the "act" gap for non-terminal targets),
+immediately followed by **exposing the existing computer/capture/run methods to voice**. Both are owned
+by the Lattices macOS app. Recording + verify are the right Phase-3 follow-ups once click + voice land.