@arach/lattices 0.2.0 → 0.6.1

package/docs/agent-layer-guide.md

@@ -0,0 +1,207 @@
+# Agent Guide: Generating Layers
+
+How to create and manage Lattices workspace layers programmatically. This guide is for AI agents (Claude Code, etc.) that want to generate layers from high-level user descriptions.
+
+## Quick Reference
+
+```bash
+# See what's on screen
+lattices windows --json
+
+# Create a layer with tiling
+lattices layer create "Design" --json '[
+  {"app": "Figma", "tile": "left"},
+  {"app": "Google Chrome", "title": "Tailwind", "tile": "right"}
+]'
+
+# Snapshot current windows as a layer
+lattices layer snap "my-context"
+
+# List / switch / delete session layers
+lattices layer session
+lattices layer session "Design"
+lattices layer delete "Design"
+lattices layer clear
+```
+
+## How It Works
+
+There are two kinds of layers:
+
+| Type | Storage | Requires restart? | How to create |
+|------|---------|-------------------|---------------|
+| **Config layers** | `~/.lattices/workspace.json` | Yes (or refresh) | Edit JSON file |
+| **Session layers** | In-memory (daemon) | No | CLI or daemon API |
+
+**Session layers are what you want.** They're created via TypeScript CLI commands, take effect immediately, and don't require restarting anything.
+
+## Step-by-Step: Generating a Layer
+
+### 1. Discover what's available
+
+```bash
+lattices windows --json
+```
+
+Returns an array of window objects:
+```json
+[
+  {
+    "wid": 1234,
+    "app": "iTerm2",
+    "title": "lattices — zsh",
+    "latticesSession": "lattices-abc123",
+    "frame": { "x": 0, "y": 25, "w": 960, "h": 1050 },
+    "spaceIds": [1]
+  },
+  {
+    "wid": 5678,
+    "app": "Google Chrome",
+    "title": "GitHub - arach/lattices",
+    "frame": { "x": 960, "y": 25, "w": 960, "h": 1050 },
+    "spaceIds": [1]
+  }
+]
+```
+
+Key fields for matching:
+- `wid` — unique window ID (most precise)
+- `app` — application name
+- `title` — window title (use for disambiguation when multiple windows of same app)
+- `latticesSession` — tmux session name (for terminal windows)
+
+### 2. Decide on a layout
+
+Pick tile positions based on how many windows and what makes sense:
+
+| Windows | Good layout | Tile values |
+|---------|-------------|-------------|
+| 2 | Side by side | `left`, `right` |
+| 2 | Stacked | `top`, `bottom` |
+| 3 | Main + sidebar | `left` (60%), `top-right`, `bottom-right` |
+| 3 | Columns | `left-third`, `center-third`, `right-third` |
+| 4 | Quadrants | `top-left`, `top-right`, `bottom-left`, `bottom-right` |
+| 1 | Focused | `maximize` or `center` |
+
+Full position reference:
+- **Halves**: `left`, `right`, `top`, `bottom`
+- **Quarters**: `top-left`, `top-right`, `bottom-left`, `bottom-right`
+- **Thirds**: `left-third`, `center-third`, `right-third`
+- **Sixths**: `top-left-third`, `top-center-third`, `top-right-third`, `bottom-left-third`, `bottom-center-third`, `bottom-right-third`
+- **Fourths**: `first-fourth`, `second-fourth`, `third-fourth`, `last-fourth`
+- **Special**: `maximize`, `center`
+- **Custom grid**: `grid:CxR:C,R` (e.g. `grid:5x3:2,1`)
+
+### 3. Create the layer
+
+**Option A: By window ID (most reliable)**
+```bash
+lattices layer create "Coding" --json '[
+  {"wid": 1234, "tile": "left"},
+  {"wid": 5678, "tile": "right"}
+]'
+```
+
+**Option B: By app name (survives window recreation)**
+```bash
+lattices layer create "Research" --json '[
+  {"app": "Google Chrome", "title": "docs", "tile": "left"},
+  {"app": "Notes", "tile": "right"}
+]'
+```
+
+**Option C: Simple wid list (no tiling)**
+```bash
+lattices layer create "Focus" wid:1234 wid:5678
+```
+
+**Option D: Snapshot everything visible**
+```bash
+lattices layer snap "Current Context"
+```
+
+### 4. Switch between layers
+
+```bash
+lattices layer session          # list all session layers
+lattices layer session "Coding" # switch to "Coding"
+lattices layer session 0        # switch by index
+```
+
+## Daemon API (Advanced)
+
+For finer control, use raw daemon calls:
+
+```bash
+# Create layer with window IDs
+lattices call session.layers.create '{"name":"Coding","windowIds":[1234,5678]}'
+
+# Create layer with app references
+lattices call session.layers.create '{"name":"Design","windows":[{"app":"Figma"},{"app":"Google Chrome","contentHint":"Tailwind"}]}'
+
+# Tile a specific window
+lattices call window.place '{"wid":1234,"placement":"left"}'
+
+# Switch layer
+lattices call session.layers.switch '{"name":"Coding"}'
+
+# List session layers
+lattices call session.layers.list
+
+# Delete
+lattices call session.layers.delete '{"name":"old-layer"}'
+```
+
+## Composing Layers from Intent
+
+When a user says something high-level, here's how to think about it:
+
+### "Make me a coding layer"
+1. Find terminal windows (iTerm2, Terminal, Warp, etc.)
+2. Find browser windows with dev-related titles (GitHub, docs, localhost)
+3. Main editor/terminal on `left`, reference material on `right`
+
+### "Set up a design layer"
+1. Find design tools (Figma, Sketch, Adobe XD)
+2. Find browser windows with design references
+3. Design tool `left` (or `maximize`), references `right`
+
+### "Create a writing layer"
+1. Find text editors, notes apps (Notes, Obsidian, iA Writer, VS Code with .md)
+2. Find research/reference windows
+3. Writing app `left` or `center`, references `right`
+
+### "Give me a communication layer"
+1. Find messaging apps (Slack, Discord, Messages)
+2. Find email (Mail, Gmail in browser)
+3. Arrange by priority — primary tool `left`, secondary `right`
+
+### "Split my work into layers by project"
+1. Group windows by project (match on title keywords, session names, or app)
+2. Create one layer per project group
+3. Use the 3-window layout pattern: main `left`, support `top-right`, `bottom-right`
+
+## App Grouping Heuristics
+
+When deciding which windows go together:
+
+| Category | Common apps | Goes well with |
+|----------|-------------|----------------|
+| **Code** | iTerm2, Terminal, VS Code, Xcode | Chrome (docs/GitHub), Simulator |
+| **Design** | Figma, Sketch, Pixelmator | Chrome (design systems), Preview |
+| **Writing** | Notes, Obsidian, iA Writer | Chrome (research), Preview |
+| **Communication** | Slack, Discord, Messages, Mail | Calendar, Notes |
+| **Media** | Spotify, Music, Podcasts | (background, no tile needed) |
+| **Reference** | Chrome, Safari, Preview, Finder | (depends on content) |
+
+Browser windows are chameleons — use `title` matching to assign them to the right layer based on their content.
+
+## Tips
+
+- Prefer `wid` when the windows are already open — it's unambiguous.
+- Use `app` + `title` when you want the layer to survive window restarts.
+- Don't put more than 4-5 windows in a single layer — it gets cramped.
+- Background apps (music, etc.) usually don't need to be in any layer.
+- The `snap` command is great for "save what I have now" scenarios.
+- Session layers are ephemeral — they live until the daemon restarts. For permanent layers, edit `~/.lattices/workspace.json`.
+- You can create multiple layers in sequence, then switch between them with `lattices layer session <name>`.

