@lattices/cli 0.4.14 → 0.6.0

package/docs/release.md

@@ -0,0 +1,171 @@
+---
+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 `@lattices/cli`.
+
+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 `@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.5.0 -m "@lattices/cli 0.5.0"
+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

@@ -14,11 +14,12 @@ for keeping file structure as architecture.
 | `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/` | Public marketing site and blog content. |
-| `apps/docs-site/` | Astro documentation site. |
+| `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. |
 
@@ -27,7 +28,7 @@ for keeping file structure as architecture.
 The root currently mixes categories:
 
 - shipped product surfaces: `apps/mac/`, `bin/`, `swift/`
-- websites: `apps/site/`, `apps/docs-site/`
+- website/docs: `apps/site/`
 - companion experiments: `apps/ios/`
 - generated or release output: `dist/`
 - maintainer and agent affordances: `docs/`, `tools/`, `tests/`
@@ -43,8 +44,7 @@ Do not reorganize everything at once. The target is:
 apps/
   mac/            # macOS menu bar app
   ios/            # iOS companion app
-  site/           # marketing site and blog content
-  docs-site/      # documentation site
+  site/           # website, documentation, and blog content
 
 packages/
   cli/            # current bin/ plus TypeScript package surface

package/docs/voice.md

@@ -12,7 +12,7 @@ matches it to an intent, and executes it.
 ## Quick start
 
 1. Install Vox (provides mic + transcription)
