📝 Dewey-driven docs overhaul: fix drift, add missing endpoints, restructure

arach · arach · commit 3e6593d59381 · 2026-03-03T14:01:40.000-05:00
- Add exports map to package.json so @arach/lattices/daemon-client resolves
- Fix all import paths from 'lattices/...' to '@arach/lattices/...'
- Add 6 missing API endpoints: processes.list/tree, terminals.list/search,
  api.schema, layout.distribute
- Fix event data shapes (windows.changed, tmux.changed) to match source
- Add 4th event (processes.changed), correct counts to 26 methods / 4 events
- Add left-third, center-third, right-third tile positions across all docs
- Add API method index table and error handling example
- Fix timeout default (3000ms not 5000ms)
- Restructure Concepts glossary from 9 h3s to a single table
- Remove duplicate h1 titles from all 7 doc pages
- Update quickstart install to npm install -g @arach/lattices
diff --git a/docs/api.md b/docs/api.md
diff --git a/docs/app.md b/docs/app.md
@@ -4,8 +4,6 @@ description: Command palette, window tiling, and session management
 order: 3
 ---
 
-# Menu Bar App
-
 The lattices menu bar app is a native macOS companion that lives in your
 menu bar and gives you quick access to all your lattices sessions.
 
@@ -125,6 +123,9 @@ frontmost window.
 | Bottom Left  | Bottom-left quarter             |
 | Bottom Right | Bottom-right quarter            |
 | Maximize     | Full visible screen             |
+| Left Third   | Left third                      |
+| Center Third | Center third                    |
+| Right Third  | Right third                     |
 | Center       | 70% width, 80% height, centered |
 
 ## Space navigation
@@ -215,7 +216,7 @@ lattices daemon status
 Or programmatically:
 
 ```js
-import { isDaemonRunning, daemonCall } from 'lattices/daemon-client'
+import { isDaemonRunning, daemonCall } from '@arach/lattices/daemon-client'
 
 if (await isDaemonRunning()) {
   const status = await daemonCall('daemon.status')
@@ -225,10 +226,10 @@ if (await isDaemonRunning()) {
 
 ### What it provides
 
-- **20 RPC methods** — read windows, sessions, projects, spaces, layers;
+- **26 RPC methods** — read windows, sessions, projects, spaces, layers, processes, terminals;
   launch/kill/sync sessions; tile/focus/move windows; switch layers;
   manage tab groups
-- **3 real-time events** — `windows.changed`, `tmux.changed`,
+- **4 real-time events** — `windows.changed`, `tmux.changed`, `processes.changed`,
   `layer.switched` — broadcast to all connected clients
 - **Window tracking** — the daemon monitors the desktop window list
   and correlates windows to lattices sessions via title tags
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -4,84 +4,20 @@ description: Core ideas, glossary, and architecture of lattices
 order: 1
 ---
 
-# Concepts
-
-## What is lattices?
-
-lattices is a developer workspace launcher. It creates pre-configured
-terminal layouts for your projects using tmux, so you can go from
-"I want to work on X" to a full development environment in one click.
-
-It has two parts:
-
-1. **CLI** (`lattices`) — creates and manages tmux sessions from the terminal
-2. **Menu bar app** — a native macOS companion for launching, tiling,
-   and navigating sessions with a command palette
-
 ## Glossary
 
-### Daemon
-The lattices daemon is a WebSocket server (`ws://127.0.0.1:9399`) that
-runs inside the menu bar app. It exposes 20 RPC methods and 3 real-time
-events, giving scripts and AI agents full programmatic control over
-sessions, windows, layers, and projects. See the
-[API reference](/docs/api).
-
-### Agent
-Any program that calls the daemon API to control the workspace
-autonomously — an AI coding agent, a shell script, a CI pipeline,
-or a custom tool. Agents can discover projects, launch sessions, tile
-windows, switch layers, and react to real-time events without human
-interaction.
-
-### Session
-A tmux session is a persistent workspace that lives in the background.
-It survives terminal crashes, disconnects, and even closing your laptop.
-Think of it as a virtual desktop for a single project.
-
-### Pane
-A pane is a single terminal view inside a session. A typical lattices
-setup has two panes side by side — one running Claude Code and one
-running your dev server. You can have up to four or more.
-
-### Attach / Detach
-Attaching connects your terminal window to an existing session.
-Detaching disconnects your terminal but keeps the session alive.
-Your dev server keeps running, Claude keeps thinking — nothing is lost.
-
-### tmux
-tmux (terminal multiplexer) is the engine behind lattices. It manages
-sessions, panes, and layouts. lattices configures tmux for you so you
-don't need to learn tmux commands — but knowing a few shortcuts helps.
-
-### Multiplexer
-A program that lets you run multiple terminal sessions inside a single
-window and switch between them. tmux is the most popular one.
-
-### Sync / Reconcile
-Sync (`lattices sync`) brings a running session back in line with its
-declared config. It recreates missing panes, re-applies the layout,
-restores labels, and re-runs commands in idle panes. Useful when a pane
-was accidentally killed but you don't want to restart the whole session.
-
-### Ensure / Prefill
-Two modes for restoring exited commands when you reattach to a session:
-
-- **Ensure** — automatically re-runs the command (hands-free recovery)
-- **Prefill** — types the command into the pane but waits for you to
-  press Enter (manual confirmation)
-
-Set via `"ensure": true` or `"prefill": true` in `.lattices.json`.
-
-### Command Palette
-The menu bar app's primary interface, opened with **Cmd+Shift+M**.
-A searchable list of actions: launch/attach projects, tile windows,
-sync sessions, restart panes, open settings.
-
-### Window Tiling
-Both the CLI (`lattices tile`) and the menu bar app can snap terminal
-windows to preset screen positions (halves, quarters, maximize, center).
-Tiling uses AppleScript bounds and respects the menu bar and dock.
+| Term | Definition |
+|------|------------|
+| **Session** | A persistent tmux workspace that lives in the background. Survives terminal crashes, disconnects, and closing your laptop. One session per project. |
+| **Pane** | A single terminal view inside a session. A typical setup has two panes side by side — Claude Code on the left, dev server on the right. |
+| **Attach / Detach** | Attaching connects your terminal to an existing session. Detaching disconnects but keeps the session alive — your dev server keeps running, Claude keeps thinking. |
+| **Daemon** | WebSocket server (`ws://127.0.0.1:9399`) inside the menu bar app. Exposes 26 RPC methods and 4 real-time events for programmatic control. See the [API reference](/docs/api). |
+| **Agent** | Any program that calls the daemon API autonomously — an AI coding agent, a shell script, a CI pipeline, or a custom tool. |
+| **Sync / Reconcile** | `lattices sync` brings a running session back in line with its declared config — recreates missing panes, re-applies layout, restores labels, re-runs commands in idle panes. |
+| **Ensure / Prefill** | Two modes for restoring exited commands on reattach. **Ensure** auto-reruns the command. **Prefill** types it but waits for you to press Enter. Set via `.lattices.json`. |
+| **Command Palette** | The menu bar app's primary interface (**Cmd+Shift+M**). Searchable list of actions: launch, tile, sync, restart, settings. |
+| **Window Tiling** | Snap terminal windows to preset screen positions (halves, quarters, thirds, maximize, center). Works from the CLI (`lattices tile`) or the command palette. |
+| **tmux** | Terminal multiplexer — the engine behind lattices. Manages sessions, panes, and layouts. lattices configures it for you. |
 
 ## How it works
 
