@lattices/cli 0.4.7 → 0.4.9

package/bin/lattices.ts

@@ -45,7 +45,7 @@ function hasTmux(): boolean {
 
 /** Commands that require tmux to be installed */
 const tmuxRequiredCommands = new Set([
-  "init", "ls", "list", "kill", "rm", "sync", "reconcile",
+  "start", "tmux", "init", "ls", "list", "kill", "rm", "sync", "reconcile",
   "restart", "respawn", "group", "groups", "tab", "status",
   "inventory", "sessions",
 ]);
@@ -53,13 +53,9 @@ const tmuxRequiredCommands = new Set([
 function requireTmux(command: string | undefined): void {
   if (hasTmux()) return;
 
-  const isImplicitCreate = command && !tmuxRequiredCommands.has(command)
-    && !["search", "s", "focus", "place", "tile", "t", "windows", "window",
-         "voice", "call", "layer", "layers", "diag", "diagnostics", "scan",
-         "ocr", "daemon", "dev", "app", "mouse", "assistant",
-         "help", "-h", "--help"].includes(command);
+  if (!command) return;
 
-  if (command && !tmuxRequiredCommands.has(command) && !isImplicitCreate) return;
+  if (!tmuxRequiredCommands.has(command)) return;
 
   console.error(`
 \x1b[1;31m✘ tmux not found\x1b[0m
@@ -395,9 +391,9 @@ function tabCommand(groupId?: string, tabName?: string): void {
 // ── Detect dev command ───────────────────────────────────────────────
 
 function detectPackageManager(dir: string): string {
-  if (existsSync(resolve(dir, "pnpm-lock.yaml"))) return "pnpm";
   if (existsSync(resolve(dir, "bun.lockb")) || existsSync(resolve(dir, "bun.lock")))
     return "bun";
+  if (existsSync(resolve(dir, "pnpm-lock.yaml"))) return "pnpm";
   if (existsSync(resolve(dir, "yarn.lock"))) return "yarn";
   return "npm";
 }
@@ -663,12 +659,12 @@ function defaultPanes(dir: string): PaneConfig[] {
   const devCmd = detectDevCommand(dir);
   if (devCmd) {
     return [
-      { name: "claude", cmd: "claude", size: 60 },
+      { name: "shell", size: 60 },
       { name: "server", cmd: devCmd },
     ];
   }
   // No dev server detected → single pane
-  return [{ name: "claude", cmd: "claude" }];
+  return [{ name: "shell" }];
 }
 
 function syncSession(): void {
@@ -765,7 +761,7 @@ function restartPane(target?: string): void {
   // Resolve target to an index
   let idx: number;
   if (target === undefined || target === null || target === "") {
-    // Default: first pane (claude)
+    // Default: first pane
     idx = 0;
   } else if (/^\d+$/.test(target)) {
     idx = parseInt(target, 10);
@@ -1718,10 +1714,12 @@ Usage:
 }
 
 function printUsage(): void {
-  console.log(`lattices — Claude Code + dev server in tmux
+  console.log(`lattices — workspace launcher for tmux, windows, layers, and the menu bar app
 
 Usage:
-  lattices                    Create session (or reattach) for current project
+  lattices                    Show workspace status and common commands
+  lattices start              Start or reattach the current directory's tmux workspace
+  lattices tmux               Alias for lattices start
   lattices init               Generate .lattices.json config for this project
   lattices ls                 List active tmux sessions
   lattices status             Show managed vs unmanaged session inventory
@@ -1780,7 +1778,7 @@ Config (.lattices.json):
   {
     "ensure": true,
     "panes": [
-      { "name": "claude", "cmd": "claude", "size": 60 },
+      { "name": "shell", "size": 60 },
       { "name": "server", "cmd": "pnpm dev" },
       { "name": "tests",  "cmd": "pnpm test --watch" }
     ]
@@ -1799,7 +1797,7 @@ Recovery:
 
   lattices restart    Kills the process in a pane and re-runs its declared command.
                     Accepts a pane name or 0-based index (default: 0 / first pane).
-                    Examples:  lattices restart         (restarts "claude")
+                    Examples:  lattices restart         (restarts the first pane)
                                lattices restart server  (restarts "server" by name)
                                lattices restart 1       (restarts pane at index 1)
 
@@ -1809,13 +1807,47 @@ Layouts:
   3+ panes →  main-vertical (first pane left, rest stacked right)
 
   ┌────────────────────┐    ┌──────────┬─────────┐    ┌──────────┬─────────┐
-  │      claude         │    │  claude   │ server  │    │  claude   │ server  │
+  │      shell          │    │  shell    │ server  │    │  shell    │ server  │
   │                     │    │  (60%)   │ (40%)   │    │  (60%)   ├─────────┤
   └────────────────────┘    └──────────┴─────────┘    │          │ tests   │
                                                        └──────────┴─────────┘
 `);
 }
 
+function printHome(): void {
+  const dir = process.cwd();
+  const sessionName = toSessionName(dir);
+  const config = readConfig(dir);
+  const panes = resolvePanes(dir);
+  const tmuxReady = hasTmux();
+  const sessionRunning = tmuxReady && sessionExists(sessionName);
+  const appRunning = runQuiet("pgrep -x Lattices >/dev/null 2>&1 && echo yes") === "yes";
+
+  console.log(`lattices — let's get you situated
+
+Current directory:
+  ${dir}
+
+Workspace:
+  session   ${sessionName}
+  config    ${config ? ".lattices.json" : "none yet"}
+  panes     ${panes.map((p) => p.name || "pane").join(", ")}
+  tmux      ${tmuxReady ? (sessionRunning ? "running" : "ready") : "missing"}
+  app       ${appRunning ? "running" : "not running"}
+
+Common commands:
+  lattices start        Start or reattach this directory's tmux workspace
+  lattices init         Create a .lattices.json for this project
+  lattices app          Launch the menu bar app
+  lattices ls           List active sessions
+  lattices help         Show the full command reference
+`);
+
+  if (!tmuxReady) {
+    console.log("tmux is not installed. Run: brew install tmux");
+  }
+}
+
 function initConfig(): void {
   const dir = process.cwd();
   const configPath = resolve(dir, ".lattices.json");
@@ -2154,6 +2186,13 @@ function statusInventory(): void {
 requireTmux(command);
 
 switch (command) {
+  case undefined:
+    printHome();
+    break;
+  case "start":
+  case "tmux":
+    createOrAttach();
+    break;
   case "init":
     initConfig();
     break;
@@ -2295,5 +2334,6 @@ switch (command) {
     printUsage();
     break;
   default:
-    createOrAttach();
+    console.log(`Unknown command: ${command}`);
+    console.log("Run `lattices help` for the full command reference.");
 }

package/docs/app.md

@@ -95,7 +95,7 @@ For each project found, the app reads:
 ## Session management
 
 The app calls the lattices CLI for session operations. Launch runs
-`lattices` in the project directory, Sync runs `lattices sync` to
+`lattices start` in the project directory, Sync runs `lattices sync` to
 reconcile panes, and Restart runs `lattices restart <pane>` to kill
 and re-run a pane's process. Detach and Kill call `tmux detach-client`
 and `tmux kill-session` directly.
@@ -159,7 +159,7 @@ in the AI corner. Configure the model and budget in Settings > AI.
 ## Settings
 
 Open via the command palette or the gear icon in the main view.
-The settings window has four tabs:
+The settings window has five tabs:
 
 ### General
 
@@ -169,6 +169,7 @@ The settings window has four tabs:
 | Mode       | `learning` or `auto` (see below)                     |
 | Scan Root  | Directory to scan for .lattices.json configs (type a path or click Browse) |
 | Updates    | Download the latest release and relaunch the app     |
+| Keyboard Remaps | Optional Caps Lock layer that maps hold to Hyper and tap to Escape |
 
 **Mode** controls how the app handles session interaction:
 
@@ -176,6 +177,33 @@ The settings window has four tabs:
   (helpful while getting used to tmux)
 - **Auto** — detaches sessions automatically (fewer prompts)
 
+### Keyboard Remaps
+
+**Keyboard remaps** are enabled by default for the laptop-friendly rule:
+
+- hold Caps Lock -> Hyper (`Control` + `Option` + `Shift` + `Command`)
+- tap Caps Lock -> Escape
+
+Rules live in `~/.lattices/keyboard-remaps.json`, and the Settings toggle
+can turn the layer off. Keyboard remaps require Accessibility permission
+because they use a local event tap.
+
+### Companion
+
+Shows the secure local bridge status, Mac bridge fingerprint, supported
+capability grants, and paired iPad or iPhone devices. The paired-device
+list shows each device fingerprint, last-seen time, and granted
+capabilities. You can refresh the list, revoke an individual device, or
+forget all trusted companions.
+
+The local companion bridge and trackpad proxy are off by default for
+privacy. Turn the bridge on in Settings > Companion, or open
+`lattices://companion/enable` to enable the bridge and jump straight to
+Companion settings. `lattices://companion/disable` turns it off again.
+
+The trackpad proxy toggle lives here. Paired devices still need the
+`input.trackpad` grant before they can send pointer events.
+
 ### AI
 
 | Setting              | Default        | Description                              |

package/docs/companion-deck.md

@@ -132,11 +132,40 @@ Standalone mode now uses:
 - per-device key agreement
 - signed requests with nonce and timestamp checks
 - encrypted deck payloads for snapshots, actions, and trackpad events
+- pairing-time capability grants, enforced again on every protected route
 
 The bridge still keeps `/health`, `/deck/manifest`, and pairing
 bootstrap lightweight so a new companion can connect and establish trust
 without an external relay or Tailscale dependency.
 
+## Reference Security Pattern
+
+The standalone bridge is the reference pattern we should share back to
+Talkie and Scout:
+
+1. Bonjour is discovery only. The TXT record exposes protocol version,
+   fingerprint, security mode, and coarse capabilities, but no project
+   names, sessions, commands, or tokens.
+2. Local-network control is opt-in. The bridge is disabled by default;
+   users enable it from Companion settings or the local
+   `lattices://companion/enable` deep link.
+3. Pairing is explicit Mac approval. A cryptographic handshake or public
+   key exchange proves key possession; it does not automatically grant
+   control.
+4. Trust is scoped. Pairing records store granted capabilities such as
+   `deck.read`, `deck.perform`, and `input.trackpad`.
+5. Every protected request is signed with a timestamp and nonce, then
+   checked for replay before the route runs.
+6. Sensitive payloads are encrypted with per-device key agreement and
+   route-bound additional authenticated data.
+7. Authorization happens after authentication. A trusted device still
+   needs the route's required capability before it can read state,
+   perform actions, or proxy input.
+
+That gives the family of apps one ergonomic model: discover nearby,
+pair once, reconnect quietly, and keep control surfaces capability
+scoped.
+
 ## Initial Action Surface
 
 The first deck action IDs are intentionally small and map to existing

package/docs/concepts.md

@@ -13,8 +13,8 @@ order: 6
 | **Agent API** | WebSocket server (`ws://127.0.0.1:9399`) inside the menu bar app. Exposes 35+ RPC methods and 5 real-time events for programmatic control. See the [API reference](/docs/api). |
 | **Agent** | Any program that calls the agent API autonomously — an AI coding agent, a shell script, a CI pipeline, or a custom tool. |
 | **Session** | A persistent tmux workspace that lives in the background. Survives terminal crashes, disconnects, and closing your laptop. One session per project. Requires tmux. |
-| **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. Requires tmux. |
-| **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. Requires tmux. |
+| **Pane** | A single terminal view inside a session. A typical setup has two panes side by side — shell on the left, dev server on the right. Requires tmux. |
+| **Attach / Detach** | Attaching connects your terminal to an existing session. Detaching disconnects but keeps the session alive — your shell and dev server keep running. Requires tmux. |
 | **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. Requires tmux. |
 | **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`. Requires tmux. |
 | **tmux** | Terminal multiplexer (optional). Provides persistent sessions, pane layouts, and command restoration. Install with `brew install tmux` if you want session management. |
@@ -24,8 +24,8 @@ order: 6
 1. You create a `.lattices.json` file in your project root (or run `lattices init`)
 2. The menu bar app discovers the project and adds it to the command palette
 3. You can tile windows, switch layers, search via OCR, and use the agent API
-4. With tmux installed, `lattices` also creates persistent terminal sessions:
-   - Each pane gets its command (claude, dev server, tests, etc.)
+4. With tmux installed, `lattices start` also creates persistent terminal sessions:
+   - Each pane gets its command (shell, dev server, tests, etc.)
    - The session persists in the background until you kill it
    - You can attach/detach from any terminal at any time
    - If `ensure` is enabled, exited commands auto-restart on reattach
@@ -94,7 +94,7 @@ and other macOS window managers.
 
 ### Ensure/prefill restoration (requires tmux)
 
-When you run `lattices` (no arguments) and a session already exists:
+When you run `lattices start` and a session already exists:
 
 1. lattices checks the `ensure` / `prefill` flag in `.lattices.json`
 2. For each pane, it queries `#{pane_current_command}` via tmux

package/docs/config.md

@@ -14,7 +14,7 @@ workspace layout. lattices reads this file when creating a session.
 ```json
 {
   "panes": [
-    { "name": "claude", "cmd": "claude" },
+    { "name": "shell" },
     { "name": "server", "cmd": "pnpm dev" }
   ]
 }
@@ -26,7 +26,7 @@ workspace layout. lattices reads this file when creating a session.
 {
   "ensure": true,
   "panes": [
-    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "shell", "size": 60 },
     { "name": "server", "cmd": "pnpm dev" },
     { "name": "tests",  "cmd": "pnpm test --watch" }
   ]
@@ -72,7 +72,7 @@ lattices picks a layout based on how many panes you define:
 
 ```
 ┌──────────┬─────────┐
-│  claude  │ server  │
+│  shell   │ server  │
 │  (60%)   │ (40%)   │
 └──────────┴─────────┘
 ```
@@ -83,7 +83,7 @@ Horizontal split. First pane on the left, second on the right.
 
 ```
 ┌──────────┬─────────┐
-│  claude  │ server  │
+│  shell   │ server  │
 │  (60%)   ├─────────┤
 │          │ tests   │
 └──────────┴─────────┘
@@ -96,7 +96,7 @@ on the right.
 
 ```
 ┌──────────┬─────────┐
-│  claude  │ server  │
+│  shell   │ server  │
 │  (60%)   ├─────────┤
 │          │ tests   │
 │          ├─────────┤
@@ -109,10 +109,10 @@ on the right.
 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:
+2. Open a shell in the left pane
+3. Auto-detect your dev command from package.json scripts and run it on the right:
    - Looks for: `dev`, `start`, `serve`, `watch` (in that order)
-   - Detects package manager: pnpm > bun > yarn > npm
+   - Detects package manager: bun > pnpm > yarn > npm
 
 ## Creating a config
 
@@ -124,7 +124,9 @@ Run `lattices init` in your project directory to generate a starter
 
 | Command                    | Description                                      |
 |----------------------------|--------------------------------------------------|
-| `lattices`                   | Create or attach to session for current project   |
+| `lattices`                   | Show workspace status and common commands         |
+| `lattices start`             | Create or attach to session for current project   |
+| `lattices tmux`              | Alias for `lattices start`                        |
 | `lattices init`              | Generate .lattices.json config for this project     |
 | `lattices ls`                | List active sessions (requires tmux)              |
 | `lattices kill [name]`       | Kill a session (defaults to current project)      |
@@ -161,6 +163,29 @@ Run `lattices init` in your project directory to generate a starter
 Aliases: `ls`/`list`, `kill`/`rm`, `sync`/`reconcile`,
 `restart`/`respawn`, `tile`/`t`.
 
+## Keyboard remaps
+
+The menu bar app can create a lightweight keyboard layer from
+`~/.lattices/keyboard-remaps.json`. The default config is:
+
+```json
+{
+  "rules": [
+    {
+      "enabled": true,
+      "from": "caps_lock",
+      "id": "caps_lock_hyper_escape",
+      "toIfAlone": "escape",
+      "toIfHeld": "hyper"
+    }
+  ]
+}
+```
+
+It is enabled by default and can be turned off from Settings -> General ->
+Keyboard remaps. Hold Caps Lock to send Hyper (`Control` + `Option` +
+`Shift` + `Command`), or tap Caps Lock alone to send Escape.
+
 ## Machine-readable output
 
 ### `--json` flag

package/docs/layers.md

@@ -49,7 +49,7 @@ to per-project configs.
 - 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 vox-ios && lattices`
+- You can still launch projects independently: `cd vox-ios && lattices start`
   creates its own standalone session as before
 
 ### Tab group fields

package/docs/overview.md

@@ -57,7 +57,7 @@ and you can reattach anytime.
 ## Example
 
 ```bash
-cd ~/my-project && lattices
+cd ~/my-project && lattices start
 ```
 
 Agents get the same control programmatically:

package/docs/quickstart.md

@@ -10,7 +10,7 @@ Four steps to a running workspace.
 
 ```bash
 git clone https://github.com/arach/lattices
-cd lattices && npm link
+cd lattices && bun link
 ```
 
 Verify: `lattices help` should print usage info.
@@ -39,7 +39,7 @@ This generates a config like:
 ```json
 {
   "panes": [
-    { "name": "claude", "cmd": "claude", "size": 60 },
+    { "name": "shell", "size": 60 },
     { "name": "server", "cmd": "bun dev" }
   ]
 }
@@ -55,12 +55,12 @@ your pane layout:
 
 ```bash
 brew install tmux
-cd ~/your-project && lattices
+cd ~/your-project && lattices start
 ```
 
 This creates a tmux session with your configured panes side by side.
 The session persists in the background — close your terminal, reopen it,
-run `lattices` again, and everything is still there.
+run `lattices start` again, and everything is still there.
 
 > **Without tmux**, you still get the menu bar app, command palette,
 > window tiling, workspace layers, OCR, and the full agent API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lattices/cli",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Agentic window manager for macOS — programmable workspace, smart layouts, managed tmux sessions, and a 35+-method agent API",
   "bin": {
     "lattices": "./bin/lattices.ts",