@arach/lattices 0.1.0

package/docs/config.md

@@ -0,0 +1,234 @@
+---
+title: Configuration
+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
+workspace layout. lattices reads this file when creating a session.
+
+### Minimal example
+
+```json
+{
+  "panes": [
+    { "name": "claude", "cmd": "claude" },
+    { "name": "server", "cmd": "pnpm dev" }
+  ]
+}
+```
+
+### Full example
+
+```json
+{
+  "ensure": true,
+  "panes": [
+    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "server", "cmd": "pnpm dev" },
+    { "name": "tests",  "cmd": "pnpm test --watch" }
+  ]
+}
+```
+
+## Config fields
+
+| Field    | Type    | Required | Description                                          |
+|----------|---------|----------|------------------------------------------------------|
+| panes    | array   | no       | List of pane definitions (see below)                 |
+| ensure   | boolean | no       | Auto-restart exited commands on reattach              |
+| prefill  | boolean | no       | Type exited commands into idle panes on reattach (you hit Enter) |
+
+`ensure` and `prefill` are mutually exclusive. If both are set,
+`ensure` takes priority.
+
+- **ensure** — when you reattach to an existing session, lattices checks
+  each pane. If a pane's process has exited and the shell is idle, lattices
+  automatically re-runs its declared command.
+- **prefill** — same check, but the command is typed into the pane
+  without pressing Enter. You review and hit Enter yourself.
+
+## Pane fields
+
+| Field  | Type   | Required | Description                         |
+|--------|--------|----------|-------------------------------------|
+| name   | string | no       | Label for the pane (shown in app)   |
+| cmd    | string | no       | Command to run when pane opens      |
+| size   | number | no       | Width % for the first pane (1-99)   |
+
+- `size` only applies to the **first pane**. It sets the width of the
+  main pane as a percentage. Default is 60.
+- `cmd` can be any shell command. If omitted, the pane opens a shell.
+- `name` is used in the lattices app to show a summary of your layout,
+  and as a target for `lattices restart <name>`.
+
+## Layouts
+
+lattices picks a layout based on how many panes you define:
+
+### 2 panes — side by side
+
+```
+┌──────────┬─────────┐
+│  claude  │ server  │
+│  (60%)   │ (40%)   │
+└──────────┴─────────┘
+```
+
+Horizontal split. First pane on the left, second on the right.
+
+### 3+ panes — main-vertical
+
+```
+┌──────────┬─────────┐
+│  claude  │ server  │
+│  (60%)   ├─────────┤
+│          │ tests   │
+└──────────┴─────────┘
+```
+
+First pane takes the left side. Remaining panes stack vertically
+on the right.
+
+### 4 panes
+
+```
+┌──────────┬─────────┐
+│  claude  │ server  │
+│  (60%)   ├─────────┤
+│          │ tests   │
+│          ├─────────┤
+│          │ logs    │
+└──────────┴─────────┘
+```
+
+## Auto-detection (no config)
+
+If there's no `.lattices.json`, lattices still works. It will:
+
+1. Create a 2-pane layout (60/40 split)
+2. Run `claude` in the left pane
+3. Auto-detect your dev command from package.json scripts:
+   - Looks for: `dev`, `start`, `serve`, `watch` (in that order)
+   - Detects package manager: pnpm > bun > yarn > npm
+
+## Creating a config
+
+Run `lattices init` in your project directory to generate a starter
+`.lattices.json` based on your project. The generated config includes
+`"ensure": true` by default.
+
+## CLI commands
+
+| Command                    | Description                                      |
+|----------------------------|--------------------------------------------------|
+| `lattices`                   | Create or attach to session for current project   |
+| `lattices init`              | Generate .lattices.json config for this project     |
+| `lattices ls`                | List active tmux sessions                         |
+| `lattices kill [name]`       | Kill a session (defaults to current project)      |
+| `lattices sync`              | Reconcile session to match declared config        |
+| `lattices restart [pane]`    | Restart a pane's process (by name or index)       |
+| `lattices tile <position>`   | Tile the frontmost window to a screen position    |
+| `lattices group [id]`        | List tab groups or launch/attach a group          |
+| `lattices groups`            | List all tab groups with status                   |
+| `lattices tab <group> [tab]` | Switch tab within a group (by label or index)     |
+| `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             |
+| `lattices app quit`          | Stop the menu bar app                             |
+| `lattices help`              | Show help                                         |
+
+Aliases: `ls`/`list`, `kill`/`rm`, `sync`/`reconcile`,
+`restart`/`respawn`, `tile`/`t`.
+
+## Machine-readable output
+
+### `--json` flag
+
+The `lattices windows` command supports a `--json` flag for structured
+output:
+
+```bash
+lattices windows --json
+```
+
+Returns a JSON array of window objects to stdout — useful for piping
+into `jq` or consuming from scripts.
+
+### Daemon responses
+
+All daemon API calls return JSON natively. If you need structured data
+from lattices, the daemon is the best path — no flags needed, no stdout
+parsing. See the [API reference](/docs/api).
+
+### Exit codes
+
+| Code | Meaning                                     |
+|------|---------------------------------------------|
+| `0`  | Success                                     |
+| `1`  | General error (missing args, bad config)    |
+| `2`  | Session not found                           |
+
+## Recovery
+
+### sync
+
+```
+lattices sync
+```
+
+Reconciles a running session to match the declared config:
+
+1. Counts actual panes vs declared panes
+2. Recreates any missing panes
+3. Re-applies the layout (main-vertical with correct width)
+4. Restores pane labels
+5. Re-runs declared commands in any idle panes
+
+Use when a pane was killed and you want to get back to the declared
+state without killing the whole session.
+
+### restart
+
+```
+lattices restart [target]
+```
+
+Kills the process in a specific pane and re-runs its declared command.
+The target can be:
+
+- A **pane name** (case-insensitive): `lattices restart server`
+- A **0-based index**: `lattices restart 1`
+- **Omitted** (defaults to pane 0): `lattices restart`
+
+The restart sequence: send Ctrl-C, wait 0.5s, check if the process
+stopped. If it's still running, escalate to SIGKILL on child
+processes. Then send the declared command.
+
+## Tile positions
+
+The `lattices tile` command moves the frontmost window to a preset
+screen position. Available positions:
+
+| Position       | Area                        |
+|----------------|-----------------------------|
+| `left`         | Left half                   |
+| `right`        | Right half                  |
+| `top`          | Top half                    |
+| `bottom`       | Bottom half                 |
+| `top-left`     | Top-left quarter            |
+| `top-right`    | Top-right quarter           |
+| `bottom-left`  | Bottom-left quarter         |
+| `bottom-right` | Bottom-right quarter        |
+| `maximize`     | Full screen (visible area)  |
+| `center`       | 70% width, 80% height, centered |
+
+Aliases: `left-half`/`left`, `right-half`/`right`, `top-half`/`top`,
+`bottom-half`/`bottom`, `max`/`maximize`.
+
+Tiling respects the menu bar and dock — it uses the visible desktop
+area, not the full screen.

package/docs/layers.md

@@ -0,0 +1,317 @@
+---
+title: Workspace Layers & Tab Groups
+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
+- **Tab groups** — related projects as tabs within a single terminal window
+
+Both features are configured in the same workspace config and
+work together.
+
+## Tab Groups
+
+Tab groups let you bundle related projects as tabs (tmux windows)
+within a single tmux session. This is useful when you have a family
+of projects — like an iOS app, macOS app, website, and API — that
+you think of as one logical unit.
+
+### Configuration
+
+Add `groups` to `~/.lattices/workspace.json`:
+
+```json
+{
+  "name": "my-setup",
+  "groups": [
+    {
+      "id": "talkie",
+      "label": "Talkie",
+      "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" }
+      ]
+    }
+  ]
+}
+```
+
+Each tab's pane layout comes from its own `.lattices.json` — no changes
+to per-project configs.
+
+### How it works
+
+- **Session naming**: `lattices-group-<id>` (e.g. `lattices-group-talkie`)
+- **tmux mapping**: 1 group = 1 tmux session, each tab = 1 tmux window,
+  each window has its own panes from that project's `.lattices.json`
+- **Independent launch still works**: `cd talkie-ios && lattices` creates
+  its own standalone session as before
+
+### Tab group fields
+
+| Field          | Type     | Description                          |
+|----------------|----------|--------------------------------------|
+| `id`           | string   | Unique identifier for the group      |
+| `label`        | string   | Display name shown in the UI         |
+| `tabs`         | array    | List of tab definitions              |
+| `tabs[].path`  | string   | Absolute path to project directory   |
+| `tabs[].label` | string?  | Tab name (defaults to directory name) |
+
+### CLI commands
+
+```bash
+lattices groups             # List all groups with status
+lattices group <id>         # Launch or attach to a group
+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)
+```
+
+### Menu bar app
+
+Tab groups appear above the project list in the menu bar panel.
+Each group row shows:
+
+- Status indicator (running/stopped)
+- Tab count badge
+- Expand/collapse to see individual tabs
+- Launch/Attach and Kill buttons
+- Per-tab "Go" buttons to switch and focus a specific tab
+
+The command palette also includes group commands:
+
+| Command                    | Description                            |
+|----------------------------|----------------------------------------|
+| Launch *group*             | Start the group session                |
+| Attach *group*             | Focus the running group session        |
+| *Group*: *Tab*             | Switch to a specific tab in a group    |
+| Kill *group* Group         | Terminate the group session            |
+
+## Layers
+
+Layers let you group projects into switchable contexts. Instead of
+juggling six terminal windows at once, define two or three layers and
+switch between them instantly — the target layer's windows come to the
+front and tile into position, while the previous layer's windows fall
+behind.
+
+All tmux sessions stay alive across switches. Nothing is detached or
+killed — layers only control which windows are focused.
+
+### Configuration
+
+Add `layers` to `~/.lattices/workspace.json`:
+
+```json
+{
+  "name": "my-setup",
+  "layers": [
+    {
+      "id": "web",
+      "label": "Web",
+      "projects": [
+        { "path": "/Users/you/dev/frontend", "tile": "left" },
+        { "path": "/Users/you/dev/api", "tile": "right" }
+      ]
+    },
+    {
+      "id": "mobile",
+      "label": "Mobile",
+      "projects": [
+        { "path": "/Users/you/dev/ios-app", "tile": "left" },
+        { "path": "/Users/you/dev/backend", "tile": "right" }
+      ]
+    }
+  ]
+}
+```
+
+### Using groups in layers
+
+Layer projects can reference a tab group instead of a single path.
+This lets you tile a whole group into a screen position:
+
+```json
+{
+  "name": "my-setup",
+  "groups": [
+    {
+      "id": "talkie",
+      "label": "Talkie",
+      "tabs": [
+        { "path": "/Users/you/dev/talkie-ios", "label": "iOS" },
+        { "path": "/Users/you/dev/talkie-web", "label": "Website" }
+      ]
+    }
+  ],
+  "layers": [
+    {
+      "id": "main",
+      "label": "Main",
+      "projects": [
+        { "group": "talkie", "tile": "top-left" },
+        { "path": "/Users/you/dev/design-system", "tile": "right" }
+      ]
+    }
+  ]
+}
+```
+
+When switching to this layer, lattices launches (or focuses) the
+"talkie" group session and tiles it to the top-left quarter, alongside
+the design-system project on the right.
+
+### Layer fields
+
+| Field             | Type     | Description                              |
+|-------------------|----------|------------------------------------------|
+| `name`            | string   | Workspace name (for your reference)      |
+| `layers`          | array    | List of layer definitions                |
+| `layers[].id`     | string   | Unique identifier (e.g. `"web"`)         |
+| `layers[].label`  | string   | Display name shown in the UI             |
+| `layers[].projects` | array  | Projects in this layer                   |
+| `projects[].path` | string?  | Absolute path to project directory       |
+| `projects[].group`| string?  | Group ID (alternative to `path`)         |
+| `projects[].tile` | string?  | Tile position (optional, see below)      |
+
+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`.
+
+### Switching layers
+
+Three ways to switch:
+
+| Method               | How                                      |
+|----------------------|------------------------------------------|
+| **Hotkey**           | Cmd+Option+1, Cmd+Option+2, Cmd+Option+3... |
+| **Layer bar**        | Click a layer pill in the menu bar panel |
+| **Command palette**  | Search "Switch to Layer" in Cmd+Shift+M  |
+
+When you switch to a layer:
+
+1. Each project's terminal window is **raised and focused**
+2. If a project isn't running yet, it gets **launched** automatically
+3. Windows with a `tile` value are **tiled** to that position
+4. The previous layer's windows stay open behind the new ones
+
+The app remembers which layer was last active across restarts.
+
+### Programmatic switching
+
+Agents and scripts can switch layers via the daemon API:
+
+```js
+import { daemonCall } from 'lattices/daemon-client'
+
+// List available layers
+const { layers, active } = await daemonCall('layers.list')
+console.log(`Active: ${layers[active].label}`)
+
+// Switch to a layer by index
+await daemonCall('layer.switch', { index: 0 })
+```
+
+The `layer.switch` call focuses and tiles all windows in the target
+layer, just like the hotkey or command palette. A `layer.switched`
+event is broadcast to all connected clients.
+
+See the [Daemon API reference](/docs/api) for more methods.
+
+### Layer bar
+
+When a workspace config is loaded, a layer bar appears between the
+header and search field in the menu bar panel:
+
+```
+ lattices  2 sessions              [↔] [⟳]
+┌────────────────────────────────────────┐
+│  ● Web          ○ Mobile               │
+│  ⌥1             ⌥2                     │
+└────────────────────────────────────────┘
+ Search projects...
+```
+
+- Active layer: filled green dot
+- Inactive layers: dim outline dot
+- Hotkey hints shown below each label
+
+## Layout examples
+
+### Single project
+
+```json
+{
+  "projects": [
+    { "path": "/Users/you/dev/talkie" }
+  ]
+}
+```
+
+No `tile` — just focuses the window wherever it is.
+
+### Two-project split
+
+```json
+{
+  "projects": [
+    { "path": "/Users/you/dev/app", "tile": "left" },
+    { "path": "/Users/you/dev/api", "tile": "right" }
+  ]
+}
+```
+
+### Group + project
+
+```json
+{
+  "projects": [
+    { "group": "talkie", "tile": "left" },
+    { "path": "/Users/you/dev/api", "tile": "right" }
+  ]
+}
+```
+
+### Four quadrants
+
+```json
+{
+  "projects": [
+    { "path": "/Users/you/dev/frontend", "tile": "top-left" },
+    { "path": "/Users/you/dev/backend", "tile": "top-right" },
+    { "path": "/Users/you/dev/mobile", "tile": "bottom-left" },
+    { "path": "/Users/you/dev/infra", "tile": "bottom-right" }
+  ]
+}
+```
+
+## Tips
+
+- Projects don't need a `.lattices.json` config to be in a layer — any
+  directory path works. If the project has a config, lattices uses it; if
+  not, it opens a plain terminal in that directory.
+- You can have up to 9 layers (Cmd+Option+1 through Cmd+Option+9).
+- Edit `workspace.json` by hand — the app re-reads it on launch. Use
+  the Refresh Projects button or restart the app to pick up changes.
+- The `tile` field is optional. Omit it if you just want the window
+  focused without repositioning.
+- Tab groups and standalone projects can coexist in the same workspace.
+  Use groups for related project families, standalone paths for
+  individual projects.

