@arach/lattices 0.2.0 → 0.6.1

package/docs/proposals/LAT-007-unified-app-shell.md

@@ -0,0 +1,128 @@
+# LAT-007: Unified App Shell
+
+## Summary
+
+Lattices should feel like one structured app, not a collection of useful
+windows added one feature at a time. The native app already has a strong
+starting point in the unified shell managed by `ScreenMapWindowController`.
+Future feature work should treat that shell as the durable product surface.
+
+Transient surfaces such as the command palette, voice command window, HUD,
+and menu bar popover should become launchers, inspectors, or fast overlays
+that route back into the shell for persistent workflows.
+
+## Product Shape
+
+The main Lattices window should own the primary information architecture:
+
+| Area | Purpose |
+|------|---------|
+| Home | Workspace status, desktop control, agent/search entry points, and discoverable project launch |
+| Assistant | Chat and agent-oriented workspace help |
+| Layout | Visual desktop map and window arrangement |
+| Desktop Inventory | Window/search/OCR inventory |
+| Activity | Logs, diagnostics, event history, and operational feedback |
+| Settings | Preferences, permissions, shortcuts, mouse, AI, OCR, companion |
+| Docs | Reference and onboarding material |
+
+The menu bar popover should stay lightweight: quick project launch plus
+buttons into the main shell. The command palette should stay global and
+action-oriented. The HUD and voice UI should stay transient and contextual.
+
+## First User Experience
+
+The friendliest starting point is Home, not Settings and not a floating
+utility panel.
+
+On first launch:
+
+1. The onboarding window introduces the product briefly.
+2. Onboarding presents optional capabilities only; it does not require project
+   setup or terminal-session setup.
+3. Completing onboarding opens the unified Home page.
+4. Home starts with desktop control, search/context, and assistant entry points;
+   project launch remains discoverable inside the app.
+5. Missing setup is explained in place. Settings remains available, but the app
+   should not throw the user into Settings just because a scan root is missing.
+
+This keeps the first mental model simple:
+
+> Lattices sees your workspace, helps arrange it, and gives agents local context.
+> Project and terminal workflows are useful depth, not the first required step.
+
+## Surface Rules
+
+1. Durable state belongs in the unified app shell.
+2. Popovers and overlays should not become alternate versions of the app.
+3. Feature entry points should navigate to an app page when the user needs
+   to read, configure, inspect, or continue a workflow.
+4. Floating panels are appropriate for short-lived interactions: search,
+   command execution, voice capture, HUD previews, and permission helpers.
+5. Settings, diagnostics, docs, assistant setup, and inventory views should
+   avoid standalone windows unless there is an explicit debugging reason.
+6. Page changes inside the shell should preserve the user's window size and
+   position. Pick a good initial size, then let the window feel stable.
+
+## Migration Plan
+
+### Phase 1: Route Existing Entry Points
+
+- Add missing primary pages to the unified shell.
+- Redirect menu, palette, hotkey, and footer links into shell pages.
+- Keep legacy utility windows available internally where useful, but stop
+  presenting them from normal app navigation.
+
+### Phase 2: Normalize Page Responsibilities
+
+- Make Home the status and launch surface.
+- Make Layout the only visual arrangement surface.
+- Make Desktop Inventory the only persistent search/inventory surface.
+- Make Activity the only persistent diagnostics surface.
+- Keep Settings and Docs under the shell instead of separate windows.
+
+### Phase 3: Reduce Duplicate UI
+
+- Convert repeated panel headers, footers, and shell chrome into reusable
+  components.
+- Move preview rendering and diagnostic log rendering into shared views.
+- Keep command palette rows and menu items as bindings to canonical actions.
+
+### Phase 4: Product-Level Navigation
+
+- Add a route helper for app pages so callers express intent like
+  `showActivity()` or `showSettings(.shortcuts)` instead of manually choosing
+  windows.
+- Add page-specific deep links for companion, docs, and diagnostics.
+- Record navigation in diagnostics so support sessions can reconstruct how a
+  user reached a feature.
+
+## First Slice
+
+The first implemented slice is Activity consolidation:
+
+- `Activity` is now a primary app-shell page.
+- Home links to Activity.
+- menu bar, command palette, hotkey, settings/docs footers, launch flag, voice,
+  and Layout log links route to the Activity page.
+- The legacy floating `DiagnosticWindow` remains for internal/debug use.
+
+The second implemented slice is first-run Home consolidation:
+
+- Completing onboarding opens Home.
+- Missing scan-root setup is handled inside Home instead of auto-opening
+  Settings.
+- Onboarding no longer introduces project-root or tmux setup.
+- Home shows a desktop-first getting-started path when no projects are
+  discovered: layout, search/context, and assistant.
+- Project scanning is skipped when the scan root is empty.
+- App-shell tab navigation preserves the current window frame instead of
+  resizing per page.
+
+## Open Questions
+
+- Should the menu bar click open Home in the unified shell by default, leaving
+  the project popover as an explicit quick-launch mode?
+- Should Command Mode become the embedded Desktop Inventory page only, with the
+  standalone panel reserved for a hotkey overlay?
+- Should Settings expose direct subroutes such as `settings.shortcuts` and
+  `settings.permissions`?