@@ -98,7 +34,7 @@ Tiling uses AppleScript bounds and respects the menu bar and dock.
 
 ```
 ┌─────────────────────────────┐
-│  AI Agents / Scripts        │  ← daemon API: 20 RPC methods, real-time events
+│  AI Agents / Scripts        │  ← daemon API: 26 RPC methods, real-time events
 ├─────────────────────────────┤
 │  Menu bar app (Swift/AppKit)│  ← GUI: command palette, tiling, project list
 ├─────────────────────────────┤
@@ -184,27 +120,16 @@ agents the same capabilities as a human using the menu bar app:
 - **Discover** — list projects, sessions, windows, and Spaces
 - **Launch** — start sessions for any scanned project
 - **Arrange** — tile windows to screen positions, move between Spaces
-- **Monitor** — subscribe to `windows.changed`, `tmux.changed`, and
-  `layer.switched` events for real-time workspace awareness
+- **Monitor** — subscribe to `windows.changed`, `tmux.changed`,
+  `layer.switched`, and `processes.changed` events for real-time
+  workspace awareness
 - **Recover** — sync sessions back to their declared config, restart
   failed panes
 
 An orchestrator agent can set up an entire multi-project workspace in
-a few calls:
-
-```js
-import { daemonCall } from 'lattices/daemon-client'
-
-await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
-await daemonCall('session.launch', { path: '/Users/you/dev/api' })
-
-const sessions = await daemonCall('tmux.sessions')
-await daemonCall('window.tile', { session: sessions[0].name, position: 'left' })
-await daemonCall('window.tile', { session: sessions[1].name, position: 'right' })
-```
-
-See the [Daemon API reference](/docs/api) for the full method list,
-event shapes, and integration patterns.
+a few `daemonCall()` invocations — launching sessions, tiling windows,
+and switching layers. See the [Daemon API reference](/docs/api) for the
+full method list, code examples, and integration patterns.
 
 ## Key shortcuts (inside tmux)
 
diff --git a/docs/config.md b/docs/config.md
@@ -4,8 +4,6 @@ description: CLI commands, .lattices.json format, and tile positions
 order: 2
 ---
 
-# Configuration
-
 ## .lattices.json
 
 Place a `.lattices.json` file in your project root to define your
@@ -225,6 +223,9 @@ screen position. Available positions:
 | `bottom-left`  | Bottom-left quarter         |
 | `bottom-right` | Bottom-right quarter        |
 | `maximize`     | Full screen (visible area)  |
+| `left-third`   | Left third                  |
+| `center-third` | Center third                |
+| `right-third`  | Right third                 |
 | `center`       | 70% width, 80% height, centered |
 
 Aliases: `left-half`/`left`, `right-half`/`right`, `top-half`/`top`,
diff --git a/docs/layers.md b/docs/layers.md
@@ -4,8 +4,6 @@ description: Group projects into switchable layers and tabbed groups
 order: 4
 ---
 
-# Workspace Layers & Tab Groups
-
 Two ways to organize related projects in `~/.lattices/workspace.json`:
 
 - **Layers** — switchable contexts that focus and tile windows
@@ -192,8 +190,9 @@ Each project entry must have either `path` or `group`, not both.
 ### Tile values
 
 Any tile position from the [config reference](/docs/config#tile-positions)
-works: `left`, `right`, `top-left`, `top-right`, `bottom-left`,
-`bottom-right`, `maximize`, `center`.
+works: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`,
+`bottom-left`, `bottom-right`, `left-third`, `center-third`,
+`right-third`, `maximize`, `center`.
 
 ### Switching layers
 