package/docs/overview.md

@@ -0,0 +1,74 @@
+---
+title: Overview
+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.
+
+## The problem
+
+Modern development means juggling multiple terminal windows: a coding
+agent in one, a dev server in another, tests in a third. Setting this up
+every morning is tedious. AI agents can't do it at all — they're trapped
+inside a single shell with no way to manage windows or switch contexts.
+
+## The solution
+
+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.
+  Agents can discover projects, launch sessions, tile windows, and
+  switch workspace layers programmatically.
+
+## What's included
+
+| Component | Description |
+|-----------|-------------|
+| **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 |
+| **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
+```
+
+```js
+import { daemonCall } from 'lattices/daemon-client'
+
+await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
+await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
+```
+
+## Who it's for
+
+- **Developers** who use tmux and want faster project switching
+- **AI agent builders** who need their agents to control the workspace
+- **Power users** who manage multiple projects across macOS Spaces
+
+## Requirements
+
+- macOS 13.0+
+- tmux (`brew install tmux`)
+- Node.js 18+
+- Swift 5.9+ (only needed to build the menu bar app from source)
+
+## Next steps
+
+- [Quickstart](/docs/quickstart) — install and run your first session in 2 minutes
+- [Concepts](/docs/concepts) — architecture, glossary, and how it all works
+- [Configuration](/docs/config) — `.lattices.json` format and CLI commands
+- [Daemon API](/docs/api) — full RPC method reference for agents and scripts

package/docs/quickstart.md

@@ -0,0 +1,82 @@
+---
+title: Quickstart
+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
+
+```bash
+brew install tmux
+```
+
+Skip if you already have it (`tmux -V` to check).
+
+## 2. Install lattices
+
+```bash
+# Clone and link
+git clone https://github.com/arach/lattices
+cd lattices
+bun link
+```
+
+Verify: `lattices help` should print usage info.
+
+## 3. Launch a workspace
+
+```bash
+cd ~/your-project
+lattices
+```
+
+This creates a tmux session with two panes side by side:
+- Left pane (60%): `claude` (AI coding agent)
+- Right pane (40%): your dev command (auto-detected from `package.json`)
+
+No config file needed — lattices auto-detects your package manager
+and dev script.
+
+## 4. Customize with .lattices.json
+
+For more control, add a config to your project:
+
+```bash
+lattices init
+```
+
+This generates a `.lattices.json` like:
+
+```json
+{
+  "ensure": true,
+  "panes": [
+    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "server", "cmd": "bun dev" }
+  ]
+}
+```
+
+Edit it to match your workflow, then run `lattices` again to apply.
+
+## 5. Launch the menu bar app
+
+```bash
+lattices app
+```
+
+This builds (or downloads) and launches the native macOS companion.
+Open the command palette with **Cmd+Shift+M** to search and launch
+any project, tile windows, or switch workspace layers.
+
+## What's next
+
+- [Concepts](/docs/concepts) — understand sessions, panes, and the architecture
+- [Configuration](/docs/config) — full `.lattices.json` reference and CLI commands
+- [Menu Bar App](/docs/app) — command palette, tiling, and settings
+- [Daemon API](/docs/api) — programmatic control for agents and scripts
+- [Layers & Groups](/docs/layers) — organize projects into switchable contexts