@lattices/cli 0.4.9 → 0.4.11

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/` | Public marketing site and blog content. |
+| `apps/docs-site/` | Astro documentation site. |
+| `docs/` | Markdown docs and engineering proposals. |
+| `tools/agents/skills/` | Agent skill pack for driving Lattices. |
+| `assets/` | Shared release/app assets. |
+| `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/`
+- websites: `apps/site/`, `apps/docs-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/           # marketing site and blog content
+  docs-site/      # documentation site
+
+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/voice-error-model.md

@@ -2,7 +2,7 @@
 
 ## Goal + anchors
 
-Use one error vocabulary for Mac voice capture/execution and iPad relay/status. The canonical protocol says Lattices borrows Vox for capture and never owns the mic directly (`docs/voice-command-protocol.md:5-7`), but the shared runtime already has a cross-platform `DeckVoiceState` slot (`swift/Sources/DeckKit/DeckRuntimeSnapshot.swift:49-68`). Current Mac code exposes local strings (`VoxError`, `executionResult`) instead of structured errors (`app/Sources/VoxClient.swift:43-59`, `app/Sources/AudioProvider.swift:343-349`); iPad has only a generic `errorMessage` (`iOS/LatticesCompanion/Sources/DeckStore.swift:18`). Normalize at DeckKit, then let each surface render the same object.
+Use one error vocabulary for Mac voice capture/execution and iPad relay/status. The canonical protocol says Lattices borrows Vox for capture and never owns the mic directly (`docs/voice-command-protocol.md:5-7`), but the shared runtime already has a cross-platform `DeckVoiceState` slot (`swift/Sources/DeckKit/DeckRuntimeSnapshot.swift:49-68`). Current Mac code exposes local strings (`VoxError`, `executionResult`) instead of structured errors (`apps/mac/Sources/VoxClient.swift:43-59`, `apps/mac/Sources/AudioProvider.swift:343-349`); iPad has only a generic `errorMessage` (`apps/ios/Sources/DeckStore.swift:18`). Normalize at DeckKit, then let each surface render the same object.
 
 ## Error structure
 
