chore: sync launchpad with upstream block/buzz main (113 commits)

.github/workflows/ci.yml

@@ -46,10 +46,14 @@ jobs:
               - 'deny.toml'
               - '.github/workflows/ci.yml'
               - 'scripts/run-tests.sh'
+              - 'scripts/model-capabilities.json'
+              - 'scripts/normative-corpus.json'
               - 'justfile'
             desktop:
               - 'scripts/check-file-sizes-core.mjs'
               - 'scripts/check-file-sizes-core.test.mjs'
+              - 'scripts/model-capabilities.json'
+              - 'scripts/normative-corpus.json'
               - 'desktop/**'
               - 'pnpm-lock.yaml'
             desktop-rust:
@@ -77,6 +81,10 @@ jobs:
         run: scripts/test-release-ref-contract.sh
       - name: Desktop release candidate contract
         run: scripts/test-desktop-release-candidate.sh
+      - name: OSS desktop promotion contract
+        run: |
+          scripts/test-oss-desktop-promotion.sh
+          scripts/test-oss-desktop-promotion-behavior.sh
       - name: Mobile release contract
         run: |
           scripts/test-mobile-release-contract.sh
@@ -318,6 +326,9 @@ jobs:
     if: github.event_name == 'push' || needs.changes.outputs.desktop == 'true' || needs.changes.outputs.desktop-rust == 'true' || needs.changes.outputs.rust == 'true'
     permissions:
       contents: read
+    env:
+      SCCACHE_GHA_ENABLED: "true"
+      SCCACHE_GHA_RW_MODE: ${{ (github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.number == 5224)) && 'READ_WRITE' || 'READ_ONLY' }}
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -342,13 +353,22 @@ jobs:
             .
             desktop/src-tauri
           save-if: ${{ github.event_name != 'pull_request' }}
+      # Cache rustc outputs for unchanged workspace crates. Trusted pushes write;
+      # the bounded PR 5224 trial writes only to its isolated merge-ref scope.
+      - name: Set up sccache
+        if: steps.relay-artifacts-cache.outputs.cache-hit != 'true'
+        uses: Mozilla-Actions/sccache-action@fc920bf0ec8de6ee65d409111f7ec508035751ba # v0.0.11 # zizmor: ignore[cache-poisoning] Bounded trial: only PR 5224 writes to its isolated merge-ref scope; trusted pushes retain production writes.
+        with:
+          version: v0.16.0
       - name: Install cargo-nextest
         if: steps.relay-artifacts-cache.outputs.cache-hit != 'true'
         uses: taiki-e/install-action@0fd46367812ee04360509b4169d9f659d6892bb2 # v2.79.15
         with:
           tool: cargo-nextest@0.9.136
       - name: Build relay artifacts
         if: steps.relay-artifacts-cache.outputs.cache-hit != 'true'
+        env:
+          RUSTC_WRAPPER: sccache
         run: |
           cargo build --profile ci -p buzz-relay -p git-credential-nostr
           cargo nextest archive \
@@ -360,7 +380,9 @@ jobs:
             --test e2e_event_reminder \
             --archive-file target/ci/backend-integration-tests.tar.zst
       - name: Save relay artifacts cache
-        if: steps.relay-artifacts-cache.outputs.cache-hit != 'true'
+        # PR-scoped exact-source entries cannot warm main or other PRs and churn
+        # the shared cache pool. sccache provides read-only PR reuse instead.
+        if: steps.relay-artifacts-cache.outputs.cache-hit != 'true' && github.event_name == 'push'
         uses: actions/cache/save@caa296126883cff596d87d8935842f9db880ef25 # v5
         with:
           path: |

.github/workflows/promote-oss-desktop-release.yml

@@ -0,0 +1,45 @@
+name: Promote OSS Desktop Auto-Update
+run-name: Promote desktop-v${{ inputs.version }} to auto-update
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Stable desktop version to promote (X.Y.Z)
+        required: true
+        type: string
+
+concurrency:
+  group: oss-desktop-auto-update-promotion
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  promote:
+    if: github.repository == 'block/buzz'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Require the reviewed workflow from main
+        env:
+          DISPATCH_REF: ${{ github.ref }}
+        run: |
+          if [ "$DISPATCH_REF" != "refs/heads/main" ]; then
+            echo "::error::OSS desktop promotion must be dispatched from main, not $DISPATCH_REF"
+            exit 1
+          fi
+
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - name: Validate and promote exact release manifest
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ inputs.version }}
+        run: scripts/promote-oss-desktop-release.sh "$VERSION"

