Spike native shells and define local-first integrations

docs/BUZZ_INTEGRATION.md

@@ -0,0 +1,84 @@
+# Buzz integration
+
+## Product boundary
+
+Buzz is Lumbridge's first-class collaboration surface, not its control plane.
+Lumbridge remains useful offline, owns its local workspace state, and never
+requires a Buzz account to open a terminal or run an agent.
+
+The initial integration provides:
+
+- connect an existing Buzz identity using an OS credential-store reference;
+- bind one or more Buzz channels to a Lumbridge workspace;
+- read and post channel messages and replies from a collaboration pane;
+- surface Buzz agents attached to a bound channel without pretending they are
+  local processes;
+- share an approved pane image to an explicitly selected channel.
+
+## Protocol shape
+
+The pinned upstream is Block's Apache-2.0 Buzz repository at commit
+`cb3144999bebc4939cb15b2200b373281d493b52`. `buzz-sdk` constructs typed Nostr
+events and broker actions but deliberately owns neither identity keys nor
+network connections. Lumbridge follows that separation:
+
+```text
+Lumbridge collaboration pane
+       | typed local command
+lumbridge-buzz
+       | Buzz SDK event/broker action
+identity signer + Buzz transport adapter
+       | signed WebSocket / HTTPS upload
+Buzz relay and attachment storage
+```
+
+The exact revision stays pinned until an audited upgrade. We use Buzz's signed
+protocol and SDK types rather than a parallel webhook format.
+
+## Identity and local data
+
+SQLite stores the account label, relay URL, public key, and an opaque secret
+store handle. The Nostr private key stays in macOS Keychain or Linux Secret
+Service. It must never enter SQLite, command arguments, crash reports, pane
+history, logs, or Git configuration.
+
+An installed Buzz CLI identity may be imported only through an explicit user
+flow that transfers it into the OS credential store. Lumbridge must not search
+the filesystem for keys. Buzz's current NIP-AB device-pairing tooling is marked
+for interoperability testing upstream, so it is not a production login promise.
+
+## Pane-image sharing
+
+Sharing is a user-visible state machine:
+
+1. Capture the selected pane only, excluding application chrome by default.
+2. Detect likely secrets and render a local preview with proposed redactions.
+3. Let the user adjust redactions, caption, and destination channel.
+4. Require confirmation of that exact preview and destination.
+5. Encode PNG or WebP, hash it, upload with the authenticated Buzz attachment
+   flow, and receive a canonical URL.
+6. Build a kind-9 Buzz message with Markdown plus an `imeta` tag, sign it using
+   the OS-held identity, and publish it.
+7. Persist only the resulting event ID, attachment metadata, destination, and
+   local audit outcome. Never persist the unredacted capture.
+
+Any change to the pixels, caption, or destination invalidates confirmation. A
+failed upload or publish is retryable but never reported as sent.
+
+## Agent integration
+
+Buzz agents and Lumbridge harnesses are different entities. A Buzz agent may be
+shown in the collaboration pane and may exchange messages through Buzz's broker
+contract. A local or remote Lumbridge harness remains owned by the Lumbridge
+runtime and communicates through ACP or a supervised PTY. Linking the two later
+requires an explicit capability grant, visible identity, and revocation path.
+
+## Test plan
+
+- deterministic unit tests for channel IDs, content limits, media metadata, and
+  the review/confirmation gate;
+- signature tests with generated fixture identities only;
+- integration tests against a disposable local Buzz relay and attachment store;
+- disconnect, duplicate-delivery, cursor-resume, and publish-retry tests;
+- rendered tests proving destination and redactions remain visible at confirm;
+- a real-account smoke test only in a manually enabled, non-CI test profile.