package/docs/quickstart.md

@@ -8,15 +8,9 @@ Four steps to a running workspace.
 
 ## 1. Install lattices
 
-```bash
-npm install -g @arach/lattices
-```
-
-Or install from source:
-
 ```bash
 git clone https://github.com/arach/lattices
-cd lattices && npm link
+cd lattices && bun link
 ```
 
 Verify: `lattices help` should print usage info.
@@ -45,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" }
   ]
 }
@@ -61,15 +55,17 @@ your pane layout:
 
 ```bash
 brew install tmux
-cd ~/your-project && lattices
+cd ~/your-project
+lattices          # home screen: status only, does not attach
+lattices start    # create or reattach the session
 ```
 
 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 daemon API.
+> window tiling, workspace layers, OCR, and the full agent API.
 
 ## What's next
 
@@ -78,4 +74,4 @@ run `lattices` again, and everything is still there.
 - [Layers & Groups](/docs/layers): organize projects into switchable contexts
 - [Screen OCR](/docs/ocr): let agents read what's on screen
 - [Concepts](/docs/concepts): sessions, panes, and the architecture
-- [Daemon API](/docs/api): programmatic control for agents and scripts
+- [Agent API](/docs/api): programmatic control for agents and scripts

package/docs/reference/dewey.config.ts