@@ -219,7 +218,7 @@ The app remembers which layer was last active across restarts.
 Agents and scripts can switch layers via the daemon API:
 
 ```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 // List available layers
 const { layers, active } = await daemonCall('layers.list')
diff --git a/docs/overview.md b/docs/overview.md
@@ -4,8 +4,6 @@ description: What lattices is and who it's for
 order: 0
 ---
 
-# Overview
-
 lattices is a macOS developer workspace manager. It pairs tmux sessions
 with a native menu bar app to give you — and your AI coding agents —
 full control over terminal layouts, window tiling, and project navigation.
@@ -24,7 +22,7 @@ lattices solves both sides:
 - **For you** — run `lattices` in any project to get a pre-configured
   tmux session. Use the menu bar app to launch, tile, and navigate
   sessions with a command palette.
-- **For agents** — the daemon API exposes 20 RPC methods over WebSocket.
+- **For agents** — the daemon API exposes 26 RPC methods over WebSocket.
   Agents can discover projects, launch sessions, tile windows, and
   switch workspace layers programmatically.
 
@@ -34,20 +32,20 @@ lattices solves both sides:
 |-----------|-------------|
 | **CLI** (`lattices`) | Create, manage, and tile tmux sessions from the terminal |
 | **Menu bar app** | Native macOS companion with command palette, tiling, and project discovery |
-| **Daemon API** | WebSocket server on `ws://127.0.0.1:9399` — 20 methods, 3 real-time events |
+| **Daemon API** | WebSocket server on `ws://127.0.0.1:9399` — 26 methods, 4 real-time events |
 | **Node.js client** | Zero-dependency `daemonCall()` helper for scripting |
 
 ## Quick taste
 
 ```bash
 # Launch a workspace (auto-detects your project)
 cd ~/my-project && lattices
-
-# Or give agents programmatic control
 ```
 
+Agents get the same control programmatically:
+
 ```js
-import { daemonCall } from 'lattices/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
 await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -4,8 +4,6 @@ description: Install lattices and launch your first workspace in 2 minutes
 order: 0.5
 ---
 
-# Quickstart
-
 Get from zero to a running workspace in five steps.
 
 ## 1. Install tmux
@@ -19,10 +17,14 @@ Skip if you already have it (`tmux -V` to check).
 ## 2. Install lattices
 
 ```bash
-# Clone and link
+npm install -g @arach/lattices
+```
+
+Or install from source:
+
+```bash
 git clone https://github.com/arach/lattices
-cd lattices
-bun link
+cd lattices && npm link
 ```
 
 Verify: `lattices help` should print usage info.
diff --git a/package.json b/package.json
@@ -20,6 +20,10 @@
     "url": "https://github.com/arach/lattices"
   },
   "license": "MIT",
+  "exports": {
+    ".": "./bin/lattices.js",
+    "./daemon-client": "./bin/daemon-client.js"
+  },
   "scripts": {
     "dev": "bun --cwd docs-site dev"
   },