@@ -48,21 +48,21 @@ Copy examples: `Mic in use by Vox — finish memo first`, `No target window`, `V
 
 ## Presentation patterns
 
-**Mac VoiceCommandWindow.** Keep the three-column cockpit. The top mic bar already owns live state (`connecting...`, `processing...`; `app/Sources/VoiceCommandWindow.swift:692-719`); render the active error as a compact red/amber status chip there. The center column uses `commandSection` cards (`app/Sources/VoiceCommandWindow.swift:1287-1304`): show a single `blocked`/`needs action` card only when the user can do something. The footer already has key chips (`app/Sources/VoiceCommandWindow.swift:1308-1348`); replace the generic command list with contextual remediation: `⌥ Retry`, `Return Open Vox`, `⌘, Permissions`. Logs stay in the right rail, using existing level colors (`app/Sources/VoiceCommandWindow.swift:1112-1150`).
+**Mac VoiceCommandWindow.** Keep the three-column cockpit. The top mic bar already owns live state (`connecting...`, `processing...`; `apps/mac/Sources/VoiceCommandWindow.swift:692-719`); render the active error as a compact red/amber status chip there. The center column uses `commandSection` cards (`apps/mac/Sources/VoiceCommandWindow.swift:1287-1304`): show a single `blocked`/`needs action` card only when the user can do something. The footer already has key chips (`apps/mac/Sources/VoiceCommandWindow.swift:1308-1348`); replace the generic command list with contextual remediation: `⌥ Retry`, `Return Open Vox`, `⌘, Permissions`. Logs stay in the right rail, using existing level colors (`apps/mac/Sources/VoiceCommandWindow.swift:1112-1150`).
 
-**Mac HUD.** `HUDTopBar.voiceStatus` already has dot, label, transcript, response (`app/Sources/HUDTopBar.swift:134-198`). Add severity tint: green idle/listening, amber connecting/recoverable, red blocked. For active voice errors, HUD shows a one-line banner in the top bar; no sheet.
+**Mac HUD.** `HUDTopBar.voiceStatus` already has dot, label, transcript, response (`apps/mac/Sources/HUDTopBar.swift:134-198`). Add severity tint: green idle/listening, amber connecting/recoverable, red blocked. For active voice errors, HUD shows a one-line banner in the top bar; no sheet.
 
-**iPad Home.** Add `HomeVoiceOverlay` as the full voice modal for active relay: title row `VOICE`, phase, transcript, Mac owner, and one remediation button. The bottom bar already has dense status slots and `hold·space` (`iOS/LatticesCompanion/Sources/Home/HomeBottomBar.swift:58-68`, `iOS/LatticesCompanion/Sources/Home/HomeBottomBar.swift:129-148`); render idle/recoverable errors inline there (`voice · reconnecting`, `voice · Vox offline`). Use a deck overlay banner only when an issued iPad action failed. Use sheets only for permissions/pairing because they need human action. This follows the chrome rule: do not remove noisy UI; replace it with state that answers “what am I controlling, who is listening, what failed?” (`/Users/arach/.claude/projects/-Users-arach-dev-lattices/memory/feedback_chrome_design.md:11-13`).
+**iPad Home.** Add `HomeVoiceOverlay` as the full voice modal for active relay: title row `VOICE`, phase, transcript, Mac owner, and one remediation button. The bottom bar already has dense status slots and `hold·space` (`apps/ios/Sources/Home/HomeBottomBar.swift:58-68`, `apps/ios/Sources/Home/HomeBottomBar.swift:129-148`); render idle/recoverable errors inline there (`voice · reconnecting`, `voice · Vox offline`). Use a deck overlay banner only when an issued iPad action failed. Use sheets only for permissions/pairing because they need human action. This follows the chrome rule: do not remove noisy UI; replace it with state that answers “what am I controlling, who is listening, what failed?” (`/Users/arach/.claude/projects/-Users-arach-dev-lattices/memory/feedback_chrome_design.md:11-13`).
 
 ## Unhappy-path prescriptions
 
-**Launch Vox on demand.** Spec flow is detect installed/not running, open Vox, show `Starting Vox...`, wait up to 10s, retry `startDictation`, then fail with manual-open copy (`docs/voice-command-protocol.md:73-89`). Current Mac waits 2s after `connect()` (`app/Sources/VoiceCommandWindow.swift:290-313`); design target is `vox_not_running` → `vox_loading` → retry → either clear error or `vox_unreachable` with `openVox`.
+**Launch Vox on demand.** Spec flow is detect installed/not running, open Vox, show `Starting Vox...`, wait up to 10s, retry `startDictation`, then fail with manual-open copy (`docs/voice-command-protocol.md:73-89`). Current Mac waits 2s after `connect()` (`apps/mac/Sources/VoiceCommandWindow.swift:290-313`); design target is `vox_not_running` → `vox_loading` → retry → either clear error or `vox_unreachable` with `openVox`.
 
 **Mic busy.** Preserve owner attribution from protocol (`docs/voice-command-protocol.md:127-135`). `mic_busy(owner: "Vox")` is warning, recoverable, retry hint `userAction`; message: `Mic in use by Vox — finish memo first`. If owner is unknown: `Mic busy — wait for current recording`.
 
 **Connection recovery.** If idle, reconnect silently and write log only. If active, show red `Connection lost`; do not auto-retry captured audio because Vox cancels dropped sockets (`docs/voice-command-protocol.md:174-188`). iPad shows `Mac voice link lost` if bridge lost, not `network` unless the iPad transport failed.
 
-**JSONL.** Add `~/.lattices/voice.jsonl` beside `lattices.log` (current log path is `~/.lattices/lattices.log`; `app/Sources/DiagnosticLog.swift:40-59`). Shape:
+**JSONL.** Add `~/.lattices/voice.jsonl` beside `lattices.log` (current log path is `~/.lattices/lattices.log`; `apps/mac/Sources/DiagnosticLog.swift:40-59`). Shape:
 
 ```json
 {"ts":"2026-04-27T14:03:11.120Z","platform":"mac","sessionId":"...","phase":"listening","event":"error","error":{"code":"mic_busy","severity":"warning","recoverable":true,"source":"vox","owner":"Vox","message":"Mic in use by Vox — finish memo first"},"transcript":null,"intent":null,"durationMs":820}
