@lattices/cli 0.3.0 → 0.4.1

package/docs/config.md

@@ -141,9 +141,13 @@ Run `lattices init` in your project directory to generate a starter
 | `lattices windows [--json]`  | List all visible windows                          |
 | `lattices window assign <wid> <layer>` | Tag a window to a layer                |
 | `lattices window map [--json]` | Show all window→layer assignments                |
+| `lattices search <query>`      | Search windows by title, app, session, OCR       |
+| `lattices search <q> --deep`   | Deep search: index + live terminal inspection    |
+| `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        |
 | `lattices scan search <query>` | Search indexed screen text                       |
 | `lattices diag [limit]`       | Show recent diagnostic entries                   |
-| `lattices focus <session>`   | Focus a session's window and switch Spaces        |
 | `lattices app`               | Launch the menu bar companion app                 |
 | `lattices app build`         | Rebuild the menu bar app from source              |
 | `lattices app restart`       | Rebuild and relaunch the menu bar app             |

package/docs/handsoff-test-scenarios.md

@@ -0,0 +1,84 @@
+# Hands-Off Mode — Test Scenarios
+
+Press Ctrl+Cmd+M, say the phrase, press Ctrl+Cmd+M again. Check the result.
+
+## 1. Basic awareness
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 1.1 | "What's the frontmost window?" | Names the app + project/title, no wid | Correct window? No numbers? |
+| 1.2 | "How many monitors do I have?" | Correct count + sizes | Matches reality? |
+| 1.3 | "What terminals do I have open?" | Lists terminals with projects/cwds | Does it know the projects? |
+| 1.4 | "Which ones are running Claude Code?" | Lists only Claude terminals + their projects | Correct? Uses hasClaude? |
+| 1.5 | "What's on my second monitor?" | Describes windows on the non-main display | Correct display? |
+
+## 2. Simple tiling
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 2.1 | "Tile Chrome left" | Chrome moves to left half | Did it move? Spoken confirmation? |
+| 2.2 | "Put iTerm on the right" | iTerm moves to right half | Correct window? |
+| 2.3 | "Maximize this window" | Frontmost window maximizes | Right window? |
+| 2.4 | "Center the Finder window" | Finder centers | Correct? |
+
+## 3. Multi-window layouts
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 3.1 | "Split Chrome and iTerm" | Chrome left, iTerm right | Both move? Spoken narration? |
+| 3.2 | "Put everything in a grid" | distribute intent fires | Windows arrange? |
+| 3.3 | "Thirds with Chrome, iTerm, and Finder" | Three apps in left/center/right thirds | Correct apps + positions? |
+| 3.4 | "Quadrants" | Four windows in corners | Reasonable choices? |
+
+## 4. Focus + switching
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 4.1 | "Focus on Slack" | Slack comes to front | Did it switch? |
+| 4.2 | "Switch to Chrome" | Chrome comes to front | Correct? |
+| 4.3 | "Go to the lattices terminal" | Focuses the iTerm in ~/dev/lattices | Right terminal? |
+| 4.4 | "Show me the Hudson Claude Code" | Focuses iTerm with hasClaude + cwd hudson | Correct? |
+
+## 5. Conversational context
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 5.1 | "Tile Chrome left" then "Now put iTerm on the right" | Two separate turns, both work | Context from turn 1 used? |
+| 5.2 | "Tile Chrome left" then "Swap them" | Chrome right, iTerm left | Understood "them"? |
+| 5.3 | "What terminals do I have?" then "Organize those" | Lists, then distributes the terminals | Connected the turns? |
+| 5.4 | "Put it back" (after any tiling) | Reverses last action | Worked? (may not be supported yet) |
+
+## 6. Intelligence
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 6.1 | "Set up for coding" | Intelligent layout based on visible apps | Reasonable? Explained reasoning? |
+| 6.2 | "I'm going to do a code review" | Suggests/applies review layout | Smart choice? |
+| 6.3 | "Clean up my desktop" | Distributes or suggests organization | Actionable? |
+| 6.4 | "Too many windows, simplify" | Suggests hiding some, focuses key ones | Reasonable? |
+
+## 7. Error handling
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 7.1 | "Focus on Firefox" | "I don't see Firefox. You have Chrome and Safari." | Honest? Names real apps? |
+| 7.2 | "Tile the Photoshop window" | "Photoshop isn't open right now." | No hallucination? |
+| 7.3 | (mumble something unclear) | "I didn't catch that. Can you say it again?" | Graceful? |
+
+## 8. Actions actually execute
+
+| # | Say | Expected | Check |
+|---|-----|----------|-------|
+| 8.1 | "Distribute my windows" | spoken + distribute action | Actions array not empty? |
+| 8.2 | "Organize my terminals" | spoken + distribute or tile actions | Actions actually fire? |
+| 8.3 | Any action command | Hear narration BEFORE windows move | Sequence correct? |
+
+## Scoring
+
+For each test:
+- ✅ Works correctly
+- ⚠️ Partially works (note what's wrong)
+- ❌ Broken (note error)
+- 🔇 No audio feedback
+
+Track in a copy of this file or in the terminal.

package/docs/layers.md

@@ -28,13 +28,13 @@ Add `groups` to `~/.lattices/workspace.json`:
   "name": "my-setup",
   "groups": [
     {
-      "id": "talkie",
-      "label": "Talkie",
+      "id": "vox",
+      "label": "Vox",
       "tabs": [
-        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
-        { "path": "/Users/you/dev/talkie-macos", "label": "macOS" },
-        { "path": "/Users/you/dev/talkie-web", "label": "Website" },
-        { "path": "/Users/you/dev/talkie-api", "label": "API" }
+        { "path": "/Users/you/dev/vox-ios", "label": "iOS" },
+        { "path": "/Users/you/dev/vox-macos", "label": "macOS" },
+        { "path": "/Users/you/dev/vox-web", "label": "Website" },
+        { "path": "/Users/you/dev/vox-api", "label": "API" }
       ]
     }
   ]
@@ -46,10 +46,10 @@ to per-project configs.
 
 ### How it works
 
-- Session name follows the pattern `lattices-group-<id>` (e.g. `lattices-group-talkie`)
+- Session name follows the pattern `lattices-group-<id>` (e.g. `lattices-group-vox`)
 - 1 group = 1 tmux session. Each tab is a tmux window, and each window
   gets its own panes from that project's `.lattices.json`
-- You can still launch projects independently: `cd talkie-ios && lattices`
+- You can still launch projects independently: `cd vox-ios && lattices`
   creates its own standalone session as before
 
 ### Tab group fields
@@ -73,9 +73,9 @@ lattices tab <group> [tab]  # Switch tab by label or index
 Examples:
 
 ```bash