.github/workflows/release.yml

@@ -907,6 +907,7 @@ jobs:
           [ "${#TRIPLES[@]}" -ge 3 ] || { echo "::error::too few platforms (${#TRIPLES[@]})"; exit 1; }
           bash desktop/scripts/generate-oss-latest-json.sh "$VERSION" "${TRIPLES[@]}" > latest.json
           cat latest.json
+          cp latest.json staged/updater-manifest.json
 
       - name: Create or verify versioned draft
         run: |
@@ -946,7 +947,3 @@ jobs:
       - name: Publish complete versioned release
         if: env.already_published != 'true'
         run: gh release edit "desktop-v${VERSION}" --draft=false
-
-      - name: Upload latest.json to rolling release last
-        if: ${{ !contains(needs.setup.outputs.version, '-') }}
-        run: gh release upload buzz-desktop-latest latest.json --clobber

.release/desktop-candidate.json

@@ -1,10 +1,10 @@
 {
   "schema": 2,
-  "version": "0.5.8",
-  "base_sha": "6a17d035f79ad582ca3f4f3cdc38d376f2c4087f",
-  "previous_tag": "desktop-v0.5.7",
-  "previous_base_sha": "74b913cff8512c015dc6f1a7473b253fa803f954",
-  "previous_merge_sha": "13c9e900c84cac1e2c8eeb7551bd1510ecb544d3",
-  "tag": "desktop-v0.5.8",
-  "commit_count": 4
+  "version": "0.5.15",
+  "base_sha": "7f61cf431af1d8f0480a0baf525881a12f2be7f2",
+  "previous_tag": "desktop-v0.5.14",
+  "previous_base_sha": "1b3dbcaaea882eeea90359c1db02e306d2f4f50a",
+  "previous_merge_sha": "82f7ed1532f50e0d28afca5580ed522f1c2ef1ca",
+  "tag": "desktop-v0.5.15",
+  "commit_count": 18
 }

AGENTS.md

@@ -6,6 +6,25 @@ code style, PR process, architecture), see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
+## Product Contract
+
+Before planning or reviewing a non-trivial change:
+
+1. Read [VISION.md](VISION.md).
+2. Read the `VISION_*.md` documents relevant to the affected product surface.
+3. Read the applicable guidance in [TESTING.md](TESTING.md) and any
+   package-local `TESTING.md`.
+4. Check that the proposed design advances, or at least does not contradict,
+   that product intent. Call out any intentional tension explicitly.
+
+Implementation describes the product today; the vision documents describe the
+product it is becoming. A locally correct change can still be wrong if it works
+against that direction. Scale validation to the change's risk and exercise the
+real workflow for user-visible or integration behavior when practical; green CI
+and runtime evidence answer different questions.
+
+---
+
 ## Ecosystem
 
 Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay, desktop, mobile, and CLI. The others handle internal builds and deployment:
@@ -90,8 +109,9 @@ See CONTRIBUTING.md for full setup details and dependency requirements.
 
 ## Quality Gates
 
-Run `just ci` before every PR — it runs `fmt` + `clippy` + desktop lint +
-unit tests + builds. Clippy passing does not mean fmt passes; run both.
+Run `just ci` before every PR — it runs repository-wide formatting, lint,
+and static checks; Rust, Tauri, desktop, and mobile tests; and desktop and web
+builds. Clippy passing does not mean fmt passes; run both.
 
 Run `just test` for integration tests if you touched `buzz-relay`,
 `buzz-db`, or `buzz-auth` — these require a running Postgres and Redis.
@@ -185,7 +205,7 @@ or invoke with the full path.
 thread. To read the linked thread:
 
 ```bash
-buzz messages thread --channel <uuid> --event <hex> --format compact
+buzz --format compact messages thread --channel <uuid> --event <hex>
 ```
 
 Extract `channel` and `id` from the URL query parameters. The optional