@@ -0,0 +1,74 @@
+/** @type {import('@arach/dewey').DeweyConfig} */
+export default {
+  project: {
+    name: 'lattices',
+    tagline: 'macOS developer workspace manager — tmux sessions with a native menu bar app for tiling, navigation, and project management',
+    type: 'cli-tool',
+    version: '0.6.1',
+  },
+
+  agent: {
+    criticalContext: [
+      'lattices has TWO primary interfaces: a TypeScript CLI (`bin/lattices.ts`) and a native Swift menu bar app (`apps/mac/Sources/`)',
+      'Session names are `<basename>-<sha256-6chars>` — both CLI and app must produce identical hashes',
+      'The app finds terminal windows via a `[lattices:session-name]` tag embedded in the tmux window title',
+      'Window navigation falls through CG → AX → AppleScript depending on macOS permissions',
+      'Space switching uses private SkyLight framework APIs loaded via dlopen at runtime',
+      'The daemon runs on ws://127.0.0.1:9399 with 35+ RPC methods and real-time events',
+    ],
+
+    entryPoints: {
+      'cli': 'bin/lattices.ts',
+      'app-helper': 'bin/lattices-app.ts',
+      'menu-bar-app': 'apps/mac/Sources/',
+      'docs': 'docs/',
+      'site': 'apps/site/',
+      'marketing-site': 'apps/site/',
+    },
+
+    rules: [
+      { pattern: 'cli', instruction: 'Check bin/lattices.ts for CLI commands and session logic' },
+      { pattern: 'app', instruction: 'Check apps/mac/Sources/ for Swift menu bar app code' },
+      { pattern: 'config', instruction: 'Check docs/config.md for .lattices.json format and CLI reference' },
+      { pattern: 'tiling', instruction: 'Check apps/mac/Sources/Core/Desktop/WindowTiler.swift and apps/mac/Sources/Core/Desktop/PlacementSpec.swift' },
+      { pattern: 'palette', instruction: 'Check apps/mac/Sources/Core/Actions/PaletteCommand.swift for command palette actions' },
+      { pattern: 'terminal', instruction: 'Check apps/mac/Sources/Core/Workspace/Terminal/Terminal.swift for supported terminals and launch logic' },
+      { pattern: 'daemon', instruction: 'Check apps/mac/Sources/Core/Daemon/DaemonServer.swift and apps/mac/Sources/Core/Daemon/LatticesApi.swift for WebSocket API' },
+      { pattern: 'api', instruction: 'Check docs/api.md for the daemon RPC reference' },
+      { pattern: 'twin', instruction: 'Check docs/twins.md and bin/project-twin.ts for the Pi-backed project twin runtime' },
+    ],
+
+    sections: ['overview', 'quickstart', 'concepts', 'twins', 'config', 'app', 'api', 'layers'],
+  },
+
+  docs: {
+    path: './docs',
+    output: './',
+    required: ['overview', 'quickstart', 'concepts', 'config'],
+  },
+
+  install: {
+    objective: 'Install the lattices CLI and optionally the native macOS menu bar companion app.',
+
+    doneWhen: {
+      command: 'lattices help',
+      expectedOutput: 'Usage information for lattices CLI',
+    },
+
+    prerequisites: [
+      'macOS 26.0+',
+      'tmux (brew install tmux)',
+      'Node.js >= 18',
+      'Swift 6.2 / Xcode 26+ (only if building the menu bar app from source)',
+    ],
+
+    steps: [
+      { description: 'Install tmux if not present', command: 'brew install tmux' },
+      { description: 'Clone the repository', command: 'git clone https://github.com/arach/lattices && cd lattices' },
+      { description: 'Link the CLI globally', command: 'bun link' },
+      { description: 'Build and launch the menu bar app', command: 'lattices app' },
+      { description: 'Create a config in your project', command: 'cd ~/your-project && lattices init' },
+      { description: 'Start your first workspace', command: 'lattices' },
+    ],
+  },
+}

package/docs/reference/install-agent.md

@@ -0,0 +1,79 @@
+# lattices
+
+> macOS developer workspace manager — tmux sessions with a native menu bar app for tiling, navigation, and project management
+
+You are an expert at installing lattices. Execute these steps autonomously
+and inform the user of any decisions made. Request approval before running
+installation commands.
+
+## OBJECTIVE
+
+Install the lattices CLI and optionally the native macOS menu bar companion app.
+
+## DONE WHEN
+
+`lattices help` returns Usage information for lattices CLI
+
+## TODO
+
+- [ ] Install tmux if not present
+- [ ] Clone the repository
+- [ ] Link the CLI globally
+- [ ] Build and launch the menu bar app
+- [ ] Create a config in your project
+- [ ] Start your first workspace
+
+## Prerequisites
+
+- macOS 26.0+
+- tmux (brew install tmux)
+- Node.js >= 18
+- Swift 6.2 / Xcode 26+ (only if building the menu bar app from source)
+
+## Step 1: Install tmux if not present
+
+```bash
+brew install tmux
+```
+
+## Step 2: Install from npm
+
+```bash
+npm install -g @lattices/cli
+```
+
+Or with your preferred package manager:
+
+```bash
+pnpm add -g @lattices/cli
+bun add -g @lattices/cli
+```
+
+### Alternative: Install from source
+
+```bash
+git clone https://github.com/arach/lattices && cd lattices
+bun link
+```
+
+## Step 3: Build and launch the menu bar app
+
+```bash
+lattices app
+```
+
+## Step 4: Create a config in your project
+
+```bash
+cd ~/your-project && lattices init
+```
+
+## Step 5: Start your first workspace
+
+```bash
+lattices
+```
+
+## EXECUTE NOW
+
+Proceed with installation following the TODO checklist above.

