Spike native shells and define local-first integrations

docs/ARCHITECTURE.md

@@ -8,7 +8,8 @@ Lumbridge should be two cooperating Rust processes:
 native desktop UI
       | local authenticated IPC
 Lumbridge session runtime
-      |-- PTYs and process trees
+      |-- local PTYs and process trees
+      |-- SSH/Tailscale transport to remote Lumbridge runtimes
       |-- ACP clients and adapters
       |-- repositories and worktrees
       |-- usage/event ledger
@@ -30,13 +31,18 @@ messages should be real from the beginning.
 - `lumbridge-harness`: manifests, launch profiles, hooks, PTY fallback adapters.
 - `lumbridge-provider`: BYOK providers and provider-neutral usage records.
 - `lumbridge-storage`: SQLite migrations, event log, snapshots, retention.
+- `lumbridge-remote`: OpenSSH/Tailscale command construction, framed stdio,
+  handshake, reconnect, heartbeat, and remote-runtime discovery.
 - `lumbridge-secrets`: Keychain/libsecret adapters and redaction.
 - `lumbridge-git`: repositories, worktrees, diffs, status, conflict state.
+- `lumbridge-buzz`: credential-free Buzz event/broker preparation and pane-share
+  safety gates; platform adapters own signing and transport.
 - `lumbridge-ui`: native desktop state and rendering.
 - `lumbridge`: installable application entry point.
 
-Only `lumbridge-core` and the entry point exist in the scaffold. New crates are
-added after their architecture spike passes.
+The scaffold currently contains `lumbridge-core`, `lumbridge-storage`,
+`lumbridge-buzz`, and the entry point. Larger runtime crates are added after
+their architecture spikes pass.
 
 ## Terminal path
 
@@ -57,13 +63,46 @@ Do not lock the project to a webview or to Zed's private implementation details
 before a measured spike. Compare:
 
 1. GPUI for a Zed-like native model and excellent text-heavy interaction.
-2. Iced/wgpu plus a dedicated terminal renderer for stable Rust portability.
-3. Tauri only as a delivery-speed baseline, not the assumed winner.
+2. Floem for an independent native Rust model with existing editor primitives.
 
 The winner must render six busy panes smoothly, keep input latency low, support
 IME/accessibility, package on macOS and both Linux targets, and avoid a license
 or upstream-stability trap.
 
+## Local-first and remote session path
+
+SQLite is device-local. It stores workspace metadata, pane layouts, event and
+usage history, remote routing profiles, and small snapshots. It never stores SSH
+private keys, Tailscale credentials, provider API keys, or subscription tokens.
+Secrets remain in the OS credential store or in the user's existing SSH agent.
+
+A remote pane is not a local PTY wrapped around a long-lived `ssh` process. Its
+durable owner is a per-user `lumbridge-runtime` on the destination:
+
+```text
+MacBook Lumbridge UI/runtime
+       |
+       | ssh host lumbridge remote connect --stdio
+       | or: tailscale ssh host lumbridge remote connect --stdio
+       v
+remote per-user Lumbridge runtime -- Unix socket -- PTYs, agents, worktrees
+       |
+       `-- remote SQLite + chunked scrollback on that machine
+```
+
+The SSH child carries a versioned framed protocol over stdio. Normal OpenSSH
+remains the default because it honors the user's config, agent, host keys,
+ProxyJump, and Tailscale addresses. `tailscale ssh` is an explicit transport for
+users who want Tailscale's SSH proxy and host-key path. Lumbridge does not
+configure a tailnet, weaken ACLs, copy SSH keys, or require a listening TCP port.
+
+The remote runtime assigns a stable session ID before acknowledging a launch.
+On network loss the local pane becomes disconnected, the remote PTY continues,
+and reconnect resumes from the last acknowledged output sequence. A second
+authorized Lumbridge installation can attach to the same remote session after
+the remote runtime arbitrates input ownership. Collaborative simultaneous input
+is not part of the first release.
+
 ## Harness integration
 
 Each harness is described by a versioned manifest: executable discovery, launch
@@ -88,6 +127,14 @@ usually expose token counts but cost still depends on cached tokens, reasoning,
 tool calls, and current pricing. Adapters normalize facts without erasing their
 source or uncertainty.
 
+## Buzz collaboration
+
+Buzz channel messages, replies, agents, and attachments use the upstream Rust
+SDK's signed Nostr semantics. SQLite stores a public identity and opaque
+credential-store handle, never the private identity key. Pane images cross the
+network only after local capture, redaction preview, explicit destination, and
+confirmation. See `BUZZ_INTEGRATION.md` for the contract and test plan.
+
 ## Persistence
 
 SQLite in WAL mode stores metadata, commands/events, normalized usage, and small
@@ -95,6 +142,11 @@ snapshots. Large scrollback chunks and binary attachments use content-addressed
 files. A write-ahead event is committed before an external mutation is reported
 as accepted. Startup replays incomplete operations and reconciles live children.
 
+Default data roots are `~/Library/Application Support/ai.karti.lumbridge/` on
+macOS and `${XDG_DATA_HOME:-~/.local/share}/lumbridge/` on Linux. Backups and
+exports are explicit; Lumbridge does not synchronize the database through a
+hidden hosted account.
+
 ## Security
 
 - macOS secrets: Keychain; Linux secrets: Secret Service/libsecret, with an
@@ -113,4 +165,3 @@ Shared contracts cover PTY, process tree, notifications, secret store, paths,
 autostart, updater, and packaging. macOS uses `forkpty`/process groups and native
 Keychain. Ubuntu and Omarchy use Unix PTYs, cgroups/systemd scopes when available,
 and Secret Service. Omarchy is treated as Arch Linux, not as a separate kernel.
-