@@ -216,7 +236,9 @@ E2E tests live in `crates/buzz-test-client/tests/`:
 - `e2e_media_extended.rs` — extended media scenarios
 - `e2e_nostr_interop.rs` — Nostr interop (NIP-50 search, NIP-10 threads, NIP-17 gift wraps)
 
-Desktop E2E: `cd desktop && pnpm exec playwright test`
+Desktop E2E: `cd desktop && pnpm test:e2e:smoke` for mock-bridge smoke
+coverage, or `pnpm test:e2e:integration` for relay-backed coverage. These
+scripts build the required E2E bridge before running Playwright.
 
 See [TESTING.md](TESTING.md) for the full multi-agent E2E guide.
 
@@ -427,11 +449,10 @@ description. See [PR #803](https://github.com/block/buzz/pull/803).
 
 1. **Kind `39000` for channel metadata, not `41`** — kind 41 is NIP-01 (unused). All kinds defined in `buzz-core/src/kind.rs`.
 2. **Relay queries must specify `kinds`** — omitting `kinds` triggers the p-gate (403). Always include explicit kind filters.
-3. **`messages search` must include `--kinds`** — an open-ended search (no kinds) hits the relay p-gate and returns 403. Pass at least `--kinds 9,45001,45003` to scope the query.
+3. **`messages search` chooses its own supported kinds** — do not add a `--kinds` option; the current command does not accept one. This differs from raw relay filters, which still need explicit kinds.
 4. **Worktrees: `cd` in the same command** — shell CWD doesn't persist between tool calls. Use `cd /path && cargo build` as one command.
 5. **Desktop crate excluded from root workspace** — `cargo test` at repo root does NOT run desktop tests. Use `cargo test --manifest-path desktop/src-tauri/Cargo.toml` explicitly.
-6. **Desktop Tauri fmt fails in worktrees and blocks commits** — the pre-commit hook runs `just desktop-tauri-fmt`, which fails in git worktrees because `cargo fmt` resolves workspace paths relative to the worktree root. Run `just desktop-tauri-fmt` from the main checkout to apply the fix, then re-stage and commit. CI is unaffected.
-7. **React render perf: `React.memo` is all-or-nothing** — it only skips a re-render when *every* prop is reference-stable; one unstable prop (inline arrow/JSX, or a hook returning a fresh `{}`/`[]`/`Map` each render) defeats it. Two repeat offenders: (a) React Query results (`useMutation`/`useQuery`) are a **new object each render** — depend on the stable method (`mutation.mutateAsync`), not the object; (b) derived `Map`/array state that recomputes on a version bump — wrap in a content-equality ref cache (`shared/hooks/useStableReference.ts`). When chasing interaction lag, **measure with DevTools closed and no perf probes** (an open Web Inspector + per-keystroke `console.log` inflate the numbers), and isolate by removing one suspect at a time rather than guessing.
+6. **React render perf: `React.memo` is all-or-nothing** — it only skips a re-render when *every* prop is reference-stable; one unstable prop (inline arrow/JSX, or a hook returning a fresh `{}`/`[]`/`Map` each render) defeats it. Two repeat offenders: (a) React Query results (`useMutation`/`useQuery`) are a **new object each render** — depend on the stable method (`mutation.mutateAsync`), not the object; (b) derived `Map`/array state that recomputes on a version bump — wrap in a content-equality ref cache (`shared/hooks/useStableReference.ts`). When chasing interaction lag, **measure with DevTools closed and no perf probes** (an open Web Inspector + per-keystroke `console.log` inflate the numbers), and isolate by removing one suspect at a time rather than guessing.
 
 ---
 
@@ -492,27 +513,12 @@ class instances, cached promises) survive across remounts. Every community-scope
 singleton needs a reset function wired into `resetCommunityState()` in
 `desktop/src/features/communities/useCommunityInit.ts`.
 