package/docs/release.md

@@ -0,0 +1,172 @@
+---
+title: Release
+description: Maintainer workflow for macOS DMG and npm releases
+order: 99
+---
+
+## macOS DMG releases
+
+The public macOS app release is a signed, notarized DMG attached to the
+GitHub release `v<version>`.
+
+There are two valid DMG paths:
+
+1. CI release: push an `app-macos-v<version>` tag or run the
+   **Release App macOS** workflow with `publish=true`.
+2. Local maintainer release: build and ship from a Mac that has the
+   Developer ID certificate and notary profile installed.
+
+Unsigned DMGs are smoke-test artifacts only. They should not create or update
+a public GitHub release.
+
+### CI release
+
+The workflow reads credentials from the GitHub `release` environment.
+
+Required environment secrets:
+
+```text
+DEVELOPER_ID_APPLICATION_CERT_BASE64
+DEVELOPER_ID_APPLICATION_CERT_PASSWORD
+KEYCHAIN_PASSWORD
+APP_STORE_CONNECT_API_KEY_P8
+```
+
+Required environment variable or secret:
+
+```text
+APP_STORE_CONNECT_KEY_ID
+```
+
+Optional environment variable or secret:
+
+```text
+APP_STORE_CONNECT_ISSUER_ID
+```
+
+Set `APP_STORE_CONNECT_ISSUER_ID` for Team API keys. Leave it unset for
+Individual API keys.
+
+Setup shape:
+
+```sh
+# Export the Developer ID Application certificate as a .p12, then:
+base64 < DeveloperIDApplication.p12 | tr -d '\n' \
+  | gh secret set DEVELOPER_ID_APPLICATION_CERT_BASE64 --repo arach/lattices --env release
+
+gh secret set DEVELOPER_ID_APPLICATION_CERT_PASSWORD --repo arach/lattices --env release
+gh secret set KEYCHAIN_PASSWORD --repo arach/lattices --env release
+gh secret set APP_STORE_CONNECT_API_KEY_P8 --repo arach/lattices --env release < AuthKey_KEYID.p8
+
+gh variable set APP_STORE_CONNECT_KEY_ID --repo arach/lattices --env release --body KEYID
+gh variable set APP_STORE_CONNECT_ISSUER_ID --repo arach/lattices --env release --body ISSUER_UUID
+```
+
+Release:
+
+```sh
+git tag -a app-macos-v0.5.0 -m "Lattices macOS 0.5.0"
+git push origin app-macos-v0.5.0
+```
+
+The workflow builds `dist/Lattices.dmg`, signs, notarizes, staples, verifies,
+then creates or updates GitHub release `v0.5.0` with both:
+
+```text
+Lattices.dmg
+Lattices-0.5.0.dmg
+```
+
+If publish is requested and signing/notary configuration is missing, the
+workflow must fail. A successful unsigned workflow run is only an artifact
+build, not a release.
+
+### Local maintainer release
+
+Use this when GitHub Actions is not provisioned with Apple credentials yet,
+or when intentionally shipping from a local release machine.
+
+Preflight:
+
+```sh
+gh auth status
+security find-identity -v -p codesigning
+xcrun notarytool history --keychain-profile notarytool-art | head
+```
+
+Build a signed, notarized DMG:
+
+```sh
+./tools/release/build-dmg.sh
+```
+
+Build and upload to GitHub Releases:
+
+```sh
+LATTICES_VERSION=0.5.0 ./tools/release/ship.sh dmg
+```
+
+The local ship script now mirrors CI: it creates or updates release `v0.5.0`,
+sets the title to `Lattices 0.5.0`, and uploads both the unversioned and
+versioned DMG assets.
+
+### Unsigned checks
+
+For a local smoke DMG:
+
+```sh
+LATTICES_SKIP_SIGN=1 LATTICES_SKIP_NOTARIZE=1 ./tools/release/build-dmg.sh
+```
+
+For CI smoke checks, run **Release App macOS** manually with `publish=false`.
+That path uploads an unsigned workflow artifact and intentionally skips the
+GitHub release step.
+
+## npm releases
+
+The CLI package is published as `@arach/lattices` (npm page) and also as
+`@lattices/cli` for back-compat — same tarball, dual publish in CI.
+
+There are two valid npm paths:
+
+1. CI release: push an `npm-v<version>` tag or run the
+   **Release Package npm** workflow with `publish=true`.
+2. Smoke check: run **Release Package npm** manually with `publish=false`.
+
+The npm workflow reads credentials from the GitHub `release` environment.
+
+Required environment secret:
+
+```text
+NPM_TOKEN
+```
+
+`NPM_TOKEN` must be an npm automation or granular access token that can
+publish `@arach/lattices` and `@lattices/cli`. It currently should authenticate as the npm user
+`arach`; if a different maintainer publishes, set environment variable
+`NPM_EXPECTED_USER` to that npm username.
+
+Setup shape:
+
+```sh
+gh secret set NPM_TOKEN --repo arach/lattices --env release
+gh variable set NPM_EXPECTED_USER --repo arach/lattices --env release --body arach
+```
+
+Release:
+
+```sh
+git tag -a npm-v0.6.1 -m "@arach/lattices 0.6.1"
+git push origin npm-v0.5.0
+```
+
+To publish the current `main` without moving a stale tag, run:
+
+```sh
+gh workflow run release-package-npm.yml --repo arach/lattices --ref main -f publish=true
+```
+
+Before publishing, CI now runs `npm whoami` and fails immediately if the token
+is missing, revoked, or belongs to the wrong npm user. This catches the common
+bad-token case before the macOS app prepack build and before npm's less useful
+package-scoped `E404` publish failure.