@@ -70,4 +70,4 @@ Copy examples: `Mic in use by Vox — finish memo first`, `No target window`, `V
 
 ## Cross-platform conventions
 
-Tone: terse cockpit, no apologies. Prefer noun-state-action: `Vox offline — starting`, `No target — pick window`, `Access denied — enable Accessibility`. Tint maps to existing palettes: Mac `Palette.detach` amber and `Palette.kill` red (`app/Sources/Theme.swift:19-23`); iPad `LatsPalette.amber/red` (`iOS/LatticesCompanion/Sources/LatsDeckScreen.swift:19-25`). Icons: `mic.fill` live, `mic.slash` denied, `waveform.badge.exclamationmark` transcription, `bolt.trianglebadge.exclamationmark` execution, `wifi.exclamationmark` connection, `scope` target. Ownership: Mac owns Vox, mic, Accessibility, intent execution, and JSONL. iPad owns relay/bridge/network presentation and never claims direct mic capture.
+Tone: terse cockpit, no apologies. Prefer noun-state-action: `Vox offline — starting`, `No target — pick window`, `Access denied — enable Accessibility`. Tint maps to existing palettes: Mac `Palette.detach` amber and `Palette.kill` red (`apps/mac/Sources/Theme.swift:19-23`); iPad `LatsPalette.amber/red` (`apps/ios/Sources/LatsDeckScreen.swift:19-25`). Icons: `mic.fill` live, `mic.slash` denied, `waveform.badge.exclamationmark` transcription, `bolt.trianglebadge.exclamationmark` execution, `wifi.exclamationmark` connection, `scope` target. Ownership: Mac owns Vox, mic, Accessibility, intent execution, and JSONL. iPad owns relay/bridge/network presentation and never claims direct mic capture.

package/docs/voice.md

@@ -134,6 +134,24 @@ 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`.
+By default it chooses the lowest-latency configured provider and, when
+Groq credentials are present, uses `groq/llama-3.1-8b-instant`.
+
+Credentials are read from process env, `.env.local`, `.env`,
+`~/.lattices/inference.json`, then `~/.config/speakeasy/settings.json`.
+For Groq, either `GROQ_API_KEY` or the common typo `GROK_API_KEY` works
+when the key has Groq's `gsk_` prefix.
+
+Override the voice engine if needed:
+
+```bash
+LATTICES_VOICE_PROVIDER=groq
+LATTICES_VOICE_MODEL=llama-3.1-8b-instant
+```
+
 ## Configuration
 
 Open **Settings > AI** to configure:

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@lattices/cli",
-  "version": "0.4.9",
-  "description": "Agentic window manager for macOS — programmable workspace, smart layouts, managed tmux sessions, and a 35+-method agent API",
+  "version": "0.4.11",
+  "description": "The agentic workspace manager for macOS — turn your desktop into a coherent API",
+  "packageManager": "bun@1.3.11",
+  "engines": {
+    "node": ">=18"
+  },
   "bin": {
     "lattices": "./bin/lattices.ts",
     "lattices-app": "./bin/lattices-app.ts"
@@ -27,10 +31,13 @@
     "./project-twin": "./bin/project-twin.ts"
   },
   "scripts": {
-    "dev": "bun --cwd docs-site dev",
-    "test:e2e": "node --experimental-strip-types --test test/e2e-daemon.test.mjs",
-    "test:e2e:voice": "node --experimental-strip-types test/eval-voice.js",
-    "typecheck": "tsc --noEmit",
+    "dev": "bun --cwd apps/docs-site dev",
+    "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"
   },
@@ -38,13 +45,16 @@
   "os": ["darwin"],
   "files": [
     "bin",
-    "app/Info.plist",
-    "app/Lattices.app",
-    "app/Lattices.entitlements",
-    "app/Package.swift",
-    "app/Resources",
-    "app/Sources",
-    "app/Tests",
+    "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/swift/Package.swift

@@ -0,0 +1,20 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "DeckKit",
+    platforms: [
+        .macOS(.v13),
+        .iOS(.v17)
+    ],
+    products: [
+        .library(name: "DeckKit", targets: ["DeckKit"])
+    ],
+    targets: [
+        .target(name: "DeckKit"),
+        .testTarget(
+            name: "DeckKitTests",
+            dependencies: ["DeckKit"]
+        )
+    ]
+)