-lattices group talkie       # Launch all Talkie tabs
-lattices tab talkie iOS     # Switch to the iOS tab
-lattices tab talkie 0       # Switch to first tab (by index)
+lattices group vox       # Launch all Vox tabs
+lattices tab vox iOS     # Switch to the iOS tab
+lattices tab vox 0       # Switch to first tab (by index)
 ```
 
 ### Menu bar app
@@ -151,7 +151,7 @@ fields instead of `path`:
       "label": "Main",
       "projects": [
         { "app": "Google Chrome", "title": "GitHub", "tile": "left" },
-        { "app": "Talkie", "tile": "top-right", "launch": "open -a Talkie" },
+        { "app": "Vox", "tile": "top-right", "launch": "open -a Vox" },
         { "path": "/Users/you/dev/frontend", "tile": "bottom-right" }
       ]
     },
@@ -182,11 +182,11 @@ This lets you tile a whole group into a screen position:
   "name": "my-setup",
   "groups": [
     {
-      "id": "talkie",
-      "label": "Talkie",
+      "id": "vox",
+      "label": "Vox",
       "tabs": [
-        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
-        { "path": "/Users/you/dev/talkie-web", "label": "Website" }
+        { "path": "/Users/you/dev/vox-ios", "label": "iOS" },
+        { "path": "/Users/you/dev/vox-web", "label": "Website" }
       ]
     }
   ],
@@ -195,7 +195,7 @@ This lets you tile a whole group into a screen position:
       "id": "main",
       "label": "Main",
       "projects": [
-        { "group": "talkie", "tile": "top-left" },
+        { "group": "vox", "tile": "top-left" },
         { "path": "/Users/you/dev/design-system", "tile": "right" }
       ]
     }
@@ -204,7 +204,7 @@ This lets you tile a whole group into a screen position:
 ```
 
 When switching to this layer, lattices launches (or focuses) the
-"talkie" group session and tiles it to the top-left quarter, alongside
+"vox" group session and tiles it to the top-left quarter, alongside
 the design-system project on the right.
 
 ### Layer fields
@@ -340,7 +340,7 @@ header and search field in the menu bar panel:
 ```json
 {
   "projects": [
-    { "path": "/Users/you/dev/talkie" }
+    { "path": "/Users/you/dev/vox" }
   ]
 }
 ```
@@ -374,7 +374,7 @@ No `tile` — just focuses the window wherever it is.
 ```json
 {
   "projects": [
-    { "group": "talkie", "tile": "left" },
+    { "group": "vox", "tile": "left" },
     { "path": "/Users/you/dev/api", "tile": "right" }
   ]
 }

package/docs/ocr.md

@@ -59,17 +59,26 @@ contextual snippets.
 ### From the CLI
 
 ```bash
+# Search windows by title, app, session, and OCR content
+lattices search "error"
+
+# Deep search — also inspects terminal tabs and processes
+lattices search "myproject" --deep
+
+# Search + focus + tile the top result
+lattices place "myproject" left
+
 # View current OCR snapshot
-lattices ocr
+lattices scan
 
-# Search OCR history
-lattices ocr search "error OR failed"
+# Search OCR history directly (FTS5 syntax)
+lattices scan search "error OR failed"
 
 # Trigger an immediate deep scan
-lattices ocr scan
+lattices scan deep
 
 # View OCR history for a specific window ID
-lattices ocr history 12345
+lattices scan history 12345
 ```
 
 ### From the agent API

package/docs/overview.md

@@ -65,7 +65,10 @@ Agents get the same control programmatically:
 ```js
 import { daemonCall } from '@lattices/cli'
 await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
-await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+await daemonCall('window.place', {
+  session: 'frontend-a1b2c3',
+  placement: { kind: 'tile', value: 'left' }
+})
 ```
 
 ## Who it's for
@@ -91,4 +94,5 @@ await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' }
 - [Configuration](/docs/config): `.lattices.json` format and CLI commands
 - [Screen scanning](/docs/ocr): AX text extraction, Vision OCR, and full-text search
 - [Concepts](/docs/concepts): architecture, glossary, and how it all works
+- [Agent Guide](/docs/agents): canonical action contracts for voice, CLI, and daemon clients
 - [Agent API](/docs/api): RPC method reference for agents and scripts