package/docs/agents.md

@@ -0,0 +1,233 @@
+---
+title: Agent Guide
+description: Canonical contracts for agents using docs URLs, CLI, voice, and the daemon API
+order: 6
+---
+
+Lattices exposes the same execution model through four surfaces:
+
+- **Docs URLs** for discovery and citation
+- **CLI** for shell-based agents
+- **Daemon API** for typed programmatic control
+- **Voice / hands-off / HUD** as clients of the same execution layer
+
+The rule is simple: agents should learn the **canonical action model**
+first, then choose the transport that fits the environment.
+
+## Canonical mutations
+
+These are the preferred action identifiers:
+
+| Action | Purpose | Preferred surface |
+|--------|---------|-------------------|
+| `window.place` | Place a window or session using a typed placement spec | `actions.execute` |
+| `layer.activate` | Bring up a workspace layer with explicit activation mode | Daemon API |
+| `space.optimize` | Rebalance a set of windows using an explicit scope and strategy | Daemon API |
+
+Compatibility wrappers still exist:
+
+| Legacy method | Canonical equivalent |
+|---------------|----------------------|
+| `window.place` | `actions.execute` with `type=window.place` |
+| `window.tile` | `window.place` |
+| `layer.switch` | `layer.activate` with `mode=launch` |
+| `layout.distribute` | `space.optimize` with `scope=visible`, `strategy=balanced` |
+
+## Discoverability
+
+Agents should use these paths in order:
+
+1. **API schema**: `lattices call api.schema`
+2. **Daemon reference**: [/docs/api](/docs/api)
+3. **Agent guide**: [/docs/agents](/docs/agents)
+4. **Voice model**: [/docs/voice](/docs/voice)
+5. **Concepts / config**: [/docs/concepts](/docs/concepts), [/docs/config](/docs/config)
+
+Useful CLI discovery commands:
+
+```bash
+lattices help
+lattices call api.schema
+lattices voice intents
+```
+
+For window actions, resolve before mutating when target identity matters:
+
+```bash
+lattices call window.resolve '{"target":{"kind":"session","session":"frontend-a1b2c3"},"placement":"left"}'
+lattices call actions.execute '{"type":"window.place","target":{"kind":"session","session":"frontend-a1b2c3"},"args":{"placement":"left"},"dryRun":true}'
+```
+
+`window.resolve` and `dryRun` return the resolved `wid`, app/title,
+target resolution path, display, and planned frame without moving the
+window.
+
+Verified `window.place` receipts include `undoable: true` when Lattices
+captured a concrete window id and previous frame. Agents can restore the
+latest undoable placement, or an entire request batch, through:
+
+```bash
+lattices call actions.undo '{}'
+lattices call actions.undo '{"requestId":"req_..."}'
+lattices call actions.undo '{"receiptId":"exec_...","dryRun":true}'
+```
+
+Undo checks that the window is still where the original receipt left it
+before restoring the previous frame. Pass `force:true` only when the
+caller intentionally wants to override a later manual move.
+
+## Agent documentation artifacts
+
+The site build emits agent-first files in addition to rendered pages.
+Use these when an agent needs raw markdown, prompt text, or a compact
+context bundle without scraping HTML.
+
+| Need | URL |
+|------|-----|
+| Discovery manifest | `/agent/manifest.json` or `/docs.json` |
+| Full docs with markdown bodies | `/agent/docs.json` or `/agent-docs.json` |
+| Prompt registry | `/agent/prompts.json` or `/prompts.json` |
+| Combined agent context | `/agent/context.md` or `/agent-context.md` |
+| Combined raw docs | `/agent/bundles/all.md` or `/docs/all.md` |
+| Core onboarding bundle | `/agent/bundles/core.md` |
+| Daemon/API bundle | `/agent/bundles/daemon-api.md` |
+| Voice and prompts bundle | `/agent/bundles/voice.md` |
+| Install bundle | `/agent/bundles/install.md` |
+| Raw markdown mirror | `/agent/raw/docs/<slug>.md` or `/docs/markdown/<slug>.md` |
+
+Prompt files are mirrored at `/prompts/<id>.md` and
+`/docs/prompts/<id>.md`. Nested docs keep path-safe slugs, for example
+`docs/reference/install-agent.md` becomes
+`/agent/raw/docs/reference/install-agent.md`.
+
+Local scripts can import the same convenience functions used by the
+build:
+
+```js
+import {
+  collectMarkdownArtifacts,
+  getMarkdownDoc,
+  getPrompt,
+  buildAgentManifest,
+  buildPromptRegistry,
+  buildContextBundle,
+  writeAgentArtifacts,
+} from './apps/site/scripts/agent-docs.mjs'
+```
+
+Run `bun run docs:agent` to regenerate the static artifacts without
+running the full site build.
+
+## Placement contract
+
+At the boundary, placements may be strings for convenience.
+Inside the daemon, the canonical contract is typed.
+
+String shorthand:
+
+```json
+{ "placement": "top-right" }
+{ "placement": "grid:3x2:2,0" }
+```
+
+Typed placement objects:
+
+```json
+{ "placement": { "kind": "tile", "value": "top-third" } }
+{ "placement": { "kind": "grid", "columns": 3, "rows": 2, "column": 2, "row": 0 } }
+{ "placement": { "kind": "fractions", "x": 0.5, "y": 0, "w": 0.5, "h": 1 } }
+```
+
+This lets voice stay natural while the executor stays explicit.
+
+## Choosing a surface
+
+Use the **daemon API** when you need:
+
+- typed receipts and traces
+- explicit targeting by `wid`, `session`, or `app`
+- composition across layers, windows, and optimization
+
+Use the **CLI** when you need:
+
+- one-shot shell execution
+- quick discovery from inside an agent terminal
+- compatibility with environments that already have `lattices`
+
+Use **docs URLs** when an agent needs:
+
+- a citeable contract
+- a stable page to open in a browser or pass to another agent
+- quick onboarding without reading source
+
+## Examples
+
+Node.js:
+
+```js
+import { daemonCall } from '@lattices/cli'
+
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('window.resolve', {
+  target: { kind: 'session', session: 'frontend-a1b2c3' },
+  placement: 'left'
+})
+await daemonCall('actions.execute', {
+  type: 'window.place',
+  target: { kind: 'session', session: 'frontend-a1b2c3' },
+  args: { placement: { kind: 'tile', value: 'left' } }
+})
+await daemonCall('layer.activate', { name: 'review', mode: 'launch' })
+await daemonCall('space.optimize', { scope: 'visible', strategy: 'balanced' })
+```
+
+CLI:
+
+```bash
+lattices call api.schema
+lattices call window.resolve '{"target":{"kind":"session","session":"frontend-a1b2c3"},"placement":"left"}'
+lattices call actions.execute '{"type":"window.place","target":{"kind":"frontmost"},"args":{"placement":"left"}}'
+lattices call window.place '{"session":"frontend-a1b2c3","placement":"left"}'
+lattices call layer.activate '{"name":"review","mode":"launch"}'
+lattices call space.optimize '{"scope":"visible","strategy":"balanced"}'
+```
+
+## Receipts and traceability
+
+Mutating daemon calls should return structured receipts when possible.
+The important fields for agents are:
+
+- resolved target
+- resolved placement / scope / mode
+- affected window IDs
+- computed plan and applied mutations
+- verification status
+- trace entries explaining why the daemon chose that path
+
+This is what keeps voice, hands-off, and scripted execution scrutable.
+
+## Voice and hands-off
+
+Voice is not a separate execution system. It should compile into the
+same canonical actions:
+
+- "put Terminal in the upper third" → `window.place`
+- "bring up review" → `layer.activate`
+- "make this nice" → `space.optimize`
+
+That keeps the interaction layer flexible while the executor stays
+predictable.
+
+## Assistant intelligence boundary
+
+Assistant planning lives in TypeScript where possible:
+
+- `bin/assistant-intelligence.ts` owns the intent catalog, prompt assembly,
+  local rule planner, desktop snapshot formatting, and plan normalization.
+- `bin/handsoff-worker.ts` and `bin/handsoff-infer.ts` call that module before
+  falling back to model inference.
+- Swift should remain the macOS execution layer: hotkeys, windows, AX/CG,
+  SkyLight, panels, and visual feedback.
+
+Use `lattices assistant plan <text> --json` to inspect the TS planner without
+launching the app or mutating the desktop.