feat(companion): add generated macos ios android reference app surfaces

apps/companion/macos/MenuBarCompanion.swift

@@ -0,0 +1,38 @@
+import Foundation
+
+struct CompanionBootstrap: Codable {
+  let schemaVersion: Int
+  let generatedAt: String
+  let gateway: Gateway
+  let node: Node
+  let runtime: Runtime
+}
+
+struct Gateway: Codable {
+  let url: String
+  let token: String?
+}
+
+struct Node: Codable {
+  let nodeId: String
+  let role: String
+  let platform: String
+  let capabilities: [String]
+}
+
+struct Runtime: Codable {
+  let heartbeatSeconds: Int
+  let handoffTimeoutMs: Int
+  let autoReconnect: Bool
+}
+
+// Reference entrypoint for a menu-bar app wrapper.
+// Production apps should prefer in-process runtime integration over shelling out.
+func launchFlynnCompanion() throws {
+  let task = Process()
+  task.executableURL = URL(fileURLWithPath: "/bin/bash")
+  task.arguments = ["./run-companion.sh"]
+  try task.run()
+}
+
+// Generated for node: macos-reference-shell (macos)

apps/companion/macos/README.md

@@ -0,0 +1,11 @@
+# Flynn Companion macos Shell Template
+
+This directory contains a generated starter template for a macos companion shell.
+
+Files:
+- `companion.bootstrap.json`: resolved Flynn companion bootstrap contract
+- `MenuBarCompanion.swift`: platform-native starter model/wrapper snippet
+
+Notes:
+- These templates are intentionally minimal and should be integrated into your app project.
+- Runtime transport should use Flynn gateway JSON-RPC node methods (`node.register`, `node.status.set`, `node.location.set`, `node.push_token.set`).

apps/companion/macos/companion.bootstrap.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-02-27T03:35:54.245Z",
+  "gateway": {
+    "url": "ws://127.0.0.1:18800"
+  },
+  "node": {
+    "nodeId": "macos-reference-shell",
+    "role": "companion",
+    "platform": "macos",
+    "capabilities": [
+      "ui.canvas",
+      "node.status.write",
+      "node.location.write",
+      "node.push.register"
+    ]
+  },
+  "runtime": {
+    "heartbeatSeconds": 30,
+    "handoffTimeoutMs": 120000,
+    "autoReconnect": true
+  }
+}