@synapta/skills 0.1.1 → 0.2.0

package/skills/voice-command-router/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: voice-command-router
+description: Route Siri / App Intents / voice commands to gateway approval actions. Voice never grants raw shell. All approvals route through the standard signed-approval pipeline.
+triggers: [synapta voice, Siri, App Intent, voice command, hands-free approval]
+network: off
+tools: []
+source:
+  origin: authored-by-synapta
+  reason: "Synapta-specific routing from Apple App Intents to gateway approval pipeline."
+  citation_patterns:
+    - "App Intents framework (Apple Developer)"
+    - "SiriKit (legacy fallback)"
+---
+
+# Voice Command Router
+
+Translate voice / App Intent invocations into bounded gateway actions. Voice never bypasses approval gates.
+
+## Allowed intents (Track A)
+
+| Intent name | Action | Requires confirmation? |
+|---|---|---|
+| `ShowSessionStatusIntent` | read session state via gateway | no (read-only) |
+| `ShowProductionSummaryIntent` | read prod incidents via gateway | no |
+| `ApproveDeploymentIntent` | sign + send `approve_phase` MCP call | **yes** (`requestConfirmation`) |
+| `RejectDeploymentIntent` | send `approve_phase` with reject | yes |
+| `PauseAgentIntent` | send `cancel` to current session | yes |
+| `OpenSessionIntent` | open the app at a session view | no |
+
+## Routing rules
+
+1. Match utterance → intent via Apple's parser (App Intents). Don't write a custom NLP layer.
+2. For every intent that mutates state (`Approve*`, `Reject*`, `Pause*`), require `requestConfirmation` and pass the entity in the summary.
+3. Construct the signed payload locally (Ed25519 key in Keychain), send via the gateway client.
+4. Translate gateway response to voice copy: success → 1 sentence; failure → 1 sentence + suggested next step.
+5. Log every voice action to the gateway audit log with `actor: 'voice'`.
+
+## Refusals
+
+The router MUST refuse:
+- Any command that maps to "execute arbitrary code / shell"
+- Any approval not within an active phase awaiting approval
+- Any command from an unpaired device or one with insufficient scope
+
+Refusal copy is short, blameless: "I can't do that from here — approval needs to happen at the terminal" or "Pairing isn't active. Open Synapta to pair first."
+
+## Anti-patterns
+
+- Free-form text input via voice that becomes a CLI command
+- Skipping `requestConfirmation` for state-mutating intents to save a tap
+- Adding custom intents that work around the approval pipeline

package/skills/widget-live-activity-sync/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: widget-live-activity-sync
+description: Sync iOS WidgetKit timelines and ActivityKit Live Activities with gateway state via push tokens + silent APNs reloads. Keep the on-device cache canonical; reconcile on app launch.
+triggers: [synapta widget sync, Live Activity, WidgetKit timeline, push token]
+network: off
+tools: []
+source:
+  origin: authored-by-synapta
+  reason: "Synapta-specific sync between gateway events and iOS surfaces."
+  citation_patterns:
+    - "ActivityKit (Apple Developer)"
+    - "WidgetKit timeline + WidgetCenter.reloadTimelines"
+    - "Push-token registration for Live Activities"
+---
+
+# Widget + Live Activity Sync
+
+Keep iOS WidgetKit timelines and ActivityKit Live Activities in lockstep with the Synapta gateway. Push-driven, never poll.
+
+## Live Activity lifecycle
+
+1. **Start**: iOS calls `Activity<DeployActivityAttributes>.request(...)`. iOS returns a `pushTokenUpdates` async stream.
+2. **Register**: iOS reads the first push token from the stream, sends it to the gateway: `POST /devices/<id>/live-activities { activityId, pushToken }`.
+3. **Update**: gateway publishes APNs Live Activity update pushes with new `content-state`. iOS receives them and the Dynamic Island / Lock Screen UI updates automatically.
+4. **End**: when the deploy completes, gateway sends a final update with `event: end` and a `dismissal-date`. Activity is removed.
+
+Push tokens are per-activity, not per-device. They expire when the activity ends.
+
+## Widget timeline reload
+
+Widgets don't get direct pushes. Use **silent APNs** to trigger:
+
+```swift
+// In the app's AppDelegate or app delegate equivalent
+func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
+  if let kind = (userInfo["synapta"] as? [String: Any])?["kind"] as? String, kind == "widget_reload" {
+    WidgetCenter.shared.reloadAllTimelines()
+    fetchCompletionHandler(.newData)
+  } else {
+    fetchCompletionHandler(.noData)
+  }
+}
+```
+
+## Reconciliation
+
+On app launch (or when widgets transition from stale → reload), fetch the latest state from the gateway and refresh:
+
+```swift
+let state = try await gateway.fetchSessionState()
+ArtifactCache.shared.update(state)
+WidgetCenter.shared.reloadAllTimelines()
+```
+
+The on-device cache (App Group shared container) is the source of truth for widgets. The gateway is the source of truth on the network.
+
+## Conflict resolution
+
+If a push arrives out of order (server timestamps, network jitter), trust the higher `timestamp` field in the APNs Live Activity payload. iOS handles ordering for ActivityKit; widgets reconcile via the cache and the `Timeline` provider's freshness logic.
+
+## Anti-patterns
+
+- Polling the gateway on a widget timer (battery + budget death)
+- Storing live data in `UserDefaults` for the widget — use App Group container or `WidgetCenter` reload + provider fetch
+- Updating Live Activities more than once per second (Apple throttles)
+- Forgetting to call `Activity.end(...)` — activities stay on Lock Screen until system kills them (~12h)