-2. Install [Claude Code](https://claude.ai/code) CLI (provides AI advisor)
+2. Connect an Assistant provider in **Settings > AI**
 3. Press **Hyper+3** to open the voice command window
 4. Hold **Option** and speak a command
 5. Release **Option** — Lattices transcribes and executes
@@ -106,9 +106,9 @@ Trigger an OCR scan of visible windows.
 
 ## AI advisor
 
-Every voice command fires a Claude Haiku advisor in parallel. The
-advisor provides commentary and follow-up suggestions in the **AI
-corner** (bottom-right of the voice command window).
+Every voice command can ask the selected Assistant provider for
+commentary and follow-up suggestions in the **AI corner** (bottom-right
+of the voice command window).
 
 When local matching handles the command well, the AI corner shows
 "no AI needed" with an optional "ask AI" button. When the advisor
@@ -119,21 +119,13 @@ suggestion button.
 
 1. You speak a command
 2. Local intent matching runs immediately (fast, free)
-3. Haiku advisor runs in parallel (takes ~2-5 seconds)
+3. The selected Assistant provider runs in parallel when connected
 4. If the advisor suggests something, a button appears in the AI corner
 5. Click the suggestion to execute it
 6. If you engage with a suggestion that the local matcher missed,
    it's recorded in `~/.lattices/advisor-learning.jsonl` for future
    improvement
 
-### Session persistence
-
-The advisor maintains a conversation session across voice commands.
-It remembers what you've asked and what worked. When the context
-reaches 75% of the model's limit, the session auto-resets.
-
-Context usage and session cost are shown in the AI corner header.
-
 ## Hands-off inference
 
 Hands-off voice uses the shared inference wrapper in `bin/infer.ts`.
@@ -158,17 +150,9 @@ Open **Settings > AI** to configure:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| Claude CLI path | Auto-detected | Path to the `claude` binary. Checks `~/.local/bin/claude`, `/usr/local/bin/claude`, `/opt/homebrew/bin/claude`, then `which claude`. |
-| Advisor model | Haiku | `haiku` (fast, cheap) or `sonnet` (smarter, slower) |
-| Budget per session | $0.50 | Maximum spend per Claude CLI invocation |
-
-### Installing Claude Code
-
-```bash
-npm install -g @anthropic-ai/claude-code
-```
-
-Or see [claude.ai/code](https://claude.ai/code) for other install methods.
+| Assistant provider | OpenAI Codex | Provider used by the in-app chat and provider-backed voice advisor. Supports OAuth providers such as GitHub Copilot and OpenAI Codex plus API-key providers. |
+| Pi runtime | Auto-detected | Installs or refreshes the provider runtime used by the in-app assistant. |
+| Provider credentials | Not authenticated | Sign in with OAuth or save an API key locally for the selected provider. |
 
 ## Layout
 
@@ -179,7 +163,7 @@ The voice command window has four sections:
 | **History** | Left column | Past commands with expandable details |
 | **Voice Command** | Center column | Current transcript, matched intent, results |
 | **Log** | Top-right | Rolling diagnostic log (last 12 entries) |
-| **AI Corner** | Bottom-right | Advisor commentary, suggestions, session stats |
+| **AI Corner** | Bottom-right | Advisor commentary, suggestions, provider readiness |
 
 ## Search architecture
 
@@ -231,7 +215,7 @@ mappings and phrase pattern improvements.
 
 - **Vox** — provides microphone access and
   speech-to-text transcription
-- **[Claude Code](https://claude.ai/code)** CLI — provides the AI advisor
-  (optional, voice commands work without it but no AI suggestions)
+- **Assistant provider** — enables provider-backed AI suggestions from
+  **Settings > AI** (optional, voice commands still work without it)
 - **Accessibility** permission — for window tiling and focus
 - **Screen Recording** permission — for window discovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lattices/cli",
-  "version": "0.4.14",
+  "version": "0.6.0",
   "description": "The agentic workspace manager for macOS — turn your desktop into a coherent API",
   "packageManager": "bun@1.3.11",
   "engines": {
@@ -31,15 +31,22 @@
     "./project-twin": "./bin/project-twin.ts"
   },
   "scripts": {
-    "dev": "bun --cwd apps/docs-site dev",
+    "dev": "bun --cwd apps/site dev",
+    "site:build": "bun --cwd apps/site build",
+    "studio:dev": "bun --cwd apps/studio dev",
+    "studio:build": "bun --cwd apps/studio build",
+    "docs:agent": "bun --cwd apps/site agent-docs",
     "check": "bun run check:types && bun run check:app",
     "check:types": "tsc --noEmit",
     "check:app": "env CLANG_MODULE_CACHE_PATH=/tmp/lattices-clang-cache SWIFTPM_TESTS_MODULECACHE=/tmp/lattices-swiftpm-cache swift build --package-path apps/mac",
     "test:e2e": "node --experimental-strip-types --test tests/e2e-daemon.test.mjs",
     "test:e2e:voice": "node --experimental-strip-types tests/eval-voice.js",
     "typecheck": "bun run check:types",
-    "build:app-bundle": "bash ./bin/lattices-dev build",
-    "prepack": "bash ./bin/lattices-dev build"
+    "build:app-bundle": "bash ./bin/lattices-build package",
+    "build:dev-app": "bash ./bin/lattices-build dev",
+    "build:dist": "bash ./bin/lattices-build dist",
+    "build:dist:local": "bash ./bin/lattices-build dist:local",
+    "prepack": "bash ./bin/lattices-build package"
   },
   "type": "module",
   "os": ["darwin"],
@@ -48,13 +55,7 @@
     "apps/mac/Info.plist",
     "apps/mac/Lattices.app",
     "apps/mac/Lattices.entitlements",
-    "apps/mac/Package.swift",
     "apps/mac/Resources",
-    "apps/mac/Sources",
-    "apps/mac/Tests",
-    "swift/Package.swift",
-    "swift/Sources",
-    "swift/Tests",
     "assets/AppIcon.icns",
     "docs"
   ],

package/apps/mac/Package.swift

@@ -1,27 +0,0 @@
-// swift-tools-version: 5.9
-import PackageDescription
-
-let package = Package(
-    name: "Lattices",
-    platforms: [.macOS(.v13)],
-    dependencies: [
-        .package(path: "../../swift")
-    ],
-    targets: [
-        .executableTarget(
-            name: "Lattices",
-            dependencies: [
-                .product(name: "DeckKit", package: "swift")
-            ],
-            path: "Sources",
-            resources: [
-                .copy("../Resources/tap.wav"),
-                .copy("../Resources/Pets"),
-            ]
-        ),
-        .testTarget(
-            name: "LatticesTests",
-            path: "Tests"
-        )
-    ]
-)

package/apps/mac/Sources/AppShell/App.swift

@@ -1,26 +0,0 @@
-import SwiftUI
-
-@main
-struct LatticesApp: App {
-    @NSApplicationDelegateAdaptor(AppDelegate.self) var delegate
-
-    var body: some Scene {
-        Settings {
-            SettingsContentView(
-                prefs: Preferences.shared,
-                scanner: ProjectScanner.shared
-            )
-            .frame(width: 900, height: 640)
-        }
-            .commands {
-                CommandGroup(after: .appInfo) {
-                    Button("Update Lattices…") {
-                        AppUpdater.shared.promptForUpdate()
-                    }
-                    .disabled(!AppUpdater.shared.canUpdate)
-
-                    Divider()
-                }
-            }
-    }
-}

package/apps/mac/Sources/AppShell/AppActivationCoordinator.swift

@@ -1,27 +0,0 @@
-import AppKit
-
-final class AppActivationCoordinator {
-    static let shared = AppActivationCoordinator()
-
-    private var surfaceVisibilityProviders: [(id: String, isVisible: () -> Bool)] = []
-
-    private init() {}
-
-    func registerSurface(id: String, isVisible: @escaping () -> Bool) {
-        guard !surfaceVisibilityProviders.contains(where: { $0.id == id }) else { return }
-        surfaceVisibilityProviders.append((id: id, isVisible: isVisible))
-    }
-
-    func refresh() {
-        let hasVisibleWindow = surfaceVisibilityProviders.contains { provider in
-            provider.isVisible()
-        }
-        let desired: NSApplication.ActivationPolicy = hasVisibleWindow ? .regular : .accessory
-        if NSApp.activationPolicy() != desired {
-            NSApp.setActivationPolicy(desired)
-            if desired == .regular {
-                NSApp.activate(ignoringOtherApps: true)
-            }
-        }
-    }
-}

package/apps/mac/Sources/AppShell/AppDelegate.swift

@@ -1,189 +0,0 @@
-import AppKit
-import Carbon
-
-extension Notification.Name {
-    static let latticesPopoverWillShow = Notification.Name("latticesPopoverWillShow")
-    static let latticesShowGeneralSettings = Notification.Name("latticesShowGeneralSettings")
-    static let latticesShowAssistantSettings = Notification.Name("latticesShowAssistantSettings")
-}
-
-class AppDelegate: NSObject, NSApplicationDelegate {
-    private var notificationObservers: [NSObjectProtocol] = []
-
-    static func updateActivationPolicy() {
-        AppActivationCoordinator.shared.refresh()
-    }
-
-    func applicationDidFinishLaunching(_ notification: Notification) {
-        NSApp.setActivationPolicy(.accessory)
-        NSApp.appearance = NSAppearance(named: .darkAqua)
-        registerDeepLinkHandler()
-        installSystemInputBoundaryObservers()
-
-        MenuBarController.shared.start()
-        registerVisibleSurfaces()
-        HotkeyBootstrap.registerHotkeys()
-
-        DispatchQueue.main.async { HUDController.shared.warmUp() }
-        DispatchQueue.main.async { MenuBarController.shared.warmUpPopover() }
-        DispatchQueue.main.async { ScreenOverlayCanvasController.shared.warmUp() }
-
-        WindowDragSnapController.shared.start()
-        MouseGestureController.shared.start()
-        KeyboardRemapController.shared.start()
-        SecureEventInputMonitor.shared.start()
-
-        if !OnboardingWindowController.shared.showIfNeeded() {
-            PermissionChecker.shared.check()
-        }
-
-        AppServicesBootstrap.start()
-
-        Task {
-            await AppUpdater.shared.checkIfNeeded()
-        }
-
-        // --diagnostics flag: auto-open diagnostics panel on launch
-        if CommandLine.arguments.contains("--diagnostics") {
-            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
-                DiagnosticWindow.shared.show()
-            }
-        }
-
-        // --screen-map flag: auto-open layout on launch
-        if CommandLine.arguments.contains("--screen-map") {
-            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
-                ScreenMapWindowController.shared.showPage(.screenMap)
-            }
-        }
-
-        // Explicit preview entry point for development/demo flows. This still
-        // requires a launch argument; the assistant never opens automatically.
-        if CommandLine.arguments.contains("--permissions-assistant") {
-            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
-                PermissionsAssistantWindowController.shared.show()
-            }
-        }
-    }
-
-    func applicationWillTerminate(_ notification: Notification) {
-        removeSystemInputBoundaryObservers()
-        SecureEventInputMonitor.shared.stop()
-        KeyboardRemapController.shared.stop()
-        AppServicesBootstrap.stop()
-    }
-
-    func applicationDidBecomeActive(_ notification: Notification) {
-        resetInputCapture(reason: "app became active")
-    }
-
-    func applicationWillResignActive(_ notification: Notification) {
-        resetInputCapture(reason: "app resigned active")
-    }
-
-    private func registerVisibleSurfaces() {
-        let coordinator = AppActivationCoordinator.shared
-        coordinator.registerSurface(id: "menuBarPopover") { MenuBarController.shared.isPopoverShown }
-        coordinator.registerSurface(id: "commandMode") { CommandModeWindow.shared.isVisible }
-        coordinator.registerSurface(id: "commandPalette") { CommandPaletteWindow.shared.isVisible }
-        coordinator.registerSurface(id: "mainWindow") { MainWindow.shared.isVisible }
-        coordinator.registerSurface(id: "screenMap") { ScreenMapWindowController.shared.isVisible }
-        coordinator.registerSurface(id: "omniSearch") { OmniSearchWindow.shared.isVisible }
-    }
-
-    private func installSystemInputBoundaryObservers() {
-        let center = NSWorkspace.shared.notificationCenter
-        notificationObservers.append(center.addObserver(
-            forName: NSWorkspace.willSleepNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.resetInputCapture(reason: "system will sleep")
-        })
-        notificationObservers.append(center.addObserver(
-            forName: NSWorkspace.didWakeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.resetInputCapture(reason: "system did wake")
-        })
-        notificationObservers.append(center.addObserver(
-            forName: NSWorkspace.screensDidWakeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.resetInputCapture(reason: "screens did wake")
-        })
-        notificationObservers.append(center.addObserver(
-            forName: NSWorkspace.screensDidSleepNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.resetInputCapture(reason: "screens did sleep")
-        })
-    }
-
-    private func removeSystemInputBoundaryObservers() {
-        let center = NSWorkspace.shared.notificationCenter
-        for observer in notificationObservers {
-            center.removeObserver(observer)
-        }
-        notificationObservers.removeAll()
-    }
-
-    private func resetInputCapture(reason: String) {
-        InputCaptureResetCenter.reset(reason: reason)
-    }
-
-    // MARK: - Deep Links
-
-    private func registerDeepLinkHandler() {
-        NSAppleEventManager.shared().setEventHandler(
-            self,
-            andSelector: #selector(handleGetURLEvent(_:withReplyEvent:)),
-            forEventClass: AEEventClass(kInternetEventClass),
-            andEventID: AEEventID(kAEGetURL)
-        )
-    }
-
-    @objc private func handleGetURLEvent(
-        _ event: NSAppleEventDescriptor,
-        withReplyEvent replyEvent: NSAppleEventDescriptor
-    ) {
-        guard
-            let value = event.paramDescriptor(forKeyword: keyDirectObject)?.stringValue,
-            let url = URL(string: value)
-        else {
-            return
-        }
-        handleDeepLink(url)
-    }
-
-    private func handleDeepLink(_ url: URL) {
-        guard url.scheme?.localizedCaseInsensitiveCompare("lattices") == .orderedSame else {
-            return
-        }
-
-        let host = url.host?.lowercased()
-        let action = url.pathComponents
-            .first { $0 != "/" }?
-            .lowercased()
-
-        guard host == "companion" else {
-            SettingsWindowController.shared.show()
-            return
-        }
-
-        switch action {
-        case "enable", "start":
-            Preferences.shared.companionBridgeEnabled = true
-            SettingsWindowController.shared.showCompanion()
-        case "disable", "stop":
-            Preferences.shared.companionBridgeEnabled = false
-            SettingsWindowController.shared.showCompanion()
-        default:
-            SettingsWindowController.shared.showCompanion()
-        }
-    }
-
-}

package/apps/mac/Sources/AppShell/AppServicesBootstrap.swift

@@ -1,25 +0,0 @@
-enum AppServicesBootstrap {
-    static func start() {
-        let diagnosticLog = DiagnosticLog.shared
-        let timedBoot = diagnosticLog.startTimed("Daemon services boot")
-        OcrStore.shared.open()
-        DesktopModel.shared.start()
-        OcrModel.shared.start()
-        TmuxModel.shared.start()
-        ProcessModel.shared.start()
-        LatticesApi.setup()
-        DaemonServer.shared.start()
-        if Preferences.shared.companionBridgeEnabled {
-            LatticesCompanionBridgeServer.shared.start()
-        } else {
-            diagnosticLog.info("CompanionBridge: disabled by preference")
-        }
-        AgentPool.shared.start()
-        diagnosticLog.finish(timedBoot)
-    }
-
-    static func stop() {
-        LatticesCompanionBridgeServer.shared.stop()
-        DaemonServer.shared.stop()
-    }
-}