package/docs/repo-structure.md

@@ -0,0 +1,100 @@
+# Repository Structure
+
+Lattices is a small project with several real product surfaces. The root should
+make those surfaces obvious.
+
+This document is the current maintainer-facing map and the proposed direction
+for keeping file structure as architecture.
+
+## Current Top-Level Areas
+
+| Path | Role |
+| --- | --- |
+| `apps/mac/` | Native macOS menu bar app. Swift/AppKit/SwiftUI package. |
+| `bin/` | Published TypeScript CLI and app helper entry points. |
+| `swift/` | Shared Swift package code used by the app. |
+| `apps/ios/` | iOS companion app experiments and local build state. |
+| `apps/site/` | Vite website, documentation, and blog content. |
+| `apps/site/scripts/agent-docs.mjs` | Agent-facing docs collector and static artifact writer. |
+| `docs/` | Markdown docs and engineering proposals. |
+| `tools/agents/skills/` | Agent skill pack for driving Lattices. |
+| `assets/` | Shared release/app assets. |
+| `scripts/` | User/dev entry-point scripts: `install.sh`, `uninstall.sh`, `build.sh`, `run.sh` (root `install.sh` is a shim forwarding here). |
+| `tools/release/` | Maintainer scripts for building and shipping. |
+| `tests/` | CLI, daemon, and evaluation tests. |
+
+## Problem
+
+The root currently mixes categories:
+
+- shipped product surfaces: `apps/mac/`, `bin/`, `swift/`
+- website/docs: `apps/site/`
+- companion experiments: `apps/ios/`
+- generated or release output: `dist/`
+- maintainer and agent affordances: `docs/`, `tools/`, `tests/`
+
+That makes the project feel larger than it is. It also makes it harder to see
+which directories are architecture and which are support material.
+
+## Target Shape
+
+Do not reorganize everything at once. The target is:
+
+```text
+apps/
+  mac/            # macOS menu bar app
+  ios/            # iOS companion app
+  site/           # website, documentation, and blog content
+
+packages/
+  cli/            # current bin/ plus TypeScript package surface
+  swift/          # current swift/
+
+docs/
+  proposals/
+
+tools/
+  release/        # release/build scripts
+  agents/skills/  # agent skill pack
+```
+
+This is intentionally similar to the `apps/` and `packages/` split used by
+small monorepos such as Flue, but adapted for Lattices' macOS app plus CLI
+shape.
+
+## Migration Rules
+
+- Move one category at a time.
+- Keep published npm entry points stable.
+- Keep app bundle and release scripts working after each move.
+- Update docs and agent instructions in the same PR as any move.
+- Avoid renames that only satisfy aesthetics without reducing ambiguity.
+- Keep generated output ignored and out of the architectural map.
+
+## Near-Term Cleanup
+
+Good first moves:
+
+1. Treat `dist/` as generated output only.
+2. Move blog content closer to the site that owns it, or explicitly document it
+   as shared content.
+3. Decide whether the iOS companion remains in this repo or moves to its own
+   repo once the companion work becomes active again.
+4. Split `docs/proposals/` for numbered engineering docs such as `LAT-001`.
+5. Decide whether `bin/` remains the package root for the CLI or becomes
+   `packages/cli/src/` before adding more exported modules.
+
+## What Stays Boring
+
+Root files should be few and intentional:
+
+- `README.md`
+- `AGENTS.md`
+- `package.json`
+- lockfile
+- TypeScript config
+- license/security/contribution docs
+- release/install affordances
+
+Everything else should either be a product surface, a package, docs, content,
+or tooling.