package/swift/Sources/DeckKit/DeckAction.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+public struct DeckActionRequest: Codable, Equatable, Sendable {
+    public var pageID: String?
+    public var actionID: String
+    public var payload: [String: DeckValue]
+
+    public init(
+        pageID: String? = nil,
+        actionID: String,
+        payload: [String: DeckValue] = [:]
+    ) {
+        self.pageID = pageID
+        self.actionID = actionID
+        self.payload = payload
+    }
+}
+
+public struct DeckActionResult: Codable, Equatable, Sendable {
+    public var ok: Bool
+    public var summary: String
+    public var detail: String?
+    public var runtimeSnapshot: DeckRuntimeSnapshot?
+    public var suggestedActions: [DeckSuggestedAction]
+
+    public init(
+        ok: Bool,
+        summary: String,
+        detail: String? = nil,
+        runtimeSnapshot: DeckRuntimeSnapshot? = nil,
+        suggestedActions: [DeckSuggestedAction] = []
+    ) {
+        self.ok = ok
+        self.summary = summary
+        self.detail = detail
+        self.runtimeSnapshot = runtimeSnapshot
+        self.suggestedActions = suggestedActions
+    }
+}
+
+public struct DeckSuggestedAction: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var title: String
+    public var iconSystemName: String?
+
+    public init(id: String, title: String, iconSystemName: String? = nil) {
+        self.id = id
+        self.title = title
+        self.iconSystemName = iconSystemName
+    }
+}

package/swift/Sources/DeckKit/DeckBridgeSecurity.swift

@@ -0,0 +1,152 @@
+import Foundation
+
+public struct DeckPairingRequest: Codable, Equatable, Sendable {
+    public var deviceID: String
+    public var deviceName: String
+    public var devicePublicKey: String
+    public var platform: String
+    public var appVersion: String?
+    public var requestedCapabilities: [String]
+
+    public init(
+        deviceID: String,
+        deviceName: String,
+        devicePublicKey: String,
+        platform: String,
+        appVersion: String? = nil,
+        requestedCapabilities: [String] = DeckBridgeCapability.defaultCompanionCapabilities
+    ) {
+        self.deviceID = deviceID
+        self.deviceName = deviceName
+        self.devicePublicKey = devicePublicKey
+        self.platform = platform
+        self.appVersion = appVersion
+        self.requestedCapabilities = requestedCapabilities
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case deviceID
+        case deviceName
+        case devicePublicKey
+        case platform
+        case appVersion
+        case requestedCapabilities
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        deviceID = try container.decode(String.self, forKey: .deviceID)
+        deviceName = try container.decode(String.self, forKey: .deviceName)
+        devicePublicKey = try container.decode(String.self, forKey: .devicePublicKey)
+        platform = try container.decode(String.self, forKey: .platform)
+        appVersion = try container.decodeIfPresent(String.self, forKey: .appVersion)
+        requestedCapabilities = try container.decodeIfPresent([String].self, forKey: .requestedCapabilities)
+            ?? DeckBridgeCapability.defaultCompanionCapabilities
+    }
+}
+
+public struct DeckPairingResponse: Codable, Equatable, Sendable {
+    public var disposition: DeckPairingDisposition
+    public var bridgeName: String
+    public var bridgePublicKey: String
+    public var bridgeFingerprint: String
+    public var requestSigningRequired: Bool
+    public var payloadEncryptionRequired: Bool
+    public var grantedCapabilities: [String]
+    public var detail: String?
+
+    public init(
+        disposition: DeckPairingDisposition,
+        bridgeName: String,
+        bridgePublicKey: String,
+        bridgeFingerprint: String,
+        requestSigningRequired: Bool,
+        payloadEncryptionRequired: Bool,
+        grantedCapabilities: [String] = DeckBridgeCapability.defaultCompanionCapabilities,
+        detail: String? = nil
+    ) {
+        self.disposition = disposition
+        self.bridgeName = bridgeName
+        self.bridgePublicKey = bridgePublicKey
+        self.bridgeFingerprint = bridgeFingerprint
+        self.requestSigningRequired = requestSigningRequired
+        self.payloadEncryptionRequired = payloadEncryptionRequired
+        self.grantedCapabilities = grantedCapabilities
+        self.detail = detail
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case disposition
+        case bridgeName
+        case bridgePublicKey
+        case bridgeFingerprint
+        case requestSigningRequired
+        case payloadEncryptionRequired
+        case grantedCapabilities
+        case detail
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        disposition = try container.decode(DeckPairingDisposition.self, forKey: .disposition)
+        bridgeName = try container.decode(String.self, forKey: .bridgeName)
+        bridgePublicKey = try container.decode(String.self, forKey: .bridgePublicKey)
+        bridgeFingerprint = try container.decode(String.self, forKey: .bridgeFingerprint)
+        requestSigningRequired = try container.decode(Bool.self, forKey: .requestSigningRequired)
+        payloadEncryptionRequired = try container.decode(Bool.self, forKey: .payloadEncryptionRequired)
+        grantedCapabilities = try container.decodeIfPresent([String].self, forKey: .grantedCapabilities)
+            ?? DeckBridgeCapability.defaultCompanionCapabilities
+        detail = try container.decodeIfPresent(String.self, forKey: .detail)
+    }
+}
+
+public enum DeckPairingDisposition: String, Codable, CaseIterable, Sendable {
+    case approved
+    case alreadyTrusted
+    case denied
+}
+
+public struct DeckEncryptedEnvelope: Codable, Equatable, Sendable {
+    public var sealedBox: String
+
+    public init(sealedBox: String) {
+        self.sealedBox = sealedBox
+    }
+}
+
+public struct DeckTrustedDeviceSummary: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var name: String
+    public var fingerprint: String
+    public var capabilities: [String]
+    public var pairedAt: Date
+    public var lastSeenAt: Date
+
+    public init(
+        id: String,
+        name: String,
+        fingerprint: String,
+        capabilities: [String] = [],
+        pairedAt: Date,
+        lastSeenAt: Date
+    ) {
+        self.id = id
+        self.name = name
+        self.fingerprint = fingerprint
+        self.capabilities = capabilities
+        self.pairedAt = pairedAt
+        self.lastSeenAt = lastSeenAt
+    }
+}
+
+public enum DeckBridgeCapability {
+    public static let deckRead = "deck.read"
+    public static let deckPerform = "deck.perform"
+    public static let inputTrackpad = "input.trackpad"
+
+    public static let defaultCompanionCapabilities = [
+        deckRead,
+        deckPerform,
+        inputTrackpad,
+    ]
+}