-Current singletons that are reset on relay boundary changes (same-relay
-reconnects preserve pending avatar verification work):
-- `relayClient.disconnect()` — WebSocket teardown + promise rejection
-- `resetRateLimitGate()` — clears any active rate-limit window from the old relay
-- `clearAllDrafts()` — message draft cache
-- `resetAgentObserverStore()` — agent observer relay store
-- `resetActiveAgentTurnsStore()` — active agent turn timers
-- `resetAgentWorkingSignal()` — agent working indicator signal
-- `resetAvatarProfileSync()` — pending verified-avatar profile writes
-- `resetAvatarPresentations()` — avatar probes, previews, and Retry toasts
-- `resetSidebarRelayConnectionCardState()` — sidebar relay card dismiss state
-- `resetMediaCaches()` — proxy port and relay origin caches
-- `resetVideoPlayerState()` — video player singleton
-- `resetRenderScopedReactionHydration()` — reaction hydration cache
-- `clearSearchHitEventCache()` — search result event cache
-- `clearMarkdownNodeCache()` — markdown parse-node cache
-- `resetLinkPreviewTitleCache()` — link preview title cache (Buzz entity titles come from relay events)
-
-**If you add a new module-level cache, Map, or class instance that holds
-community-scoped data, you must add its reset to `resetCommunityState()`.**
-Failure to do so causes data from the old community to leak into the new one.
+`resetCommunityState()` is the canonical inventory of community-scoped
+singletons. **If you add a new module-level cache, Map, or class instance that
+holds community-scoped data, add its reset there in the same change.** Failure
+to do so causes data from the old community to leak into the new one. Avoid
+duplicating its complete reset list here; the implementation is the source of
+truth.
 
 Key files:
 - `desktop/src/app/App.tsx` — community key, init gate, remount boundary
@@ -537,9 +543,23 @@ The mobile app lives in `mobile/` — a Flutter app using Riverpod + Hooks.
 
 - **NEVER use `StatefulWidget`** — favor Riverpod for state and always use
   `HookConsumerWidget` or `ConsumerWidget` with `flutter_hooks` for local state.
-- **NEVER run `flutter run`, `flutter build`, `flutter clean`, or
-  `flutter upgrade`** — only `flutter test`, `flutter analyze`, and
-  `dart format` are safe for agents to run.
+- Agents may build and run the Flutter app when it materially helps implement,
+  debug, or validate mobile changes. Prefer the smallest relevant command and
+  reuse an already-running simulator/emulator and the app's configured staging
+  or production community when that is sufficient. Do not start or rebuild
+  local relay services unless the task specifically requires relay-side or
+  isolated integration behavior.
+- For iOS runtime validation, prefer `just mobile-dev`; it applies the
+  worktree-specific debug identity and runs `flutter run`. Direct `flutter run`
+  or IDE workflows are also allowed. Use `just mobile-build-android` only when
+  an APK build is relevant to the task.
+- Do not rebuild, reinstall, or relaunch merely for ceremony. Preserve Flutter's
+  incremental build cache and use hot reload/restart where appropriate. Use
+  `flutter clean` only when stale build artifacts are a credible cause. Run
+  `flutter upgrade` only when the task explicitly requires a toolchain change.
+- For user-visible or integration changes, exercise the affected workflow in a
+  real app when practical and report the device/simulator, connected community,
+  and workflow actually tested.
 - **Do NOT use `print()`** — use `debugPrint()` or structured logging.
 - Prefer `context.colors` and `context.textTheme` (via theme extensions)
   over raw `Theme.of(context)` calls.
@@ -565,12 +585,16 @@ flutter test
 
 Or from repo root: `just mobile-fmt` (auto-fix), `just mobile-check` (lint + fmt check), `just mobile-test` (tests).
 
-To run the app locally (starts Docker, relay, iOS simulator automatically):
+To run the app locally with a worktree-specific debug identity and a
+started or reused iOS Simulator:
 
 ```bash
 just mobile-dev
 ```
 
+This runs `flutter run` against the app's configured community; it does not
+start Docker or local relay services.
+
 When run from a git worktree, `just mobile-dev` (and `just
 mobile-build-android`) give the debug build a per-worktree app identifier
 (keyed to the worktree directory name) and a branch-labelled app name via