package/docs/terminal-kit.md

@@ -0,0 +1,87 @@
+# LatticesTerminalKit
+
+`LatticesTerminalKit` is the reusable Swift terminal-inventory slice of
+lattices. It is designed for native hosts such as Scout that should embed the
+same macOS probes directly instead of talking to the lattices daemon or CLI.
+
+## V1 Scope
+
+The first slice inventories:
+
+- Apple Terminal
+- iTerm2
+- Ghostty
+
+It intentionally stays read-oriented. Focus and placement actions can build on
+the returned handles later, but the v1 contract is an observed terminal
+projection, not a canonical session or message store.
+
+## Import
+
+The product lives in the repo's reusable Swift package:
+
+```swift
+import LatticesTerminalKit
+
+let snapshot = TerminalInventory.snapshot()
+```
+
+For bounded tmux pane context:
+
+```swift
+let snapshot = TerminalInventory.snapshot(options: .init(
+    includePaneContent: true,
+    paneContentLineLimit: 120
+))
+```
+
+## Snapshot Shape
+
+`TerminalInventorySnapshot` contains:
+
+- `snapshotId`
+- `observedAt`
+- `terminals`
+- `tmuxSessions`
+- `terminalTabs`
+- `terminalWindows`
+
+Each `TerminalInstance` includes:
+
+- identity: `stableKey`, `tty`, app name, bundle id, app pid
+- terminal UI: window id/title, tab index/title, terminal session id
+- process context: interesting process rows, shell pid, cwd, cwd source
+- tmux context: session and pane id
+- harness detection: `detectedHarnesses` for Claude and Codex signals
+- action preparation: `focusHandle`, `placementHandle`, `capabilities`
+- trust metadata: `provenance` with confidence for tty/cwd/window/tmux/harness
+- optional inspection: bounded `paneCapture`
+
+## Join Strategy
+
+The kit joins by TTY first.
+
+Inputs:
+
+- process table from `ps`
+- cwd lookup from batched `lsof`
+- tmux sessions and panes
+- AppleScript tab probes for Terminal and iTerm2
+- CG window inventory for Terminal, iTerm2, and Ghostty
+
+Window resolution order:
+
+1. lattices title tag: `[lattices:<session>]`
+2. app window index from Terminal/iTerm2 tab probes
+3. CG owner process tree TTY, used especially for Ghostty
+
+Ghostty is expected to be window-level in v1. The kit does not synthesize stable
+tab ids from titles or z-order.
+
+## Notes For Scout
+
+CG window IDs are useful but volatile. Consumers should pair them with
+`stableKey`, app pid, bundle id, tty, and tmux pane identity where available.
+
+Pane capture is opt-in and ephemeral. It should be treated as drill-down context,
+not as durable chat or terminal history.