package/swift/Sources/DeckKit/DeckCockpit.swift

@@ -0,0 +1,82 @@
+import Foundation
+
+public struct DeckCockpitState: Codable, Equatable, Sendable {
+    public var title: String?
+    public var detail: String?
+    public var pages: [DeckCockpitPage]
+
+    public init(
+        title: String? = nil,
+        detail: String? = nil,
+        pages: [DeckCockpitPage]
+    ) {
+        self.title = title
+        self.detail = detail
+        self.pages = pages
+    }
+}
+
+public struct DeckCockpitPage: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var title: String
+    public var subtitle: String?
+    public var columns: Int
+    public var tiles: [DeckCockpitTile]
+
+    public init(
+        id: String,
+        title: String,
+        subtitle: String? = nil,
+        columns: Int = 4,
+        tiles: [DeckCockpitTile]
+    ) {
+        self.id = id
+        self.title = title
+        self.subtitle = subtitle
+        self.columns = columns
+        self.tiles = tiles
+    }
+}
+
+public struct DeckCockpitTile: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var shortcutID: String
+    public var title: String
+    public var subtitle: String?
+    public var iconSystemName: String
+    public var accentToken: String?
+    public var deckID: String?
+    public var categoryTint: String?
+    public var actionID: String?
+    public var payload: [String: DeckValue]
+    public var isEnabled: Bool
+    public var isActive: Bool
+
+    public init(
+        id: String,
+        shortcutID: String,
+        title: String,
+        subtitle: String? = nil,
+        iconSystemName: String,
+        accentToken: String? = nil,
+        deckID: String? = nil,
+        categoryTint: String? = nil,
+        actionID: String? = nil,
+        payload: [String: DeckValue] = [:],
+        isEnabled: Bool = true,
+        isActive: Bool = false
+    ) {
+        self.id = id
+        self.shortcutID = shortcutID
+        self.title = title
+        self.subtitle = subtitle
+        self.iconSystemName = iconSystemName
+        self.accentToken = accentToken
+        self.deckID = deckID
+        self.categoryTint = categoryTint
+        self.actionID = actionID
+        self.payload = payload
+        self.isEnabled = isEnabled
+        self.isActive = isActive
+    }
+}

package/swift/Sources/DeckKit/DeckHost.swift

@@ -0,0 +1,7 @@
+import Foundation
+
+public protocol DeckHost: Sendable {
+    func manifest() async throws -> DeckManifest
+    func runtimeSnapshot() async throws -> DeckRuntimeSnapshot
+    func perform(_ request: DeckActionRequest) async throws -> DeckActionResult
+}