Merge pull request #3663 from vitorpamplona/claude/sqlite-query-performance-bh2j27

SQLite query scaling: FTS contentless, tag-merge, pooled statements

.claude/CLAUDE.md

@@ -13,7 +13,10 @@ a non-interactive JVM command-line client that drives the same `quartz` + `commo
 humans, agents, and interop tests. `quic` is a from-scratch pure-Kotlin QUIC v1 + HTTP/3 +
 WebTransport client (no JNI, no BouncyCastle), built because no Android-compatible Java QUIC library
 exists. `geode` is a standalone JVM Nostr relay (Ktor) built on quartz's
-relay-server code; smaller modules are `benchmark` (Android macrobenchmarks) and
+relay-server code; smaller modules are `benchmark` (Android macrobenchmarks),
+`relayBench` (head-to-head relay benchmark — boots geode, strfry and other
+relay binaries, replays a shared deterministic corpus, measures ingest/query/
+NIP-77 sync; `./relayBench/run.sh`, see `relayBench/README.md`) and
 `quic-interop` (QUIC interop runner, lives at `quic/interop`). `nestsClient` runs
 the audio-room protocol on top of `:quic` for the NIP-53 audio-rooms feature. It implements both IETF `draft-ietf-moq-transport-17` (under
 `moq/`) and **moq-lite Lite-03** (kixelated's variant, under `moq/lite/`); the
@@ -76,12 +79,44 @@ amethyst/
 - `nestsClient/` = MoQ + audio-rooms client; takes `:quic` as transport,
   Quartz for crypto, `MediaCodec` / `AudioRecord` / `AudioTrack` for audio.
 - `amethyst/` & `desktopApp/` = Platform-native layouts and navigation
-- `cli/` = Thin assembly layer over `quartz/` + `commons/` (no new logic allowed)
+- `cli/` = Thin assembly layer over `quartz/` + `commons/` (no new logic
+  allowed). May also depend on `:geode` (for `amy serve`, which embeds the
+  standalone relay); never on `:amethyst` or `:desktopApp`.
 
 **Plans per module:** design docs for new subsystems live in the owning
 module's `plans/YYYY-MM-DD-<slug>.md` (e.g. `cli/plans/`, `commons/plans/`).
 The global `docs/plans/` folder is frozen — don't add new plans there.
 
+## Android Runtime Processes (IMPORTANT — the app runs in TWO processes)
+
+The Android app is **not single-process**. Android instantiates the one `Amethyst`
+Application class (there is no per-process Application in the manifest) in **both**:
+
+- **main** — the normal app: UI, account, signer, `LocalCache`, relay client.
+  `Amethyst.instance` (`AppModules`) is built here.
+- **`:napplet`** — the sandboxed WebView host for NIP-5D napplets / NIP-5A nSites
+  (`NappletHostActivity`, declared `android:process=":napplet"`). It holds **no**
+  account or keys; `Amethyst.onCreate()` early-returns here so `Amethyst.instance`
+  is **left unset** (touching it throws `UninitializedPropertyAccessException`).
+  The sandbox runtime lives in its own module **`:nappletHost`** (depends only on
+  `:commons` + `:quartz`, **never** `:amethyst`) so it *cannot* import
+  `Amethyst`/`LocalCache`/`Account` — the broker-side (signer, gateways, registry)
+  stays in `:amethyst` and the two halves talk over Messenger IPC.
+
+Consequences — don't get caught assuming one process:
+
+- **Processes don't share memory.** Every `object`/companion/`static` is a
+  *separate copy per process*: `LocalCache` (an `object`), `NappletLaunchRegistry`,
+  etc. The populated `LocalCache` lives only in **main**; the sandbox neither
+  builds nor should reference it (a stray reference would lazily create a second,
+  empty cache there).
+- **Don't assume `Amethyst.instance` exists.** Any code reachable from `:napplet`
+  (the host activity, content server, or an Application lifecycle callback like
+  `onTrimMemory`) must guard on the process and never reach for `instance`.
+- **Cross-process state goes over Messenger IPC**, never a shared singleton — this
+  is why the broker (main) owns `NappletLaunchRegistry` and the sandbox only relays
+  an opaque token. See `amethyst/plans/2026-06-22-napplet-nsite-security.md`.
+
 ## Tech Stack
 
 Exact versions live in `gradle/libs.versions.toml` (the source of truth — check
@@ -125,6 +160,17 @@ Summarize the survey in your plan: for each component, note whether it's
 reused as-is, extracted from `amethyst/` to `commons/`, genuinely new
 (platform-specific only), or a duplicate of an existing pattern to avoid.
 
+**Relay client ops already exist — don't hand-roll subscribe/REQ/publish loops.**
+One-shot and high-level relay operations (fetch a set, fetch one, page past the
+relay cap, publish-and-confirm, NIP-45 count, NIP-77 sync/reconcile) are
+`INostrClient` **extension functions** in
+`quartz/…/nip01Core/relay/client/accessories/` (+ `…/reqs/` for the flow/subscribe
+helpers). Because they're extensions, they don't surface under "usages of
+`NostrClient`" or in completion — grep that package (or read its `README.md`, which
+catalogs them) before writing a new subscription/collect loop. Reuse `fetchAll`,
+`fetchFirst`, `fetchAllPages`, `publishAndConfirm`, `count`, `negentropyReconcile`,
+etc. instead of re-implementing them.
+
 **Share vs keep platform-native:**
 
 - **Share** → `quartz/commonMain/` (business logic, data models, protocol) and
@@ -236,6 +282,41 @@ Do this before considering the task complete.
 - The only acceptable inline fully-qualified names are: a genuine name
   collision (prefer `import ... as Alias` instead), or where the language
   requires it. Comments, KDoc, and string literals are exempt.
+- **Prefer the `androidx.core` KTX extension over the raw platform Java call**
+  when one exists — this is what Android Lint's `UseKtx` flags. Common swaps:
+  `Bitmap.createBitmap(w, h, cfg)` → `createBitmap(w, h)`,
+  `Bitmap.createScaledBitmap(src, w, h, f)` → `src.scale(w, h, f)`,
+  `Uri.parse(s)` → `s.toUri()`, and `prefs.edit()…apply()` → `prefs.edit { }`.
+  Only adopt the KTX form when it's behaviour-preserving: keep any explicit
+  argument that differs from the extension's default (a non-`ARGB_8888`
+  `Bitmap.Config`, `scale(filter = false)`), and leave calls the KTX has no
+  equivalent for (e.g. the `createBitmap` pixels/matrix overloads, or a
+  conditional-`apply()` editor loop) untouched.
+- **This "prefer the KTX sugar" rule does NOT extend to collection operators.**
+  The KTX preference is about platform wrappers (`Bitmap`/`Uri`/`SharedPreferences`),
+  which compile to the identical call. Collections are the opposite: in hot
+  event/parse paths Quartz deliberately uses raw JVM arrays (`TagArray =
+  Array<Array<String>>`) and the inline `fast*` operators (`fastForEach`,
+  `fastAny`, `fastFirstOrNull`, `fastFirstNotNullOfOrNull`, … in
+  `nip01Core/core/TagArray.kt`) instead of Kotlin `List` + stdlib
+  `forEach`/`map`/`filter`/`any` — the `fast*` variants allocate no iterator,
+  no intermediate list, and no lambda object. Don't "modernize" those into
+  stdlib collection calls; match the surrounding hot-path style.
+- **Never put raw invisible/bidirectional Unicode characters in source files**
+  — write them as `\uXXXX` escapes instead (`'\u202E'`, `Regex("[\u200B-\u200D\uFEFF]")`).
+  This covers the bidi family Sonar's Trojan-Source rule (CVE-2021-42574)
+  flags — U+202A–U+202E, the isolates U+2066–U+2069, U+200E/U+200F, U+061C —
+  plus zero-width characters (U+200B–U+200D, U+FEFF, U+2060). The escape
+  compiles to the identical codepoint, so behaviour is unchanged; the point is
+  that the file on disk stays visually unambiguous. Applies even when the
+  character is *intentional* (sanitizer strip-lists, adversarial test
+  payloads) — that's data, and escapes express it just as well. Exceptions:
+  U+200D as part of a real emoji ZWJ sequence in test data (👩‍👧 — functional,
+  not a bidi control), and LRM/RLM inside Crowdin-managed `strings.xml`
+  translations (legitimate RTL typography; don't touch those files by hand
+  anyway). Note the tooling trap: the Edit tool may normalise a typed
+  `\uXXXX` back into the raw character — if that happens, do the replacement
+  at byte level (`perl -CSD -pe 's/\x{202E}/\\u202E/g'`).
 
 ### Navigation Shell
 - **Desktop**: Sidebar + main content area
@@ -245,3 +326,12 @@ Do this before considering the task complete.
 
 - Commits: Conventional commits (`feat:`, `fix:`, etc.)
 - Never use `--no-verify`
+
+### Remotes & pull requests
+
+A PR can be published two ways, via two **kinds** of remote — identify them by **URL** (`git remote -v`), because the names vary per clone and **a collaborator may have only one**:
+
+- a **GitHub** remote (`github.com/vitorpamplona/amethyst`) — the **canonical** `main`; moves constantly. Standard `gh` PR flow.
+- a **git-over-nostr** remote (`nostr://…/relay.ngit.dev/amethyst`, via `ngit`) — pushing fans out to GitHub **and** the GRASP git servers; **PRs here are nostr proposals** (the `pr/feat/*` branches), reviewed on **gitworkshop.dev** — *not* GitHub PRs. (In the maintainer's checkout these happen to be named `upstream` and `origin` respectively, but don't rely on that.)
+
+Before opening, revising, or merging a PR by **either** path, use the **`ngit-pr`** skill. It covers when to use which, identifying your remotes by URL, the `gh` and `ngit` commands, and — critically for the nostr path — the three-mains alignment gate (GitHub main vs the lagging nostr `main` vs local `main`) that its create/revise/merge flows depend on. Skipping it leads to rejected pushes and PRs that don't show up as revisions.

.claude/hooks/pre-push-spotless.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# PreToolUse gate: make sure Kotlin is spotless-clean BEFORE it leaves the box.
+#
+# Fires on `git push` (Bash tool) and on the create_pull_request MCP tool. Runs
+# `spotlessApply`; if that reformats any tracked .kt/.kts file, the push/PR is
+# blocked (exit 2) so the agent commits the formatting fix first. This turns
+# CI's `spotlessCheck` failure into an in-session block — no red PR, no round
+# trip. `spotlessApply` runs the same formatters CI's `spotlessCheck` verifies,
+# so a clean apply means a green check.
+set -uo pipefail
+
+cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
+
+# --- Parse the tool call off stdin; decide whether this call is a boundary. ---
+payload="$(cat)"
+should_gate="$(
+  printf '%s' "$payload" | python3 -c '
+import json, shlex, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print("no"); sys.exit(0)
+tool = data.get("tool_name", "")
+if tool.endswith("create_pull_request"):
+    print("yes"); sys.exit(0)
+if tool != "Bash":
+    print("no"); sys.exit(0)
+cmd = (data.get("tool_input") or {}).get("command", "")
+# Tokenize like a shell so `push` inside a quoted commit message or heredoc
+# stays one token and is NOT mistaken for the push subcommand.
+try:
+    tokens = shlex.split(cmd, comments=True)
+except ValueError:
+    tokens = cmd.split()
+GLOBAL_WITH_ARG = {"-c", "-C", "--namespace", "--git-dir", "--work-tree", "--exec-path"}
+for i, t in enumerate(tokens):
+    if t != "git" and not t.endswith("/git"):
+        continue
+    j = i + 1
+    while j < len(tokens):  # skip git global options to reach the subcommand
+        tok = tokens[j]
+        if tok in GLOBAL_WITH_ARG:
+            j += 2; continue
+        if tok.startswith("-"):
+            j += 1; continue
+        break
+    if j < len(tokens) and tokens[j] == "push":
+        print("yes"); sys.exit(0)
+print("no")
+' 2>/dev/null
+)"
+
+[ "$should_gate" = "yes" ] || exit 0
+
+# Nothing to format if no Kotlin is tracked/changed at all — cheap early out.
+if ! git ls-files --error-unmatch '*.kt' '*.kts' >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Snapshot Kotlin state (vs HEAD, so staged + unstaged both count) before/after
+# formatting; any delta means the committed tree wasn't spotless.
+before="$(git diff HEAD -- '*.kt' '*.kts' 2>/dev/null | sha1sum)"
+
+log="$(mktemp /tmp/spotless-gate.XXXXXX.log)"
+if ! ./gradlew spotlessApply >"$log" 2>&1; then
+  # Any failure blocks. The web sandbox pre-seeds the Gradle distribution (see
+  # .claude/hooks/session-start.sh) and Gradle resolves deps through the proxy,
+  # so spotlessApply no longer fails for infra reasons — a failure here is a
+  # real formatting/compile error, not a restricted-sandbox hiccup.
+  echo "BLOCKED: spotlessApply failed — fix the build/formatting error before pushing." >&2
+  echo "----- gradle output (tail) -----" >&2
+  tail -n 40 "$log" >&2
+  rm -f "$log"
+  exit 2
+fi
+rm -f "$log"
+
+after="$(git diff HEAD -- '*.kt' '*.kts' 2>/dev/null | sha1sum)"
+
+if [ "$before" != "$after" ]; then
+  echo "BLOCKED: spotlessApply reformatted Kotlin files that were about to be pushed." >&2
+  echo "The changes below are now in your working tree. Commit them, then retry:" >&2
+  echo >&2
+  git diff --name-only HEAD -- '*.kt' '*.kts' >&2
+  echo >&2
+  echo "  git add -A && git commit -m 'style: apply spotless' && <retry the push>" >&2
+  echo "(CI runs 'spotlessCheck'; pushing now would fail the lint job.)" >&2
+  exit 2
+fi
+
+exit 0

.claude/hooks/session-start.sh

@@ -211,6 +211,60 @@ install_konan_dep "llvm-19-x86_64-linux-essentials-109" \
 install_konan_dep "libffi-3.2.1-2-linux-x86-64" \
   "$KONAN_DEPS_URL/libffi-3.2.1-2-linux-x86-64.tar.gz"
 
+# --- Gradle distribution: pre-seed the wrapper distribution ---
+# The wrapper's distributionUrl (services.gradle.org) 307-redirects to
+# github.com release assets, which the web sandbox's git-only GitHub proxy
+# blocks (403) even at Full network access — so `./gradlew` can't bootstrap.
+# Download the pinned distribution from a mirror instead, but verify it against
+# Gradle's OFFICIAL sha256 (served from services.gradle.org, reachable here)
+# so a tampered/wrong mirror file is rejected and never executed. Idempotent:
+# skips entirely if the distribution is already installed.
+seed_gradle_distribution() {
+  local props="$CLAUDE_PROJECT_DIR/gradle/wrapper/gradle-wrapper.properties"
+  [ -f "$props" ] || return 0
+  local url zip name hash dir ver official mirror ok=""
+  url=$(sed -n 's/^distributionUrl=//p' "$props" | sed 's/\\//g')
+  [ -n "$url" ] || return 0
+  zip=${url##*/}; name=${zip%.zip}
+  # Gradle stores the dist under base36(md5(distributionUrl)) — derive it so this
+  # keeps working across version bumps instead of hardcoding the hash dir.
+  hash=$(python3 - "$url" <<'PY'
+import hashlib, sys
+n = int.from_bytes(hashlib.md5(sys.argv[1].encode()).digest(), 'big')
+d = "0123456789abcdefghijklmnopqrstuvwxyz"; s = ""
+while n:
+    s = d[n % 36] + s; n //= 36
+print(s or "0")
+PY
+)
+  dir="${GRADLE_USER_HOME:-$HOME/.gradle}/wrapper/dists/$name/$hash"
+  ver=${name%-bin}; ver=${ver%-all}
+  if [ -x "$dir/$ver/bin/gradle" ]; then return 0; fi   # already installed
+  echo "Seeding Gradle distribution $ver (github release blocked; using verified mirror)..." >&2
+  mkdir -p "$dir"
+  official=$(curl -fsSL "https://services.gradle.org/distributions/${zip}.sha256") || {
+    echo "Could not fetch official Gradle checksum; leaving gradlew to fail as before." >&2
+    return 0
+  }
+  for mirror in \
+      "https://mirrors.cloud.tencent.com/gradle" \
+      "https://mirrors.huaweicloud.com/gradle"; do
+    if curl -fsSL -o "$dir/$zip" "$mirror/$zip" \
+       && echo "${official}  $dir/$zip" | sha256sum -c - >/dev/null 2>&1; then
+      ok=1; break
+    fi
+    echo "Mirror $mirror failed download/verify; trying next." >&2
+    rm -f "$dir/$zip"
+  done
+  if [ -z "$ok" ]; then
+    echo "Gradle seed failed against all mirrors; leaving gradlew to fail as before." >&2
+    return 0
+  fi
+  unzip -q "$dir/$zip" -d "$dir" && touch "$dir/$zip.ok"
+  echo "Gradle $ver seeded and verified against official sha256." >&2
+}
+seed_gradle_distribution
+
 cd "$CLAUDE_PROJECT_DIR"
 ./gradlew --version > /dev/null 2>&1
 

.claude/settings.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|mcp__github__create_pull_request",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-push-spotless.sh",
+            "timeout": 180
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "hooks": [

.claude/skills/amy-expert/SKILL.md

@@ -129,10 +129,12 @@ via `Output.emit`. The template is in `references/command-template.md`;
 copy it rather than re-deriving it.
 
 Wire-up checklist:
-1. New file in `cli/commands/` with the `object` pattern.
-2. Add a branch in `Commands.kt`.
-3. Add a branch in `Main.kt`'s `dispatch` (or under `marmotDispatch`
-   / a new group dispatcher).
+1. New file in `cli/commands/` with the `object` pattern. Sub-verb
+   `dispatch` functions use the shared `route(...)` helper in
+   `Router.kt` rather than a hand-rolled `when (tail[0])`.
+2. Add a branch in `Main.kt`'s `dispatch` (top-level verbs call the
+   command object directly, e.g. `"relay" -> RelayCommands.dispatch(…)`;
+   `marmot` sub-verbs go through `marmotDispatch`'s `route` map).
 4. Extend `printUsage()` in `Main.kt`.
 5. Add the row to `cli/README.md`'s command table.
 6. Update `cli/ROADMAP.md` — move the row from 🆕 / 📦 to ✅.
@@ -173,6 +175,7 @@ cli/
     ├── secrets/           # SecretStore backends (keychain / ncryptsec / plaintext)
     └── commands/          # one file (or group) per top-level verb
         ├── UseCommand.kt          # `amy use NAME`
+        ├── Router.kt              # `route(...)` shared sub-verb dispatcher
         ├── InitCommands.kt        # init, whoami
         ├── CreateCommand.kt + LoginCommand.kt
         ├── RelayCommands.kt
@@ -186,15 +189,30 @@ cli/
         ├── MessageCommands.kt
         ├── MarmotResetCommand.kt
         ├── AwaitCommands.kt
-        └── StoreCommands.kt
+        ├── StoreCommands.kt
+        ├── AdminCommand.kt        # `amy admin RELAY METHOD` (NIP-86)
+        ├── ServeCommand.kt        # `amy serve` (embeds :geode)
+        └── cashu/                 # `amy cashu …` (NIP-60/61) — thin wrappers
+            ├── CashuCommands.kt   #   over commons CashuWalletOps / CashuWalletReader
+            ├── CashuWalletCommands.kt + CashuBalanceCommand.kt + CashuMintCommands.kt
+            └── CashuReceiveCommands.kt + CashuSendCommands.kt
+                + CashuMaintenanceCommands.kt + CashuMintRecCommands.kt
 ```
 
 Shared logic consumed by Amy lives in `commons/`:
 - `commons/account/` — account bootstrap
 - `commons/marmot/` — MLS / group state
+- `commons/cashu/` — `ops/CashuWalletOps` (jvmAndroid) + `CashuWalletReader`
+  + `CashuKeysetCounterStore`; the NIP-60/61 wallet, shared with Android.
+- `commons/relayManagement/Nip86Retriever` — NIP-86 HTTP client, shared with
+  the Android relay-management screen.
 - `commons/defaults/` — default relays, kinds
 - Consult `commons/plans/` for cross-cutting design work in flight.
 
+A few amy verbs lean on modules beyond `quartz`/`commons`: `amy serve`
+depends on `:geode` (the standalone relay) — the one allowed extra module
+dependency. `:amethyst` / `:desktopApp` remain forbidden (Rule 5).
+
 ## Common mistakes to refuse
 
 - **Adding protocol logic to `cli/`.** Push back, offer to extract.

.claude/skills/amy-expert/references/command-template.md

@@ -18,8 +18,7 @@ object NotePublishCommand {
         val args = Args(rest)
         val text = args.positional(0, "text")
 
-        val ctx = Context.open(dataDir)
-        try {
+        Context.open(dataDir).use { ctx ->
             ctx.prepare()
 
             val event = com.vitorpamplona.amethyst.commons.note
@@ -33,13 +32,15 @@ object NotePublishCommand {
                 "rejected_by"   to ack.filterValues { !it }.keys.map { it.url },
             ))
             return 0
-        } finally {
-            ctx.close()
         }
     }
 }
 ```
 
+`Context` is `AutoCloseable`; wrap it in `use { }` so it's closed
+(RunState flushed, relays disconnected) on every exit path — never a
+hand-rolled `try { } finally { ctx.close() }`.
+
 `Output.emit(...)` handles the text-vs-JSON mode automatically. The
 result map IS the `--json` shape; the human-readable text default is
 derived from the same map by `Output.kt`'s renderer.
@@ -51,39 +52,34 @@ When a feature has several verbs (`note publish`, `note show`,
 
 ```kotlin
 object NoteCommands {
-    suspend fun dispatch(dataDir: DataDir, tail: Array<String>): Int {
-        if (tail.isEmpty()) return Output.error("bad_args", "note <publish|show|react>")
-        val rest = tail.drop(1).toTypedArray()
-        return when (tail[0]) {
-            "publish" -> NotePublishCommand.run(dataDir, rest)
-            "show"    -> NoteShowCommand.run(dataDir, rest)
-            "react"   -> NoteReactCommand.run(dataDir, rest)
-            else      -> Output.error("bad_args", "note ${tail[0]}")
-        }
-    }
+    suspend fun dispatch(dataDir: DataDir, tail: Array<String>): Int =
+        route("note", tail, "note <publish|show|react>", mapOf(
+            "publish" to { rest -> NotePublishCommand.run(dataDir, rest) },
+            "show"    to { rest -> NoteShowCommand.run(dataDir, rest) },
+            "react"   to { rest -> NoteReactCommand.run(dataDir, rest) },
+        ))
 }
 ```
 
-Each verb gets its own file. Once a single file crosses ~200 lines,
-split it — see `GroupCommands.kt` and its siblings as the reference.
+The shared `route(name, tail, usage, routes)` helper (`Router.kt`)
+handles the empty-input and unknown-verb `bad_args` branches, so the
+`dispatch` body is just the verb→handler map. Each verb gets its own
+file. Once a single file crosses ~200 lines, split it — see
+`GroupCommands.kt` and its siblings as the reference.
 
 ## Wire-up checklist
 
 For every new command:
 
 1. File under `cli/commands/`.
-2. Branch in `Commands.kt`:
+2. Branch in `Main.kt`'s top-level `dispatch`, calling the command
+   object directly:
    ```kotlin
-   suspend fun note(dataDir: DataDir, tail: Array<String>): Int =
-       NoteCommands.dispatch(dataDir, tail)
+   "note" -> NoteCommands.dispatch(dataDir, tail)
    ```
-3. Branch in `Main.kt`'s top-level `dispatch`:
-   ```kotlin
-   "note" -> Commands.note(dataDir, tail)
-   ```
-4. Line in `printUsage()` explaining the verb.
-5. Row in `cli/README.md`'s command table.
-6. Status flip in `cli/ROADMAP.md` (🆕 / 📦 → ✅).
+3. Line in `printUsage()` explaining the verb.
+4. Row in `cli/README.md`'s command table.
+5. Status flip in `cli/ROADMAP.md` (🆕 / 📦 → ✅).
 
 ## What not to do
 
@@ -95,7 +91,7 @@ For every new command:
   them to `error: …` (text mode) / `{"error":…}` (JSON mode) plus the
   right exit code.
 - No holding a connection open across invocations — every run opens
-  a fresh `Context` and closes it in `finally`.
+  a fresh `Context` inside `use { }` so it closes on every exit path.
 - No blocking reads for user input — take a flag.
 - No global flags that collide with subcommand flags. `--name` is
   reserved for subcommand use (group/profile name); the global

.claude/skills/find-missing-translations/SKILL.md

@@ -7,7 +7,9 @@ description: Use when comparing Android strings.xml locale files to find untrans
 
 ## Overview
 
-Extract string resource keys from the default `values/strings.xml` that are absent in a target locale's `strings.xml`, excluding non-translatable entries. Outputs missing keys and offers to translate them.
+Extract string resource keys from a default `values/strings.xml` that are absent in a target locale's `strings.xml`, excluding non-translatable entries. Outputs missing keys and offers to translate them.
+
+The repo now has **two independent Crowdin-managed resource trees** — you must scan **both** (see "Resource trees" below).
 
 ## When to Use
 
@@ -15,6 +17,56 @@ Extract string resource keys from the default `values/strings.xml` that are abse
 - Preparing a batch of strings for a translator
 - Checking translation coverage after adding new features
 
+## Resource trees (scan BOTH)
+
+There are two separate `strings.xml` trees, each with its own default `values/` and per-locale `values-<locale>/` files, each wired into `crowdin.yml` independently:
+
+| Tree | Default file | Per-locale file |
+|------|--------------|-----------------|
+| **amethyst** (Android app) | `amethyst/src/main/res/values/strings.xml` | `amethyst/src/main/res/values-<locale>/strings.xml` |
+| **commons** (KMP Compose resources, shared by Android + Desktop) | `commons/src/commonMain/composeResources/values/strings.xml` | `commons/src/commonMain/composeResources/values-<locale>/strings.xml` |
+
+The `commons` tree appeared when shared event-renderer composables were extracted out of `amethyst/` into `commons/` (Compose Multiplatform `stringResource`). It is **not** a copy of the amethyst tree — the vast majority of its keys are commons-only; only a small handful overlap. Every diff/count/translate command below works on either tree by swapping the base path — **run the whole technique once per tree** and report them separately (each maps to its own Crowdin file, so the counts should reconcile against two different Crowdin UI numbers).
+
+**Locale-qualifier caveat:** `commons` uses the same region-qualified locale dirs as amethyst for our four targets (`values-cs`, `values-de-rDE`, `values-sv-rSE`, `values-pt-rBR`), but the *full* set of locale dirs differs between trees. Enumerate `values-*` under each tree's own base rather than assuming they match.
+
+**Overlap (copy — but only after checking the English matches):** a few `commons` keys share a *name* with a key in the amethyst tree. For such a key already translated in the amethyst locale file you may **copy the existing approved translation verbatim** — but **only if the two English source values are byte-identical.** A shared key name does **not** guarantee a shared meaning.
+
+> ⚠️ **Mistake we actually made (2026-07-18):** `napplet_card_permissions` exists in *both* trees with the *same key name* but *different English* — commons = `"What it can access"`, amethyst = `"Permissions:"`. Copying the amethyst translation by key name produced the wrong string in commons (it said "Permissions:" where the UI reads "What it can access"). **Always diff the English values, not just the key names.** When the English differs, translate the commons value fresh — or, better, find the amethyst key whose *value* matches (here `favorite_app_access_show` = "What it can access") and copy *that* approved translation.
+
+Detect name-overlap **and flag value mismatches** in one pass:
+
+```bash
+cdef=commons/src/commonMain/composeResources/values/strings.xml
+adef=amethyst/src/main/res/values/strings.xml
+comm -12 \
+  <(grep '<string name=' "$cdef" | sed 's/.*name="\([^"]*\)".*/\1/' | sort -u) \
+  <(grep '<string name=' "$adef" | grep -v 'translatable="false"' | sed 's/.*name="\([^"]*\)".*/\1/' | sort -u) \
+| while read -r k; do
+    cv=$(grep -m1 "name=\"$k\"" "$cdef" | sed 's/.*>\(.*\)<\/string>/\1/')
+    av=$(grep -m1 "name=\"$k\"" "$adef" | sed 's/.*>\(.*\)<\/string>/\1/')
+    [ "$cv" = "$av" ] && echo "SAFE-COPY   $k" || echo "VALUE-DIFFERS $k  commons=\"$cv\"  amethyst=\"$av\""
+  done
+```
+
+Only `SAFE-COPY` keys may be copied verbatim. For `VALUE-DIFFERS`, translate the commons English fresh (or copy from the amethyst key that has the *matching value*).
+
+**Whitespace-quote convention differs between trees.** Android string resources use surrounding double-quotes to preserve leading/trailing whitespace (`"replying to "`). The **commons Compose-resources tree does NOT use this convention** — it authors trailing/leading spaces raw and unquoted (`replying to `). So when copying/translating a commons string with edge whitespace, **match the commons source: raw spaces, no wrapping quotes.** (Mistake we made: we copied amethyst's quoted `"replying to "` into commons, where the quotes would render literally.) A quick check for stray quote-wrapping you introduced:
+
+```bash
+grep -nE '<string name="[^"]*">"' commons/src/commonMain/composeResources/values-*/strings.xml
+# The commons English tree has zero quote-wrapped values — any hit in a locale file is almost certainly a bad copy from amethyst.
+```
+
+**Why two catalogs exist — the duplication is NOT a bug to "fix" (don't ask again).** You will see the same English text (`Cancel`, `Save`, `Delete`, `Open`, …) defined *many* times across the amethyst tree under per-feature keys **and** once more in commons under generic keys (`action_cancel`, `action_save`, …). This is **required architecture, not an error:**
+
+- The two trees are **different resource systems**: amethyst uses Android `R.string`; commons uses Compose-Multiplatform `Res.string` (`com.vitorpamplona.amethyst.commons.resources.Res`).
+- **`commons` cannot depend on `amethyst`** (amethyst depends on commons — the reverse would be circular). So a composable extracted *into* commons physically cannot reference `R.string.cancel`; it needs its own string, hence the generic `action_*` keys. That is the only way an extracted shared composable can render "Cancel."
+- The scattered amethyst per-feature duplicates (`nip46_signer_cancel`, `nest_create_cancel`, …) are **pre-existing tech debt**; the commons keys did not create them.
+- Both catalogs are Crowdin-managed **independently**, and Crowdin's translation memory pre-fills repeats, so translating the same word in both trees is **not** wasted effort.
+
+**Do not** treat the value-overlap as something to deduplicate during a translation pass. Migrating amethyst's own screens onto the shared `action_*` strings is a *separate, optional* refactor and a maintainer call — out of scope for this skill. Just translate each tree correctly and independently.
+
 ## Background: Crowdin strip-identical behavior
 
 This repo syncs translations via Crowdin (branch `l10n_crowdin_translations`). Crowdin's default export behavior **omits any translation that exactly equals the source**, so a key that the translator deliberately kept as English (common for brand terms like `"Nowhere Drop"`, single-word loanwords like `"Apps"` / `"Feed"` / `"Issues"`, or version prefixes like `"v%1$s"`) will not appear in the locale's `strings.xml` even though the Crowdin UI shows it as 100% translated.
@@ -38,23 +90,45 @@ The default set of locales (unless the user specifies otherwise):
 
 | Locale | Language | Directory |
 |--------|----------|-----------|
-| `cs-rCZ` | Czech | `values-cs-rCZ` |
+| `cs` | Czech | `values-cs` |
 | `pt-rBR` | Brazilian Portuguese | `values-pt-rBR` |
 | `sv-rSE` | Swedish | `values-sv-rSE` |
 | `de-rDE` | German | `values-de-rDE` |
 
+> Czech was consolidated onto the base qualifier (PR #3461, 2026-07-03): a
+> `cs: cs` `languages_mapping` entry in `crowdin.yml` makes Crowdin export to
+> `values-cs`, and `values-cs-rCZ` no longer exists. The other locales still
+> use Crowdin's default region-qualified `androidCode` until they are
+> consolidated the same way — update this table as each one moves.
+
 ## Technique
 
 ### 1. Identify files
 
+Do this for **each** resource tree (see "Resource trees" above). The examples below use the amethyst base path; repeat every step with the commons base path swapped in.
+
 ```
+# amethyst tree
 Default:  amethyst/src/main/res/values/strings.xml
 Target:   amethyst/src/main/res/values-<locale>/strings.xml
+
+# commons tree
+Default:  commons/src/commonMain/composeResources/values/strings.xml
+Target:   commons/src/commonMain/composeResources/values-<locale>/strings.xml
 ```
 
-### 2. Find missing keys using cs-rCZ as reference
+A convenient way to run the whole technique twice is to loop over the two base dirs:
 
-Always diff against `cs-rCZ` first — it is the most complete locale and serves as the reference. Any keys missing in `cs-rCZ` will also be missing in the other target locales.
+```bash
+for base in amethyst/src/main/res commons/src/commonMain/composeResources; do
+  echo "########## tree: $base ##########"
+  # ... run the diff/count/value-extraction commands with $base/values[...] ...
+done
+```
+
+### 2. Find missing keys using cs as reference
+
+Always diff against `cs` first — it is the most complete locale and serves as the reference. Any keys missing in `cs` will also be missing in the other target locales.
 
 You MUST diff **both** `<string name=` AND `<plurals name=` — these are independent resource types and a key that is a `<plurals>` in the source will never appear in a `<string>` diff. Forgetting `<plurals>` is the most common silent failure of this skill (it misses things like `music_playlist_track_count`, `notification_count_more`, etc.).
 
@@ -65,7 +139,7 @@ comm -23 \
   <(grep '<string name=' amethyst/src/main/res/values/strings.xml \
     | grep -v 'translatable="false"' \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-  <(grep '<string name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
+  <(grep '<string name=' amethyst/src/main/res/values-cs/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort)
 
 # Plurals: a separate resource type — MUST be diffed independently
@@ -73,16 +147,16 @@ echo "=== missing <plurals> ==="
 comm -23 \
   <(grep '<plurals name=' amethyst/src/main/res/values/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-  <(grep '<plurals name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
+  <(grep '<plurals name=' amethyst/src/main/res/values-cs/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort)
 ```
 
 This gives two lists of missing key names — keep them separate; `<plurals>` translations need the per-locale CLDR category set (see Step 5 → "Plurals: handle with care").
 
-Crowdin can asymmetrically strip keys across locales (each translator independently chose source-identical for different keys), so **cs-rCZ is not a reliable upper bound**. Diff **every** target locale and union the results — don't assume the cs-rCZ set covers the others. A quick per-locale count is a useful sanity check against the Crowdin UI's "N untranslated":
+Crowdin can asymmetrically strip keys across locales (each translator independently chose source-identical for different keys), so **cs is not a reliable upper bound**. Diff **every** target locale and union the results — don't assume the cs set covers the others. A quick per-locale count is a useful sanity check against the Crowdin UI's "N untranslated":
 
 ```bash
-for locale in cs-rCZ de-rDE sv-rSE pt-rBR; do
+for locale in cs de-rDE sv-rSE pt-rBR; do
   ns=$(comm -23 \
     <(grep '<string name=' amethyst/src/main/res/values/strings.xml \
       | grep -v 'translatable="false"' | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
@@ -111,7 +185,7 @@ done < <(comm -23 \
   <(grep '<string name=' amethyst/src/main/res/values/strings.xml \
     | grep -v 'translatable="false"' \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-  <(grep '<string name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
+  <(grep '<string name=' amethyst/src/main/res/values-cs/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
 
 # Missing <plurals>: extract the multi-line block (opening tag through </plurals>)
@@ -124,7 +198,7 @@ while IFS= read -r key; do
 done < <(comm -23 \
   <(grep '<plurals name=' amethyst/src/main/res/values/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-  <(grep '<plurals name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
+  <(grep '<plurals name=' amethyst/src/main/res/values-cs/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
 ```
 
@@ -147,8 +221,10 @@ Flag and offer to fix:
 ```bash
 # Scan every locale's strings.xml for <item quantity="one"> entries that
 # hardcode "1" (or other literal digits) instead of using a placeholder.
-# Looks at default + all values-* locales.
-for f in amethyst/src/main/res/values/strings.xml amethyst/src/main/res/values-*/strings.xml; do
+# Looks at default + all values-* locales, in BOTH resource trees.
+for f in amethyst/src/main/res/values/strings.xml amethyst/src/main/res/values-*/strings.xml \
+         commons/src/commonMain/composeResources/values/strings.xml \
+         commons/src/commonMain/composeResources/values-*/strings.xml; do
   awk -v file="$f" '
     /<plurals/ { in_plurals = 1; name = $0; sub(/.*name="/, "", name); sub(/".*/, "", name) }
     in_plurals && /quantity="one"/ {
@@ -167,7 +243,9 @@ done
 Then scan for dead `quantity="zero"` entries. CLDR's `zero` category is integer-bearing only in **Arabic (`ar`)** and **Welsh (`cy`)**. In every other locale, count=0 falls through to `other`, so a `<item quantity="zero">` entry is dead and likely a translator/author bug (or it silently never fires):
 
 ```bash
-for f in amethyst/src/main/res/values/strings.xml amethyst/src/main/res/values-*/strings.xml; do
+for f in amethyst/src/main/res/values/strings.xml amethyst/src/main/res/values-*/strings.xml \
+         commons/src/commonMain/composeResources/values/strings.xml \
+         commons/src/commonMain/composeResources/values-*/strings.xml; do
   # Skip Arabic and Welsh — they natively use the zero category.
   case "$f" in
     *values-ar*|*values-cy*) continue ;;
@@ -199,7 +277,7 @@ done < <(comm -23 \
   <(grep '<string name=' amethyst/src/main/res/values/strings.xml \
     | grep -v 'translatable="false"' \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-  <(grep '<string name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
+  <(grep '<string name=' amethyst/src/main/res/values-cs/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
 ```
 
@@ -254,14 +332,48 @@ When adding translated strings to locale files:
 
 - **Append new strings at the bottom** of the file, just before the closing `</resources>` tag.
 - Do NOT try to insert them in alphabetical or matching order — a separate process handles ordering.
+- **Insert into each locale ONLY the keys missing from *that* locale — never a shared "union" block.** Because Crowdin strips keys asymmetrically (Step 2), a key you translate may already exist in some target locales. If you compute one union set of missing keys, translate it, and paste the *same* block into every locale, you will create **duplicate keys** in whichever locales already had them. Drive the insertion off the **per-locale** diff, not the union:
+
+  ```bash
+  # For each locale, insert only the keys comm -23 reports missing FOR THAT LOCALE.
+  for l in cs de-rDE sv-rSE pt-rBR; do
+    missing=$(comm -23 \
+      <(grep '<string name=' $base/values/strings.xml | grep -v 'translatable="false"' \
+        | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
+      <(grep '<string name=' $base/values-$l/strings.xml \
+        | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
+    # ... append ONLY the $missing keys' translations to values-$l/strings.xml ...
+  done
+  ```
+
+  (This bit us on 2026-07-21: `ps1_save_block`, `podcast_value_for_value`, and `chats_history_relays` were each missing in only *some* commons locales, but the same 3-key block was pasted into all four — producing duplicates in the locales that already had them.)
+
+- **After inserting, verify each edited file has no duplicate keys AND is well-formed XML — before you call the task done.** A duplicate key is not a warning: the `commons` tree's Compose-resources build task fails hard on it (`convertXmlValueResourcesForCommonMain: … Duplicated key '…'`), which breaks the build for everyone. Quick post-insertion gate over every file you touched:
+
+  ```bash
+  for f in <every edited strings.xml>; do
+    dups=$(grep -oE '<(string|plurals) name="[^"]*"' "$f" \
+      | sed 's/.*name="\([^"]*\)"/\1/' | sort | uniq -d)
+    [ -n "$dups" ] && echo "DUP in $f: $dups"
+    python3 -c "import xml.dom.minidom; xml.dom.minidom.parse('$f')" \
+      || echo "MALFORMED $f"
+  done
+  # For a commons change, also run the build task that enforces this:
+  #   ./gradlew :commons:convertXmlValueResourcesForCommonMain
+  ```
 
 ## Common Mistakes
 
+- **Scanning only the amethyst tree** — there are now **two** Crowdin-managed `strings.xml` trees (`amethyst/src/main/res` and `commons/src/commonMain/composeResources`). A key extracted into `commons/` will never show up in the amethyst diff. Run the whole technique once per tree (see "Resource trees") and report each separately.
+- **Copying an overlapping `commons` translation by key name alone** — a shared key name does NOT mean shared English. `napplet_card_permissions` is "What it can access" in commons but "Permissions:" in amethyst; copying by name produced the wrong string. Diff the English *values* first; copy verbatim only when they're byte-identical, else translate fresh (see "Overlap" in Resource trees).
+- **Applying amethyst's `"…"` whitespace-quote convention to a commons string** — the commons Compose-resources tree authors edge whitespace raw and unquoted; wrapping quotes copied from amethyst render literally there. Match the commons source format.
+- **Trying to "dedupe" the amethyst↔commons value-overlap** — it's required architecture (commons can't depend on amethyst, so shared composables need their own `Res.string` catalog), not an error. Don't fold consolidation into a translation pass.
 - **Forgetting `translatable="false"`** — these should never appear in locale files
 - **Diffing only `<string name=`** — `<plurals>` is a separate resource type; a source `<plurals>` missing from a locale will never show up in a `<string>` diff. Always run the diff twice (once per resource type) as shown in Step 2. The same goes for `<string-array>` if the project uses it.
 - **Trusting a git "sync-timestamp" heuristic to pre-filter the list** — this skill used to skip keys added before the last `New Crowdin translations` commit, on the theory that Crowdin had already "decided" them. It was dropped: a key added shortly before an export that translators hadn't reached yet is genuinely missing, so the heuristic silently dropped real work. Use the raw on-disk diff and reconcile against the Crowdin web UI's untranslated count instead.
 - **Adding source-identical fallbacks locally** — they get overwritten on the next Crowdin sync. Android falls back to `values/strings.xml` at runtime anyway, so a key intentionally kept as English already renders correctly. Skip these by inspection (brand terms, loanwords, `v%1$s`-style strings); don't translate them to an identical value.
-- **Skipping per-locale diffs when only diffing cs-rCZ** — Crowdin can strip different keys in different locales (each translator's choice), so cs-rCZ is not a reliable upper bound. Diff each target locale and union the results.
+- **Skipping per-locale diffs when only diffing cs** — Crowdin can strip different keys in different locales (each translator's choice), so cs is not a reliable upper bound. Diff each target locale and union the results.
+- **Pasting the union set of missing keys into every locale → duplicate keys** — the union is the right set to *translate*, but the wrong set to *insert*. A key missing in only some locales, inserted into all of them, duplicates in the ones that already had it. Drive each file's insertion off its own per-locale diff (see Step 6). In `commons`, a duplicate key is build-breaking: `convertXmlValueResourcesForCommonMain` fails with `Duplicated key '…'`. **Always run the post-insertion duplicate + XML-wellformedness gate in Step 6 before declaring done.** (Happened 2026-07-21 with `ps1_save_block` / `podcast_value_for_value` / `chats_history_relays`.)
 - **Inserting strings in a specific position** — always append at the bottom; ordering is handled separately
 - **Hardcoding `"1"` in a `<plurals>` `quantity="one"` item** — always use the count placeholder; otherwise non-English `one` categories produce wrong text
 - **Copying English's `one`/`other` set into every locale** — each language must include all CLDR plural categories it uses (e.g. Czech needs `one`, `few`, `many`, `other`)

.claude/skills/ngit-pr/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: ngit-pr
+description: How to create, review, revise, and merge pull requests in this repo, which can be published TWO ways — GitHub (the `gh` CLI) and git-over-nostr (the `ngit` CLI, where PRs are nostr **proposals** reviewed on gitworkshop.dev). Use whenever a task involves opening/updating/merging a PR by either mechanism, the `pr/feat/*` branches, the `ngit` or `gh` CLIs, gitworkshop.dev, or a `nostr://` remote. Remote names vary per clone (and a collaborator may have only one) — this skill identifies remotes by URL, and covers the three-mains alignment gate the nostr flow depends on.
+---
+
+# Pull requests: GitHub **and** git-over-nostr
+
+This repo can be contributed to **two** ways, via **two kinds** of remote. Both end up in GitHub `main`.
+
+| Remote kind | URL pattern | Role |
+|--|--|--|
+| **GitHub** | `github.com/vitorpamplona/amethyst` | **Canonical** `main`. Moves constantly (bots merge often) — a moving target. |
+| **git-over-nostr** | `nostr://…/relay.ngit.dev/amethyst` | `ngit`. A push fans out to GitHub **and** the GRASP git servers and publishes nostr events. PRs are **proposals**, reviewed on **gitworkshop.dev**. |
+
+## Step 0 — identify YOUR remotes (names are not universal)
+
+Remote **names are per-clone**. In the maintainer's checkout the GitHub remote is `upstream` and the nostr remote is `origin`, but yours may differ, and **you may have only one of them** (e.g. cloned straight from `nostr://…`, so the nostr remote is your `origin` and there is no separate GitHub remote — pushing it still reaches GitHub via fan-out). Detect by **URL**, never assume a name:
+
+```bash
+git remote -v
+GH_REMOTE=$(git remote -v    | awk '/github\.com/   {print $1; exit}')   # GitHub remote (may be empty)
+NOSTR_REMOTE=$(git remote -v | awk '/nostr:\/\//     {print $1; exit}')  # git-over-nostr remote (may be empty)
+echo "github=$GH_REMOTE  nostr=$NOSTR_REMOTE"
+```
+
+The examples below use `$GH_REMOTE` / `$NOSTR_REMOTE` — substitute whichever you have.
+
+## Which path?
+
+| | **GitHub path** (`gh`) | **nostr path** (`ngit`) |
+|--|--|--|
+| Needs | a GitHub remote + `gh auth status` | a `nostr://` remote + `ngit` ≥ 2.5.0 |
+| PR lives on | GitHub only | nostr + GitHub + GRASP (fans out) |
+| Use when | Default; PR only needs to be on GitHub. Simplest, no alignment gate. | The PR must be visible/reviewable over nostr (gitworkshop), or you're revising/merging an existing **proposal** (a `pr/feat/*`). |
+
+**Default to GitHub** unless the task is specifically about a nostr proposal (e.g. "the PRs on origin", a gitworkshop link, a `pr/feat/*` branch). If you only have one remote, that decides the path for you. Revise/merge a PR on **the same path it was created** — don't revise a GitHub PR via ngit or vice-versa.
+
+---
+
+# GitHub path (`gh`)
+
+The normal flow most of this repo's history uses ("Merge pull request #NNNN …"). Requires a GitHub remote (`$GH_REMOTE`) and `gh auth status` OK.
+
+```bash
+# create — branch off main, push, open the PR
+git checkout -b feat/<slug> main
+git push -u "$GH_REMOTE" feat/<slug>
+gh pr create --repo vitorpamplona/amethyst --base main --head feat/<slug> \
+  --title "feat: …" --body "…"
+
+# review / list
+gh pr list --repo vitorpamplona/amethyst
+gh pr view <number> --repo vitorpamplona/amethyst   # --comments for the thread
+
+# revise — push more commits to the same branch
+git push "$GH_REMOTE" feat/<slug>
+
+# merge (maintainer)
+gh pr merge <number> --repo vitorpamplona/amethyst --merge   # or --squash
+```
+
+GitHub is the source of truth for this path — no three-mains gate. Standard Git Workflow rules from CLAUDE.md still apply (conventional commits, never `--no-verify`).
+
+---
+
+# nostr path (`ngit`)
+
+Requires a `nostr://` remote (`$NOSTR_REMOTE`) and `ngit` ≥ 2.5.0 (`ngit --version`).
+
+**Mental model:** an ngit PR ("proposal") is a *linear patch series off `main`*, published as nostr events. A "revision" is a new version of that proposal. Merging applies the series to `main` and publishes a merged-status event. There is **no** GitHub PR number; `ngit pr merge` makes a plain merge commit (amend it to a readable message).
+
+## ⚠ The three-mains alignment gate (the thing that breaks everything)
+
+Up to **three** `main` heads drift apart:
+
+- GitHub main (`$GH_REMOTE/main` if you have it) — newest, moves every few minutes
+- nostr main (`$NOSTR_REMOTE/main` tracking ref) — **lags**, often far behind
+- local `main`
+
+**Every create/revise/merge requires the proposal's base to equal the nostr `main`, and pushing `main` to the nostr remote requires GitHub's main to be an ancestor of what you push.** When misaligned, ngit **rejects pre-flight and publishes nothing** (safe — nothing half-breaks; realign and retry). Don't `--force` past it.
+
+```bash
+git fetch --all
+echo "github=$([ -n "$GH_REMOTE" ] && git rev-parse "$GH_REMOTE/main")  \
+nostr=$(git ls-remote "$NOSTR_REMOTE" -h refs/heads/main | awk '{print $1}')  \
+local=$(git rev-parse main)"
+# all present heads equal → proceed.
+# local behind GitHub?  git merge --ff-only "$GH_REMOTE/main"  (or "$NOSTR_REMOTE/main" if that's all you have)
+# nostr behind local?   git push "$NOSTR_REMOTE" main   (clean fast-forward only)
+```
+
+If you have **only** the nostr remote: align local `main` to `$NOSTR_REMOTE/main`; GitHub is handled by fan-out, and any GitHub/GRASP disagreement surfaces as an ngit rejection on push. If GitHub diverged from nostr (`out of sync with nostr` on push), that's a maintainer `ngit sync --ref-name refs/heads/main --force` situation — **stop and ask the human**, don't run a forced sync unprompted.
+
+## Pushes are slow — run them in the background
+
+`git push "$NOSTR_REMOTE" …`, `ngit send`, and `ngit pr merge` fan out to relays + GRASP servers and **routinely exceed 2 minutes**. Run with `run_in_background: true` and poll (e.g. `git ls-remote "$NOSTR_REMOTE"` for the expected ref). A foreground call hits the 2-minute tool timeout even while the push is actually succeeding.
+
+## Identity
+
+`ngit account whoami` shows the signing key; `ngit send`/`ngit pr merge` sign with **that** key regardless of original author. The maintainer (`VitorPamplona`, `_@vitorpamplona.com`) revising/merging a contributor's proposal with their own key is expected.
+
+## List / view
+
+```bash
+ngit pr list                                   # open + draft
+ngit pr list --status open,draft,closed,merged,applied
+ngit pr view <FULL-hex-event-id | nevent>      # FULL id, not the short prefix
+```
+
+In `git branch -r`, proposals show as `<nostr-remote>/pr/feat/<slug>(<short-id>)` — the `(...)` is an ngit annotation; the real ref is `pr/feat/<slug>`. Status `applied` == merged.
+
+## Create
+
+Push a `pr/`-prefixed branch (linear, off current `main`):
+
+```bash
+git push -o 'title=My title' -o 'description=line1\n\nline2' -u "$NOSTR_REMOTE" pr/feat/<slug>
+```
+
+Advanced (cover letter, labels): `ngit send` — see `ngit send --help`.
+
+## Revise (publish a new version)
+
+The revision must be a **linear series off the current `main`** (a merge commit is the wrong shape).
+
+```bash
+# 1. align (gate above), then build the linear series:
+git checkout -b <work> main
+git cherry-pick <original-pr-tip>      # existing PR commits
+git cherry-pick <your-new-commits…>    # yours on top   (or: git rebase main)
+
+# 2. verify it compiles + tests pass; tree == your intended change.
+
+# 3. publish as a new version, linked to the proposal:
+ngit send --in-reply-to <proposal-nevent> \
+  --subject "<keep or update title>" \
+  --description "<what changed>" \
+  -d main                              # SINCE_OR_RANGE "main" → commits in main..HEAD
+```
+
+`--in-reply-to` threads it under the same proposal on gitworkshop. **No `--force`** once the base equals the nostr `main`. `proposal builds on a commit N ahead of 'origin/main'` ⇒ gate unmet — realign and re-rebase, don't force. Verify: `git ls-remote "$NOSTR_REMOTE" | grep <short-id>` shows `refs/pr/<full-id>/head` at your new tip.
+
+## Merge into main
+
+The merge is **local**; the merged-status event publishes on the subsequent push.
+
+```bash
+# 1. ALIGN (mandatory) — all present mains equal.
+
+git checkout main
+ngit pr merge <FULL-hex-event-id> -d        # local merge commit; marks proposal "applied"
+                                            #   --squash for a squash merge
+
+# 2. amend the generic merge message to something readable:
+git commit --amend -F - <<'MSG'
+Merge PR: <title>
+
+Merges nostr proposal <short-id> into main:
+- <commit summaries>
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+MSG
+
+# 3. sanity-check, then publish (background — slow):
+[ -n "$GH_REMOTE" ] && { git merge-base --is-ancestor "$GH_REMOTE/main" HEAD && echo "clean FF push" || echo "github moved; realign"; }
+git push "$NOSTR_REMOTE" main
+```
+
+Confirm: `ngit pr list --status applied` shows it `applied`, and (if you have it) `git fetch "$GH_REMOTE"` fast-forwards GitHub's main to your merge.
+
+## Cleanup
+
+Delete throwaway branches pushed to the nostr remote (e.g. a `merge/*` used before switching to the proper flow): `git push "$NOSTR_REMOTE" --delete <branch>` (the per-GRASP "non-existent ref" warnings are idempotent fan-out). Delete the local merged branches ngit creates (`pr/feat/<slug>(...)`) and your work branch.
+
+## Failure modes — quick reference
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `proposal builds on a commit N ahead of 'origin/main'` | base ≠ stale nostr `main` | realign `main`, rebase series, resend (no `--force`) |
+| `! [remote rejected] main … out of sync with nostr` | GitHub main diverged from nostr | maintainer `ngit sync … --force` — **ask the human** |
+| push "succeeds" but nothing on gitworkshop | pushed a plain branch, not a proposal | use `pr/`-prefix or `ngit send --in-reply-to` |
+| `ngit pr view`/`merge` "failed to parse event id" | used the short prefix | pass the **full** hex id or `nevent` |
+| push hangs / times out at 2 min | normal GRASP fan-out latency | run in background; verify via `git ls-remote` |

.claude/skills/nostr-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nostr-expert
-description: Nostr protocol implementation patterns in Quartz (AmethystMultiplatform's KMP Nostr library). Use when working with: (1) Nostr events (creating, parsing, signing), (2) Event kinds and tags, (3) NIP implementations (80+ NIP packages in quartz/), (4) Event builders and TagArrayBuilder DSL, (5) Nostr cryptography (secp256k1, NIP-44 encryption), (6) Relay communication patterns, (7) Bech32 encoding (npub, nsec, note, nevent). Complements nostr-protocol agent (NIP specs) - this skill provides Quartz codebase patterns and implementation details.
+description: Nostr protocol implementation patterns in Quartz (AmethystMultiplatform's KMP Nostr library). Use when working with: (1) Nostr events (creating, parsing, signing), (2) Event kinds and tags, (3) NIP implementations (80+ NIP packages in quartz/), (4) Event builders and TagArrayBuilder DSL, (5) Nostr cryptography (secp256k1, NIP-44 encryption), (6) Relay communication patterns, (7) Bech32 encoding (npub, nsec, note, nevent), (8) Resolving user input (hex, npub, nprofile, or NIP-05 `name@domain` internet identifiers) to a pubkey. Complements nostr-protocol agent (NIP specs) - this skill provides Quartz codebase patterns and implementation details.
 ---
 
 # Nostr Protocol Expert (Quartz Implementation)
@@ -15,6 +15,7 @@ Practical patterns for working with Nostr in Quartz, AmethystMultiplatform's KMP
 - Finding NIP implementations in quartz/ codebase
 - Nostr cryptography (secp256k1 signing, NIP-44 encryption)
 - Bech32 encoding/decoding (npub, nsec, note formats)
+- Resolving user input (hex / npub / nprofile / NIP-05 `name@domain`) to a pubkey
 - Event validation and verification
 
 **For NIP specifications** → Use `nostr-protocol` agent
@@ -345,6 +346,55 @@ object Nip04 {
 
 **Note**: Use NIP-44 (`Nip44`) for new implementations. NIP-04 has security issues.
 
+## Hex Encoding (HexKey ↔ ByteArray)
+
+Pubkeys, event ids and signatures are lower-case hex. Quartz uses the `HexKey`
+typealias (`= String`) plus extensions in `nip01Core/core/HexKey.kt`, backed by
+the `Hex` object in `utils/Hex.kt`. **Use these — never hand-roll a byte loop or
+import a third-party hex codec.**
+
+```kotlin
+import com.vitorpamplona.quartz.nip01Core.core.toHexKey
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArray
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArrayOrNull
+import com.vitorpamplona.quartz.nip01Core.core.isValid
+import com.vitorpamplona.quartz.utils.Hex
+
+val hex: HexKey = bytes.toHexKey()            // ByteArray -> lower-case hex
+val back: ByteArray = hex.hexToByteArray()    // hex -> ByteArray (throws on odd length)
+val safe: ByteArray? = input.hexToByteArrayOrNull()  // null on invalid hex
+
+Hex.isHex(input)     // valid hex, any length
+Hex.isHex64(input)   // ~30% faster fast-path for a 32-byte key/id
+hex.isValid()        // 64 chars + valid hex (pubkey / event-id shape)
+Hex.isEqual(hex, bytes)  // compare hex to bytes without decoding
+```
+
+Constants `PUBKEY_LENGTH` / `EVENT_ID_LENGTH` (both 64) live in `nip01Core.core`.
+
+## Core Utilities (time, random, event id)
+
+Reuse these instead of hand-rolling — each avoids a common mistake:
+
+```kotlin
+import com.vitorpamplona.quartz.utils.TimeUtils
+import com.vitorpamplona.quartz.utils.RandomInstance
+import com.vitorpamplona.quartz.utils.sha256.sha256
+import com.vitorpamplona.quartz.nip01Core.crypto.EventHasher
+
+TimeUtils.now()            // Unix SECONDS for created_at — not currentTimeMillis()/1000
+TimeUtils.oneHourAgo()     // relative filter bounds (…Ago / …FromNow); all in seconds
+RandomInstance.bytes(32)   // secure random (SecureRandom) — for nonces/keys, not kotlin.random.Random
+RandomInstance.randomChars()   // 16-char subscription id
+
+sha256(bytes)              // raw hash primitive
+EventHasher.hashId(pubKey, createdAt, kind, tags, content)   // canonical event id
+EventHasher.hashIdCheck(id, pubKey, createdAt, kind, tags, content)  // verify untrusted events
+```
+
+`EventHasher` serializes `[0, pubkey, created_at, kind, tags, content]` in the
+exact form NIP-01 requires — prefer it over calling `sha256` on your own JSON.
+
 ## Bech32 Encoding (NIP-19)
 
 Encoding uses extension functions on `ByteArray` (`nip19Bech32/ByteArrayExt.kt`);
@@ -375,6 +425,25 @@ when (val entity = Nip19Parser.uriToRoute(input)?.entity) {
 }
 ```
 
+## Resolving User Input to a Pubkey (NIP-05 + NIP-19)
+
+**Before writing any `if (isHex) … else if (npub) … else if ("@" in s) fetchWellKnown()` logic, stop — it already exists.** `resolveUserHexOrNull` in `quartz/nip05DnsIdentifiers/` accepts every identifier form a user might type and returns a 64-hex pubkey.
+
+```kotlin
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.resolveUserHexOrNull
+
+// hex | npub1… | nprofile1… | nsec1… | name@domain.tld  →  HexKey? (null if unrecognized/lookup fails)
+val pubkey = resolveUserHexOrNull(userInput, nip05Client)
+```
+
+- Tries the **synchronous** hex/bech32 path first (`decodePublicKeyAsHexOrNull`) — only NIP-05-shaped input hits the network.
+- `suspend`; re-throws only `CancellationException`. Pass `nip05Client = null` for offline contexts.
+- Build the client with `Nip05Client(fetcher = OkHttpNip05Fetcher { _ -> okHttp })` (see `cli/Context.kt`). The OkHttp fetcher already runs on IO and disables redirects per the NIP-05 spec — don't re-implement the `.well-known/nostr.json` fetch or JSON parse.
+- Need only hex/bech32 (no network)? Use `decodePublicKeyAsHexOrNull(input)` directly.
+- Need to *verify* a claimed identifier maps back to a pubkey? `nip05Client.verify(Nip05Id.parse(id)!!, pubkey)`.
+
+See `references/nip05-identifiers.md` for the full API surface (`Nip05Id`, `Nip05Client`, `Nip05Parser`, `KeyInfoSet`, Namecoin `.bit`) and the hand-rolled anti-pattern to avoid.
+
 ## Event Validation
 
 ```kotlin
@@ -503,6 +572,7 @@ Or see `references/nip-catalog.md` for complete catalog.
 - **references/event-hierarchy.md** - Event class hierarchy, kind classifications, common types
 - **references/tag-patterns.md** - Tag structure, TagArrayBuilder DSL, common tag types, parsing patterns
 - **references/nip19-bech32.md** - `Nip19Parser`, `Bech32Util`, `TlvBuilder`, entity types (NPub, NSec, NEvent, NAddress, NProfile, NRelay, NEmbed)
+- **references/nip05-identifiers.md** - Resolving any identifier (hex/npub/nprofile/nsec/`name@domain`) to a pubkey via `resolveUserHexOrNull`; `Nip05Client`, `Nip05Id`, `Nip05Parser`, Namecoin `.bit` — and the hand-rolled anti-pattern to avoid
 - **references/event-factory.md** - `EventFactory` dispatch pattern and how to register a new kind
 - **references/crypto-and-encryption.md** - Event signing/verification, secp256k1 abstraction, NIP-44 encryption, `SharedKeyCache`
 - **references/large-cache.md** - `LargeCache<K,V>` expect/actual + `ICacheOperations` functional API
@@ -518,6 +588,9 @@ Or see `references/nip-catalog.md` for complete catalog.
 | Verify signature | `event.verify()` | nip01Core/core/ |
 | Encrypt (NIP-44) | `Nip44v2.encrypt(...)` | nip44Encryption/ |
 | Bech32 encode | `Nip19.npubEncode(...)` | nip19Bech32/ |
+| Resolve input → pubkey | `resolveUserHexOrNull(input, nip05Client)` | nip05DnsIdentifiers/ |
+| Decode bech32 → pubkey (no net) | `decodePublicKeyAsHexOrNull(input)` | nip19Bech32/ |
+| Verify NIP-05 identifier | `nip05Client.verify(Nip05Id.parse(id)!!, hex)` | nip05DnsIdentifiers/ |
 | Find NIP | `scripts/nip-lookup.sh <number>` | - |
 
 ## Common Event Kinds

.claude/skills/nostr-expert/references/nip-catalog.md

@@ -13,7 +13,7 @@ under `experimental/`**. The categorized list below may lag behind —
 | 02 | `nip02FollowList/` | ContactListEvent.kt | Follow/contact lists (kind 3) |
 | 03 | `nip03Timestamp/` | OpenTimestampsAttestation.kt | Timestamps |
 | 04 | `nip04Dm/` | EncryptedDmEvent.kt | Legacy encrypted DMs (deprecated for NIP-17) |
-| 05 | `nip05DnsIdentifiers/` | Nip05Verifier.kt | DNS-based verification |
+| 05 | `nip05DnsIdentifiers/` | UserHexResolver.kt, Nip05Client.kt | Internet identifiers; `resolveUserHexOrNull` resolves hex/npub/nprofile/`name@domain` → pubkey (see references/nip05-identifiers.md) |
 | 06 | `nip06KeyDerivation/` | Mnemonic-related | BIP-39 key derivation |
 | 09 | `nip09Deletions/` | DeletionEvent.kt | Event deletion requests (kind 5) |
 | 11 | `nip11RelayInfo/` | RelayInformation.kt | Relay metadata |

.claude/skills/nostr-expert/references/nip05-identifiers.md

@@ -0,0 +1,98 @@
+# NIP-05: Identifiers → Pubkey Resolution
+
+How Quartz turns anything a human might type — a raw hex pubkey, an `npub`/`nprofile`/`nsec`, or a NIP-05 internet identifier (`alice@domain.tld`) — into a 64-hex Nostr pubkey. **Everything below already exists in `quartz/nip05DnsIdentifiers/`. Do not hand-roll it.**
+
+## TL;DR — the one function you almost always want
+
+```kotlin
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.resolveUserHexOrNull
+
+// hex | npub1… | nprofile1… | nsec1… | name@domain.tld  →  64-hex pubkey (or null)
+val pubkey: HexKey? = resolveUserHexOrNull(userInput, nip05Client)
+```
+
+`resolveUserHexOrNull(input, nip05Client)` (in `UserHexResolver.kt`) is the canonical "accept any identifier form" resolver. It:
+
+- trims input, tries the **synchronous** bech32/hex path first (`decodePublicKeyAsHexOrNull`), so hex/`npub`/`nprofile`/`nsec` never touch the network;
+- only issues an HTTPS fetch for genuinely NIP-05-shaped input (`name@domain.tld`), gated by a cheap `looksLikeNip05()` precheck;
+- returns `null` on anything unrecognizable or on a failed NIP-05 lookup (network error / no match);
+- re-throws **only** `CancellationException`, so it's safe inside structured concurrency.
+
+Pass `nip05Client = null` in pure-offline contexts — NIP-05-shaped inputs then fall through to `null` and no HTTP is attempted.
+
+## ❌ Do not write this (the hand-rolled anti-pattern)
+
+```kotlin
+// DON'T. This re-implements resolveUserHexOrNull badly:
+//  - no nsec support
+//  - no input validation (accepts IP-literal / malformed domains → spurious fetches)
+//  - hand-parses JSON instead of using Nip05Parser
+//  - bespoke httpGet ignores the "MUST NOT follow redirects" rule
+//  - swallows CancellationException, breaking structured concurrency
+fun resolveObserver(input: String): String? {
+    if (Hex.isHex64(input)) return input.lowercase()
+    if (input.startsWith("npub1") || input.startsWith("nprofile1")) { /* … */ }
+    if ("@" in input) return resolveNip05(input)  // bespoke well-known fetch
+    return null
+}
+```
+
+## ✅ Do this instead
+
+```kotlin
+// CLI already exposes it — commands call Context.requireUserHex(input):
+val pubHex = resolveUserHexOrNull(input, nip05Client)
+    ?: return Output.error("bad_args", "expected npub, nprofile, 64-hex, or name@domain.tld")
+```
+
+## Building an `Nip05Client`
+
+`resolveUserHexOrNull` takes an `INip05Client`. On JVM/Android, wire the OkHttp fetcher (mirror what `cli/Context.kt` does):
+
+```kotlin
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.Nip05Client
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.OkHttpNip05Fetcher
+
+val nip05Client = Nip05Client(fetcher = OkHttpNip05Fetcher { _ -> okHttpClient })
+```
+
+`OkHttpNip05Fetcher` already runs on `Dispatchers.IO` and disables redirects per the NIP-05 spec ("Fetchers MUST ignore any HTTP redirects"). Don't re-implement the fetch.
+
+For tests / offline code, `EmptyNip05Client` is a no-op stub.
+
+## The pieces (all in `quartz/…/nip05DnsIdentifiers/`)
+
+| Type | File | Purpose |
+|------|------|---------|
+| `resolveUserHexOrNull(input, client?)` | `UserHexResolver.kt` | **Start here.** Any identifier form → 64-hex pubkey, or null. `suspend`. |
+| `Nip05Id` | `Nip05Id.kt` | Parsed `name@domain`. `Nip05Id.parse(str)` validates (RFC 5321 local-part + hostname rules, rejects IP literals) and lowercases. `toUserUrl()` / `toDomainUrl()` build the `.well-known/nostr.json` URLs. `toDisplayValue()` collapses the `_` wildcard to just the domain. |
+| `INip05Client` / `Nip05Client` | `INip05Client.kt`, `Nip05Client.kt` | Async resolver. `get(id): Nip05KeyInfo?` (pubkey + relays), `verify(id, hex): Boolean`, `load(id): KeyInfoSet?`, `list(domain): KeyInfoSet`, `loadClinkOffer(id): String?`. Auto-routes `.bit` domains to Namecoin. `EmptyNip05Client` = offline no-op. |
+| `Nip05Fetcher` / `OkHttpNip05Fetcher` | `Nip05Fetcher.kt`, `OkHttpNip05Fetcher.kt` (jvmAndroid) | Transport SAM. OkHttp actual disables redirects + runs on IO. |
+| `Nip05Parser` | `Nip05Parser.kt` | JSON `.well-known/nostr.json` codec: `parseHexKey`, `parseHexKeyAndRelays`, `parse` → `KeyInfoSet`, `parseClinkOffer`. |
+| `Nip05KeyInfo` / `KeyInfoSet` | `Nip05KeyInfo.kt`, `KeyInfoSet.kt` | `Nip05KeyInfo(pubkey, relays)`; `KeyInfoSet(names: Map, relays: Map)` = the full domain listing. |
+| `NamecoinNameResolver` | `namecoin/NamecoinNameResolver.kt` | `.bit` / `d/…` / `id/…` blockchain identifiers. `isNamecoinIdentifier(str)`, `resolve(str)`. Invoked automatically by `Nip05Client` — you rarely call it directly. |
+
+## When you only need the pure (synchronous, no-network) part
+
+If the input can only be hex/bech32 (no NIP-05), skip the client entirely:
+
+```kotlin
+import com.vitorpamplona.quartz.nip19Bech32.decodePublicKeyAsHexOrNull
+
+// hex | npub1… | nprofile1… | nsec1…  →  64-hex pubkey (or null). No suspend, no network.
+val pubkey: HexKey? = decodePublicKeyAsHexOrNull(input)
+```
+
+See `references/nip19-bech32.md` for the full bech32 entity story. `resolveUserHexOrNull` is just this function plus the NIP-05 HTTP fallback.
+
+## Verifying a claimed identifier
+
+To confirm a profile's advertised `nip05` actually points back to its pubkey (NIP-05 verification), use `verify`, not `get`:
+
+```kotlin
+val ok: Boolean = nip05Client.verify(Nip05Id.parse("alice@domain.tld")!!, profilePubkeyHex)
+```
+
+## Tests
+
+`quartz/src/commonTest/…/nip05DnsIdentifiers/Nip05Test.kt` covers parsing, URL construction, case-normalization, CLINK offers, and the validation rejects (IP literals, malformed domains).

.claude/skills/quartz-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quartz-integration
-description: Integration guide for using the Quartz Nostr KMP library in external projects. Use when: (1) adding Quartz as a Gradle dependency, (2) setting up NostrClient with WebSocket, (3) creating/signing/sending events, (4) building relay subscriptions with Filter, (5) handling keys with KeyPair/NostrSignerInternal, (6) using Bech32 encoding/decoding (NIP-19), (7) platform-specific setup (Android vs JVM/Desktop), (8) NIP-57 zaps, NIP-17 DMs, NIP-44 encryption in external projects.
+description: Integration guide for using the Quartz Nostr KMP library in external projects. Use when: (1) adding Quartz as a Gradle dependency, (2) setting up NostrClient with WebSocket, (3) creating/signing/sending events, (4) building relay subscriptions with Filter, (5) handling keys with KeyPair/NostrSignerInternal, (6) using Bech32 encoding/decoding (NIP-19), (7) platform-specific setup (Android vs JVM/Desktop), (8) NIP-57 zaps, NIP-17 DMs, NIP-44 encryption in external projects, (9) running a relay on Quartz and serving/building its NIP-11 relay information document (application/nostr+json).
 ---
 
 # Quartz Integration Guide
@@ -134,13 +134,14 @@ val privKeyHex: String? = keyPair.privKey?.toHexKey()
 
 ```kotlin
 import com.vitorpamplona.quartz.nip01Core.core.toHexKey
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArray
 import com.vitorpamplona.quartz.nip19Bech32.Nip19Parser
 
 // ByteArray → hex
 val hex = byteArray.toHexKey()
 
 // hex → ByteArray
-val bytes = HexKey.decodeHex(hex)
+val bytes = hex.hexToByteArray()
 
 // Bech32 import (npub, nsec)
 val parsed = Nip19Parser.uriToRoute("npub1abc...")
@@ -148,6 +149,126 @@ val parsed = Nip19Parser.uriToRoute("npub1abc...")
 val parsed = Nip19Parser.uriToRoute("nsec1abc...")
 ```
 
+> Hex ↔ ByteArray is a first-class utility in Quartz — see **§3.1 Hex utilities** below.
+
+---
+
+### 3.1 Hex utilities (HexKey ↔ ByteArray)
+
+Nostr keys, event ids and signatures travel as lower-case hex strings. Quartz
+models this with the `HexKey` typealias (just a `String`) plus extension
+functions — **do not** write your own byte loop or pull in a third-party codec.
+
+**Packages:** `com.vitorpamplona.quartz.nip01Core.core` (the extensions) and
+`com.vitorpamplona.quartz.utils` (the underlying `Hex` object).
+
+```kotlin
+import com.vitorpamplona.quartz.nip01Core.core.HexKey            // typealias = String
+import com.vitorpamplona.quartz.nip01Core.core.toHexKey          // ByteArray → hex
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArray    // hex → ByteArray
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArrayOrNull
+import com.vitorpamplona.quartz.nip01Core.core.isValid
+import com.vitorpamplona.quartz.utils.Hex
+
+// Encode / decode
+val hex: HexKey = pubKeyBytes.toHexKey()      // lower-case, 2 chars per byte
+val bytes: ByteArray = hex.hexToByteArray()   // throws on odd length
+
+// Untrusted input → decode safely
+val maybe: ByteArray? = userInput.hexToByteArrayOrNull()  // null if not valid hex
+
+// Validate without decoding (no allocation)
+Hex.isHex(userInput)        // even-length, all hex digits (any length)
+Hex.isHex64(userInput)      // fast path for a 32-byte key/id (checks first 64 chars)
+hex.isValid()               // 64 chars AND valid hex (pubkey / event-id shape)
+
+// Compare a hex string to raw bytes without decoding
+Hex.isEqual(incomingHexId, myIdBytes)
+```
+
+| Need | Call | Notes |
+|------|------|-------|
+| ByteArray → hex | `bytes.toHexKey()` | lower-case output |
+| hex → ByteArray (strict) | `hex.hexToByteArray()` | throws on odd length |
+| hex → ByteArray (safe) | `hex.hexToByteArrayOrNull()` | `null` on invalid hex |
+| is this valid hex? | `Hex.isHex(s)` / `Hex.isHex64(s)` | `isHex64` ~30% faster for keys/ids |
+| is this a pubkey/id shape? | `hex.isValid()` | 64 chars + valid hex |
+| hex == bytes? | `Hex.isEqual(hex, bytes)` | no decode allocation |
+
+Constants `PUBKEY_LENGTH` and `EVENT_ID_LENGTH` (both `64`) live in the same
+`nip01Core.core` package.
+
+---
+
+### 3.2 Everyday utilities (time, random, hashing, bech32, base64)
+
+These small helpers exist so you don't reinvent them — and several have a
+footgun the built-in avoids. **Prefer them over stdlib/hand-rolled equivalents.**
+
+**Time — `TimeUtils` (`com.vitorpamplona.quartz.utils`).** Everything is in Unix
+**seconds** (what `created_at` and filter `since`/`until` use), *not* millis.
+
+```kotlin
+import com.vitorpamplona.quartz.utils.TimeUtils
+
+val createdAt = TimeUtils.now()          // seconds — for created_at. NOT currentTimeMillis()/1000
+val since = TimeUtils.oneDayAgo()        // relative filter bounds: oneHourAgo(), fiveMinutesAgo()…
+val fresh = TimeUtils.withinTenMinutes(event.createdAt)  // NIP-42/NIP-98 freshness
+// TimeUtils.nowMillis() is the only millisecond helper — non-protocol use only.
+```
+
+**Secure random — `RandomInstance` (`utils`).** Backed by `SecureRandom`; use it
+for anything security-sensitive instead of `kotlin.random.Random`.
+
+```kotlin
+import com.vitorpamplona.quartz.utils.RandomInstance
+
+val nonce = RandomInstance.bytes(32)     // nonces, salts, keys
+val subId = RandomInstance.randomChars() // 16-char [a-zA-Z0-9] subscription id
+```
+
+**Hashing — `sha256(...)` + `EventHasher`.** `sha256` is the raw primitive; to
+compute/verify an **event id** use `EventHasher`, which canonically serializes
+`[0, pubkey, created_at, kind, tags, content]` before hashing (getting this wrong
+is what makes relays reject an event). Typed builders already do this for you.
+
+```kotlin
+import com.vitorpamplona.quartz.utils.sha256.sha256
+import com.vitorpamplona.quartz.nip01Core.crypto.EventHasher
+
+val digest = sha256(bytes)               // raw 32-byte hash
+val id = EventHasher.hashId(pubKey, createdAt, kind, tags, content)
+val valid = EventHasher.hashIdCheck(event.id, event.pubKey, event.createdAt, event.kind, event.tags, event.content)
+```
+
+**Bech32.** For `npub`/`nsec`/`note`/… prefer the NIP-19 layer (`ByteArray.toNpub()`,
+`Nip19Parser.uriToRoute(...)` — see §10). Drop to the low-level
+`Bech32` object (`nip19Bech32.bech32`) only for a custom prefix:
+
+```kotlin
+import com.vitorpamplona.quartz.nip19Bech32.bech32.Bech32
+import com.vitorpamplona.quartz.nip19Bech32.bech32.bechToBytes
+
+val addr = Bech32.encodeBytes("npub", pubKeyBytes, Bech32.Encoding.Bech32)
+val bytes = "npub1...".bechToBytes("npub")   // decode + assert the prefix
+```
+
+**Base64.** Quartz has no wrapper — use the Kotlin stdlib `kotlin.io.encoding.Base64`
+directly, and match the variant the spec wants: NIP-44/NIP-04 payloads use
+`Base64.Default` (standard, padded); url-safe contexts use `Base64.UrlSafe`
+(configure padding via `.withPadding(...)`).
+
+| Need | Call |
+|------|------|
+| Now (event `created_at`) | `TimeUtils.now()` (seconds) |
+| Relative filter bound | `TimeUtils.oneDayAgo()` / `oneHourAgo()` / … |
+| Secure random bytes | `RandomInstance.bytes(n)` |
+| Subscription id | `RandomInstance.randomChars()` |
+| Raw hash | `sha256(bytes)` |
+| Event id / verify | `EventHasher.hashId(...)` / `hashIdCheck(...)` |
+| Bech32 custom prefix | `Bech32.encodeBytes(hrp, bytes, enc)` / `s.bechToBytes(hrp)` |
+| Base64 | `kotlin.io.encoding.Base64` (`.Default` / `.UrlSafe`) |
+
 ---
 
 ## 4. Signing Events
@@ -634,7 +755,100 @@ val results = store.query<Event>(Filter(search = "bitcoin"))
 
 ---
 
-## 15. Quick Reference
+## 15. NIP-11 Relay Information Document
+
+If you're standing up a relay on Quartz's relay-server code, serve your NIP-11
+document with the **type-safe builder** — don't hand-write the JSON string.
+
+**Package:** `com.vitorpamplona.quartz.nip11RelayInfo`
+
+```kotlin
+import com.vitorpamplona.quartz.nip11RelayInfo.Nip11RelayInformation
+import com.vitorpamplona.quartz.nip11RelayInfo.relayInformation
+
+val info =
+    relayInformation {
+        name = "sot"
+        description = "NIP-50 profile search ranked by Nostr web-of-trust"
+        software = "https://github.com/vitorpamplona/sot"
+        version = "0.1"
+        supports(1, 11, 42, 50)   // ints → spec-compliant [1,11,42,50] in the JSON
+    }
+
+val json = info.toJson()          // null/empty fields are omitted
+```
+
+Serve it at the relay root, branching on the `Accept` header (Ktor example):
+
+```kotlin
+import com.vitorpamplona.quartz.nip11RelayInfo.Nip11RelayInformation
+import io.ktor.http.ContentType
+
+get("/") {
+    val accept = call.request.headers[HttpHeaders.Accept].orEmpty()
+    if (accept.contains(Nip11RelayInformation.CONTENT_TYPE)) {      // "application/nostr+json"
+        call.respondText(json, ContentType.parse(Nip11RelayInformation.CONTENT_TYPE))
+    } else {
+        call.respondText("Open a WebSocket (NIP-01) or send Accept: ${Nip11RelayInformation.CONTENT_TYPE}")
+    }
+}
+```
+
+### Nested objects, lists, and enforced limits
+
+```kotlin
+val info =
+    relayInformation {
+        name = "Paid Relay"
+        supports(1, 11, 42)
+        supportsExtensions("nip50-search")   // supported_nip_extensions
+        countries("US", "CA")                // relay_countries; also languages(...), tags(...)
+        nip50Features("profile_search")      // the `nip50` field
+
+        // limitation { } — camelCase maps to NIP-11 snake_case fields
+        limitation {
+            maxSubscriptions = 20
+            maxFilters = 10
+            authRequired = true
+        }
+
+        // fees { } — each helper is repeatable
+        fees {
+            admission(amount = 1000, unit = "msats")
+            publication(amount = 100, unit = "msats", kinds = listOf(1, 30023))
+        }
+
+        // retention(...) — call once per policy entry
+        retention(kinds = listOf(0, 3), count = 1)
+    }
+```
+
+**Keep advertised limits in sync with enforced ones.** If you build a
+`RelayLimits` for the server's policy chain, hand the *same* object to the
+builder so what you publish can never drift from what you enforce:
+
+```kotlin
+import com.vitorpamplona.quartz.nip01Core.relay.server.policies.RelayLimits
+
+val limits = RelayLimits(maxSubscriptions = 20, maxFilters = 10, maxLimit = 500, authRequired = true)
+
+val info =
+    relayInformation {
+        name = "My Relay"
+        supports(1, 11, 42, 45)
+        limitation(limits)        // == limits.toNip11Limitation()
+    }
+```
+
+To load an operator-supplied doc from disk or a string instead of building it,
+use `Nip11RelayInformation.fromJson(json)`.
+
+> `geode` (Quartz's standalone relay) builds its default document exactly this
+> way — see `geode/.../RelayInfo.kt`.
+
+---
+
+## 16. Quick Reference
 
 | Task | API | Package |
 |------|-----|---------|
@@ -644,6 +858,13 @@ val results = store.query<Event>(Filter(search = "bitcoin"))
 | Sign event | `signer.sign(template)` | `nip01Core.signers` |
 | Serialize | `event.toJson()` | `nip01Core.core` |
 | Parse | `Event.fromJson(json)` | `nip01Core.core` |
+| ByteArray → hex | `bytes.toHexKey()` | `nip01Core.core` |
+| hex → ByteArray | `hex.hexToByteArray()` / `hex.hexToByteArrayOrNull()` | `nip01Core.core` |
+| Validate hex | `Hex.isHex(s)` / `Hex.isHex64(s)` / `hex.isValid()` | `utils`, `nip01Core.core` |
+| Now (seconds) | `TimeUtils.now()` | `utils` |
+| Relative time | `TimeUtils.oneDayAgo()` / `oneHourAgo()` | `utils` |
+| Secure random | `RandomInstance.bytes(n)` / `randomChars()` | `utils` |
+| Hash / event id | `sha256(bytes)` / `EventHasher.hashId(...)` | `utils.sha256`, `nip01Core.crypto` |
 | Normalize relay URL | `RelayUrlNormalizer.normalize("wss://...")` | `nip01Core.relay.normalizer` |
 | Setup relay client | `NostrClient(BasicOkHttpWebSocket.Builder { okhttp })` | `nip01Core.relay.client` |
 | Subscribe | `client.openReqSubscription(subId, mapOf(relay to filters), listener)` | `nip01Core.relay.client` |
@@ -651,6 +872,8 @@ val results = store.query<Event>(Filter(search = "bitcoin"))
 | NIP-44 encrypt | `signer.nip44Encrypt(text, recipientPubKey)` | `nip01Core.signers` |
 | Bech32 decode | `Nip19Parser.uriToRoute("npub1...")` | `nip19Bech32` |
 | Bech32 encode | `Nip19Bech32.createNPub(pubKeyHex)` | `nip19Bech32` |
+| Build NIP-11 doc | `relayInformation { name = ...; supports(1, 11) }` | `nip11RelayInfo` |
+| Serialize NIP-11 doc | `info.toJson()` (media type `Nip11RelayInformation.CONTENT_TYPE`) | `nip11RelayInfo` |
 
 ## Common Event Kinds
 

.claude/skills/relay-client/SKILL.md

@@ -123,6 +123,12 @@ Each subscription tracks "End of Stored Events" per relay. The eose manager in `
 
 ## Related
 
+- **Headless / one-shot client ops** (CLI, geode, tests, non-compose code): don't go
+  through `Subscribable` — use the `INostrClient` extension functions in
+  `quartz/…/nip01Core/relay/client/accessories/` (`fetchAll`, `fetchFirst`,
+  `fetchAllPages`, `publishAndConfirm`, `count`, `negentropyReconcile`/`negentropySync`,
+  …). They're extensions, so they don't show up under "usages of `NostrClient`" — see
+  that package's `README.md` for the catalog before writing a raw subscribe/collect loop.
 - `nostr-expert/references/tag-patterns.md` — how tags inform what a filter needs to look for.
 - `kotlin-coroutines/references/relay-patterns.md` — relay pool internals (sibling layer beneath assemblers).
 - `feed-patterns` skill — feeds compose several Subscribables (content + metadata + reactions).

.gitattributes

@@ -0,0 +1,4 @@
+# Gzip-compressed test corpora (e.g. nostr_vitor_startup_data.json.gz): treat as
+# binary so git never applies CRLF/text normalization or textual diff/merge, which
+# would corrupt the compressed stream (important on Windows checkouts).
+*.gz binary

.github/workflows/build.yml

@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 15
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -66,7 +66,7 @@ jobs:
         shell: bash
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -122,7 +122,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -181,7 +181,7 @@ jobs:
     timeout-minutes: 60
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5

.github/workflows/bump-homebrew-formula.yml

@@ -0,0 +1,157 @@
+name: Bump Homebrew Formula (amy CLI)
+
+# Sibling of bump-homebrew.yml, but for a DIFFERENT Homebrew artifact:
+#   - bump-homebrew.yml  -> Cask   `amethyst-nostr`  (the desktop GUI app / DMG)
+#   - this workflow      -> Formula `amy`            (the headless CLI jar bundle)
+#
+# What it does today: after a stable release, download the published
+# `amy-<version>-jvm.tar.gz` bundle, compute its sha256, and open a PR that
+# syncs `cli/packaging/homebrew/amy.rb`'s url + sha256 to that release. That is
+# exactly the manual step the formula header calls out ("replace the version in
+# the url and the sha256 with the values for the actual published release
+# asset"), so keeping the in-repo reference formula accurate makes the eventual
+# homebrew-core submission a copy-paste.
+#
+# What it does NOT do yet: open a PR against Homebrew/homebrew-core. `brew
+# bump-formula-pr` can only bump a formula that already EXISTS in homebrew-core,
+# and `amy` has never been submitted there — that first submission is a manual,
+# human-reviewed new-formula PR (the one-time bootstrap). Once it lands, wire the
+# auto-bump here (symmetric to the cask action in bump-homebrew.yml) — see the
+# "TODO(bootstrap)" note at the bottom of this file.
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to sync (for manual recovery)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+  # The "Report failure" step opens a [release-ops] issue via
+  # github.rest.issues.create, which needs issues:write.
+  issues: write
+
+concurrency:
+  # Serialize per tag; do not cancel in-progress runs.
+  group: bump-homebrew-formula-${{ github.event.release.tag_name || inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  sync-formula:
+    if: github.event_name == 'workflow_dispatch' || github.event.release.prerelease == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Re-assert stable release
+        uses: ./.github/actions/assert-stable-release
+        with:
+          tag: ${{ github.event.release.tag_name || inputs.tag }}
+          is_prerelease: ${{ github.event.release.prerelease || 'false' }}
+          is_draft: ${{ github.event.release.draft || 'false' }}
+
+      - name: Resolve version
+        id: ver
+        run: |
+          set -euo pipefail
+          TAG="${{ github.event.release.tag_name || inputs.tag }}"
+          VER="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "ver=$VER" >> "$GITHUB_OUTPUT"
+
+      - name: Download jvm bundle and compute sha256
+        id: asset
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.ver.outputs.tag }}"
+          VER="${{ steps.ver.outputs.ver }}"
+          URL="https://github.com/${{ github.repository }}/releases/download/${TAG}/amy-${VER}-jvm.tar.gz"
+          echo "Fetching $URL"
+          # The `released` event can fire a hair before every matrix leg finishes
+          # uploading; retry with backoff (mirrors the repo's push/pull retry ethos).
+          ok=0
+          for i in 1 2 3 4 5; do
+            if curl -fsSL -o amy-jvm.tar.gz "$URL"; then ok=1; break; fi
+            wait=$(( 2 ** i ))
+            echo "attempt $i failed; retrying in ${wait}s"
+            sleep "$wait"
+          done
+          [[ "$ok" == 1 ]] || { echo "::error::could not download $URL"; exit 1; }
+          test -s amy-jvm.tar.gz
+          SHA=$(shasum -a 256 amy-jvm.tar.gz | awk '{print $1}')
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          echo "sha256=$SHA" >> "$GITHUB_OUTPUT"
+          echo "amy-${VER}-jvm.tar.gz -> $SHA"
+
+      - name: Update reference formula
+        run: |
+          set -euo pipefail
+          FORMULA=cli/packaging/homebrew/amy.rb
+          URL="${{ steps.asset.outputs.url }}"
+          SHA="${{ steps.asset.outputs.sha256 }}"
+          # Rewrite the two indented lines in the formula block. Anchoring on the
+          # 2-space indent avoids touching the header comment's example curl url.
+          sed -i -E "s|^(  url ).*|\1\"${URL}\"|" "$FORMULA"
+          sed -i -E "s|^(  sha256 ).*|\1\"${SHA}\"|" "$FORMULA"
+          echo "----- $FORMULA -----"
+          grep -E "^  (url|sha256) " "$FORMULA"
+
+      - name: Open or update the formula-sync PR
+        # peter-evans/create-pull-request is MIT-licensed CI-only tooling (not
+        # linked into any shipped artifact). It no-ops when there is no diff.
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          base: main
+          branch: chore/bump-amy-formula-${{ steps.ver.outputs.tag }}
+          add-paths: cli/packaging/homebrew/amy.rb
+          commit-message: 'chore: sync amy Homebrew formula to ${{ steps.ver.outputs.tag }}'
+          title: 'chore: sync amy Homebrew formula to ${{ steps.ver.outputs.tag }}'
+          body: |
+            Auto-synced `cli/packaging/homebrew/amy.rb` to the
+            `${{ steps.ver.outputs.tag }}` release:
+
+            - `url`    -> `${{ steps.asset.outputs.url }}`
+            - `sha256` -> `${{ steps.asset.outputs.sha256 }}`
+
+            Opened by `.github/workflows/bump-homebrew-formula.yml`. Merge to keep
+            the reference formula ready for the homebrew-core submission/bump.
+
+      # TODO(bootstrap): once `amy` is accepted into Homebrew/homebrew-core, add a
+      # step here that opens the homebrew-core bump PR automatically — symmetric to
+      # the cask bump in bump-homebrew.yml (a pinned macauley/action-homebrew-bump-
+      # formula, or `brew bump-formula-pr amy --url=<url> --sha256=<sha>` with a
+      # HOMEBREW_TOKEN). It is intentionally omitted until then because
+      # bump-formula-pr errors on a formula that is not yet in the tap.
+
+      - name: Report failure
+        if: failure()
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const tag = context.payload.release?.tag_name || context.payload.inputs?.tag || 'unknown';
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `[release-ops] bump-homebrew-formula failed for ${tag}`,
+              body: [
+                `amy Homebrew formula sync failed for release \`${tag}\`.`,
+                ``,
+                `- Run: ${runUrl}`,
+                `- Channel: Homebrew Formula (\`amy\` CLI)`,
+                ``,
+                `Recovery options:`,
+                `1. Re-run the workflow once the underlying issue is fixed`,
+                `2. Manually update \`cli/packaging/homebrew/amy.rb\` (url + sha256) from the release asset`,
+                `3. Check the release actually published \`amy-${tag.replace(/^v/, '')}-jvm.tar.gz\``
+              ].join('\n'),
+              labels: ['release-ops', 'bug']
+            });

.github/workflows/bump-homebrew.yml

@@ -15,6 +15,10 @@ on:
 
 permissions:
   contents: read
+  # The "Report failure" step below opens a [release-ops] issue via
+  # github.rest.issues.create; that needs issues:write. Without it the failure
+  # reporter itself 403s and no alert is ever filed.
+  issues: write
 
 concurrency:
   # Serialize bumps per tag; do not cancel in-progress bumps.
@@ -28,7 +32,7 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Re-assert stable release
         uses: ./.github/actions/assert-stable-release

.github/workflows/bump-winget.yml

@@ -12,6 +12,10 @@ on:
 
 permissions:
   contents: read
+  # The "Report failure" step below opens a [release-ops] issue via
+  # github.rest.issues.create; that needs issues:write. Without it the failure
+  # reporter itself 403s and no alert is ever filed.
+  issues: write
 
 concurrency:
   group: bump-winget-${{ github.event.release.tag_name || inputs.tag }}
@@ -24,7 +28,7 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Re-assert stable release
         uses: ./.github/actions/assert-stable-release

.github/workflows/create-release.yml

@@ -44,13 +44,13 @@ jobs:
           - { os: ubuntu-latest,  arch: x64,   family: linux,          tasks: "packageReleaseDeb packageReleaseRpm" }
           - { os: ubuntu-latest,  arch: x64,   family: linux-portable, tasks: "createReleaseAppImage createReleaseDistributable" }
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 45
+    timeout-minutes: 60  # linux-portable leg also downloads the freedesktop runtime + builds the Flatpak bundle
     defaults:
       run:
         shell: bash
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -101,6 +101,25 @@ jobs:
           fi
           chmod +x desktopApp/packaging/appimage/appimagetool-x86_64.AppImage
 
+      # Flatpak tooling + the freedesktop runtime/sdk the manifest pins
+      # (runtime-version is greped from the manifest so this never drifts).
+      # Retried: the runtime download from Flathub is ~1 GB and flatpak
+      # install resumes cleanly on re-run.
+      - name: Install Flatpak tooling + runtimes (linux-portable only)
+        if: matrix.family == 'linux-portable'
+        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60  # v4.0.0
+        with:
+          max_attempts: 3
+          timeout_minutes: 15
+          command: |
+            set -euo pipefail
+            sudo apt-get update && sudo apt-get install -y flatpak flatpak-builder
+            flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+            FDO_VER=$(grep -E "^runtime-version:" desktopApp/packaging/flatpak/com.vitorpamplona.amethyst.Desktop.yml | cut -d"'" -f2)
+            flatpak install --user --noninteractive flathub \
+              "org.freedesktop.Platform//${FDO_VER}" \
+              "org.freedesktop.Sdk//${FDO_VER}"
+
       # macOS only: import the Developer ID Application cert into a throwaway
       # keychain so jpackage's codesign pass can find it. Soft — if the
       # MAC_CERTIFICATE_P12 secret isn't set (forks, or before Apple creds are
@@ -161,6 +180,36 @@ jobs:
             ( cd "$APP" && tar czf "../../../../portable/amethyst-desktop-${VER}-linux-x64.tar.gz" Amethyst/ )
           fi
 
+      # Flatpak bundle: wraps the same createReleaseDistributable tree the
+      # AppImage uses. The manifest (desktopApp/packaging/flatpak/) copies the
+      # prebuilt jpackage tree into /app — no Gradle runs inside the sandbox.
+      # build-bundle emits a single-file .flatpak whose baked-in runtime-repo
+      # lets the user's flatpak fetch the freedesktop runtime from Flathub on
+      # install. --disable-rofiles-fuse: GH runners lack a usable rofiles-fuse.
+      - name: Build Flatpak bundle (linux-portable only)
+        if: matrix.family == 'linux-portable'
+        run: |
+          set -euo pipefail
+          VER="${{ steps.ver.outputs.version }}"
+          PKG="desktopApp/packaging/flatpak"
+          APP_ID="com.vitorpamplona.amethyst.Desktop"
+          OUT="desktopApp/build/flatpak"
+          # Inject the AppStream <release> entry for this build (the checked-in
+          # metainfo deliberately carries none — CI is the source of truth).
+          sed -i "s|<releases>|<releases>\n    <release version=\"${VER}\" date=\"$(date -u +%F)\" />|" \
+            "${PKG}/${APP_ID}.metainfo.xml"
+          mkdir -p "$OUT"
+          flatpak-builder --user --force-clean --disable-rofiles-fuse \
+            --state-dir="${OUT}/.flatpak-builder" \
+            --repo="${OUT}/repo" \
+            "${OUT}/build-dir" \
+            "${PKG}/${APP_ID}.yml"
+          flatpak build-bundle "${OUT}/repo" \
+            "${OUT}/Amethyst-${VER}-x86_64.flatpak" \
+            "$APP_ID" \
+            --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo
+          ls -la "$OUT"
+
       - name: Collect + rename assets
         run: |
           set -euo pipefail
@@ -200,7 +249,7 @@ jobs:
 
       - name: Upload to GH Release (skip on dry-run)
         if: github.event_name != 'workflow_dispatch' || github.event.inputs.dry_run != 'true'
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b  # v3.0.1
         with:
           files: dist/*
           tag_name: ${{ steps.ver.outputs.tag }}
@@ -249,7 +298,7 @@ jobs:
         shell: bash
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -451,7 +500,7 @@ jobs:
 
       - name: Upload to GH Release (skip on dry-run)
         if: github.event_name != 'workflow_dispatch' || github.event.inputs.dry_run != 'true'
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b  # v3.0.1
         with:
           files: dist/*
           tag_name: ${{ steps.ver.outputs.tag }}
@@ -479,7 +528,7 @@ jobs:
     timeout-minutes: 60
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -488,7 +537,7 @@ jobs:
           java-version: 21
 
       - name: Cache gradle
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: |
             ~/.gradle/caches
@@ -572,6 +621,48 @@ jobs:
              "dist/amethyst-fdroid-${TAG}.aab"
           ls -la dist
 
+      # Accrescent does not accept AABs or monolithic APKs — it requires a signed
+      # APK set (.apks) of split APKs generated by bundletool from the AAB. We build
+      # it from the F-Droid flavor (no proprietary Google deps) and sign the splits
+      # with the same release keystore used above. Upload is still manual: drop this
+      # .apks into https://console.accrescent.app (no publish API/CLI exists yet).
+      - name: Build Accrescent APK set (F-Droid)
+        env:
+          SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
+          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+          KEY_STORE_PASSWORD: ${{ secrets.KEY_STORE_PASSWORD }}
+          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          BUNDLETOOL_VERSION="1.18.3"  # must be >= 1.11.4 per Accrescent requirements
+          curl -fsSL -o bundletool.jar \
+            "https://github.com/google/bundletool/releases/download/${BUNDLETOOL_VERSION}/bundletool-all-${BUNDLETOOL_VERSION}.jar"
+
+          # Same base64 keystore secret consumed by the r0adkll signing steps above.
+          echo "$SIGNING_KEY" | base64 -d > release.keystore
+
+          # --mode=default emits the split-APK set Accrescent wants (NOT --mode=universal,
+          # which produces a monolithic APK that Accrescent rejects).
+          java -jar bundletool.jar build-apks \
+            --bundle="dist/amethyst-fdroid-${TAG}.aab" \
+            --output="dist/amethyst-fdroid-${TAG}.apks" \
+            --ks=release.keystore \
+            --ks-key-alias="$KEY_ALIAS" \
+            --ks-pass="pass:$KEY_STORE_PASSWORD" \
+            --key-pass="pass:$KEY_PASSWORD" \
+            --mode=default
+
+          rm -f release.keystore bundletool.jar
+
+          # Accrescent's automated check rejects an APK set larger than 128 MiB.
+          SIZE_BYTES=$(stat -c%s "dist/amethyst-fdroid-${TAG}.apks")
+          echo "Accrescent APK set size: $((SIZE_BYTES / 1024 / 1024)) MiB"
+          if [ "$SIZE_BYTES" -gt $((128 * 1024 * 1024)) ]; then
+            echo "::warning::amethyst-fdroid-${TAG}.apks exceeds Accrescent's 128 MiB limit; the console will reject this upload."
+          fi
+          ls -la dist
+
       - name: Classify release
         id: classify
         run: |
@@ -584,7 +675,7 @@ jobs:
           fi
 
       - name: Upload Android assets to GH Release
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b  # v3.0.1
         with:
           files: dist/*
           tag_name: ${{ github.ref_name }}

.github/workflows/crowdin.yml

@@ -10,12 +10,21 @@ permissions:
   pull-requests: write
 
 jobs:
+  # Single job so the Crowdin translation sync and the translator-placeholder seed
+  # land in ONE pull request instead of two. The Crowdin action only downloads into
+  # the working tree (push_translations/create_pull_request disabled); the seed
+  # script then edits translators.json; finally one create-pull-request step opens a
+  # single PR with both sets of changes (and no-ops when there is no diff).
   synchronize-with-crowdin:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
+        with:
+          # Need tags so scripts/translators.sh can resolve the last v* release tag
+          # for the "since last tag" window.
+          fetch-depth: 0
 
       - name: crowdin action
         uses: crowdin/github-action@v2
@@ -23,50 +32,52 @@ jobs:
           upload_sources: true
           upload_translations: true
           download_translations: true
-          localization_branch_name: l10n_crowdin_translations
-          create_pull_request: true
-          pull_request_title: 'New Crowdin Translations'
-          pull_request_body: 'New Crowdin translations by [Crowdin GH Action](https://github.com/crowdin/github-action)'
-          pull_request_base_branch_name: 'main'
+          # Let the downloaded translations stay in the working tree; the single
+          # create-pull-request step below opens the combined PR.
+          push_translations: false
+          create_pull_request: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
           CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
 
-  # Keep docs/changelog/translators.json seeded with everyone who has translated
-  # recently, so the per-release `## Translations` credits (scripts/translators.sh)
-  # can resolve them to npubs. Runs independently of the sync job above and only
-  # opens/updates a PR when a genuinely new contributor appears.
-  seed-translators:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-        with:
-          # Need tags so the script can resolve the last v* release tag for the
-          # "since last tag" window.
-          fetch-depth: 0
+      # crowdin/github-action runs in a Docker container as root, so any file or
+      # directory it downloads (especially a brand-new locale folder like
+      # values-en-rGB/) ends up owned by root. The unprivileged runner user in
+      # the create-pull-request step below then can't unlink those files, which
+      # aborts its branch checkout with "unable to unlink ... Permission denied".
+      # Reclaim ownership of the whole working tree before touching git.
+      - name: Fix ownership after Crowdin Docker action
+        run: sudo chown -R "$(id -u):$(id -g)" "$GITHUB_WORKSPACE"
 
+      # Keep docs/changelog/translators.json seeded with everyone who has translated
+      # recently, so the per-release `## Translations` credits (scripts/translators.sh)
+      # can resolve them to npubs. Only adds rows when a genuinely new contributor
+      # appears.
       - name: Seed translator placeholders from Crowdin
         run: bash scripts/translators.sh --seed
         env:
           CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
           CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
 
-      - name: Open or update the seed PR
+      - name: Open or update the combined Crowdin PR
         # peter-evans/create-pull-request is MIT-licensed CI-only tooling (not
         # linked into any shipped artifact). It no-ops when there is no diff.
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           base: main
-          branch: chore/seed-translators
-          add-paths: docs/changelog/translators.json
-          commit-message: 'chore: seed translator npub placeholders from Crowdin'
-          title: 'Seed translator npub placeholders'
+          branch: l10n_crowdin_translations
+          add-paths: |
+            amethyst/src/main/res/**/strings.xml
+            commons/src/commonMain/composeResources/**/strings.xml
+            docs/changelog/translators.json
+          commit-message: 'chore: sync Crowdin translations and seed translator npub placeholders'
+          title: 'New Crowdin Translations'
           body: |
-            New Crowdin contributors were added to `docs/changelog/translators.json`
+            New Crowdin translations by [Crowdin GH Action](https://github.com/crowdin/github-action).
+
+            Any new Crowdin contributors were added to `docs/changelog/translators.json`
             with blank npubs. Fill in the npubs you have so the next release's
             `## Translations` credits generate automatically via
-            `scripts/translators.sh --from <prev-tag> --to <this-tag>`.
+            `scripts/translators.sh --from <prev-tag> --to <this-tag>`.

.github/workflows/smoke-test-desktop.yml

@@ -25,7 +25,7 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5
@@ -55,7 +55,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up JDK 21
         uses: actions/setup-java@v5

.gitignore

@@ -180,6 +180,11 @@ desktopApp/src/jvmMain/appResources/*/ffmpeg/*
 desktopApp/packaging/appimage/appimagetool-x86_64.AppImage
 desktopApp/packaging/appimage/squashfs-root/
 
+# flatpak-builder state/cache from local builds (CI uses --state-dir under desktopApp/build/)
+.flatpak-builder/
+desktopApp/packaging/flatpak/**/build-dir/
+desktopApp/packaging/flatpak/**/repo/
+
 # Git worktrees
 .worktrees/
 .claude/worktrees/

BUILDING.md

@@ -37,7 +37,9 @@ Platform-specific:
 - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
 - **Windows**: WiX Toolset 3.x on PATH (for MSI). `winget install WiXToolset.WiXToolset`
 - **Linux (all)**: nothing extra for `.deb`; `rpm` + `fakeroot` for `.rpm`;
-  `appimagetool` + `desktop-file-utils` for AppImage
+  `appimagetool` + `desktop-file-utils` for AppImage; `flatpak` +
+  `flatpak-builder` for the Flatpak bundle (see
+  [`desktopApp/packaging/flatpak/README.md`](desktopApp/packaging/flatpak/README.md))
 
 Install Linux RPM tooling:
 
@@ -109,6 +111,7 @@ are **not** required to build Amethyst from the committed sources.
 | Linux `.deb` | `./gradlew :desktopApp:packageReleaseDeb` | `desktopApp/build/compose/binaries/main-release/deb/amethyst_*.deb` |
 | Linux `.rpm` | `./gradlew :desktopApp:packageReleaseRpm` | `desktopApp/build/compose/binaries/main-release/rpm/amethyst-*.rpm` |
 | Linux AppImage | `./gradlew :desktopApp:createReleaseAppImage` | `desktopApp/build/appimage/Amethyst-*-x86_64.AppImage` |
+| Linux Flatpak | `flatpak-builder` over `createReleaseDistributable` output — see [`desktopApp/packaging/flatpak/README.md`](desktopApp/packaging/flatpak/README.md) | `desktopApp/build/flatpak/Amethyst-*-x86_64.flatpak` (CI) |
 | Windows `.zip` portable | See below (inline `7z`) | — |
 | Linux `.tar.gz` portable | See below (inline `tar`) | — |
 
@@ -148,7 +151,7 @@ Where:
 | `<version>` | Tag stripped of leading `vX.YY.ZZ`                    |
 | `<family>` | `macos`, `windows`, `linux`                           |
 | `<arch>` | `x64`, `arm64`                                        |
-| `<ext>` | `dmg`, `msi`, `zip`, `deb`, `rpm`, `AppImage`, `tar.gz` |
+| `<ext>` | `dmg`, `msi`, `zip`, `deb`, `rpm`, `AppImage`, `flatpak`, `tar.gz` |
 
 Single source of truth: [`scripts/asset-name.sh`](scripts/asset-name.sh).
 Package manager manifests (Homebrew cask, Winget) depend on this exact scheme —
@@ -160,6 +163,136 @@ Examples:
 - `amethyst-desktop-1.12.1-macos-arm64.dmg`
 - `amethyst-desktop-1.12.1-windows-x64.msi`
 - `amethyst-desktop-1.12.1-linux-x64.AppImage`
+- `amethyst-desktop-1.12.1-linux-x64.flatpak`
+
+---
+
+## Reproducible Android builds
+
+The release APKs are **bit-for-bit reproducible**: anyone can rebuild the exact
+bytes we ship (minus the signature) from the tagged source and confirm the
+artifact on F-Droid / Zapstore / GitHub was built from this code and nothing
+else. What makes that hold:
+
+- **Pinned toolchain.** AGP, Kotlin, R8, and the Compose compiler are pinned in
+  `gradle/libs.versions.toml`; the build targets **JDK 21**. R8 is deterministic
+  for a fixed version + inputs, so the minified output is stable. Build with the
+  same JDK 21 you see in `BUILDING.md` / CI.
+- **No build-time clock.** Nothing injects `System.currentTimeMillis()` /
+  build dates into `BuildConfig` (a Spotless rule bans the call in `quartz` and
+  `commons`), and AGP normalizes ZIP entry timestamps, so two builds an hour
+  apart are identical.
+- **Deterministic version name.** `generateVersionName` only appends a branch
+  suffix off feature branches; a release tag builds in detached-`HEAD` (or from a
+  source tarball with no `.git`) resolve to the bare `app` version.
+- **No dependency-metadata blob.** `dependenciesInfo { includeInApk = false;
+  includeInBundle = false }` in `amethyst/build.gradle.kts` stops AGP from
+  embedding the Google-encrypted dependency protobuf in the signing block — that
+  ciphertext is non-deterministic.
+- **Reproducible native library.** The bundled Tor (Arti) `.so` is the one
+  binary we compile ourselves; it is built reproducibly from source (pinned Rust
+  toolchain, locked deps, canonical build path). See
+  [`tools/arti-build/README.md`](tools/arti-build/README.md) → "Reproducible
+  builds". All other native libs (`secp256k1`, `webrtc`) are version-pinned Maven
+  prebuilts and so are byte-identical by download.
+
+### Verify a release APK reproduces
+
+```bash
+# 1. Check out the exact released tag and build the same variant unsigned.
+git checkout v1.12.1
+./gradlew clean :amethyst:assembleFdroidRelease
+
+# 2. Diff your unsigned build against the published APK, ignoring only the
+#    signature (META-INF/*). apksigner + a zip-aware diff is the simplest check;
+#    diffoscope gives a human-readable breakdown of any remaining delta.
+diffoscope \
+  amethyst/build/outputs/apk/fdroid/release/amethyst-fdroid-arm64-v8a-release-unsigned.apk \
+  amethyst-fdroid-arm64-v8a-1.12.1.apk
+```
+
+A clean run shows differences confined to `META-INF/` (the signing files). Any
+diff in `classes*.dex`, `resources.arsc`, or native libs means something in the
+toolchain drifted — file it before publishing.
+
+---
+
+## Local SonarQube analysis (opt-in)
+
+The build supports running a [SonarQube](https://www.sonarsource.com/products/sonarqube/)
+analysis against a locally hosted server. It is **off by default**: unless you
+opt in, the scanner plugin is neither downloaded nor applied and the build is
+unaffected.
+
+### 1. Install and start a local SonarQube server
+
+Either run the official Docker image:
+
+```bash
+docker run -d --name sonarqube -p 9000:9000 sonarqube:community
+```
+
+or download the [Community Build zip](https://www.sonarsource.com/products/sonarqube/downloads/),
+unzip it, and start it (requires a JDK 17+ on `PATH`):
+
+```bash
+cd sonarqube-<version>
+bin/macosx-universal-64/sonar.sh console   # pick the folder matching your OS
+```
+
+Once it reports up, open <http://localhost:9000> (first login `admin`/`admin`,
+you'll be asked to change it), create a **local project** named `Amethyst` with
+project key `Amethyst`, and generate a **project analysis token** for it
+(*Project Settings → Analysis Method → With Gradle*, or
+*My Account → Security → Generate token*). The token looks like `sqp_…`.
+
+### 2. Point the build at your server
+
+Add the server and token to `local.properties` (gitignored — the token never
+lands in the repo):
+
+```properties
+sonar.host.url=http://localhost:9000
+sonar.token=sqp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 3. Run the analysis
+
+```bash
+./gradlew sonar
+```
+
+When it finishes, browse the results at
+<http://localhost:9000/dashboard?id=Amethyst>.
+
+### 4. Optional: include Android Lint results
+
+The scanner auto-imports each Android module's lint report and shows the
+findings as external issues alongside Sonar's own. It only *imports* — it never
+runs lint itself — so without the reports on disk the analysis warns
+`Unable to import Android Lint report file(s)`. Generate them first, then run
+the scan as a **separate** invocation (chaining lint and `sonar` in one Gradle
+call does not guarantee lint finishes first):
+
+```bash
+./gradlew :amethyst:lintPlayDebug :benchmark:lintBenchmark :nappletHost:lintDebug
+./gradlew sonar
+```
+
+The reports persist under each module's `build/reports/`, so re-run lint only
+when you want fresh lint data in the next scan.
+
+Every `sonar.*` entry in `local.properties` is forwarded to the scanner, so any
+[analysis parameter](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/analysis-parameters/)
+can be set there. `sonar.projectKey` / `sonar.projectName` default to the root
+project name (`Amethyst`).
+
+Even when opted in, the scanner plugin only loads on invocations that actually
+request the `sonar` task — ordinary builds and IDE syncs are unaffected (which
+is also why `./gradlew tasks` doesn't list it).
+
+Note: the SonarQube Gradle scanner plugin is LGPL-3.0. It is a build-time-only
+tool fetched after explicit opt-in; it is never linked into shipped artifacts.
 
 ---
 
@@ -496,12 +629,18 @@ State is shared across install channels (DMG, Homebrew, MSI, Winget, .deb,
 expose downgrade migration risks — **prefer a single install channel per
 machine**.
 
+**Exception: Flatpak.** The sandbox redirects XDG dirs into
+`~/.var/app/com.vitorpamplona.amethyst.Desktop/`, so a Flatpak install keeps
+its own separate state and does not see (or risk downgrading) state written
+by any other channel.
+
 | OS | App location | State directories |
 |---|---|---|
 | macOS | `/Applications/Amethyst.app` | `~/Library/Application Support/Amethyst`<br>`~/Library/Preferences/com.vitorpamplona.amethyst.desktop.plist`<br>`~/Library/Caches/Amethyst` |
 | Windows | `%LOCALAPPDATA%\Amethyst` or `C:\Program Files\Amethyst` | `%APPDATA%\Amethyst`<br>`%LOCALAPPDATA%\Amethyst` |
 | Linux (deb/rpm) | `/opt/amethyst` | `~/.config/amethyst`<br>`~/.local/share/amethyst`<br>`~/.cache/amethyst` |
 | Linux (AppImage/tar.gz) | user-chosen | Same as above |
+| Linux (Flatpak) | `/var/lib/flatpak` or `~/.local/share/flatpak` | `~/.var/app/com.vitorpamplona.amethyst.Desktop/` |
 
 Uninstall:
 
@@ -510,6 +649,8 @@ Uninstall:
 - .deb: `sudo apt remove amethyst`
 - .rpm: `sudo dnf remove amethyst`
 - AppImage / tar.gz: delete the file / extracted directory
+- Flatpak: `flatpak uninstall com.vitorpamplona.amethyst.Desktop` (add
+  `--delete-data` to also remove `~/.var/app/…`)
 - macOS `.dmg`: drag from `/Applications` to Trash, then delete state dirs manually
 
 ---

PLANS.md

@@ -0,0 +1,83 @@
+# Amethyst plans index
+
+_Cross-module roll-up of every `plans/` folder. Surveyed 2026-06-30._
+
+Plans in this repo are **decentralized**: each module keeps its own design docs
+in `<module>/plans/YYYY-MM-DD-<slug>.md` (see `.claude/CLAUDE.md` →
+"Plans per module"). There is no single plans directory — **this file is the
+master index** that stitches the per-folder indexes together.
+
+Each plan carries a `Status:` header (shipped | in-progress | queued |
+abandoned) backed by codebase evidence. **Shipped** plans are moved into each
+folder's `archive/`; live work stays at the top level. For the full per-folder
+listing (including archived plans), open that folder's `README.md`.
+
+> `docs/plans/` is the **frozen** legacy global folder — it is indexed here for
+> completeness, but new plans must go in the owning module's `plans/` folder.
+
+## Totals
+
+**142 plans** across 10 folders:
+
+| Status | Count |
+| ------ | ----: |
+| shipped (archived) | 122 |
+| in-progress | 9 |
+| queued | 8 |
+| abandoned | 3 |
+
+## By module
+
+| Module | Plans | Shipped | In-prog | Queued | Aband. | Index |
+| ------ | ----: | ------: | ------: | -----: | -----: | ----- |
+| amethyst | 21 | 19 | 1 | 1 | 0 | [amethyst/plans](amethyst/plans/README.md) |
+| nestsClient | 26 | 23 | 1 | 2 | 0 | [nestsClient/plans](nestsClient/plans/README.md) |
+| desktopApp | 13 | 10 | 2 | 1 | 0 | [desktopApp/plans](desktopApp/plans/README.md) |
+| quartz | 10 | 7 | 0 | 3 | 0 | [quartz/plans](quartz/plans/README.md) |
+| commons | 6 | 2 | 2 | 2 | 0 | [commons/plans](commons/plans/README.md) |
+| cli | 6 | 5 | 1 | 0 | 0 | [cli/plans](cli/plans/README.md) |
+| quic | 4 | 3 | 0 | 0 | 1 | [quic/plans](quic/plans/README.md) |
+| quic/interop | 1 | 1 | 0 | 0 | 0 | [quic/interop/plans](quic/interop/plans/README.md) |
+| geode | 5 | 4 | 0 | 0 | 0 | [geode/plans](geode/plans/README.md) |
+| docs (frozen) | 52 | 48 | 2 | 0 | 2 | [docs/plans](docs/plans/README.md) |
+
+## Live work (not shipped)
+
+Everything still open, across all modules. Shipped plans are omitted here — find
+them under each folder's `archive/` via the per-module index above.
+
+### In progress (9)
+
+| Module | Plan | Summary |
+| ------ | ---- | ------- |
+| amethyst | [ios-support](amethyst/plans/2026-05-24-ios-support.md) | KMP-to-iOS port; quartz/commons iOS targets configured (Phase 1) but no `iosApp` module yet. |
+| commons | [custom-feeds-plan](commons/plans/2026-05-04-custom-feeds-plan.md) | Custom feeds; model + builder + kind 31890 + desktop UI shipped, but relay-filter layer, DVM marketplace, kind 10090 sync, list resolution pending. |
+| commons | [nest-subscription-manager-extraction](commons/plans/2026-05-06-nest-subscription-manager-extraction.md) | Split per-speaker subscription state machine out of `NestViewModel`; only the `ActiveSubscription` stepping-stone extracted. |
+| desktopApp | [wallet-zapping-test-coverage](desktopApp/plans/2026-05-12-feat-desktop-wallet-zapping-test-coverage-plan.md) | NWC handler + RPC round-trip tests shipped; wallet-column-state and zap-dialog-logic tests still missing. |
+| desktopApp | [napplet-desktop-host](desktopApp/plans/2026-06-21-napplet-desktop-host.md) | Desktop NIP-5A/5D host; shared core extractions done, desktop engine/scheme-handler/transport/UI edge not built. |
+| cli | [cashu-cli](cli/plans/2026-05-28-cashu-cli.md) | NIP-60/61/87 Cashu wallet verbs in amy; full command surface ships, production-mint interop harness pending. |
+| nestsClient | [t16-closure-roadmap](nestsClient/plans/2026-05-07-t16-closure-roadmap.md) | Priorities 1 & 2 closed and suite passes, but CI gating deferred and framesPerGroup rerun + two upstream items open. |
+| docs | [viewport-aware-metadata-loading](docs/plans/2026-04-29-perf-viewport-aware-metadata-loading-plan.md) | Base preloader/rate-limiter infra exists but the LazyListState/snapshotFlow viewport selection isn't clearly wired. |
+| docs | [macos-bunker-relogin](docs/plans/2026-06-18-fix-desktop-macos-bunker-relogin-plan.md) | PR 1 defense-in-depth shipped, but the cold-boot root cause is still open/unidentified. |
+
+### Queued (8)
+
+| Module | Plan | Summary |
+| ------ | ---- | ------- |
+| amethyst | [napplet-inter-applet](amethyst/plans/2026-06-20-napplet-inter-applet.md) | NAP-INC / NAP-INTENT inter-applet messaging; prerequisites (multi-applet hosting, archetype registry, `MESSAGING` capability) not built. |
+| quartz | [local-headers-explorer](quartz/plans/2026-05-08-local-headers-explorer.md) | Headers-only Bitcoin P2P client to verify NIP-03 OTS attestations without a trusted block explorer. |
+| quartz | [giftwrap-deletion-requests](quartz/plans/2026-06-12-giftwrap-deletion-requests.md) | Let a recipient-authored kind-5 delete/block a gift wrap (kind 1059) addressed to them. |
+| quartz | [incremental-negentropy-storage](quartz/plans/2026-07-03-incremental-negentropy-storage.md) | Always-current (created_at, id) index so cold NEG-OPENs stop paying a full scan + seal. |
+| commons | [event-renderer](commons/plans/2026-04-21-event-renderer.md) | Cross-platform UI-agnostic `RenderedEvent` subsystem shared by Amy, Desktop, Android; not started. |
+| commons | [amethyst-to-commons-migration](commons/plans/2026-05-30-amethyst-to-commons-migration.md) | Roadmap to move shared `amethyst` Android code into `commons`; keystone `Account`/`LocalCache` extraction not begun. |
+| desktopApp | [embedded-wallet-phase2-research](desktopApp/plans/2026-05-21-embedded-wallet-phase2-research.md) | Research for an embedded self-custodial Lightning wallet (Breez/ldk-node/lightning-kmp); parked, no code. |
+| nestsClient | [cross-stack-interop-ci-gating](nestsClient/plans/2026-05-07-cross-stack-interop-ci-gating.md) | CI gating for the cross-stack interop suite; infra built then removed over wallclock cost, kept as a ready revisit target. |
+| nestsClient | [framespergroup-production-rerun](nestsClient/plans/2026-05-07-framespergroup-production-rerun.md) | Re-run the two-phone field tests to settle the framesPerGroup test-pin (5) vs default (50); needs prod-rig access. |
+
+### Abandoned (3)
+
+| Module | Plan | Summary |
+| ------ | ---- | ------- |
+| quic | [congestion-control](quic/plans/2026-05-05-congestion-control.md) | NewReno congestion control parked indefinitely; the real concern was solved by the smaller `SendBuffer.bestEffort` fix instead. |
+| docs | [desktop-relay-config-single-source](docs/plans/2026-04-23-feat-desktop-relay-config-single-source-plan.md) | Single `DesktopRelayConfig` class never built; relay state landed as `DesktopRelayCategories`/`LocalRelayCategories` instead. |
+| docs | [macos-vlc-bundled-discovery](docs/plans/2026-05-18-fix-macos-vlc-bundled-discovery-plan.md) | macOS bundled-VLC `setenv` discovery fix; moot after VLC/VLCJ was removed entirely in the kdroidFilter migration. |

PULL_NOTIFICATION.md

@@ -158,13 +158,17 @@ Google Play Services infrastructure.
 
 ### Layer 4: AlarmManager Watchdog (5 minutes)
 
-**What:** `ServiceWatchdogManager` fires an `ELAPSED_REALTIME_WAKEUP` alarm every 5
+**What:** `ServiceWatchdogManager` fires an `ELAPSED_REALTIME` alarm every 5
 minutes. The receiver checks if the service should be running and restarts it.
 
 **Why needed:** This is the "belt and suspenders" layer. If all of the above layers fail
 (sticky restart blocked, alarm from `onTaskRemoved` didn't fire, broadcast wasn't
-delivered), the watchdog will catch it within 5 minutes. Uses `ELAPSED_REALTIME_WAKEUP` to
-wake the device from sleep, ensuring the check happens even in Doze.
+delivered), the watchdog will catch it within 5 minutes of the device being awake.
+The alarm deliberately does NOT use the `_WAKEUP` variant: pulling the CPU out of
+sleep every 5 minutes is a battery cost with no payoff, because a service restarted
+on a sleeping device can't do useful network work until the device wakes anyway.
+While the device sleeps, Layer 5 (WorkManager) and Layer 8 (FCM/UnifiedPush) cover
+delivery; the moment the device wakes, the pending watchdog alarm fires.
 
 ### Layer 5: WorkManager Periodic Catch-Up (15 minutes)
 

README.md

@@ -17,7 +17,7 @@ Join the social network you control.
 [![Maven Central](https://img.shields.io/maven-central/v/com.vitorpamplona.quartz/quartz?label=Quartz%20%28Maven%20Central%29&labelColor=27303D&color=0877d2)](https://central.sonatype.com/artifact/com.vitorpamplona.quartz/quartz)
 [![JitPack snapshots](https://img.shields.io/badge/Quartz%20snapshots-JitPack-27303D?labelColor=27303D&color=0877d2)](https://jitpack.io/#vitorpamplona/amethyst)
 [![CI](https://img.shields.io/github/actions/workflow/status/vitorpamplona/amethyst/build.yml?labelColor=27303D)](https://github.com/vitorpamplona/amethyst/actions/workflows/build.yml)
-[![License: Apache-2.0](https://img.shields.io/github/license/vitorpamplona/amethyst?labelColor=27303D&color=0877d2)](/LICENSE)
+[![License: MIT](https://img.shields.io/github/license/vitorpamplona/amethyst?labelColor=27303D&color=0877d2)](/LICENSE)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/vitorpamplona/amethyst)
 
 ## Download and Install
@@ -56,6 +56,37 @@ _Coming soon (separate PR): Scoop (Windows), AUR (Arch Linux)._
 
 </div>
 
+## Verifying the APK signature
+
+If you sideload Amethyst (Obtainium, GitHub Releases, Zap Store), verify that your
+APK is signed by the official release key before installing. All official Amethyst
+APKs — both the `googleplay` and `fdroid` flavors — are signed with the same
+certificate, whose SHA-256 fingerprint is:
+
+```
+C2:D0:AA:86:BC:B6:B6:20:90:56:1A:41:BB:E3:36:E9:8B:78:C2:D0:21:0A:49:8D:C8:85:F2:8E:13:48:CF:17
+```
+
+To check a downloaded APK yourself, run (`apksigner` ships with the Android SDK
+build-tools):
+
+```bash
+apksigner verify --print-certs amethyst-*.apk
+```
+
+and confirm the reported `Signer #1 certificate SHA-256 digest` is
+`c2d0aa86bcb6b62090561a41bbe336e98b78c2d0210a498dc885f28e1348cf17`.
+Without the Android SDK, `keytool -printcert -jarfile amethyst-*.apk` (bundled
+with any JDK) prints the same SHA-256 fingerprint.
+
+With [AppVerifier](https://github.com/soupslurpr/appverifier), paste or share the
+APK and compare against:
+
+```
+com.vitorpamplona.amethyst
+C2:D0:AA:86:BC:B6:B6:20:90:56:1A:41:BB:E3:36:E9:8B:78:C2:D0:21:0A:49:8D:C8:85:F2:8E:13:48:CF:17
+```
+
 ## Supported Features
 
 <img align="right" src="./docs/screenshots/home.png" data-canonical-src="./docs/screenshots/home.png" width="350px">

SKILL.md

@@ -24,7 +24,9 @@ Build customized Amethyst Nostr clients for Android. Fork, rebrand, customize, a
 
 2. **Android SDK**
    - Command-line tools from https://developer.android.com/studio#command-line-tools-only
-   - Required components: build-tools, platform-tools, platforms;android-35
+   - Required components: build-tools, platform-tools, platforms;android-37
+   - The exact SDK level is `android-compileSdk` in `gradle/libs.versions.toml` —
+     check there if this number has drifted.
 
 3. **Git** for cloning the repository
 
@@ -66,48 +68,54 @@ keyPassword=your-password
 
 ### 3. Configure Signing
 
-Add to `amethyst/build.gradle` inside the `android {}` block:
+Add to `amethyst/build.gradle.kts` inside the `android {}` block:
 
-```gradle
-def keystorePropertiesFile = rootProject.file("keystore.properties")
-def keystoreProperties = new Properties()
+```kotlin
+val keystorePropertiesFile = rootProject.file("keystore.properties")
+val keystoreProperties = Properties()
 if (keystorePropertiesFile.exists()) {
-    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
+    keystorePropertiesFile.inputStream().use { keystoreProperties.load(it) }
 }
 
 signingConfigs {
-    release {
+    create("release") {
         if (keystorePropertiesFile.exists()) {
-            storeFile rootProject.file(keystoreProperties['storeFile'])
-            storePassword keystoreProperties['storePassword']
-            keyAlias keystoreProperties['keyAlias']
-            keyPassword keystoreProperties['keyPassword']
+            storeFile = rootProject.file(keystoreProperties["storeFile"] as String)
+            storePassword = keystoreProperties["storePassword"] as String
+            keyAlias = keystoreProperties["keyAlias"] as String
+            keyPassword = keystoreProperties["keyPassword"] as String
         }
     }
 }
 ```
 
+This needs `import java.util.Properties` at the top of the file.
+
 Update the release buildType to use the signing config:
-```gradle
+```kotlin
 buildTypes {
-    release {
-        signingConfig signingConfigs.release
+    getByName("release") {
+        signingConfig = signingConfigs.getByName("release")
         // ... existing config
     }
 }
 ```
 
+Verify with `./gradlew :amethyst:signingReport` — the release variants should
+report your keystore rather than `~/.android/debug.keystore`.
+
 ### 4. Disable Google Services (Required for F-Droid)
 
 **⚠️ CRITICAL:** The Google Services plugin fails when you change the package name. For F-Droid builds, disable it.
 
-Edit `amethyst/build.gradle`, comment out the plugin:
-```gradle
+Edit `amethyst/build.gradle.kts`, comment out the plugin:
+```kotlin
 plugins {
     alias(libs.plugins.androidApplication)
-    alias(libs.plugins.jetbrainsKotlinAndroid)
     // alias(libs.plugins.googleServices)  // DISABLED for F-Droid
     alias(libs.plugins.jetbrainsComposeCompiler)
+    alias(libs.plugins.serialization)
+    alias(libs.plugins.googleKsp)
 }
 ```
 
@@ -141,8 +149,8 @@ Edit `amethyst/src/main/res/values/strings.xml`:
 
 ### Change Package ID
 
-Edit `amethyst/build.gradle`:
-```gradle
+Edit `amethyst/build.gradle.kts`:
+```kotlin
 android {
     defaultConfig {
         applicationId = "com.yourcompany.yourapp"
@@ -152,8 +160,8 @@ android {
 
 ### Change Project Name
 
-Edit `settings.gradle`:
-```gradle
+Edit `settings.gradle.kts`:
+```kotlin
 rootProject.name = "YourAppName"
 ```
 
@@ -167,36 +175,28 @@ Replace icon files in:
 
 Make your app identify itself on posts with `["client", "YourAppName"]`.
 
-**1. Create tag builder extension:**
+You do **not** need to add the tag per event type. The client tag is applied
+centrally by `NostrSignerWithClientTag`, a signer decorator that appends the tag
+to everything it signs (and respects the user's "add client tag" privacy
+setting). Changing the name is a one-constant edit:
 
-Create `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/tags/clientTag/TagArrayBuilderExt.kt`:
+Edit `amethyst/src/main/java/com/vitorpamplona/amethyst/model/accountsCache/AccountCacheState.kt`:
 ```kotlin
-package com.vitorpamplona.quartz.nip01Core.tags.clientTag
-
-import com.vitorpamplona.quartz.nip01Core.core.Event
-import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
-
-fun <T : Event> TagArrayBuilder<T>.client(clientName: String) = 
-    addUnique(arrayOf(ClientTag.TAG_NAME, clientName))
+const val CLIENT_TAG_NAME = "YourAppName"
 ```
 
-**2. Add to TextNoteEvent:**
+That constant is passed to `NostrSignerWithClientTag` when the account's signer
+is built, so every signed event carries your name.
 
-Edit `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip10Notes/TextNoteEvent.kt`:
-
-Add import:
-```kotlin
-import com.vitorpamplona.quartz.nip01Core.tags.clientTag.client
-```
-
-In both `build()` functions, add after `alt(...)`:
-```kotlin
-client("YourAppName")
-```
+The tag itself lives in
+`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip89AppHandlers/clientTag/`
+(`ClientTag`, `TagArrayBuilderExt`, `NostrSignerWithClientTag`) — you only need to
+touch it if you want the optional NIP-89 handler address / relay hint variants.
 
 ### Modify Default Relays
 
-Edit relay configuration in `quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/` or the UI settings files.
+Edit `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/defaults/Constants.kt`
+(see also `AmethystDefaults.kt` and `DefaultDmIndexerRelays.kt` in the same folder).
 
 ## Troubleshooting
 

amethyst/build.gradle.kts

@@ -1,4 +1,7 @@
+import org.gradle.api.services.BuildService
+import org.gradle.api.services.BuildServiceParameters
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
     alias(libs.plugins.androidApplication)
@@ -87,8 +90,10 @@ android {
         vectorDrawables {
             useSupportLibrary = true
         }
-        @Suppress("UnstableApiUsage")
-        resourceConfigurations +=
+    }
+
+    androidResources {
+        localeFilters +=
             listOf(
                 "ar",
                 "ar-rSA",
@@ -264,6 +269,23 @@ android {
         resValues = true
     }
 
+    // Reproducible builds: keep AGP from embedding the dependency-metadata blob
+    // in the APK/AAB. That blob is a protobuf of the resolved dependency tree
+    // encrypted with a Google public key; the ciphertext is non-deterministic,
+    // so its presence makes every release artifact impossible to reproduce
+    // bit-for-bit. Dropping it (F-Droid's documented recommendation) lets
+    // F-Droid / Zapstore independently rebuild and verify our developer-signed
+    // APKs.
+    //
+    // Play-channel trade-off: with includeInBundle = false the uploaded .aab no
+    // longer carries this metadata, so Play Console's app-dependency insights /
+    // known-vulnerability SDK alerts go unpopulated. Uploads still succeed; only
+    // that advisory feature is lost.
+    dependenciesInfo {
+        includeInApk = false
+        includeInBundle = false
+    }
+
     packaging {
         resources {
             excludes += listOf("/META-INF/{AL2.0,LGPL2.1}", "**/libscrypt.dylib")
@@ -323,6 +345,30 @@ kotlin {
     }
 }
 
+// Gradle schedules Kotlin compilations of different variants of this module
+// concurrently (e.g. playDebug + playBenchmark when CI runs unit tests, lint,
+// and assembleBenchmark in one invocation), but they all share a single Kotlin
+// daemon whose heap (kotlin.daemon.jvmargs) cannot fit two full :amethyst
+// codegen passes — CI runs died with "GC overhead limit exceeded" inside the
+// daemon. This no-op shared build service with maxParallelUsages = 1 tells the
+// scheduler to run this module's Kotlin compile tasks one at a time; other
+// projects' tasks (JVM tests, lint analysis, packaging) still run in parallel.
+//
+// CI-only: the OOM needs a cache-cold compile of several variants at once,
+// which local builds (incremental, usually one variant) don't produce.
+abstract class AmethystKotlinCompileLimiter : BuildService<BuildServiceParameters.None>
+
+if (System.getenv("CI") != null) {
+    val kotlinCompileLimiter =
+        gradle.sharedServices.registerIfAbsent("amethystKotlinCompileLimiter", AmethystKotlinCompileLimiter::class) {
+            maxParallelUsages.set(1)
+        }
+
+    tasks.withType<KotlinCompile>().configureEach {
+        usesService(kotlinCompileLimiter)
+    }
+}
+
 composeCompiler {
     reportsDestination = layout.buildDirectory.dir("compose_compiler")
     metricsDestination = layout.buildDirectory.dir("compose_compiler")
@@ -331,12 +377,35 @@ composeCompiler {
 dependencies {
     implementation(platform(libs.androidx.compose.bom))
 
+    // Compose composition tracing — DEBUG ONLY, profiling aid (not shipped). Makes each
+    // recomposition show up as a NAMED slice in Perfetto system traces so we can see which
+    // composable recomposes (e.g. during the cold-start feed first-paint). All Apache-2.0.
+    // Usage: runtime-enable, then capture a Perfetto trace with the `track_event` data source:
+    //   adb shell am broadcast -a androidx.tracing.perfetto.action.ENABLE_TRACING \
+    //     -n com.vitorpamplona.amethyst.debug/androidx.tracing.perfetto.TracingReceiver
+    debugImplementation("androidx.compose.runtime:runtime-tracing")
+    debugImplementation("androidx.tracing:tracing-perfetto:1.0.0")
+    debugImplementation("androidx.tracing:tracing-perfetto-binary:1.0.0")
+
     implementation(project(":quartz"))
     implementation(project(":commons"))
     implementation(project(":nestsClient"))
+    implementation(project(":nappletHost"))
+    // Compose Multiplatform resources runtime, so app-side screens that share a
+    // string with a commons renderer can read commons' generated `Res` directly
+    // instead of duplicating the key in the Android res tree.
+    implementation(libs.jetbrains.compose.components.resources)
     implementation(libs.androidx.core.ktx)
     implementation(libs.androidx.activity.compose)
 
+    // Hardened WebView host for sandboxed napplet/nsite rendering (origin-restricted message bridge).
+    implementation(libs.androidx.webkit)
+
+    // Client side of the cross-process UI embedding: renders the sandboxed browser surface (hosted in
+    // the keyless `:napplet` process) inside a Compose component in the main app.
+    implementation(libs.androidx.privacysandbox.ui.core)
+    implementation(libs.androidx.privacysandbox.ui.client)
+
     implementation(libs.androidx.ui)
     implementation(libs.androidx.ui.graphics)
     implementation(libs.androidx.ui.tooling.preview)
@@ -421,6 +490,9 @@ dependencies {
     implementation(libs.markdown.ui.material3)
     implementation(libs.markdown.commonmark)
 
+    // Syntax highlighting for the git repository code browser (Apache-2.0)
+    implementation(libs.highlights)
+
     // LaTeX math rendering ($...$ and $$...$$ inline equations)
     implementation(libs.jlatexmath.android)
     implementation(libs.jlatexmath.font.greek)
@@ -495,6 +567,7 @@ dependencies {
     testImplementation(libs.junit)
     testImplementation(libs.mockk)
     testImplementation(libs.kotlinx.coroutines.test)
+    testImplementation(libs.secp256k1.kmp.jni.jvm)
 
     androidTestImplementation(platform(libs.androidx.compose.bom))
     androidTestImplementation(libs.androidx.junit)

amethyst/plans/2026-05-24-ios-support.md

@@ -1,5 +1,8 @@
 # iOS Support for Amethyst
 
+> **Status:** in-progress — `iosArm64`/`iosSimulatorArm64` targets are configured in `quartz` and `commons` (Phase 1), but no `iosApp` module exists yet — later phases not built.
+> _Audited 2026-06-30._
+
 **Date:** 2026-05-24
 **Status:** Phase 1 complete; Phase 2 in flight
 **Owner:** TBD

amethyst/plans/2026-06-20-napplet-inter-applet.md

@@ -0,0 +1,97 @@
+# Napplet inter-applet communication (NAP-INC / NAP-INTENT) — design notes
+
+> **Status:** queued — Explicitly deferred; no `MESSAGING` capability exists in `NappletCapability` and the prerequisites (multi-applet hosting, archetype registry) are unbuilt.
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-20
+**Status:** Deferred — design only. Prereqs not yet built (see below).
+**Parent:** `amethyst/plans/2026-06-19-napplet-sandbox-host.md`
+
+## Why this is deferred (not just "next")
+
+Inter-applet messaging is the one napplet capability that needs **new
+architecture**, not just a new broker op + gateway. Two hard prerequisites are
+missing today:
+
+1. **Multiple applets running at once.** `NappletHostActivity` is declared
+   `launchMode="singleTask"` and hosts exactly one applet. True live A↔B
+   messaging (the full NAP-INC request/result transport) requires either
+   multi-applet hosting (several iframes in one host, or several host processes)
+   plus a routing layer — none of which exists.
+2. **An archetype / handler registry.** NAP-INTENT dispatches by *archetype*
+   (`note`, `feed`, `profile`, …) to a default-handler napplet. Our
+   `NappletManifest` has no `handles`/archetype declaration and there is no
+   "which napplet is the default handler for X" registry.
+
+Both are sizeable subsystems. Shipping a half-version would also risk **forking
+the wire format** from upstream while it is still being defined.
+
+## Upstream model (napplet/naps survey, 2026-06-20)
+
+Inter-applet is split into two shell-mediated specs (applets never reach each
+other directly — every message crosses the shell/broker):
+
+- **NAP-INC** (`inc`) — the transport. Messages are `{ type: "domain.action",
+  id, … }`, request/result correlated by `id`. Addressing is direct
+  (napplet→napplet) *or* archetype-mediated by the runtime.
+- **NAP-INTENT** (`intent`) — invoke a napplet by **archetype** via
+  default-handler dispatch (`shell.supports("intent")`). The shell launches the
+  handler; napplets cannot invoke directly.
+- **NAP-1…5** — concrete protocols on top of NAP-INC: `profile:*` (NAP-1),
+  `stream:*` (NAP-2), `chat:*` (NAP-3), `note:open` (NAP-4), `feed:*` (NAP-5).
+  Producer/consumer model.
+
+Discovery is capability-probe based: `shell.supports("inc")`,
+`shell.supports("inc", "NAP-N")`.
+
+## How it would map onto our boundary
+
+The broker model fits "shell-mediated" naturally — every message would cross
+`NappletBrokerService` exactly like every other capability, gated by the ledger.
+The pieces:
+
+1. **Capability.** Add `NappletCapability.MESSAGING` mapped from NAP domains
+   `inc` / `intent` (default-deny like every other domain). Consent is a *link*
+   grant ("Applet A may message / open Applet B"), distinct from per-op consent.
+2. **Protocol.** New `NappletRequest`/`NappletResponse` variants under
+   `MESSAGING`, shaped to mirror NAP-INC (`type = "domain.action"`, `id`
+   correlation) so we don't fork the wire format.
+3. **Addressing.** Direct by napplet coordinate first; archetype dispatch only
+   after the registry (below) exists.
+
+### Two viable implementation shapes (pick at build time)
+
+- **NAP-INTENT, direct coordinate** — `napplet.intent({ target, payload })` →
+  consent → broker resolves `target` to a manifest in `LocalCache` → launches it
+  via a `NappletIntentLauncher` gateway, passing an initial payload the target
+  reads on startup (`napplet.intent` / `onIntent`). Fits the single-applet model
+  (you switch to the target). No simultaneous hosting needed. **Lowest lift; most
+  aligned with NAP-INTENT.** Result-return across the switch is awkward (fire-and-
+  forget, or a callback event).
+- **NAP-INC brokered mailbox** — `napplet.sendTo(coordinate, msg)` /
+  `pollMessages()` with broker-persisted per-napplet inboxes, consent per link.
+  Works with no simultaneous hosting and is fully unit-testable, but it is async
+  fire-and-collect, not the request/result transport upstream describes.
+
+Full live NAP-INC (simultaneous A↔B, request/result) needs the multi-applet
+hosting prereq regardless.
+
+## Prerequisites to build first
+
+1. **Multi-applet hosting** — either N iframes in one `NappletHostActivity` with
+   per-iframe origin isolation + routing, or a host-per-applet process model and
+   a cross-process router in the broker. Decide the model before coding NAP-INC.
+2. **Archetype registry** — a manifest `handles`/archetype tag (align with
+   upstream naps), an index over installed napplets, and a user-set default
+   handler per archetype (mirror NIP-89 handler selection, which Amethyst already
+   models for app recommendations).
+3. **Link-consent UX** — distinct from capability consent: "Allow *Chess* to open
+   *Wallet*?", revocable per pair in a permissions screen.
+
+## Recommendation
+
+When picked up: start with **NAP-INTENT direct-coordinate** (smallest, aligned,
+no new hosting), build the archetype registry next (unlocks default-handler
+dispatch + reuses NIP-89 patterns), and only then tackle live NAP-INC once
+multi-applet hosting lands. Keep the wire `type`/`id` shape identical to upstream
+NAP-INC throughout to avoid a fork.

amethyst/plans/2026-07-01-auth-permission-architecture.md

@@ -0,0 +1,385 @@
+# Contextual AUTH Permissions — Ask *why*, and trust follows
+
+**Date:** 2026-07-01
+**Module:** `amethyst` (+ shared bits in `commons`)
+**Status:** Implemented — see "As-built" below for where the shipped design diverged from this proposal.
+
+## As-built (final)
+
+The implementation kept this doc's core ideas (purpose derivation, a prompt bus,
+per-relay overrides, grant rationale) but the policy model was reshaped during
+review:
+
+- **Global mode is `RelayAuthPolicy { ALWAYS, NEVER, CUSTOM }`** — the earlier
+  `IF_IN_MY_LIST` / `TRUSTED_FOLLOWS` values were dropped. `CUSTOM` applies a
+  `RelayAuthCustomToggles` set of independent switches: **my relays & venues**,
+  **read posts from follows**, **message follows**, **message strangers**
+  (off by default). New-install default is `CUSTOM` with the first three on.
+- **`AuthPurpose` is a `data class` (kind + counterparties + venues)** over an
+  `AuthPurposeKind` enum (SEND_DM, NOTIFY_INBOX, READ_OUTBOX, POST_VENUE,
+  READ_VENUE, MY_OWN_RELAY, OTHER) — not a sealed interface. Venues (NIP-28
+  public chats, NIP-72 communities, NIP-53 live activities) are first-class.
+- **Settings screen** uses the app's settings design system (`SettingsSection`
+  card + `SettingsSwitchTile`) for the toggles and a grouped, lazily-rendered
+  per-relay list (NIP-11 icon, `displayUrl`, tap → relay info).
+- **Give-up signal**: quartz's outbox surfaces `onEventGaveUp`, toasted by
+  `RelayPublishFailureToast`. `auth-required` NAKs never burn the retry budget
+  (they reset it) so a slow AUTH handshake can't drop the event.
+- **Known limitation**: an event queued to a relay the user then *denies* stays
+  pending in the outbox (auth-required never gives up); evicting it would need a
+  quartz "give up on relay for this event" API — deferred.
+
+## Context
+
+Now that Amethyst answers NIP-42 relay AUTH challenges, we need to decide
+*when* to reveal the user's identity to a relay — and, crucially, to tell the
+user **why** an auth is being requested so they can make an informed choice.
+
+The motivating cases:
+
+- **NIP-17 DM send.** The recipient's DM inbox relays (kind 10050) may require
+  auth. If we silently refuse, the message never leaves the device and the user
+  has no idea why. We should ask: *"Relay X wants you to log in to deliver your
+  private message to Alice — allow?"*
+- **Public inbox notifications.** Replying to / mentioning / reacting to someone
+  publishes to *their* NIP-65 inbox (kind 10002 read relays), which may require
+  auth.
+- **Feed download from outboxes.** Reading a followed author's posts may require
+  auth to *their* write/outbox relays.
+
+We also want an **automatic mode** for users who trust Amethyst's judgement:
+auth (or not) based on a follow-graph heuristic — *if I follow the counterparty
+(in any follow list), I trust them enough to reveal my identity to the relay
+that serves them.* And regardless of mode, **explicit per-relay overrides** must
+be able to force-allow or force-block a single relay. The blocked-relay list
+(kind 10006) is a hard block.
+
+## What already exists (reuse — do NOT rebuild)
+
+The NIP-42 plumbing and a first-cut permission gate are already in place:
+
+| Piece | Location |
+|---|---|
+| AUTH challenge receipt, kind-22242 signing, resend-on-OK | `quartz/.../nip01Core/relay/client/auth/RelayAuthenticator.kt`, `RelayAuthStatus.kt`, `nip42RelayAuth/RelayAuthEvent.kt` |
+| Permission gate (per logged-in account) | `amethyst/.../service/relayClient/authCommand/model/AuthCoordinator.kt` |
+| Decision engine (per-relay override → global policy) | `.../authCommand/model/RelayAuthPermissionLedger.kt` |
+| Policy enum `ALWAYS`/`NEVER`/`IF_IN_MY_LIST`, decision enum `ALLOW`/`DENY` | `commons/.../relayauth/RelayAuthPolicy.kt` |
+| Per-relay override persistence interface + DataStore impl | `commons/.../relayauth/RelayAuthPermissionStore.kt`, `amethyst/.../authCommand/model/DataStoreRelayAuthPermissionStore.kt` |
+| Settings screen (global policy + per-relay list) | `amethyst/.../ui/screen/loggedIn/relayauth/RelayAuthSettingsScreen.kt` |
+| Global policy setting, persisted local-only | `AccountSettings.defaultRelayAuthPolicy`, `LocalPreferences` key `DEFAULT_RELAY_AUTH_POLICY` |
+| Blocked-relay list (kind 10006) | `amethyst/.../model/nip51Lists/blockedRelays/BlockedRelayListState.kt` (`.flow`) |
+| Follow checks | `Account.isFollowing(...)`, `Account.allFollows.flow.value.authors`, `FollowListsState.isUserInFollowSets(...)` |
+| DM / NIP-65 relay lookups | `DmRelayListState`, `Nip65RelayListState` (+ per-user via `LocalCache`) |
+
+## The gap
+
+`RelayAuthPermissionLedger.decide(relayUrl)` receives **only a relay URL**. It
+resolves ALLOW/DENY **silently and immediately**. Three things are missing:
+
+1. **No purpose/"why".** The decision point can't tell a DM-send from a
+   feed-read from a stranger's random challenge, so it can't explain itself or
+   attribute the relay to a counterparty.
+2. **No interactive ASK.** `RelayAuthDecision` is binary. A DENY silently drops
+   the auth (and the send fails with no feedback).
+3. **No follow-based trust.** `IF_IN_MY_LIST` only checks *my own* relays, never
+   "this relay belongs to someone I follow."
+
+## Recommended architecture
+
+Four changes, smallest surface first.
+
+### 1. Carry the *purpose* to the decision point — `AuthPurpose` + an intent registry
+
+New (in `commons/.../relayauth/`, KMP-safe, no Android deps):
+
+```kotlin
+sealed interface AuthPurpose {
+    data class SendDM(val recipients: Set<HexKey>) : AuthPurpose          // recipient DM inboxes (10050)
+    data class NotifyInbox(val recipients: Set<HexKey>) : AuthPurpose     // recipient NIP-65 read relays
+    data class ReadOutbox(val author: HexKey?) : AuthPurpose              // author write/outbox relays
+    data object MyOwnRelay : AuthPurpose                                  // relay in my own lists
+    data object Unknown : AuthPurpose                                     // bare challenge, no attribution
+}
+```
+
+The auth path is **reactive** (relay pushes the challenge; the lambda only knows
+the URL). Most intent is already recoverable from quartz's per-relay pending
+events + active filters (see "Where it lives" below), so the registry below is
+**minimal** — only for hints quartz can't infer (e.g. the human recipient behind
+an encrypted gift wrap). It lives with the coordinator, since `LocalCache`/
+`Account` are main-process only:
+
+```kotlin
+// amethyst/.../service/relayClient/authCommand/model/RelayAuthIntentRegistry.kt
+class RelayAuthIntentRegistry {
+    fun register(relay: NormalizedRelayUrl, purpose: AuthPurpose)   // short TTL entry
+    fun purposesFor(relay: NormalizedRelayUrl): List<AuthPurpose>   // read at decision time
+}
+```
+
+Representative registration sites (each already computes its target relays):
+- NIP-17 DM send → `SendDM(recipients)` on each recipient DM-inbox relay.
+- Reply/mention/reaction broadcast → `NotifyInbox(recipients)`.
+- Outbox feed subscriptions → `ReadOutbox(author)`.
+
+*Race note:* keying by relay URL means concurrent purposes can collide; store a
+small time-bounded **set** per relay and let the resolver consider all live
+entries (the prompt can say "to send your DM to Alice and 2 others"). Acceptable
+for a UX hint + trust check; the persisted decision is what actually gates.
+
+### 1b. Persist *why* each relay was granted (grant rationale)
+
+The decision stays **relay-based**, but each relay's stored record must also
+remember **why** it was granted, so the settings screen can show, per relay,
+purpose-grouped lines of counterparty users (with avatars):
+
+> **wss://inbox.example.com** — Allowed
+> · To send DMs to: (avatars) Alice, Bob, Carol
+> · To download posts from: (avatars) Dave, Erin
+
+Extend the persisted per-relay record from a bare `RelayAuthDecision` to
+`decision + rationale`, where the rationale is an accumulated map keyed by
+purpose kind:
+
+```kotlin
+// commons/.../relayauth/RelayAuthGrant.kt (new)
+data class RelayAuthGrant(
+    val decision: RelayAuthDecision,
+    // purpose kind -> counterparty pubkeys seen for this relay under that purpose
+    val rationale: Map<AuthPurposeKind, Set<HexKey>> = emptyMap(),
+    val lastUsedAt: Long = 0L,
+)
+enum class AuthPurposeKind { SEND_DM, NOTIFY_INBOX, READ_OUTBOX, MY_OWN_RELAY }
+```
+
+The rationale is **updated every time** an auth is granted/re-used for that
+relay: merge the current `AuthPurpose` counterparties into the matching kind's
+set and refresh `lastUsedAt`. This keeps the "why" current as new
+DMs/notifications/feeds route through the relay. Store only pubkeys — names and
+avatars are resolved for display from `LocalCache` at render time, so the store
+stays privacy-light and small.
+
+### 2. Add an `ASK` outcome and a context-aware resolver
+
+Extend the decision enum and generalize `decide()`:
+
+```kotlin
+enum class RelayAuthDecision { ALLOW, DENY, ASK }   // ASK added
+
+class RelayAuthContext(val relayUrl: String, val purposes: List<AuthPurpose>)
+```
+
+`RelayAuthPermissionLedger.decide(ctx)` precedence (highest → lowest):
+
+1. **Blocked-relay list** (kind 10006) → `DENY`. Never reveal identity to a
+   blocked relay, whatever the policy.
+2. **Explicit per-relay override** (`RelayAuthPermissionStore`) → return it.
+3. **Global policy**:
+   - `NEVER` → `DENY`
+   - `ALWAYS` → `ALLOW`
+   - `IF_IN_MY_LIST` → `ALLOW` if relay ∈ my relay lists, else fall through
+   - `TRUSTED_FOLLOWS` *(new — see idea A below)* → `ALLOW` if relay ∈ my lists
+     **or** any counterparty in `ctx.purposes` is followed (`Account.allFollows`
+     / `FollowListsState.isUserInFollowSets`) and the purpose permits it; else
+     fall through.
+4. **Fall-through**: `ASK` if the purpose is attributable (we can show a reason);
+   otherwise `DENY` silently (don't prompt for anonymous stranger challenges).
+
+Keep the current relay-only `decide(url)` as a thin overload calling
+`decide(RelayAuthContext(url, registry.purposesFor(url)))` so existing callers
+compile.
+
+Whenever the resolver yields `ALLOW` and an auth is actually sent — regardless
+of *how* it was allowed (auto policy, stored override, or a just-approved ASK) —
+call `store.recordUse(relayUrl, purpose)` for each attributed purpose so the
+grant rationale (§1b) stays current.
+
+### 3. Surface the ASK prompt to the UI and await the answer
+
+The `signWithAllLoggedInUsers` lambda in `AuthCoordinator` is **already a
+`suspend` context**, so the resolver can suspend and await a user decision — no
+restructuring of the auth send path.
+
+- Add an event stream on the coordinator (or account):
+  `SharedFlow<RelayAuthRequest>` where
+  `RelayAuthRequest(relay, purposes, reply: CompletableDeferred<UserAuthChoice>)`.
+  (Follows the repo's one-shot-event flow pattern — see `kotlin-flow-state-event-modeling`.)
+- A composable observer (registered in the logged-in scaffold) collects the flow
+  and shows a dialog: *"{relay} requires you to log in to {reason}."* with
+  actions **Allow once / Always allow this relay / Block this relay**. The last
+  two write through `RelayAuthPermissionLedger.setDecision(...)`.
+- The lambda `await`s the deferred (bounded by a timeout consistent with
+  `RelayAuthStatus`), then proceeds to sign or returns `emptyList()`.
+
+Reason strings are derived from `AuthPurpose` via a small mapper (resolve
+recipient pubkeys → display names through `LocalCache`).
+
+### 4. New policy mode + settings
+
+- Add `TRUSTED_FOLLOWS` to `RelayAuthPolicy` (recommended — idea A).
+- `RelayAuthSettingsScreen`: add the new mode with an explanatory blurb; the
+  per-relay override list already supports force-allow/force-block (now
+  three-state incl. "ask"). No storage-format change if we keep decisions
+  per-relay (idea B, recommended default).
+
+## Where it lives: quartz (generic mechanism) vs amethyst (policy + UI)
+
+Goal (per the brief): if the auth+resend mechanism can be made **robust and
+generic**, it belongs in **quartz**; only the *semantics* (why / follow-trust /
+prompt copy / rationale UI) stay in **amethyst**.
+
+### The resend queue already exists in quartz — and is the "intent registry"
+
+`PoolEventOutbox` / `PoolEventOutboxState` already persist outgoing events
+per-relay across reconnects, and `NostrClient.syncFilters(relay)` — called on
+connect **and after an auth OK** (`RelayAuthenticator.checkAuthResults`) —
+already re-sends pending EVENTs, not just REQ subscriptions. So the park-and-
+flush half of idea C is largely built; we just need to make it correct.
+
+It also means we mostly **don't need a separate `RelayAuthIntentRegistry`**:
+quartz already knows, per relay, the *pending outgoing events*
+(`PoolEventOutbox`) and the *active subscription filters* (`activeRequests`).
+That set IS the intent. At AUTH time quartz can hand the injected decision
+callback this context; amethyst derives purpose from it (a pending kind-1059
+gift wrap → `SendDM`; a REQ whose `authors` are followed → `ReadOutbox`). Keep a
+tiny registry only for hints quartz can't infer (e.g. the human recipient behind
+a gift wrap, which is encrypted) — but drive the common cases off quartz state.
+
+### Generic fixes to land in quartz (`nip01Core/relay/client/`)
+
+1. **Treat `auth-required` as a first-class deferred state, not a burned retry.**
+   *(Landed — commit 2.)* The resend-after-auth path already works:
+   `syncFilters` on the auth `OK` re-sends every still-pending EVENT, so the
+   common single-round case (send → `auth-required` → auth → resend → accepted)
+   already delivered. The narrow bug: `PoolEventOutboxState.newResponse` sent
+   `auth-required` down the generic-failure path, so each NAK consumed the
+   per-relay retry budget (`isDone() = responses.size > 2 || tries.size > 3`).
+   Budget exhaustion isn't checked on the NAK itself but on the **next
+   `newTry`** — i.e. the resend `syncFilters` issues after the auth `OK`. So
+   across *repeated* rounds (slow external NIP-55 signer, reconnect churn, or a
+   relay that re-challenges) the saved event could be **evicted right as it was
+   about to be redelivered**. Fix: `auth-required` records no failure and leaves
+   `relaysRemaining` untouched (mirrors `StandaloneRelayClient`'s
+   `!msg.message.startsWith("auth-required")`), so the existing resend can
+   redeliver no matter how many auth rounds elapse first.
+2. **Real retry policy instead of a hard count.** Replace the `>2 / >3` cliff
+   with bounded retries + backoff, and a **terminal "gave up" notification**
+   (via `RelayConnectionListener` / a publish-result callback) so events are
+   never *silently* dropped. `NostrClientPublishExt.publishAndConfirmDetailed`
+   and `pendingPublishRelaysFor` already give higher layers a confirmation
+   surface to build on.
+3. **Enrich the injected auth-decision callback with pending context.** The
+   `signWithAllLoggedInUsers = (relayUrl, authTemplate) -> …` hook in
+   `RelayAuthenticator` currently gets only the URL. Pass a generic
+   `RelayAuthChallengeContext` carrying the relay's pending events + active
+   filters, and let it return not just "sign or not" but an outcome that can
+   **suspend for a host decision**. The `AuthPurpose`/`RelayAuthContext` types
+   move to a quartz-neutral shape (opaque to quartz); amethyst supplies the
+   resolver.
+4. **Expose an "event is blocked on auth for relay X" signal** so a host UI can
+   show the prompt and reflect "queued, not lost." A `SharedFlow`/listener on the
+   client, host-agnostic.
+
+### What stays in amethyst
+
+The *policy and meaning*: blocked-list + follow-graph resolver, purpose/
+counterparty derivation (needs `LocalCache`/`Account`, main-process only), the
+`TRUSTED_FOLLOWS` mode, the ASK prompt UI, and the per-relay **grant rationale**
+persistence + settings rows (§1b). These depend on identity/UI and cannot live
+in quartz.
+
+## A few ideas / open decisions
+
+These are the knobs where more than one answer is defensible. Recommendation
+first.
+
+- **A. Follow-based trust shape.** *(Recommended: new `TRUSTED_FOLLOWS` policy
+  mode.)* Cleanest extension of the existing enum + settings radio group.
+  Alternatives: a separate independent "trust relays of people I follow" toggle
+  that layers on any base mode (more flexible, more UI); or never-automatic —
+  follow-status only pre-selects the "remember" button in the ASK dialog (most
+  conservative).
+
+- **B. Decision memory granularity.** *(Decided: per-relay — the decision gate
+  is one ALLOW/DENY per relay.)* We keep the gate relay-based but enrich the
+  stored record with the grant rationale (§1b) so the settings screen can
+  explain each relay. Rejected alternative: making the *gate itself*
+  per-purpose × per-relay (allow relay X for DMs but keep asking for feed reads)
+  — richer but more confusing; the rationale display gives the transparency
+  without splitting the gate.
+
+- **C. In-flight send when auth isn't yet granted.** *(Recommended: fix
+  quartz's existing outbox so park-and-flush is the default.)* The queue already
+  exists (`PoolEventOutbox` + `syncFilters`-after-auth); the work is making
+  `auth-required` a deferred state (not a burned retry) and adding backoff + a
+  terminal give-up signal — see the quartz section above. This is strictly
+  better than the amethyst-only best-effort/retry fallback and is generic, so it
+  belongs in quartz. Best-effort remains the trivial fallback only if we choose
+  not to touch quartz.
+
+- **D. Which purposes auto-trust covers.** DMs and public inbox notifications are
+  clear yes. Outbox/feed reads ("maybe" in the brief) could be a sub-toggle
+  under `TRUSTED_FOLLOWS` so reading is treated more liberally than writing.
+
+## Files to touch
+
+- `commons/.../relayauth/RelayAuthPolicy.kt` — add `TRUSTED_FOLLOWS`, add `ASK`.
+- `commons/.../relayauth/AuthPurpose.kt` — **new** sealed hierarchy + `RelayAuthContext` + `AuthPurposeKind`.
+- `commons/.../relayauth/RelayAuthGrant.kt` — **new** per-relay record (decision + rationale, §1b).
+- `commons/.../relayauth/RelayAuthPermissionStore.kt` + `amethyst/.../DataStoreRelayAuthPermissionStore.kt`
+  — store/load `RelayAuthGrant` (decision + rationale) instead of a bare decision; add a
+  `recordUse(relayUrl, purpose)` merge that updates the rationale + `lastUsedAt`.
+- `amethyst/.../authCommand/model/RelayAuthPermissionLedger.kt` — context-aware
+  `decide(ctx)`, blocked-list + follow-trust inputs, `ASK` fall-through.
+- `amethyst/.../authCommand/model/RelayAuthIntentRegistry.kt` — **new, minimal**:
+  only for hints quartz can't infer (e.g. the recipient behind an encrypted gift
+  wrap). Common purposes are derived from quartz's pending events + active
+  filters instead.
+
+**Quartz (generic mechanism — see the quartz section):**
+- `quartz/.../nip01Core/relay/client/pool/PoolEventOutboxState.kt` +
+  `PoolEventOutbox.kt` — `auth-required` as a pending-auth state excluded from
+  `isDone()`; bounded retry + backoff; terminal give-up notification.
+- `quartz/.../nip01Core/relay/client/auth/RelayAuthenticator.kt` — pass a
+  `RelayAuthChallengeContext` (pending events + active filters) to the injected
+  decision hook; allow the hook to suspend for a host decision.
+- `quartz/.../nip01Core/relay/client/listeners/RelayConnectionListener.kt` (or a
+  new client `SharedFlow`) — "event blocked on auth for relay X" + "gave up"
+  signals. Fold the good `StandaloneRelayClient` auth-retry logic into the
+  production path.
+- `amethyst/.../authCommand/model/AuthCoordinator.kt` — build `RelayAuthContext`
+  from the registry, emit `RelayAuthRequest` on `ASK`, await the reply.
+- Wire the ledger's new inputs where it's constructed (blocked-list flow,
+  follow-check, relay-ownership lookups from `DmRelayListState`/`Nip65RelayListState`).
+- Registration calls at the DM sender, reply/reaction broadcaster, and outbox
+  feed subscription.
+- `amethyst/.../ui/screen/loggedIn/relayauth/RelayAuthSettingsScreen.kt` — new
+  mode; three-state per-relay overrides; **per-relay rationale rows** grouped by
+  purpose ("To send DMs to: …", "To download posts from: …") rendering
+  counterparty avatars + names resolved from `LocalCache`.
+- New composable dialog + observer for `RelayAuthRequest`, hosted in the
+  logged-in scaffold.
+
+## Verification
+
+- **Unit (commons/amethyst JVM):** table-test `decide(ctx)` across the
+  precedence ladder — blocked beats override beats policy; `TRUSTED_FOLLOWS`
+  allows a followed-counterparty relay and falls to `ASK` for a stranger;
+  `Unknown` purpose → silent `DENY`.
+- **Quartz outbox (JVM unit tests):** an `auth-required` NAK does **not** advance
+  `isDone()` and the event survives; after a simulated auth OK, `syncFilters`
+  re-sends it; a non-auth terminal error still discards; retries honor backoff
+  and emit a give-up signal instead of a silent drop. Include a race test:
+  repeated `auth-required` NAKs before auth completes must not drop the event.
+- **Intent registry:** register/expire, multi-purpose merge on one relay.
+- **Grant rationale:** `recordUse` merges new counterparties into the right
+  purpose kind, dedupes, refreshes `lastUsedAt`; `allDecisions()`/settings query
+  returns the grouped rationale for rendering.
+- **`amy` interop:** drive a NIP-17 send to a recipient whose 10050 relay
+  requires auth against a local auth-required relay (`amy serve` / geode) and
+  confirm the AUTH round-trip + delivery once allowed. (Enforces the
+  verify-don't-guess rule.)
+- **Manual:** send a DM to a followed vs non-followed npub on an auth-required
+  inbox under each policy mode; confirm the prompt copy names the right reason
+  and that Always/Block persist.
+- `./gradlew :commons:test :amethyst:testDebugUnitTest` and `./gradlew spotlessApply`.

amethyst/plans/2026-07-07-nip29-armada-study.md

@@ -0,0 +1,538 @@
+# NIP-29 Relay-Based Groups — Deep Study of Armada + Amethyst Integration Plan
+
+**Date:** 2026-07-07
+**Status:** Research / design study (no code yet)
+**Reference client studied:** [Armada](https://gitlab.com/soapbox-pub/armada) (Soapbox), commit at HEAD of `main`
+**Spec:** [NIP-29](https://github.com/nostr-protocol/nips/blob/master/29.md)
+
+This document is a deep study of how **Armada** — a Discord-style NIP-29 client
+by Soapbox — creates events, manages chat, displays information, and handles
+invites/joins/leaves, followed by a concrete plan for bringing NIP-29 into
+Amethyst. It is written to answer "how does relay-based group chat actually work
+in a shipping client, and where does it slot into Amethyst's existing chat
+stack."
+
+---
+
+## 0. TL;DR for the impatient
+
+- **NIP-29 groups live on ONE relay.** A group is addressed by the pair
+  `(relayUrl, groupId)`. The relay is the source of truth — it signs the group's
+  metadata/membership/roles and enforces who may write. This is fundamentally
+  different from Nostr's usual "publish everywhere" model.
+- **Armada models it as Discord:** a **server = a relay**, a **channel = a
+  NIP-29 group**. The far-left rail is a list of relays; picking one shows that
+  relay's channels; picking a channel shows its kind-9 message timeline.
+- **The user's home base is kind 10009** (NIP-51 "simple groups list"): it stores
+  both the relays they've added (`r` tags) and the groups they've joined
+  (`group` tags), privately (NIP-44 encrypted to self).
+- **Amethyst is already ~70% wired for this at the protocol layer.** Quartz has a
+  `nip29RelayGroups` package (metadata/moderation/request events) **and** a
+  `nip43RelayMembers` package (the relay-level membership handshake Armada uses).
+  The main protocol gap is the **kind-9 group chat *message* event** itself.
+- **Amethyst also already has the perfect UX analog:** the `ephemChat` feature
+  (NIP-C7, kind 23333) is a *relay-scoped* chat room identified by a
+  `RoomId(id, relayUrl)` — the exact shape of a NIP-29 group address — with a
+  full channel/screen/join/leave UI under
+  `amethyst/.../ui/screen/loggedIn/chats/publicChannels/ephemChat/`. NIP-29 is a
+  managed, moderated sibling of that feature.
+
+---
+
+## 1. NIP-29 protocol primer (the parts that matter)
+
+### 1.1 The addressing model
+
+A group is **not** a global object. It exists on a specific relay, and its id is
+only unique *within that relay*. So every reference to a group is the pair:
+
+```
+(relay websocket URL, group id)
+```
+
+The group id is a short opaque string (Armada mints 8 random bytes → 16 hex
+chars). Everything that happens "in" the group is tagged with `["h", "<groupId>"]`
+and published **only** to that relay.
+
+### 1.2 Event kinds
+
+| Kind | Name | Signed by | Purpose |
+|------|------|-----------|---------|
+| **9** | group chat message | user | the actual chat line (has `["h", groupId]`) |
+| 11 | group thread/forum post | user | long-form/threaded root |
+| 1111 | NIP-22 comment | user | threaded reply to a chat message |
+| 7 | reaction | user | emoji reaction (scoped by `h`) |
+| 1068 | poll (NIP-88) | user | poll posted into the timeline |
+| **9000** | put-user | user (admin) | add member / set roles |
+| **9001** | remove-user | user (admin) | remove member |
+| **9002** | edit-metadata | user (admin) | change name/about/picture/flags |
+| 9005 | delete-event | user (admin) | moderator delete a message |
+| **9007** | create-group | user (admin) | create a new group |
+| 9008 | delete-group | user (admin) | delete a group |
+| **9009** | create-invite | user (admin) | mint an invite code |
+| **9021** | join-request | user | ask to join (optional `code`) |
+| **9022** | leave-request | user | leave the group |
+| **39000** | group metadata | **relay** | name, picture, about, flags (addressable, `d`=groupId) |
+| **39001** | group admins | **relay** | `["p", pubkey, role…]` list |
+| **39002** | group members | **relay** | `["p", pubkey]` list |
+| **39003** | group roles | **relay** | `["role", name, desc]` definitions |
+| 39004 | live AV participants | **relay** | LiveKit room presence (Armada extension use) |
+
+The **9xxx** events are user-authored **requests/commands**; the relay validates
+the author's role and, if accepted, updates the group state and re-emits the
+**39xxx** relay-signed snapshots. **Clients read 39xxx, write 9xxx.**
+
+### 1.3 Group metadata flags (kind 39000 tags)
+
+`name`, `picture`, `about` carry display data. Boolean status is presence-based:
+
+- `private` — only members can **read** (relay gates reads behind NIP-42 AUTH).
+- `restricted`* — only members can **write**.
+- `closed` — join requests are ignored; you need an invite code.
+- `hidden` — metadata hidden from non-members.
+- `livekit` — group has an AV room.
+- `supported_kinds` — whitelist of accepted kinds (absent = all).
+
+The antonyms are `public` / `open` (Armada's `edit-metadata` emits the antonym
+tag to *clear* `private`/`closed`; see §2.4).
+
+### 1.4 The `previous` tag (timeline references) — and why Armada drops it
+
+NIP-29 defines an optional `["previous", <id-prefix>, …]` tag: each event should
+reference the first-8-chars of several of the group's recent events so a relay
+can reject events that were composed against a *forked* view of the timeline
+(anti-context-spam). **Armada deliberately does not emit it** — see the
+verbatim rationale in `ChatComposer.buildMessageTags`:
+
+> relay29's `CheckPreviousTag` rejects any event whose first `previous` ref isn't
+> in the group's in-memory last-50 ring. We can only pick refs from a local (and
+> own-excluded) message snapshot, which routinely drifts out of that window —
+> especially when replying to older messages — causing the relay to silently drop
+> legitimate messages/replies. `previous` is optional in NIP-29 and only guards
+> against relay-fork attacks, which don't apply to this single-host-per-group
+> deployment.
+
+**Takeaway for Amethyst:** Quartz *has* a `PreviousTag` class, but a
+single-host-per-group deployment does not need it, and emitting it naively causes
+silent drops. Start without it (like Armada); only add it if targeting a relay
+that enforces it.
+
+---
+
+## 2. How Armada creates events
+
+Armada's whole NIP-29 protocol layer is ~770 lines in
+`client/src/lib/nip29.ts` (constants, parsers, tag builders), driven by a set of
+TanStack-Query hooks in `client/src/hooks/`. Every write goes through a single
+`useNostrPublish` mutation whose `relay` option **pins the event to the group's
+host relay** — this is the linchpin of the whole design.
+
+### 2.1 The publish chokepoint (`useNostrPublish.ts`)
+
+```ts
+// EventTemplate has an optional `relay?: string`.
+// When set, publish ONLY to this relay (NIP-29 group traffic must stay on
+// the group's host server). When omitted, the event goes to all app relays.
+if (relay) {
+  await nostr.relay(relay).event(event, …);   // single-relay send
+} else {
+  await nostr.event(event, …);                // fan out to app relays
+}
+```
+
+It also: adds a NIP-89 `["client", APP_NAME]` tag, adds `published_at` for
+replaceable kinds, stores the signed event locally *before* the network call (so
+optimistic UI + offline retry work), and normalizes relay rejection strings for
+toasts (`relayRejectionMessage`).
+
+**Every NIP-29 write in Armada passes `relay: relayUrl`.** Group/channel events
+*never* touch the general app relays. This is the single most important
+invariant to replicate.
+
+### 2.2 Create a group (`CreateGroupDialog.tsx` + `useGroupModeration.ts`)
+
+A "create channel" is a **two-event sequence**, then a bookkeeping write:
+
+```ts
+// 1. kind 9007 create-group — just the h tag.
+await createGroup({ groupId });
+//    → publishEvent({ kind: 9007, content: "", tags: [["h", groupId]], relay })
+
+// 2. kind 9002 edit-metadata — name/about/visibility.
+await editMetadata.mutateAsync({ name, about, isPrivate, isClosed });
+//    → tags: [["h", groupId], ["name", name], ["about", about],
+//             [isPrivate ? "private" : "public"], [isClosed ? "closed" : "open"]]
+
+// 3. remember it in the user's kind 10009 list (best-effort).
+updateList({ type: "add-group", ref: { id: groupId, relay: relayUrl } });
+```
+
+The group id is client-minted (`crypto.getRandomValues(8)` → hex). The creator
+becomes admin automatically (the relay assigns the group-creator role). Then the
+UI navigates to `/s/<relayParam>/<groupId>`.
+
+> Server note: Armada's own relay (`server/group.go`) **restricts kind 9007 to
+> configured admin pubkeys** — on that deployment only operators create channels.
+> That's a relay-policy choice, not a NIP-29 requirement.
+
+### 2.3 Send a chat message (`ChatComposer.tsx`)
+
+A message is **kind 9** with `["h", groupId]` plus standard Nostr tags. The tag
+builder (`buildMessageTags`) assembles:
+
+- `["h", groupId]` — always first, required.
+- `["t", hashtag]` — extracted hashtags.
+- `["p", pubkey]` — NIP-27 mentions decoded from `nostr:npub…` in content.
+- NIP-10 marked reply tags when replying:
+  `["e", rootId, relay, "root", rootAuthor]` + `["e", replyId, relay, "reply", replyAuthor]`.
+- `["q", …]` — NIP-18 quotes for embedded nevent/naddr.
+- NIP-30 custom emoji tags, NIP-92 `imeta` tags for uploads.
+- **No `previous` tag** (see §1.4).
+
+Sending is **optimistic**: the event is signed locally, inserted into the
+timeline cache with a `pending` status, then sent. Because the id is computed at
+sign time, the relay's echo of the same event dedupes automatically against the
+optimistic copy (id match) and flips it to confirmed.
+
+### 2.4 Edit metadata / moderation (`useGroupModeration.ts`)
+
+All moderation is one small hook returning mutations, each a single pinned
+publish. Exact tag shapes:
+
+| Action | kind | tags |
+|--------|------|------|
+| putUser | 9000 | `[["h",g], ["p", pubkey, ...roles]]` |
+| removeUser | 9001 | `[["h",g], ["p", pubkey]]` (content = reason) |
+| deleteEvent | 9005 | `[["h",g], ["e", eventId]]` |
+| editMetadata | 9002 | `[["h",g], ...metadataTags(patch)]` |
+| deleteGroup | 9008 | `[["h",g]]` |
+| createInvite | 9009 | `[["h",g], ["code", code]]` |
+
+`metadataTags` emits antonym tags to clear flags (`public`/`open`) but only
+*asserts* `restricted`/`hidden` (no documented antonyms). After a successful
+moderation write, the relevant TanStack query keys are invalidated so the
+39xxx-derived views refetch.
+
+### 2.5 Invites (`InvitePeopleDialog.tsx`)
+
+Opening the invite dialog **immediately mints an invite and builds a link** — the
+"silly-easy part." Two-tier logic:
+
+1. **Prefer a relay-level claim (NIP-43 / zooid).** `useRelayClaim` queries the
+   relay for a `kind 28935` invite it issues to authed members; if present, its
+   `claim` tag value is the invite code.
+2. **Fall back to a per-group NIP-29 code (kind 9009).** If the relay issues no
+   claim, mint a random 6-byte code and publish `createInvite({ code })`.
+
+The shareable URL is `…/s/<relayParam>/<groupId>?code=<code>`. Anyone opening it
+hits `GroupPage`, which auto-joins using the `code` query param.
+
+### 2.6 Join / leave / membership (`useGroupMembership.ts`, `useRelayMembership.ts`)
+
+**Join (kind 9021)** is a two-step handshake, in this order:
+
+```ts
+// 1. Best-effort RELAY-level join first (zooid/Coracle relays gate ALL writes
+//    behind relay membership, rejecting non-members before group join is even
+//    considered). Ephemeral kind 28934 carrying the invite as a `claim` tag.
+//    NEVER throws — no-ops on relays that don't implement it (e.g. relay29).
+await joinRelay({ relayUrl, claim: code });
+
+// 2. The real NIP-29 group join. Same invite carried as a `code` tag.
+await publishEvent({ kind: 9021, content: reason, tags: [["h",g], ["code",code]], relay });
+//    "already a member" rejection is treated as success.
+```
+
+**Leave (kind 9022):** `publishEvent({ kind: 9022, tags: [["h",g]], relay })`.
+The relay auto-issues the corresponding 9001 remove-user.
+
+**Membership state** is derived per NIP-29 by querying the *latest* of
+`{kinds:[9000,9001], "#h":[g], "#p":[me]}` on the host relay — 9000 latest ⇒
+member, 9001 latest ⇒ not. Polls every 30s; 15s stale time.
+
+**Relay membership (NIP-43)** is its own layer, cleanly separated: `useRelayClaim`
+(fetch a 28935 claim), `useJoinRelay` (publish 28934 with the claim),
+`useLeaveRelay` (28936). All best-effort and non-throwing — the group join is the
+source of truth for the actual outcome.
+
+---
+
+## 3. How Armada displays information
+
+### 3.1 The three-pane Discord layout
+
+```
+┌────┬──────────────┬───────────────────────────┐
+│rail│ channel list │  message timeline          │
+│    │ (this relay) │  + composer                │
+│ 🟦 │  # general   │  ...kind 9 messages...     │
+│ 🟩 │  # random    │                            │
+│ ➕ │  # dev       │  [type a message]          │
+└────┴──────────────┴───────────────────────────┘
+ servers  channels          chat
+ =relays  =NIP-29 groups     =kind 9
+```
+
+- **`ServerRail.tsx`** — the far-left vertical rail. Each icon is a **relay**
+  (`{ kind: "server", url }`), fed by the pinned `PLATFORM_RELAYS` +
+  `config.addedRelays`. Supports Discord-style drag-to-reorder and **folders**.
+  (It also unifies in Concord E2EE communities, which are *not* NIP-29 — ignore
+  those.) Server order is synced to the kind-10009 `r` tags.
+- **`ChannelSidebar`** — for the selected relay, lists its groups via
+  `useRelayGroups(relayUrl)`.
+- **`GroupChat.tsx`** — the timeline + composer for the selected group.
+
+Selecting a relay first, then a room, is *exactly* the "select the relay first
+and then pick the rooms in each relay" UX in the ask. Folders are Armada's answer
+to "organization to group rooms on" — but note they group **relays**, not rooms;
+rooms are grouped implicitly by their host relay.
+
+### 3.2 Fetching a relay's channels (`useRelayGroups.ts`)
+
+Lists a relay's groups by querying `{kinds:[39000]}` on that relay. Key
+subtleties:
+
+- **Trust:** kind 39000 must be signed by the relay's own key. Armada reads the
+  relay's `self`/`pubkey` from its NIP-11 doc and adds `authors:[relaySelf]` so
+  **forged metadata from other publishers is never trusted**. Until NIP-11
+  resolves it races a direct fetch (2s) then refetches once when the key lands.
+- **Hidden groups:** relays hide closed/private groups from open listings, so the
+  ids the user *remembers* (their kind-10009 `group` tags for this relay) are
+  queried explicitly by `#d` and merged in.
+- **Provenance scoping:** several relays can share a signing key (zooid ships a
+  shared identity), so author-scoping alone bleeds channels across relays. Armada
+  records *which relay actually served* each cached event ("provenance") and
+  scopes the IndexedDB cache read by it. This is a real, painful edge case worth
+  remembering.
+- **Cache-as-floor:** cached events are merged *under* live ones so a sparse/flaky
+  relay read can only add, never clear the list. Long stale time (1h), no polling
+  — channel metadata is the most stable thing in the app.
+
+### 3.3 Fetching a group's roster (`useGroup.ts`)
+
+One query pulls the newest of `{kinds:[39000,39001,39002,39003], "#d":[groupId]}`
+(optionally author-scoped to the relay key) and composes
+`{ group, admins, members, roles }` (newest event per kind wins). **Local-first:**
+the plaintext 39xxx events are mirrored to IndexedDB, so a previously-opened
+group renders its roster instantly, with a background relay refresh.
+
+### 3.4 The message timeline (`useGroupMessages.ts`)
+
+The most sophisticated hook. For `(relayUrl, groupId)`:
+
+- **Timeline kinds:** kind 9 + kind 1068 (polls); live sub also watches kind 5
+  (deletions).
+- **Local-first + snapshot-first paint:** seeds from a synchronous localStorage
+  "last screenful" snapshot → IndexedDB store → background relay page, merged
+  append-only so nothing already shown is dropped.
+- **Scroll-up pagination:** `loadOlder()` walks an `until` cursor with a
+  gap-guard (Ditto's pattern) so a stale straggler doesn't leap the cursor past
+  real history.
+- **Live subscription:** one `req` with a 5-minute `since` lookback (so a message
+  that arrived via push before the group was opened still replays); dedupes by id;
+  processes kind-5 deletions by dropping referenced ids.
+- **Optimistic send status** map (`pending`/`failed`) reconciled by relay echo.
+- **Resilience:** 60s backstop poll + refetch-on-focus/reconnect to heal
+  half-dead mobile sockets where the live socket silently died.
+
+### 3.5 Group discovery / "home" (`useUserGroupList.ts`, kind 10009)
+
+The **cross-device source of truth** for a user's memberships is a single kind
+10009 event (NIP-51 "simple groups"):
+
+- `group` tags `["group", id, relay]` — joined groups (with host relay).
+- `r` tags `["r", relayUrl]` — servers/relays in use.
+- Both stored as **NIP-44 private items** (encrypted to self in `.content`);
+  read-modify-write via `useUpdateUserGroupList`. Armada persists the *decrypted*
+  list to disk ("folded cache") so boot doesn't pay a signer round-trip, and
+  refuses to write if it couldn't decrypt the prior list (avoids wiping it).
+
+There is also a `useGroupSearch` (NIP-50 `search` scoped by `#h`, merged with the
+local timeline cache) for in-group message search.
+
+### 3.6 What else rides on the `h` tag
+
+Armada extends the group with several kinds, all scoped by `["h", groupId]` so
+the relay routes/authorizes them: **pins** (kind 39041, an Armada extension,
+addressable `d`=groupId, admin-only), **calendar events** (NIP-52
+31922/31923/31925), **reactions** (kind 7), **threaded replies** (kind 1111
+NIP-22 comments), and **webxdc mini-apps** (9450/24450). All follow the same
+pattern: `["h", groupId]` + pin to host relay. Useful precedent that "anything
+can be a group event if it carries `h` and the relay accepts the kind."
+
+---
+
+## 4. Design constraints & gotchas (the expensive lessons)
+
+1. **Relay-scoping is absolute.** Group events go only to the host relay, and
+   group queries hit only the host relay. Amethyst's relay client fans out to
+   many relays by default — NIP-29 needs a *single-relay* send/subscribe path.
+2. **39xxx is relay-signed; trust it by the relay's own key.** Filter directory
+   queries by `authors:[relayNip11Pubkey]`. Never trust group metadata otherwise.
+3. **Shared relay identities bleed groups.** If you cache 39000 by author only,
+   two relays sharing a key cross-contaminate. Track per-relay provenance.
+4. **`previous` tags cause silent drops** unless you can guarantee refs are in the
+   relay's last-50 ring. Omit them for single-host groups.
+5. **Two membership layers.** NIP-29 group membership (9000/9001) is distinct from
+   relay-level membership (NIP-43, 28934/28935). Community relays (zooid) gate on
+   the latter *first*. Do the relay handshake best-effort, treat the group join as
+   authoritative.
+6. **Cache-as-floor everywhere.** A flaky relay returning nothing must never blank
+   a channel list or roster. Merge cache under live, never overwrite.
+7. **Optimistic UI needs local signing.** Sign locally, insert with pending
+   status, dedupe on relay echo by id.
+
+---
+
+## 5. Amethyst integration plan
+
+### 5.1 What already exists (survey)
+
+**Protocol (Quartz) — largely present.** `quartz/.../nip29RelayGroups/` already
+has:
+
+- `metadata/` — `GroupMetadataEvent` (kind **39000**), `GroupAdminsEvent`
+  (39001), `GroupMembersEvent` (39002), `SupportedRolesEvent` (39003).
+- `moderation/` — `CreateGroupEvent` (9007), `EditMetadataEvent` (9002),
+  `PutUserEvent` (9000), `RemoveUserEvent` (9001), `DeleteEventEvent` (9005),
+  `DeleteGroupEvent` (9008), `CreateInviteEvent` (9009), plus tag helpers.
+- `request/` — `JoinRequestEvent` (9021), `LeaveRequestEvent` (9022).
+- `tags/` — `GroupIdTag` (the `h` tag), `CodeTag`, `GroupAdminTag`, `RoleTag`,
+  and even a `PreviousTag`.
+
+**Relay membership (Quartz) — present.** `quartz/.../nip43RelayMembers/` has the
+full NIP-43 handshake Armada calls "relay membership": `RelayJoinRequestEvent`,
+`RelayInviteRequestEvent`, `RelayAddMemberEvent`, `RelayLeaveRequestEvent`,
+`RelayMembershipListEvent`, `ClaimTag`, `MemberTag`. There's even an
+`amethyst/.../ui/screen/loggedIn/relays/nip43/RelayMembersScreen.kt`.
+
+**The UX analog (commons + amethyst) — present and close.** The `ephemChat`
+feature (NIP-C7, kind **23333**) is a *relay-scoped* chat room:
+
+- `quartz/.../experimental/ephemChat/chat/EphemeralChatEvent.kt` — kind 23333,
+  with `RoomId(room, relayUrl)` — **the same `(relay, id)` shape as a NIP-29
+  address.**
+- `commons/.../model/emphChat/EphemeralChatChannel.kt` — `EphemeralChatChannel`
+  with `relays() = setOf(roomId.relayUrl)`, wired into `LocalCache`, `Account`,
+  `Note`, plus an `EphemeralChatListState`.
+- `amethyst/.../ui/screen/loggedIn/chats/publicChannels/ephemChat/` — a full UI:
+  `EphemeralChatScreen`, `LoadEphemeralChatChannel`, `EphemeralChatChannelHeader`,
+  `JoinChatButton`/`LeaveChatButton`, a `NewEphemeralChatScreen`, and datasource
+  sub-assemblers (`FilterMessagesToEphemeralChat`, etc.).
+
+So the Messages/Chats screen already hosts **four** conversation types:
+NIP-04/17 DMs, NIP-28 public channels, and NIP-C7 ephemeral chats — all under
+`chats/`. **NIP-29 groups become the fourth sibling.**
+
+### 5.2 The main protocol gap
+
+There is **no kind-9 group chat message event** in `nip29RelayGroups/`
+(`CreateInviteEvent` at 9009 is the highest kind present; nothing for kind 9).
+The 9xxx moderation, 39xxx metadata, and 9021/9022 request events exist, but the
+actual message carrier does not. This is the first thing to build:
+
+- `nip29RelayGroups/chat/GroupChatEvent.kt` — kind 9, `["h", groupId]` required,
+  NIP-10 reply markers, NIP-27 mentions, NIP-92 imeta, NIP-30 emoji — mirror
+  `ChannelMessageEvent` (NIP-28) which already does all of this, but swap the
+  channel `e`-root tag for the `h` group tag. Optionally kind 11 (thread) and
+  reuse NIP-22 `CommentEvent` for replies.
+
+Also verify the existing 39000–39003 parsers expose the flag tags
+(`private`/`closed`/`restricted`/`hidden`/`livekit`/`supported_kinds`) and roles
+per §1.3; extend if not.
+
+### 5.3 Recommended architecture mapping
+
+| Armada (React) | Amethyst target | Notes |
+|----------------|-----------------|-------|
+| `lib/nip29.ts` | `quartz/.../nip29RelayGroups/` | mostly exists; add kind-9 `GroupChatEvent` + any missing parsers |
+| `useNostrPublish({relay})` | a single-relay send in `commons/.../relayClient/` | **critical new capability**: publish/subscribe pinned to one relay |
+| `useRelayGroups` | a `RelayGroupsState` / filter assembler | query 39000 on one relay, author-scoped to its NIP-11 key |
+| `useGroup` | `GroupChannel` model + roster state | compose newest 39000–39003; mirror `EphemeralChatChannel` |
+| `useGroupMessages` | a NIP-29 `FeedFilter` + `FeedContentState` | reuse `chats/publicChannels/datasource` sub-assembler pattern |
+| `useUserGroupList` (10009) | an `Account` state object (like `ephemeralChatListState`) | NIP-44 private items; StateFlow of joined groups + servers |
+| `useGroupMembership` | membership derivation from 9000/9001 | latest-wins per NIP-29 |
+| `useRelayMembership` (NIP-43) | already in `nip43RelayMembers` + `RelayMembersScreen` | best-effort handshake before join |
+| `ServerRail` + `ChannelSidebar` | Android: a relay picker → channel list inside the Chats tab | see §5.4 |
+| `GroupChat` + `ChatComposer` | reuse the ephemChat/NIP-28 chat screen + composer | swap the datasource + send to kind 9 + `h` |
+
+**Placement per CLAUDE.md:** protocol → `quartz/`; the group model, list state,
+membership derivation, ViewModels/filters → `commons/` (so Desktop + CLI share);
+screen composables + navigation → `amethyst/` (bottom-nav) and `desktopApp/`
+(sidebar). The ephemChat feature is the template to copy for all three layers.
+
+### 5.4 Recommended Amethyst UX
+
+The ask floats three options; the study points to a clear answer:
+
+- **Not** a flat list of rooms mixed into the DM inbox. NIP-29 rooms are
+  relay-scoped and there can be many per relay — mixing them into the DM room
+  list loses the relay grouping and doesn't scale.
+- **Yes** to "select the relay first, then pick rooms in that relay." This is
+  Armada's model and it matches the protocol's addressing exactly. On Android
+  (bottom-nav, no room for a permanent Discord rail), the natural shape is:
+  - A **"Groups"/"Servers" entry inside the existing Chats tab** (alongside DMs,
+    Public Chats, Ephemeral Chats).
+  - Level 1: **your relays** (from kind-10009 `r` tags) — an "add relay" affordance
+    and each row shows unread rollup.
+  - Level 2: tap a relay → **its channels** (from `useRelayGroups`-equivalent),
+    with a create-channel action (subject to relay policy).
+  - Level 3: tap a channel → the **existing chat screen**, re-pointed at a NIP-29
+    kind-9 datasource.
+  - "Organization to group rooms on" = the **relay is the grouping**; add
+    Discord-style relay folders later if desired (Armada's `railLayout`).
+- Desktop can render the true three-pane rail (it already uses a sidebar shell).
+
+Deep-linking: adopt Armada's invite-link idea via Nostr-native addressing —
+`naddr` to the kind-39000 (kind + relay-key author + `d`=groupId + relay hint),
+plus an optional invite `code`. Amethyst already resolves `naddr`; a group `naddr`
+should route into the channel and, if a code is present, fire a 9021 join.
+
+### 5.5 Suggested build order
+
+1. **Quartz:** add `GroupChatEvent` (kind 9) + builders; confirm 39000 flag/role
+   parsing. Unit-test against Armada-produced events (spin up `./start.sh` or use
+   `chat.soapbox.pub`).
+2. **Relay client:** add a single-relay pinned publish + subscription path
+   (the `relay: relayUrl` equivalent). This unblocks everything else.
+3. **commons:** `GroupChannel` model + `UserGroupListState` on `Account` (kind
+   10009, mirror `EphemeralChatListState`) + membership derivation.
+4. **commons:** NIP-29 message `FeedFilter`/`FeedContentState` (copy the
+   ephemChat/NIP-28 sub-assembler; timeline kinds 9 + 1068 + 5).
+5. **amethyst:** relay-picker → channel-list screens in the Chats tab; re-point
+   the chat screen/composer at the kind-9 datasource; join/leave/create/invite
+   dialogs (reuse `nip43RelayMembers` for the relay handshake).
+6. **Later:** roles/moderation UI, pins, reactions, threads, calendar, LiveKit AV.
+
+### 5.6 Explicitly out of scope
+
+Armada's `concord-v1`/`concord-v2` directories are a **separate** end-to-end
+encrypted community protocol (sealed envelopes, rekeying) — *not* NIP-29. They
+share the chat *components* via a `ChatTransport` abstraction but nothing else.
+Ignore them for NIP-29. (The `ChatTransport` pattern — a presentational chat UI
+fed by a capability interface — is itself a nice idea worth borrowing so DMs,
+NIP-28, ephemeral, and NIP-29 all render through one component.)
+
+---
+
+## 6. Key file references
+
+**Armada (studied):**
+- `client/src/lib/nip29.ts` — constants, parsers, tag builders
+- `client/src/hooks/useNostrPublish.ts` — the `relay`-pinned publish chokepoint
+- `client/src/hooks/useGroupModeration.ts` — 9000/9001/9002/9005/9007/9008/9009
+- `client/src/hooks/useGroupMembership.ts` + `useRelayMembership.ts` — 9021/9022 + NIP-43
+- `client/src/hooks/useRelayGroups.ts` / `useGroup.ts` / `useGroupMessages.ts` — display
+- `client/src/hooks/useUserGroupList.ts` — kind 10009 home base
+- `client/src/components/layout/ServerRail.tsx` — Discord rail (relay = server)
+- `client/src/components/chat/ChatComposer.tsx` — kind-9 send + the `previous`-tag rationale
+- `client/src/components/dialogs/{CreateGroup,InvitePeople}Dialog.tsx`
+- `server/group.go`, `server/invites.go`, `server/unmanaged.go` — relay29 policy
+
+**Amethyst (integration surface):**
+- `quartz/.../nip29RelayGroups/**` — existing protocol events (add kind-9 chat)
+- `quartz/.../nip43RelayMembers/**` — relay membership handshake
+- `quartz/.../experimental/ephemChat/**` + `commons/.../model/emphChat/**` — the relay-scoped chat analog
+- `amethyst/.../ui/screen/loggedIn/chats/publicChannels/ephemChat/**` — UI template
+- `amethyst/.../ui/screen/loggedIn/relays/nip43/RelayMembersScreen.kt`
+- `quartz/.../nip28PublicChat/message/ChannelMessageEvent.kt` — the kind-9 builder to mirror

amethyst/plans/2026-07-10-concord-mobile-integration.md

@@ -0,0 +1,208 @@
+# Concord — Mobile Integration Plan (mirroring NIP-29 Relay Groups)
+
+## Context
+
+The Concord protocol engine is complete in `quartz/…/concord/` (CORD-01…07,
+~65 tests) and driven end-to-end by the `amy concord` CLI over a commons
+`ConcordActions` layer. This plan covers the **Android app integration**, and it
+deliberately **mirrors the just-merged NIP-29 relay-groups feature** — that work
+used Soapbox's Armada as a study base and established the exact Amethyst touch
+points a group-chat protocol should plug into. Wherever possible we clone the
+NIP-29 file structure with Concord equivalents rather than inventing parallels.
+
+Naming: user-facing = **"Concord Channels"** (Amethyst reserves "community" for
+NIP-72). Protocol-internal code keeps the spec term `community`.
+
+## The one structural difference from NIP-29
+
+NIP-29 group metadata (kind 39000) is **relay-signed and public**, so groups are
+browsable. Concord communities are **end-to-end encrypted**: the only public
+artifact is the addressable kind-33301 invite **bundle**, whose content is
+token-gated. Consequences for the mirror:
+
+- **Addressing** is by *derived stream pubkey* (`group_key.pk` per plane/epoch),
+  not `(hostRelay, groupId)`. A Concord channel lives at its plane address and
+  may be mirrored on several relays (the community's relay set), not pinned to
+  one host. So `ConcordChannel.relays()` = the community relay set.
+- **Discovery** cannot preview E2EE content. The discovery feed surfaces **public
+  invite links** (kind-33301 bundles + links shared in notes), filtered by
+  author/hashtag — the entry action is *redeem a link*, not *browse contents*.
+  This is a genuinely thinner surface than NIP-29; documented, not a bug.
+- **Membership = key possession**, verified locally from the folded Control Plane
+  + banlist (already implemented), not from relay-signed 39001/39002.
+
+## Per-account persistence & subscription model (Concord is between NIP-17 and NIP-28/29)
+
+Separate **addressing** from **encryption/membership** and Concord's place is clear:
+
+| Concern | NIP-28 | NIP-29 | NIP-17 | **Concord** |
+|---|---|---|---|---|
+| Find messages by | channel id | `(relay, h)` | `#p = me` | **`authors=[derived plane pk]`** |
+| Content | public | public | E2EE to you | **E2EE to a shared key** |
+| Decrypt with | — | — | your key | **per-channel derived conv key** |
+| Membership | open | relay roster | key possession | **key possession** |
+| "My rooms" home | follow list | kind-10009 | chatroom set | **kind-13302 (carries secrets)** |
+
+The decisive point: a Concord wrap's `p` tag is **ephemeral**, so you can never
+find messages with `#p = me` (the NIP-17 model). You subscribe **by author = the
+derived plane pubkey** (NIP-28/29 addressing), a query only a secret-holder can
+form, and decrypt with the shared plane key (NIP-17 E2EE).
+
+**Home base = kind-13302 `ConcordCommunityList`** (built in quartz): NIP-44
+self-encrypted, replaceable, relay-synced. Unlike NIP-17 (only secret is your
+identity key) or NIP-29 (public group tags), **each entry carries the community
+secrets** (`community_root`, salt, epoch, private-channel keys). Same trust model
+as NIP-17's recoverable giftwrapped history: a leaked nsec exposes them, nothing
+worse. `ConcordChannelListState` wraps 13302 exactly like `RelayGroupListState`
+wraps 10009 / `EphemeralChatListState` wraps its list — **same wiring, entries
+hold keys.**
+
+**In-memory projection (LocalCache):** `ConcordChannel` keyed by
+`(communityId, channelId)`, holding the folded Control-Plane state + decrypted
+messages — recomputed from events, never persisted as identity (the NIP-28/29
+half).
+
+**Subscription = per-plane author REQ, fanned out from the joined list** — not a
+single `#p=me` catch-all. `ConcordMyChannelsFilterAssembler` (mirrors NIP-29's
+`RelayGroupMyJoinedGroupsFilterAssembler`) walks `account.concordChannelList`,
+derives each community's control-plane + channel-plane addresses, and issues
+`{kinds:[1059], authors:[planePk]}` per plane across the community's relays.
+
+**Secrets at rest:** relay copy is self-NIP-44-encrypted (13302); the on-device
+mirror can be wrapped with `commons/keystorage`.
+
+## Layering (same as NIP-29)
+
+- `quartz/…/concord/` — protocol (done)
+- `commons/…/model/concord/` — `ConcordChannel`, `ConcordChannelListState`,
+  membership/view-mode enums, discovery constraint (platform-agnostic)
+- `amethyst/…/chats/publicChannels/concord/` — screens, feed filters, datasource
+  subassemblers, navigation
+- `commons/…/actions/ConcordActions.kt` — builders/filters/folding (done)
+- `cli/…/commands/Concord*Commands.kt` — verbs (done; already matches the
+  `RelayGroupCommands` route+verb-map pattern)
+
+## Mirror map (NIP-29 file → Concord equivalent)
+
+### commons state
+- `model/nip29RelayGroups/RelayGroupChannel.kt` → **`model/concord/ConcordChannel.kt`**
+  — a `Channel` subclass keyed by a `ConcordChannelId(communityId, channelId)`,
+  holding the folded `ConcordCommunityState` + this channel's messages StateFlow,
+  `relays()` = community relay set, `membershipOf()` from the authority resolver,
+  `placeholderNote()`.
+- `RelayGroupListState.kt` → **`model/concord/ConcordChannelListState.kt`** —
+  backed by the **kind-13302** joined-communities list (already in quartz:
+  `ConcordCommunityList`). Exposes `liveCommunities: StateFlow<List<Entry>>` and
+  `liveServers: StateFlow<Set<communityId>>`. `join(community)`/`leave` do
+  read-modify-write of the 13302 event. Mirrors `EphemeralChatListState`.
+- `RelayGroupMembership.kt` → **`ConcordMembership.kt`** (OWNER/ADMIN/MEMBER/BANNED/
+  NONE) derived from `AuthorityResolver` (rank + banlist).
+- `RelayGroupViewMode.kt` → **`ConcordViewMode.kt`** (INLINE/GROUPED).
+- `model/nip29RelayGroups/GroupDiscoveryConstraint.kt` → **`ConcordDiscoveryConstraint.kt`**
+  (AllPublic / ByPeople / ByHashtags) matching against a public invite bundle.
+
+### Account wiring (`amethyst/…/model/Account.kt`)
+Add right after the `relayGroupList` lines (~382): a
+`ConcordChannelListState(signer, cache, decryptionCache, scope, settings)` field
++ its decryption cache. Action methods next to `joinRelayGroup` (~1472):
+`createConcordCommunity`, `joinConcordFromLink`, `postConcordMessage`,
+`createConcordInvite`, `banConcordMember`, `follow/unfollow(ConcordChannel)` →
+delegate to `ConcordChannelListState`. Writes go through the community relay set.
+Add `concordViewMode` to `AccountSettings.kt`.
+
+### LocalCache (`amethyst/…/model/LocalCache.kt`)
+Add a `LargeCache<ConcordChannelId, ConcordChannel>` index + `getOrCreateConcordChannel`,
+and route inbound kind-1059 wraps on known plane addresses into the fold (decrypt
+→ edition/message). Mirrors `getOrCreateRelayGroupChannel`.
+
+### Messages inbox integration (THE key mirror)
+- `chats/rooms/dal/ChatroomListKnownFeedFilter.kt` + `ChatroomListNewFeedFilter.kt`
+  — extend the 5-way `feed()` concatenation to **6-way**: add a `concordChannels`
+  block reading `account.concordChannelList.liveCommunities`, branching on
+  `concordViewMode` (INLINE = one row per channel via
+  `LocalCache.getOrCreateConcordChannel(...).newestChatNote() ?: placeholderNote()`;
+  GROUPED = one synthetic `ConcordServerRoomNote(communityId, newest)` per
+  community). Update `applyFilter`/`updateListWith` with a
+  `filterRelevantConcordMessages(...)` keyed by `concordRowKey()`.
+- `chats/rooms/dal/RelayGroupServerRoomNote.kt` → **`ConcordServerRoomNote.kt`** —
+  synthetic event-less Note collapsing a community's channels into one inbox row.
+- `chats/rooms/ChatroomHeaderCompose.kt` — add `rendersWithoutEvent` branches for
+  `ConcordServerRoomNote` and channel placeholders; `ConcordServerRoomCompose` →
+  `Route.ConcordServer(communityId)`; `ConcordRoomCompose` (chip = community name)
+  → `routeFor(channel)`. **This is where the "chip opens the Concord Channel"
+  requirement lands.**
+
+### Screens (`amethyst/…/chats/publicChannels/concord/`, mirror `relayGroup/`)
+- `ConcordServerList.kt` (community rows) · `ConcordChannelListScreen.kt(communityId)`
+  (a community's channels, from the folded Control Plane) ·
+  `ConcordChatScreen.kt(communityId, channelId, …)` (top-level route target) ·
+  `ConcordChannelView.kt` (reuse the NIP-28 `ChannelFeedViewModel`/`ChannelView`
+  stack via the `ConcordChannel: Channel` subclass) · `ConcordMembersScreen.kt` ·
+  `ConcordMetadataScreen.kt`/`ViewModel.kt` (create/edit) · `ConcordTopBar.kt`
+  (name + role badge + Members/Edit/Invite/Ban/Leave menu) · `LoadConcordChannel.kt`.
+- Compose composer gated on `membershipOf(me).isMember()`; else a "redeem an
+  invite to post" notice.
+
+### Discovery feed (GitRepositories-style triad; thinner than NIP-29)
+- `concord/dal/ConcordDiscoveryFeedFilter.kt` (`AdditiveFeedFilter<Note>` over
+  public kind-33301 bundles; "My Communities" branch = the 13302 list) +
+  `concord/dal/ConcordDiscoveryConstraint.kt` bridge +
+  `concord/datasource/subassemblies/FilterConcordBundlesBy{Authors,Follows,Hashtag}.kt`.
+  `ConcordDiscoveryScreen.kt` = `DisappearingScaffold` + `FeedFilterSpinner` +
+  `RenderFeedContentState` with `ConcordDiscoveryCard` (name + Join button). FAB →
+  `ConcordBrowse`/redeem-link.
+
+### Navigation (`ui/navigation/routes/Routes.kt` + `AppNavigation.kt`)
+`@Serializable` routes: `Concord`(communityId, channelId, +draftId?/inviteToken?),
+`ConcordServer`(communityId), `ConcordMembers`, `ConcordCreate`, `ConcordEdit`,
+`Concords`(object, bottom-nav → discovery), `ConcordBrowse`. `RouteMaker.routeFor(ConcordChannel)`
++ deep-link: an invite URL/`nostr:`-embedded link → `Route.Concord(..., inviteToken=…)`,
+auto-redeeming on open (mirror NIP-29's inviteCode auto-join). Wire through
+`BouncingIntentNav.kt`.
+
+### Invite/redeem UI + linkification
+- `InviteConcordDialog.kt` (moderator: mint + share link via `ConcordActions.mintInviteLink`)
+  · `JoinConcordDialog.kt` (paste a link → redeem) · `ui/components/ConcordInviteCard.kt`
+  (render a link as a preview card; tap → `Route.Concord(inviteToken)`) ·
+  `ui/components/ClickableConcordInviteLink.kt` (inline linkify shared invite URLs).
+
+### Notifications (your explicit ask)
+Route a Concord message notification click to the **channel chat**, not the feed:
+in the notification builder + `BouncingIntentNav`, map a Concord message
+notification to `Route.Concord(communityId, channelId)`. Mirror how NIP-29
+group notifications resolve via `routeFor`.
+
+### Zaps & likes
+Because `ConcordChannel` extends `Channel` and messages render through the shared
+`ChannelView`, reactions (kind 7) and zaps attach through the existing chat
+reaction/zap path — but they must be **wrapped on the channel plane** (kind-7/9735
+rumors sealed like messages, bound to channel+epoch), not published in the clear.
+Add `ConcordActions.buildReaction`/`buildZapRequest` that wrap on the plane, and
+point the shared reaction/zap affordances at them for Concord notes.
+
+## Build order (each a tested, shippable slice)
+1. **commons foundation** — `ConcordChannel`, `ConcordChannelListState` (13302),
+   membership/view-mode enums; unit tests. Wire into `Account.kt` + `AccountSettings`.
+2. **LocalCache index** + inbound wrap folding.
+3. **Messages inbox** 6-way concat + `ConcordServerRoomNote` + header render/nav
+   (delivers the chip-opens-channel behavior).
+4. **Chat screens** (reuse NIP-28 `ChannelView`) + nav routes + create/invite/join.
+5. **Discovery feed** triad (public invite bundles).
+6. **Notifications routing + zaps/likes on-plane.**
+
+## Verification
+- commons: `:commons:jvmTest` unit tests for `ConcordChannelListState` (13302
+  round-trip/merge) and `ConcordChannel` folding, mirroring
+  `RelayGroupListDecryptionTest`/`RelayGroupChannelTest`.
+- Android: `:amethyst:installDebug`; create a community, see it in Messages with a
+  chip, tap → channel opens, send/receive between two emulators, redeem an invite
+  link deep-link, verify a notification click opens the chat. Cross-check against
+  `amy concord` (same relay) for wire interop, and against Armada for protocol
+  interop (`Nip29ArmadaInteropTest` is the precedent).
+
+## Gotchas carried from the NIP-29 study
+- Membership has two independent layers (Concord authority vs NIP-43 relay
+  membership); we only implement Concord authority.
+- Cache-as-floor + optimistic local signing for snappy UX.
+- E2EE means no server-side moderation and no metadata preview — surface state
+  from the local fold only.

amethyst/plans/2026-07-12-dual-reply-minichat.md

@@ -0,0 +1,113 @@
+# Dual-mode replies: inline + "minichat" threads across all chats
+
+## Goal
+
+Give every Amethyst chat two ways to reply, chosen at send time:
+
+- **Inline reply** — a normal chat message that references its parent and stays in
+  the main timeline (today's behavior). On the wire this is the chat protocol's
+  native reply: NIP-C7 kind-9 with a `q` quote (Concord), kind-42 reply (NIP-28),
+  kind-9 `+h` reply (NIP-29), kind-14 reply (NIP-17 DM).
+- **Minichat reply** — a **kind-1111 NIP-22 `CommentEvent`** rooted at the parent
+  message. It is pulled *out* of the main timeline and shown in a separate
+  **minichat** ("chat within a chat") opened from the parent. This matches Soapbox
+  Armada exactly (kind-9 `q` = inline quote, kind-1111 = thread).
+
+The rule is uniform and protocol-agnostic: **any kind-1111 whose root is a chat
+message opens as that message's minichat.** So the same treatment automatically
+covers Concord kind-9, NIP-28 kind-42, NIP-29 kind-9, and (later) NIP-17 kind-14 —
+wherever a 1111 lands on a chat message.
+
+## Reuse survey (what already exists — do NOT rebuild)
+
+| Need | Reuse |
+|---|---|
+| kind-1111 reply builder (NIP-22 `K/E/P`+`k/e/p`) | `quartz/.../nip22Comments/CommentEvent.replyBuilder`; Concord's `ChannelChat.reply` already uses it |
+| 1111 → parent wiring | `LocalCache.computeReplyTo` (CommentEvent branch) → `parentNote.replies`; minichat content = `note.replies.filter { it.event is CommentEvent }` |
+| "N replies" chip | `observeNoteReplyCount(note, avm)` (EventObservers.kt) — already used by `RelayGroupThreadsScreen` |
+| Shared per-row action strip | `ChatMessageCompose.NormalChatNote` `detailRow` `Row` — one place, every chat type |
+| Thread rendering | `threadview/ThreadFeedView` + `ThreadAssembler.findThreadFor`; NIP-29 `RelayGroupThreadsScreen` as the chat-adjacent precedent |
+| Per-message 1111 REQ (public chats) | `FilterRepliesAndReactionsToNotes` (kinds incl 1111, `#e`) via `EventFinder`; `RelayGroupThreadFeedFilterAssembler` (compose-scoped `#h`+1111 sub) |
+| Composer reply state + "replying-to" preview | `*NewMessageViewModel.replyTo` + `chats/utils/DisplayReplyingToNote` |
+| NIP-22 comment composer | `note/nip22Comments/CommentPostViewModel` (full-featured) |
+
+Concord already delivers kind-1111 replies through the existing channel-plane
+subscription (they're wrapped like every other rumor), so **no new subscription is
+needed for Concord** — only the timeline split, the chip, the minichat screen, and
+the composer picker.
+
+## Design
+
+### 1. Wire model (settled — matches Armada)
+- Inline reply → native chat reply event, native reply tags, stays in timeline.
+- Minichat reply → kind-1111 `CommentEvent`: uppercase `K/E/P` at the immutable
+  thread root (the chat message), lowercase `k/e/p` at the immediate parent, plus
+  whatever binding the plane requires (Concord: `channel`/`epoch`). One level:
+  replying inside a minichat roots the new 1111 at the **same** root message
+  (parent = the message being answered, root = the minichat root), rendered flat —
+  so minichat messages don't spawn sub-threads. (The wire still permits nesting;
+  we render flat.)
+
+### 2. Timeline vs minichat split (rendering)
+- **Main feed** excludes kind-1111 comments whose root is a chat message — they
+  live in the minichat, not as flat siblings. Implemented in the shared
+  `ChannelFeedFilter` / `ChatroomFeedFilter` by dropping `CommentEvent`s that root
+  onto a message already in the feed (keep everything else).
+- Each root message row shows an **"N replies" chip** (from `observeNoteReplyCount`
+  restricted to CommentEvent replies) in the `detailRow` strip; tap → minichat route.
+
+### 3. Minichat screen
+- A thread screen keyed by the **root message id** (+ the channel/room key needed to
+  re-derive the plane / re-subscribe). Renders the root message pinned at top, then
+  its kind-1111 replies as a flat mini-timeline (reuse `ChatroomMessageCompose`), with
+  its own composer that always sends kind-1111 rooted at this message.
+- Back it with `ThreadFeedView`/`ThreadAssembler` where possible; for Concord, feed
+  it from `rootNote.replies` (already populated) + a lifecycle sub that keeps the
+  plane live.
+
+### 4. Composer mode picker
+- Add `replyMode: ReplyMode {INLINE, MINICHAT}` next to `replyTo` in each
+  `*NewMessageViewModel` (Concord `ConcordNewMessageViewModel`, DM
+  `ChatNewMessageViewModel`, channels `ChannelNewMessageViewModel`).
+- Render a small toggle beside `DisplayReplyingToNote` ("Reply in chat" ⇄ "Reply in
+  thread"). Default = INLINE (least surprise; user opts into pulling it aside).
+- Send branch: `MINICHAT` routes to the kind-1111 builder
+  (`CommentEvent.replyBuilder` / Concord `buildChannelReply`), `INLINE` keeps the
+  native reply builder.
+
+### 5. Subscriptions
+- **Concord**: none new (1111 arrives via the channel plane). Just ensure the
+  timeline filter and minichat read `rootNote.replies`.
+- **NIP-28 / NIP-29 (phase 2)**: add a compose-scoped assembler (clone
+  `RelayGroupThreadFeedFilterAssembler`) that REQs `{kinds:[1111], "#e":[<visible
+  message ids>]}` (and `#E`) off the feed's current message-id set (from
+  `FeedContentState`). Reuse the same minichat screen/row.
+- **NIP-17 DM (phase 3, later)**: kind-1111 replies must be gift-wrapped like the
+  kind-14s; deferred — needs an encrypted-comment path, more design.
+
+## Phasing
+
+1. **Phase 1 — Concord, full UX + all shared pieces.** ReplyMode enum + composer
+   toggle; timeline split (drop chat-rooted 1111s); "N replies" chip in the shared
+   `detailRow`; minichat route + screen; Concord send branch. Delivers the complete
+   dual-mode experience for Concord and builds every shared component.
+2. **Phase 2 — public chats.** Per-message 1111 subscription for NIP-28 + NIP-29;
+   reuse the Phase-1 chip/screen/composer. NIP-29 already has a thread screen to
+   reconcile with.
+3. **Phase 3 — DMs.** Gift-wrapped kind-1111 minichat for NIP-17. Deferred.
+
+## Decisions (settled)
+- **Default mode** when tapping reply: **INLINE**. User opts into MINICHAT via the toggle.
+- **Minichat depth**: **flat, one level**. Replying inside a minichat roots at the
+  same message; no sub-threads.
+- **Scope now**: **Phase 1 + 2 together** — Concord AND public chats (NIP-28/NIP-29).
+  DMs (phase 3) still deferred.
+- **Screen styling**: **chat-styled bubbles** (reuse `ChatroomMessageCompose`) so the
+  minichat reads as "a chat within a chat".
+
+## Verification
+- quartz/commons unit tests for the reply-mode builders + the timeline-filter split
+  (a chat-rooted 1111 is excluded from the feed but present in `rootNote.replies`).
+- On-device: in Concord, reply inline (stays in timeline) and reply-in-thread (opens
+  minichat); confirm Armada shows our minichat replies as a thread and its threads
+  open as our minichat; confirm the "N replies" chip count.

amethyst/plans/2026-07-12-relay-ping-interval-study.md

@@ -0,0 +1,245 @@
+# WebSocket Ping Interval Study — 122 Production Relays
+
+**Date:** 2026-07-12
+**Question:** Would relays drop Amethyst's connections if the client WebSocket
+ping interval were raised (e.g. 120s → 240s on mobile data to save battery)?
+Was the long-standing 120s value ever load-bearing, and what is the best
+middle ground?
+
+**Answer (TL;DR):** Keep a single **120s** ping interval on every network.
+Raising it to 240s saves almost no battery — 90% of surveyed relays send
+their *own* pings every 30–70s, which OkHttp must answer, so the radio's
+wake cadence is set by the relays, not by our interval — and it starts
+dropping real relay tiers: 240s pings lose `relay.ditto.pub` (~240s idle
+timeout) and every `nostr1.com`-hosted relay (~300s tier); 300s pings even
+lose `relay.snort.social` (~600s tier). Lowering below 120s would only
+rescue a ~120s tier of 6/122 relays that already cycle today, at 2× the
+ping traffic on every other connection. 120s is, by measurement, the sweet
+spot it was presumably never designed to be.
+
+---
+
+## 1. Motivation
+
+`OkHttpClientFactoryForRelays` sets `pingInterval(120s)` on every relay
+WebSocket. During battery work the interval was tentatively doubled on
+mobile data on the theory that each client ping on an otherwise-idle
+cellular connection wakes the radio and pays the multi-second tail-energy
+cost. The maintainer asked the right question: *do we actually know how
+production relays react to different ping intervals?* Nobody had tested
+the 120s value. This study answers it empirically.
+
+Two distinct drop mechanisms are in play:
+
+1. **Relay/reverse-proxy idle timeouts** — testable from any vantage.
+2. **Carrier NAT idle timeouts** — only testable from a real cellular
+   network (not from this environment; see §7).
+
+## 2. Relay population
+
+Production relays were harvested by fetching **600 kind:10002 (NIP-65)
+relay-list events** from indexer relays (`indexer.coracle.social`,
+`user.kindpag.es`) and counting `r`-tag references: **1,468 distinct
+relays**, ranked by how many users actually list them. The **top 140**
+(plus all Amethyst default relays) formed the test population.
+
+- **122 relays accepted a WebSocket** from the test vantage.
+- 18 were unreachable *from a datacenter IP* (Cloudflare 403 challenges:
+  `nostr.wine`, `relay.0xchat.com`; TCP resets: `relay.nostr.band`,
+  `nostr.bitcoiner.social`, `relayable.org`, `nostr.fmt.wiz.biz`; plus
+  ordinary 5xx/410s). These blocks are IP-reputation-based, not
+  ping-related, and don't affect the conclusions — but they mean the
+  study cannot speak for those relays.
+
+## 3. Method
+
+Three experiments, all through the same stack (Python `websocket-client`,
+TLS, one REQ per connection whose filter matches nothing, so the relay
+answers EOSE and the connection then carries zero application traffic).
+Server pings were always answered with pongs automatically (as OkHttp
+does) and logged.
+
+- **Phase A — idle survival.** 140 relays, **zero client pings**, hold
+  for **780s (13 min)**. Records: drop time, close code, server-ping
+  timestamps. A relay surviving 780s of total client-ping silence proves
+  *any* client interval ≤ 780s is safe for it.
+- **Phase B — ping efficacy.** Every Phase A dropper re-tested with
+  client pings at **55 / 110 / 120 / 180 / 240 / 300s** (one connection
+  per interval, window = observed idle timeout + 2 ping cycles + margin,
+  capped at 780s). This distinguishes "pings reset the relay's idle
+  timer" from "only data frames count".
+- **Case study —** `relay.ditto.pub` with 60s pings for 420s (it had
+  dropped an idle connection at 257s while *its own* ping got our pong at
+  123s — proving pongs don't reset its timer but client pings do).
+
+## 4. Phase A results — idle survival with zero client pings
+
+**99 of 122 relays (81%) survived 13 minutes of complete client-ping
+silence.** For four out of five relays, the client ping interval is
+irrelevant to connection survival at any plausible value.
+
+The 23 droppers cluster into clean idle-timeout tiers:
+
+| Tier | Count | Relays |
+|---|---|---|
+| < 30s (probe rejected / non-idle close) | 2 | `nostr.petrkr.net/strfry`, `next.nsite.run` |
+| **~60s** | 8 | `nostr.pareto.space` (47s), `nostr.vps.satsnode.xyz` (×2), `relay.mostro.network`, `nostr.bond/alpha`, `nostr.sgiath.dev`, `nostr.bitcoinplebs.de`, `nostr.schneimi.de` |
+| **~120s** | 8 | `cfrelay.snowcait.workers.dev` (118s), `nostr-verified.wellorder.net` (120.7s), `nostr-pub.wellorder.net` (120.8s), `git.shakespeare.diy` (125.7s), `nostr-relay.irgenius.org` (126.0s), `nostr-verif.slothy.win` (126.1s), `nostr.bit4use.com` (126.6s), `sendit.nosflare.com` (131.4s) |
+| **~240s** | 1 | `relay.ditto.pub` (240.9s; 257.1s in an earlier run) |
+| **~300s** | 2 | `david.nostr1.com` (300.5s), `dkkc.nostr1.com` (300.7s) — i.e. the **nostr1.com / relay.tools hosting tier** |
+| **~600s** | 2 | `nos.lol/<haven path>` (600.8s), `relay.snort.social` (601.0s) |
+
+### Server-ping cadence (the finding that reframes the question)
+
+Among the 99 relays that held an idle connection for the full window:
+
+| Server→client ping cadence | Relays |
+|---|---|
+| ≤ 35s | 45 |
+| 36–70s | 37 |
+| ~300s | 8 |
+| no server pings at all | 9 |
+
+**90 of 99 relays ping the client; 82 of them every ≤ 70s.** OkHttp
+answers every server ping with a pong regardless of the client-side
+`pingInterval`. So on a connected cellular device the radio is being
+woken every 30–70s *per connection* by the relays themselves. Changing
+the client interval from 120s to 240s does not change that cadence at
+all — the client ping is a rounding error in the connection's keepalive
+traffic. **The claimed battery saving of a longer client ping interval
+does not exist in practice.** (Corollary: the real mobile-battery lever
+is connected time and connection count in the background — which the
+app already minimizes by disconnecting 30s after backgrounding — not
+the ping schedule.)
+
+## 5. Phase B results — which client intervals keep the droppers alive
+
+For every idle-dropper, one connection per candidate interval
+(`x@T` = dropped at T seconds despite pinging at that interval;
+`skip` = interval ≥ observed idle timeout, unsafe by construction):
+
+| relay | idle-drop | 55s | 110s | 120s | 180s | 240s | 300s | max safe |
+|---|---|---|---|---|---|---|---|---|
+| nostr.pareto.space | 46.9s | skip | skip | skip | skip | skip | skip | none |
+| nostr.vps.satsnode.xyz | 51.1s | skip | skip | skip | skip | skip | skip | none |
+| nostr.vps.satsnode.xyz/… | 51.2s | skip | skip | skip | skip | skip | skip | none |
+| relay.mostro.network | 60.5s | x@60.8 | skip | skip | skip | skip | skip | none |
+| nostr.bond/alpha | 60.8s | x@60.9 | skip | skip | skip | skip | skip | none |
+| nostr.sgiath.dev | 60.8s | x@60.9 | skip | skip | skip | skip | skip | none |
+| nostr.bitcoinplebs.de | 60.9s | x@61.1 | skip | skip | skip | skip | skip | none |
+| nostr.schneimi.de | 62.2s | x@61.1 | skip | skip | skip | skip | skip | none |
+| cfrelay.snowcait.workers.dev | 118.2s | x@85.0 | x@74.5 | skip | skip | skip | skip | none |
+| nostr-verified.wellorder.net | 120.7s | **OK** | x@120.7 | x@120.8 | skip | skip | skip | 55s |
+| nostr-pub.wellorder.net | 120.8s | **OK** | x@120.8 | x@120.8 | skip | skip | skip | 55s |
+| git.shakespeare.diy/… | 125.7s | **OK** | x@125.9 | x@126.1 | skip | skip | skip | 55s |
+| nostr-relay.irgenius.org | 126.0s | **OK** | x@125.8 | x@125.9 | skip | skip | skip | 55s |
+| nostr-verif.slothy.win | 126.1s | **OK** | x@126.1 | x@126.3 | skip | skip | skip | 55s |
+| nostr.bit4use.com | 126.6s | **OK** | x@126.4 | x@126.5 | skip | skip | skip | 55s |
+| sendit.nosflare.com | 131.4s | x@81.7 | x@41.9 | x@7.0 | skip | skip | skip | none |
+| **relay.ditto.pub** | 240.9s | OK | OK | **OK** | x@673.5 | **x@609.8** | skip | **120s** |
+| **david.nostr1.com** | 300.5s | OK | OK | **OK** | x@300.6 | **x@300.7** | x@300.7 | **120s** |
+| **dkkc.nostr1.com/…** | 300.7s | OK | OK | **OK** | x@300.7 | **x@301.1** | x@300.6 | **120s** |
+| nos.lol/<haven path> | 600.8s | OK | OK | OK | OK | OK | x@602.1 | 240s |
+| **relay.snort.social** | 601.0s | OK | OK | OK | OK | OK | **x@607.7** | 240s |
+
+Key observations:
+
+1. **A client ping interval numerically below the idle timeout is NOT
+   sufficient.** 180s and 240s pings failed against the ~300s
+   `nostr1.com` tier, and 300s pings failed against the ~600s
+   `snort.social` tier, even though each ping "should" have arrived in
+   time. The empirical rule across every tier: **pings only reliably
+   reset a relay's idle timer when the interval is at most roughly half
+   the timeout.** (Likely cause: these stacks check activity in coarse
+   windows rather than resetting a precise per-frame deadline, so an
+   interval near the window size loses boundary races.)
+2. The **~60s tier is unsalvageable** — even 55s pings didn't help
+   (their timers count only data frames). These 8 relays drop idle
+   Amethyst connections *today* under the 120s setting and would under
+   any setting; the existing reconnect-on-demand path is the correct
+   handling for them.
+3. The **~120s tier is only rescued by ≤55s pings** — meaning
+   **today's 120s interval never kept them alive either** (110s and
+   120s pings both failed). They cycle today; they'd cycle at 240s.
+   No candidate change affects them.
+4. The tiers that DO depend on our ping interval are exactly
+   **ditto (~240s), nostr1.com (~300s), and snort/nos.lol-haven
+   (~600s)** — and 120s holds all of them, while 240s loses the first
+   two and 300s loses all three.
+
+Connections kept alive (of 122 reachable), by candidate interval:
+**55s → 110 · 120s → 104 · 240s → 101 · 300s → 99.**
+
+The `relay.ditto.pub` case study confirms the mechanism: with an idle
+connection its *own* ping at t=123s received our pong and it still
+closed at 257s (pongs don't count as activity), but with 60s client
+pings it stayed up indefinitely (client pings do count).
+
+## 6. Why not go lower than 120s?
+
+55s pings would rescue the ~120s tier (6 relays). But:
+
+- those relays already cycle today, so the status quo loses nothing;
+- 55s pings double the client-ping traffic on all ~100+ connections to
+  rescue 5% of relays whose operators chose aggressive timeouts;
+- the radio is already woken every ≤70s on 82/122 connections by server
+  pings, so the *incremental* battery cost is modest — but so is the
+  benefit, and drop/reconnect for those 6 relays is already handled
+  gracefully by `BasicRelayClient`'s backoff + the keep-alive sweep.
+
+A per-relay adaptive interval (shorten pings only for relays observed to
+drop idle connections) is possible future work, but OkHttp's
+`pingInterval` is per-client, not per-socket, so it would require
+per-relay client instances — not worth the complexity for 6 relays.
+
+## 7. Carrier NAT — the part this study cannot measure
+
+The other purpose of client pings is keeping carrier NAT/firewall
+mappings alive on cellular. That is untestable from a datacenter vantage.
+Published measurements and platform folklore put aggressive carrier TCP
+idle timeouts around 4–5 minutes (most are 15–30 min; FCM survives on
+~28 min heartbeats *with OS cooperation Amethyst doesn't get*). 120s
+sits comfortably inside even the aggressive bound, so relay-side and
+NAT-side constraints agree on the same answer. Anyone wanting to raise
+the interval later must first re-run Phase B *and* validate on real
+cellular networks — the relay data alone already rules out 240s.
+
+## 8. Decision
+
+- **`WEBSOCKET_PING_INTERVAL_SECS = 120`, one value for wifi and mobile.**
+  The tentative 240s mobile value was reverted in this same branch after
+  these measurements: it saved ~nothing (server pings dominate radio
+  wakes) and dropped the ditto and nostr1.com tiers.
+- OkHttp's `pingInterval` doubles as the dead-connection detector (a
+  missed pong fails the socket within one interval), so 120s also keeps
+  failure detection twice as fast as 240s would — relevant after silent
+  network path changes.
+
+## 9. Reproduction
+
+Vantage caveats: datacenter egress IP (18 relays refused it), all
+traffic via an HTTP CONNECT proxy. A control connection with 100s pings
+survived every window, ruling out proxy-imposed idle limits ≤ 780s.
+
+Sketch (Python `websocket-client`): open `wss://` to each relay, send
+one REQ whose filter matches nothing (`{"kinds":[1],"authors":["00…01"],
+"limit":1}`), auto-pong server pings, and either never ping (Phase A,
+780s window) or ping at the candidate interval (Phase B). Log connect /
+EOSE / server-ping / close timestamps. Population: top-N relays by
+`r`-tag frequency across kind:10002 events fetched from indexer relays.
+
+## Appendix — Phase A survivor cadences (99 relays)
+
+Server-ping cadence measured over the 13-minute window. `none` means the
+relay sent no pings at all and still held the idle connection.
+
+| cadence | relays |
+|---|---|
+| ~25–35s | `articles.layer3.news`, `aegis.relayted.de`, `assistantrelay.rodbishop.nz`, `bots.utxo.one`, `custom.fiatjaf.com`, `dev.calendar-relay.edufeed.org`, `greensoul.space` (×2), `groups.0xchat.com`, `groups.satsdisco.com`, `h.codingarena.top/inbox`, `haven.calva.dev/inbox`, `haven.nostrfreedom.net`, `haven.relayted.de`, `hist.nostr.land`, `lang.relays.land` (×3), `nexus.libernet.app`, `nip17.com`, `nostr-01.uid.ovh`, `nostr-relay.derekross.me` (×2), `nostr.damupi.com/inbox`, `nostr.easydns.ca`, `nostr.kfx.fr` (×2), `nostr.land`, `nostr.nothing.is-lost.org/haven`, and 17 more at ~30s; `nostrelites.org`, `purplepag.es`, `relay.noswhere.com` at ~30s |
+| ~55–70s | `nostr.thalheim.io`, `nostr.xmr.rocks`, `offchain.pub`, `relay.mostr.pub`, `relay.nostr.net`, `relay.primal.net`, `relay.damus.io`, `indexer.coracle.social`, `directory.yabu.me`, `user.kindpag.es`, `profiles.nostr1.com`, `nostr.oxtr.dev`, and ~25 more |
+| ~300s | `nostr-relay.corb.net`, `nostr.001.j5s9.dev`, `nostr.8777.ch`, `nostr.einundzwanzig.space`, `nostr.mikoshi.de`, `nostr.pbfs.io`, `nostr.sectiontwo.org`, `nostr.wild-vibes.ts.net` |
+| none | `nos.lol`, `nostr.mom`, `relay.divine.video`, `relay.fountain.fm`, `koru.bitcointxoko.org`, `nostr-pr02.redscrypt.org`, 2 × Cloudflare-Workers relays, 1 other |
+
+Raw JSON for both phases (per-relay timestamps, close codes, server-ping
+series) was captured during the study session; the tables above are the
+complete decision-relevant summary.

amethyst/plans/2026-07-12-resource-usage-ledger.md

@@ -0,0 +1,178 @@
+# Resource Usage Ledger — battery/data accounting, user-visible + NIP-17 reportable
+
+**Date:** 2026-07-12
+**Goal:** Let users (and developers) see how much network, connection time, and
+background activity the app consumes, per subsystem — and let a user send that
+data to the developers over NIP-17, reusing the crash-report consent pattern.
+When consumption crosses "something is wrong" thresholds, proactively ask the
+user (rate-limited, opt-out-able) whether they'd like to send a report.
+
+Background: the 2026-07-12 ping-interval study (see
+`2026-07-12-relay-ping-interval-study.md`) showed the dominant energy proxy is
+connection-time (relays server-ping every 30–70s while connected) and that
+battery bugs are production-only phenomena — so the ledger ships in release,
+collects passively, and never transmits anything without an explicit user
+action.
+
+## Survey (existing components reused)
+
+- **Send path** — the crash-report pipeline: `DisplayCrashMessages` prefills
+  the NIP-17 DM composer via `routeToMessage(user = <dev pubkey>, draftMessage,
+  expiresDays = 30)`; the user taps Send; `Account.sendNip17PrivateMessage`
+  gift-wraps to the recipient's kind-10050 DM relays. Reused as-is — the
+  ledger only builds a different draft string.
+- **Persistence idiom** — `ScheduledPostStore` (Jackson + Mutex + tmp-rename +
+  version envelope + StateFlow). Cloned as `ResourceUsageStore`.
+- **Relay traffic** — counted by a new `RelayConnectionListener`
+  (same hook `RelayStats` uses), NOT by modifying quartz.
+- **Connection time** — integrated from `INostrClient.connectedRelaysFlow()`
+  (exact between emissions; no timers).
+- **Network class** — `ConnectivityManager.isMobileOrFalse` StateFlow.
+- **Foreground** — new tiny `ForegroundTracker` (ActivityLifecycleCallbacks →
+  StateFlow<Boolean>), registered next to `AppForegroundRecycleHook`;
+  `MainActivity.isResumed` is not observable and slightly stricter than
+  process-foreground.
+- **HTTP subsystems** — `RoleBasedHttpClientBuilder` already funnels every
+  role (image/video/uploads/money/nip05/preview/push) through two shared
+  clients; a cached per-role `newBuilder().addInterceptor(counting)` wrapper
+  gives per-subsystem byte attribution without touching the shared clients.
+- **UI idioms** — `NotificationSettingsScreen` structure (`Scaffold` +
+  `TopBarWithBackButton` + `SettingsSection` cards), route in `Routes.kt`,
+  `composableFromEnd` registration, catalog entry via
+  `SettingsCatalogBuilder.symEntry` (icon: existing `MaterialSymbols.Bolt` —
+  no font regen).
+- **App-open dialog** — `DisplayCrashMessages` pattern, mounted in the same
+  `AppNavigation` block.
+
+## Design
+
+### Counters
+Flat `Map<String, Long>` per UTC epoch-day, retained ~30 days. Key grammar:
+`<area>...<mobile|wifi>.<fg|bg>[.<rx|tx>]`, e.g.:
+
+- `net.image.mobile.bg.rx` — bytes downloaded by the image subsystem on
+  cellular while backgrounded (same for video/uploads/money/nip05/preview/push)
+- `relay.msg.wifi.fg.rx|tx` — approx relay websocket payload bytes
+- `relay.connms.mobile.bg` — relay-connection-milliseconds (Σ relays × time)
+- `wakelock.notif.ms` / `wakelock.notif.count`
+- `worker.scheduledPost.runs` / `worker.calendarReminder.runs` /
+  `worker.notificationCatchUp.runs`
+- `app.starts` — process starts (detects WorkManager cold-start churn)
+- `relay.connects.<net>.<vis>` / `relay.connfails.<net>.<vis>` — completed
+  (re)connections and failed dials; each connect paid a TCP+TLS handshake,
+  so high daily counts are the reconnect-churn signature
+- `cpu.ms` — whole-process CPU time deltas ([android.os.Process
+  .getElapsedCpuTime] sampled at flush): the honest aggregate of parsing,
+  crypto, coroutines, and UI without per-subsystem guesswork
+- `app.fgms` — time with UI visible; display power is proportional to it and
+  it's the denominator for every per-day comparison
+- `crypto.verify.count` / `crypto.verify.us` — event signature verifications
+  (LocalCache.justVerify hook), settling "does Schnorr verify cost matter"
+  with data
+- `net.<role>.<net>.<vis>.reqs` / `.activems` — HTTP request counts and
+  active-transfer time per subsystem; counting lives on the shared base
+  client (OkHttpClientFactory) with tag-based role attribution, so untagged
+  callers land in `other` instead of escaping the ledger
+- `net.bursts.<net>.<vis>` — estimated radio wake-ups from HTTP burst
+  patterns (new activity after >10s of HTTP silence): the battery-relevant
+  measure that bytes alone can't capture, since scattered small requests
+  each pay the radio ramp+tail
+- `media.playms` — actual media playback time (ExoPlayer isPlaying
+  segments): decoder + screen + streaming at once, the denominator for
+  video bytes
+
+- `pow.ms` / `pow.sessions` — NIP-13 mining time (any job mining in the
+  PoW queue): full-core CPU, the largest attributable CPU consumer
+- `tor.ms` / `tor.starts` — in-app (Arti) Tor uptime and bootstraps, from the
+  raw TorService status (NOT TorManager.status, whose WhileSubscribed
+  upstream calls service.start() when collected). External Tor (Orbot) is
+  deliberately untracked — its battery belongs to Orbot
+- `service.alwayson.ms` — NotificationRelayService uptime: the mode context
+  that explains a device's relay connection-time
+- `call.ms`/`call.sessions`, `nests.ms`/`nests.sessions` — calls and NIP-53
+  audio rooms (mic + Opus + live media connection), from the foreground
+  services' lifecycles
+- `location.ms` — time actively listening for GPS updates (geohash tagging);
+  mostly a tripwire for a leaked location subscription
+- `crypto.decrypt.count/us`, `crypto.encrypt.count/us` — NIP-04/44 work via a
+  MeteringNostrSigner decorator wrapped inside NostrSignerWithClientTag at
+  account load; durations metered only for local-key signers (external/
+  remote waits are IPC/network, not CPU)
+- `sign.local|nip46|nip55.count` — signatures by signer kind: NIP-46 is a
+  relay round-trip and NIP-55 an Amber IPC wake, so the kind is the
+  battery-relevant dimension (this supersedes "signing is negligible", which
+  is only true for local keys)
+- `battery.drain.fg|bg` — measured battery percent while discharging, sampled
+  at flush from BatteryManager: NOT app-isolated, but the ground truth that
+  report corpora can correlate the other counters against
+
+- `screen.<Name>.ms` — foreground time per screen, added after the original
+  privacy review: only the route's base NAME is recorded (screenNameOf strips
+  every navigation argument before the value leaves the nav layer), so the
+  ledger can say "Profile" but never whose profile
+
+Deliberately not tracked (v1): per-coroutine or per-dispatcher CPU (needs a
+thread registry; `cpu.ms` answers whether CPU matters at all first).
+(Two earlier v1 exclusions were later revisited: per-screen time ships with
+names-only privacy as above, and signing is now counted per signer kind
+because NIP-46/NIP-55 signatures are network/IPC round-trips, not local CPU.)
+
+Flat keys keep the store schema-free: new counters need no migration.
+
+### Components (`amethyst/.../service/resourceusage/`)
+- `UsageKeys` — key constants/builders + dimension helpers.
+- `ResourceUsageStore` — daily buckets on disk (`resource_usage.json`),
+  `mergeInto(day, deltas)`, `allDays()`, prune, plus alert state
+  (lastAlertAtSec, optOut).
+- `ResourceUsageAccountant` — in-memory `ConcurrentHashMap<String, LongAdder>`
+  hot path (`add()` is called per relay frame), debounced flush (30s) into the
+  store, day-rollover handling, merged read API for UI/report.
+- `ForegroundTracker` — startedActivities>0 as StateFlow.
+- `RelayUsageListener` — `RelayConnectionListener` counting sent/received
+  frame sizes with current network/visibility dims.
+- `RelayConnectionTimeIntegrator` — combines connectedRelays × isMobile ×
+  isForeground; closes an accounting segment on every change and on
+  `closeOpenSegment()` (called from accountant flush and reads, so multi-hour
+  stable background sessions still account without any timer).
+- `UsageCountingInterceptor` + counting response body — per-role HTTP bytes;
+  wrapped clients cached per (role, base client identity).
+- `ResourceUsageReportAssembler` — Markdown: device/app header (crash-report
+  style), human summary (today + 7 days), fenced per-day counter dump.
+- `ResourceUsageAlerts` — pure threshold logic (see below) + rate limiting.
+- `DisplayResourceUsageAlert` — consent dialog (view details / send / not
+  now / don't ask again).
+- UI: `ResourceUsageScreen` under `ui/screen/loggedIn/settings/`.
+
+### Wiring (AppModules / Amethyst / hooks)
+- store + accountant + integrator constructed in `AppModules`; listener added
+  via `client.addConnectionListener`.
+- `ForegroundTracker` registered in `Amethyst.onCreate` (main process only).
+- `RoleBasedHttpClientBuilder` gains an optional usage meter.
+- `EventNotificationConsumer.withWakeLock` gains an optional held-duration
+  callback (threaded through `NotificationDispatcher`).
+- Workers increment their run counters via `Amethyst.instance` (guarded).
+- `AppModules.trim()` flushes the accountant (backgrounding = natural flush).
+
+### Alert thresholds (v1, deliberately conservative — tune with real reports)
+Evaluated on the last *complete* day, OR today once exceeded:
+- background cellular traffic > 50 MB/day
+- relay connection time > 12 relay-hours/day while backgrounded on cellular
+- notification wakelock held > 30 min/day
+- process starts > 75/day
+Rate limit: at most one prompt per 7 days; "don't ask again" persisted.
+Never auto-sends: every path goes through the DM composer where the user sees
+exactly what will be sent and must tap Send.
+
+### Privacy
+Counters are sizes, durations, and counts — no URLs, no relay names, no event
+content. The report includes device model fields identical to the crash
+report. Everything stays on-device until the user explicitly sends the DM
+(NIP-40 30-day expiration, same as crash reports).
+
+### Explicitly out of scope (v1)
+- Layer 1 (Perfetto/ODPM macrobenchmarks) and Layer 2 (`TrafficStats` socket
+  tags) — add only if the ledger proves blind somewhere (e.g. WS bytes are
+  payload-approximate; TrafficStats would give exact on-wire bytes).
+- Per-relay attribution in the ledger (RelayStats screens already exist).
+- Desktop: accountant/store are Android-module for now; extraction to commons
+  is mechanical if desktop wants it.

amethyst/plans/2026-07-13-chat-scroll-performance.md

@@ -0,0 +1,124 @@
+# Chat feed scroll performance — fast fling through thousands of messages
+
+Status: plan. Owner: chat feed (`amethyst/.../ui/screen/loggedIn/chats/feed/`).
+
+## Problem
+
+A fling through a long chat history composes hundreds of `ChatroomMessageCompose`
+rows per second. Each newly composed row currently pays for work that is either
+(a) derivable off the composition path, (b) only needed for *recent* messages, or
+(c) side-effectful (coroutines, relay-filter updates) and therefore multiplies
+into churn under velocity. The redesign added per-row observers (group position,
+reaction chips, delivery ticks) that are individually cheap but sum up at 1000+
+rows.
+
+## What is already fine (verified, don't re-litigate)
+
+- **Rich text parse is cached**: `TranslatableRichTextViewer` →
+  `CachedRichTextParser.parseText` behind `remember(content, tags)`; re-scrolling
+  past a message doesn't re-parse.
+- **Engagement flows are sampled**: `observeNoteReactions/Zaps/Replies` sample at
+  200–500ms, and the EventFinder assembler folds all subscribed note ids into a
+  small number of shared REQs (`SingleSubEoseManager`), not one REQ per note.
+- **LazyColumn hygiene**: stable `key = idHex`, `contentType = kind`,
+  `animateItem()` gated by performance mode.
+- **Tracker fan-out fixed**: delivery state is one small StateFlow per message.
+
+## Per-row cost inventory (composition of ONE new row during fling)
+
+| # | Cost | Where | Class |
+|---|------|-------|-------|
+| 1 | 4× `dateFormatter` (ThreadLocal `SimpleDateFormat` for >24h-old messages) for group break checks, + 2 more in `NewDateOrSubjectDivisor` | `ChatGroupPosition.groupsWith`, `NewDateOrSubjectDivisor` | CPU, per row |
+| 2 | 3× `collectAsStateWithLifecycle` on metadata flows | `watchChatGroupPosition` | collector churn |
+| 3 | `LaunchedEffect` → `loadAndMarkAsRead(route, createdAt)` coroutine | `NormalChatNote` | 1 coroutine/row; read-marker lock churn |
+| 4 | `LaunchedEffect` → `accountViewModel.decrypt(note)` for the jumbo flag | `NormalChatNote` | 1 coroutine/row, even for plaintext kinds |
+| 5 | Reaction observer + zap observer subscriptions (ids added to shared relay filters; filter update per batch) | `ChatReactionChips`, `ObserveZapAmountText` | relay REQ re-issue churn under velocity |
+| 6 | 2× flow collectors for delivery ticks on own messages, forever, even for long-settled history | `ChatDeliveryTicks` | collector churn |
+| 7 | Per-row animation/gesture state: `animateColorAsState`, press `InteractionSource`, swipe `pointerInput`, highlight `LaunchedEffect` | `ChatBubbleLayout` | allocation, mostly unavoidable |
+| 8 | Media/link previews kick Coil requests immediately | `TranslatableRichTextViewer` children | IO churn during fling |
+
+Feed-level:
+
+| # | Cost | Where |
+|---|------|-------|
+| 9 | `shouldHighlight = highlightedNoteId.value == item.idHex` reads one state in every item lambda → all visible items recompose when it changes (rare; low) | `ChatFeedLoaded` |
+| 10 | `onScrollToNote` recreated when `ChatFeedLoaded` recomposes → unstable param defeats item skipping | `ChatFeedLoaded` |
+| 11 | Feed invalidation rebuilds the sorted list; every reaction arriving during scroll can reorder/emit | `FeedContentState` (existing infra, sampled) |
+
+## Plan
+
+### Phase 0 — Measure first (do not skip)
+
+1. **Macrobenchmark**: add a `benchmark` scenario that seeds `LocalCache` with
+   5–10k synthetic `ChannelMessageEvent`s (mixed: text, links, emoji-only, a few
+   with reactions/zaps) and flings the public-chat screen. Metrics:
+   `frameDurationCpuMs` P50/P90/P99, jank %, `frameOverrunMs`.
+2. **Composition tracing / recomposition counts** on a seeded room; compose
+   compiler reports (`composables.txt`) for `ChatroomMessageCompose`,
+   `NormalChatNote`, `InnerChatBubble`, `ChatReactionChips` — verify skippability
+   and find unstable params (expect #10).
+3. Record baseline numbers in this file before changing anything.
+
+### Phase 1 — Kill per-row CPU and coroutines (expected biggest wins)
+
+4. **Day-stamp grouping (#1)**: replace `dateFormatter` equality in `groupsWith`
+   with an epoch-local-day integer comparison (`(createdAt + zoneOffsetSeconds) / 86400`),
+   and give `NewDateOrSubjectDivisor` the same predicate so the break condition
+   stays mirrored (only its *display* string needs formatting, and only when a
+   divider actually renders). Zero `SimpleDateFormat` on the scroll path.
+5. **Hoist read-marking (#3)**: replace the per-row `LaunchedEffect` with one
+   feed-level `snapshotFlow { listState.firstVisibleItem createdAt }`-driven
+   marker update (only the newest visible timestamp matters; the marker is
+   monotonic). One coroutine per scroll session instead of one per row.
+6. **Jumbo without a coroutine (#4)**: only launch the decrypt effect for
+   encrypted kinds (`PrivateDmEvent`, sealed rumors not yet in the decrypt
+   cache). Plaintext kinds (public chats, NIP-17 rumors already unwrapped —
+   the vast majority) take the synchronous path only.
+7. **Retire settled delivery ticks (#6)**: once a message is fully accepted (or
+   untracked and older than the tracker window), render the tick from a
+   `remember`ed terminal value and drop both collectors. Only in-flight sends
+   keep live flows.
+8. **Group position with fewer collectors (#2)**: collect the three metadata
+   flows only while any of the three notes is missing `event`/`author`
+   (the common case for history is all-loaded → pure `remember`, no collectors).
+
+### Phase 2 — Tame side-effect churn under velocity
+
+9. **Defer new relay-filter membership while flinging (#5)**: gate
+   `EventFinderFilterAssemblerSubscription` enrollment on
+   `!listState.isScrollInProgress` (or debounce enrollment ~300ms): rows that
+   fly past never join the reaction/zap filters; rows you settle on subscribe
+   as today. Needs a small `LocalScrollSettled` composition local (provided by
+   `ChatFeedLoaded`) so `ChatReactionChips`/`ChatDeliveryTicks` can wait without
+   threading params. Verify with #1 measurements that filter re-issues drop.
+10. **Defer media loads (#8)**: same settled-gate for the image/video preview
+    composables inside chat bubbles (placeholder immediately, Coil request on
+    settle). Coil cancels in-flight requests on dispose already, but not
+    starting them is cheaper than cancel.
+11. **Stabilize item lambdas (#10)**: `remember(items.list, listState)` around
+    `onScrollToNote`; pass `shouldHighlight` via `derivedStateOf` keyed per item
+    (#9) so only the highlighted row recomposes.
+
+### Phase 3 — Structural (only if Phase 1/2 measurements demand more)
+
+12. **Precomputed row model**: build a lightweight `ChatFeedRow(note, groupPos,
+    dayStamp, isJumbo, isSystem)` list inside `FeedContentState` (background
+    thread, once per feed update) so item composition becomes pure rendering.
+    This subsumes #4/#8 above but is a bigger refactor of shared feed infra —
+    justify with numbers first.
+13. **Finer contentType**: distinguish `bubble / jumbo / system / zap-card`
+    contentTypes so Lazy slot reuse doesn't rebuild structurally different rows.
+14. **Prefetch tuning**: evaluate `LazyListPrefetchStrategy(nestedPrefetchItemCount)`
+    for the fling case on Compose ≥1.7.
+
+### Phase 4 — Regression guardrails
+
+15. Wire the Phase-0 macrobenchmark into CI (or at least a documented manual
+    run before releases touching the chat feed), and re-record numbers here.
+
+## Non-goals
+
+- Virtualizing bubble internals (Compose already skips off-screen work).
+- Caching parsed rich text more aggressively (already LRU-cached).
+- Changing feed sorting/invalidation infra (shared with all feeds; separate plan
+  if measurements point there).

amethyst/plans/2026-07-13-cord06-refounding.md

@@ -0,0 +1,83 @@
+# CORD-06 Refounding — real member removal for Concord
+
+## Problem
+
+Concord membership is key possession: a banned member (CORD-04 banlist) still
+holds the community's `community_root`, so every client just *declines to show*
+their posts — they can still decrypt everything. That is a soft removal. CORD-06
+adds the hard removal: rotate the key so a removed member's key stops working for
+anything sent afterwards.
+
+The quartz crypto for the kind-3303 rekey blob (`ConcordRekey`, `RekeyBlob`)
+already existed and was tested, but nothing in the app called it. This wires the
+whole path — build, publish, receive, persist, UI — around a **Refounding**
+(whole-community rotation), the removal that matters while Amethyst supports only
+public channels (a per-channel rekey needs private channels, not built yet).
+
+## What a Refounding does (CORD-06 §3)
+
+1. Ban the removed members on the current Control Plane (so the compacted snapshot
+   carries the ban).
+2. Roll `community_root` to a fresh random 32 bytes at `rootEpoch + 1`. Public
+   channels + the Control/Guestbook planes all derive from the root, so rolling it
+   rotates every plane at once.
+3. Republish the **compacted** Control Plane under the new root — keep only each
+   entity's head edition and re-wrap its *original plaintext seal*, so the original
+   authors' signatures survive re-encryption (a fresh joiner verifies the slim
+   state exactly as it verified the full chain).
+4. Mint per-recipient kind-3303 rekey blobs delivering the new root to every
+   retained member, sealed + addressed under the **prior** root on the
+   `base-rekey-pseudonym(prior_root, community_id, new_epoch)` address — which every
+   current member precomputes, so they receive it live. A removed member gets no
+   blob and can never derive the new root.
+
+## Layers
+
+- **quartz** `concord/cord06Rekey/`
+  - `ConcordKeyDerivation`: `baseRekeyAddress` / `channelRekeyAddress` (the rekey
+    stream addresses), `epochKeyCommitment` (`prevcommit`, CORD-02 §A.5).
+  - `ConcordRekey`: signer-based `blobForSigner` / `findNewKeyWithSigner` (bunker
+    accounts open a blob with one `nip44Decrypt`, no raw key).
+  - `ConcordRefounding`: `compactControlPlane`, `buildBaseRekeyWraps`, `build`
+    (whole refounding), `findNewRoot` (receive: verify scope/epoch/continuity, find
+    my blob). `OpenedStreamEvent` now also carries the inner `seal` so compaction
+    can re-wrap it. Tests in `ConcordRefoundingTest`.
+- **commons**
+  - `ConcordActions`: `guestbookPlane` / `nextBaseRekeyPlane`, `buildGuestbookJoin`
+    / `guestbookMembers`, `buildRefounding`, `openBaseRekey`.
+  - `ConcordCommunitySession`: folds the Guestbook plane into `members`
+    (the recipient set), buffers inbound base-rekey wraps (`pendingBaseRekeyWraps`),
+    exposes `controlPlaneWraps` for compaction, and AUTHs to + subscribes the
+    Guestbook and next-epoch base-rekey planes (`streamKeys`, `subscribeAddresses`).
+  - `ConcordSessionRegistry.sync`: rebuilds a session when its entry's root/epoch
+    changed — the session is a pure function of its entry, so adopting a new root is
+    just a persisted entry swap.
+  - `ConcordSubscriptionPlanner.auxiliaryPlaneSubs`: REQs the Guestbook + next
+    base-rekey planes for every joined community.
+- **amethyst**
+  - `Account`: announces a Guestbook JOIN on create/join (`announceConcordGuestbookJoin`)
+    so members are visible to a future rotator; `refoundConcordCommunity` (owner /
+    BAN-holder) bans + rolls + publishes + persists; `drainConcordRekeys` (revision
+    tick) adopts an inbound rotation from an authorized rotator; `adoptConcordRoot`
+    persists the new root (prior root kept as a `HeldRoot`) and re-seeds the new
+    epoch's Guestbook, guarded against double-adopt.
+  - `AccountViewModel.removeConcordMember`; `ConcordMembersScreen` "Remove from
+    community" action + confirm dialog, gated exactly like Ban.
+
+## Recipient set
+
+The rotator re-keys **Guestbook membership ∪ the privileged roster ∪ self**, minus
+the removed and the already-banned. The Guestbook is best-effort/off-consensus, so
+a member who joined but whose Guestbook JOIN hasn't propagated to the rotator would
+be missed and locked out — the accepted trade for a serverless, key-possession
+membership model. Adopting a new root re-announces the Guestbook JOIN at the new
+epoch so cascading removals keep a live membership.
+
+## Known limitations / follow-ups
+
+- No explicit "you were removed" detection: a removed member simply stops receiving
+  new content (their old-epoch keys still read history). CORD-06's "held all n
+  chunks, none is mine ⇒ removed" self-eviction is not implemented.
+- Per-channel rekey (single private channel) is not wired — needs private channels.
+- Race convergence (two rotators, same epoch, lexicographically-lowest-key wins) is
+  not implemented; single-rotator (owner/admin) refounding is the supported path.

amethyst/plans/2026-07-15-bitchat-geohash-interop.md

@@ -0,0 +1,71 @@
+# Bitchat geohash chat interop
+
+Status: **Phase 1 (public geohash channels) shipped.** Phase 2 (encrypted DMs)
+is designed but not implemented.
+
+## What Bitchat does (verified against `permissionlesstech/bitchat`
+iOS + `bitchat-android`)
+
+Bitchat's Nostr side has two chat features. Amethyst is a pure-Nostr client
+(no BLE mesh / Noise identity), so only the Nostr halves are in scope.
+
+### Public geohash channels ("location channels") — SHIPPED
+- Message = **kind 20000** (ephemeral), content = plain UTF-8 text.
+  Tags: `["g", geohash]` (required), `["n", nickname]` (optional),
+  `["t","teleport"]` (optional). Optional NIP-13 `["nonce", …]` PoW, default 8
+  bits, used to relax per-sender relay rate limits.
+- Presence = **kind 20001**, only the `g` tag, empty content.
+- Subscribe: `kinds:[20000,20001]`, `#g:[geohash]` (exact cell).
+- Precision levels (geohash chars): building 8, block 7, neighborhood 6,
+  city 5, province 4, region 2.
+- Identity = a per-geohash throwaway key `HMAC-SHA256(deviceSeed, geohash)`,
+  deterministic per (device, cell), unlinkable to the user's npub.
+- **Relay routing is geographic and load-bearing:** a cell's traffic goes to the
+  5 relays nearest the cell center, chosen from the public MIT-licensed
+  `permissionlesstech/georelays` CSV both clients load. If Amethyst used any
+  other relay set its messages would not rendezvous with Bitchat clients.
+
+### Private DMs — NOT YET IMPLEMENTED (Phase 2)
+- Standard NIP-17/59: rumor kind 14, seal kind 13, gift wrap kind 1059, wrap
+  under a throwaway key, NIP-44 v2.
+- **The kind-14 rumor content is NOT plain text.** It is
+  `"bitchat1:" + base64url(<binary bitchat packet>)` — a `BitchatPacket`
+  (TLV + a `NoisePayloadType` byte) carrying the private message, delivery ACKs,
+  and read receipts. Full DM interop therefore requires porting that binary
+  framing (`NostrEmbeddedBitChat.swift` / `NostrEmbeddedBitChat.kt`).
+- Two DM flavors: geohash DMs (gift-wrapped to a participant's per-geohash
+  pubkey) and stable-identity DMs (to an npub learned via Bitchat's mesh
+  `[FAVORITED]:<npub>` handshake — mesh-specific, mostly N/A for a Nostr client).
+
+## What shipped (Phase 1)
+
+- **quartz** `experimental/bitchat/`: `GeohashChatEvent` (20000),
+  `GeohashPresenceEvent` (20001), `GeohashKeyDerivation` (per-geohash key),
+  registered in `EventFactory`. PoW reuses the existing `nip13Pow` `PoWTag`.
+- **commons** `service/georelay/`: `GeoRelayDirectory` (closest-N by haversine,
+  host tie-break, `:443` dedup), `GeoRelayCsvLoader` (runtime CSV fetch + fallback).
+- **amethyst**: `GeohashChatScreen` + `GeohashChatViewModel` (live subscription +
+  send), `GeohashChatDeviceSeed` (global encrypted seed store),
+  `Account.signWithAndSendPrivately`, `Route.GeohashChat`, and a chat action on
+  the geohash feed screen.
+- **cli**: `amy geochat listen|send|keys` — the interop harness. Verified with a
+  live send→relay→listen round-trip (kind 20000, PoW, `g`/`n` tags intact).
+
+## Follow-ups
+
+1. **Encrypted DMs (Phase 2).** Port the `bitchat1:` binary packet
+   (`BitchatPacket` TLV + `NoisePayloadType`) into quartz, wrap/unwrap it in the
+   existing NIP-17 stack (`GiftWrapEvent`/`SealedRumorEvent`/`ChatMessageEvent`),
+   handle geohash DMs (to a per-geohash pubkey) and delivery/read receipts.
+   Add `amy geochat dm` for interop testing.
+2. **Desktop UI.** The shared pieces (quartz events, `GeoRelayDirectory`) are
+   already cross-platform; add a desktop `GeohashChatScreen` equivalent.
+3. **LocalCache integration (optional).** The current Android screen manages its
+   own subscription/state rather than routing through `LocalCache`/the chatroom
+   list. Integrating would give unread badges and a unified chat list, at the
+   cost of a `Channel`/feed-filter/datasource fork.
+4. **Location-driven channel picker.** Use `LocationState` to offer the
+   region/province/city/neighborhood/block/building cells for the user's current
+   position, plus a manual/teleport entry.
+5. **Presence heartbeats + i18n.** Periodically emit kind 20001 while a channel
+   is open; extract the hardcoded screen strings into `strings.xml`.

amethyst/plans/2026-07-16-location-chats-first-class.md

@@ -0,0 +1,171 @@
+# Making location (geohash) chats first-class in Amethyst
+
+Builds on `2026-07-15-bitchat-geohash-interop.md` (Phase 1 shipped: protocol,
+geo-relay routing, a self-contained chat screen, `amy geochat`). This plan takes
+it from a bolt-on screen to a native feature woven into Home, Messages, and the
+map.
+
+## The one constraint that shapes everything
+
+Geohash **chat** (kind 20000) is signed with anonymous per-cell throwaway keys,
+unlinkable to npubs. So "which of my follows are chatting here" is **not
+derivable from the chat stream**. Any "follows are active near you" signal must
+come from a *linkable* source:
+
+- **kind-1 geohash notes** (`GeoHashFeedFilter` scans `LocalCache.notes` for
+  `isTaggedGeoHash`; authors are real npubs) → intersect with
+  `account.kind3FollowList` = genuine "follows near this place." This is the
+  template `HomeLiveFilter.followsThatParticipateOn` already uses, just sourced
+  from notes instead of chat events.
+- **kind-10081 geohash follow lists** (`GeohashListEvent`) — the user's own, and
+  optionally follows' public lists.
+- Anonymous **liveliness** (kind-20000/20001 presence counts) — "N people here",
+  no identities.
+
+The Home bubble is therefore: *anonymous liveliness + follows' geo-note activity
+→ tap into the cell's chat.* We will not imply the chat reveals who's there.
+
+## Key architectural decision: reuse what exists
+
+1. **Joined channels = the geohash follow list (kind 10081).** `account.geohashList`
+   (`model/nip51Lists/geohashLists/GeohashListState.kt`, `flow: StateFlow<Set<String>>`,
+   `follow`/`unfollow`, NIP-44-private capable) already models "geohashes I care
+   about." Treat *following a geohash* as *joining its location channel*. No new
+   list type, and it's private-capable. (Trade-off: today it also drives the
+   kind-1 notes feed; we're overloading one list for both "notes near here" and
+   "chat here." Acceptable — it's the same user intent. Alternative if we want
+   separation: a local, unpublished joined-set matching Bitchat's ephemerality.)
+
+2. **Make geohash chat LocalCache-backed** so it can flow through the same feed
+   machinery as every other room. This is the crux of "first-class": the Messages
+   list, Home bubbles, unread counts, and pins all read from `LocalCache`
+   channels. Model it on the ephemeral-chat feature end to end.
+
+## Phase A — Data model + LocalCache integration (foundation)
+
+- `commons/.../model/geohashChat/GeohashChatChannel.kt` — a `Channel` subtype
+  keyed by geohash (mirror `model/emphChat/EphemeralChatChannel.kt`).
+  `toBestDisplayName()` returns the reverse-geocoded place (or `#geohash`).
+- `LocalCache`: add a `geohashChannels` map + a consumer that routes
+  `GeohashChatEvent`/`GeohashPresenceEvent` into the channel (mirror
+  `ephemeralChannels`/`liveChatChannels` + `getOrCreateEphemeralChannel`).
+- A rooms-list **subassembler** that subscribes to the joined geohashes
+  (`account.geohashList.flow` → `GeoRelayDirectory.closestRelays(g)`, kinds
+  20000/20001, `#g`) and feeds LocalCache — mirror
+  `chats/rooms/datasource/FollowingEphemeralChatSubAssembler.kt` +
+  `FilterFollowingEphemeralChats.kt`.
+- Migrate `GeohashChatViewModel` to read the channel's notes from LocalCache
+  (via `LocalCache.observeNotes` like `NestLobbyScreen`) instead of its private
+  subscription — unifies the live view with the cached one and lets the screen
+  reuse the full `ChatroomMessageCompose` (reactions, replies) later. Keep the
+  send path (per-geohash signer + PoW + geo relays) as-is.
+- Ephemeral caveat: relays don't store kind 20000, so joined-cell rooms only show
+  messages seen while subscribed. Scope background subscriptions to *joined* cells
+  (+ the current-location cell) to bound battery/relay load; document the cap.
+
+## Phase B — Messages tab
+
+- `chats/rooms/dal/ChatroomListKnownFeedFilter.kt` — add a 7th family
+  (`geohashChannels` from `account.geohashList`) to `feed()` + `applyFilter`
+  (newest message per cell), mirroring `filterRelevantEphemeralChats`.
+- `chats/rooms/ChatroomHeaderCompose.kt` — add a `GeohashRoomCompose` branch in
+  `ChatroomEntry` → `nav.nav(Route.GeohashChat(geohash))`, with a location-pin
+  `HeaderPill`, the cell name (`LoadCityName`), and a live participant count (no
+  avatars — anonymous).
+- `chats/rooms/NewConversationScreen.kt` — append one `ConversationType`
+  ("Location chat", geohash icon/accent, pros/cons, `route = Route.NewGeohashChat`)
+  to the *Relay* section of `conversationSections` (single source of truth).
+
+## Phase C — The builder ("+" → create/join)
+
+- `Route.NewGeohashChat` + `NewGeohashChatScreen.kt` (mirror
+  `ephemChat/metadata/NewEphemeralChatScreen.kt`). Three ways to pick a cell:
+  1. **Current location levels.** New `GeohashChannelLevel` mapper
+     (region=2, province=4, city=5, neighborhood=6, block=7, building=8 chars —
+     the Bitchat levels; `GeohashPrecision` has the char counts but not the
+     names). From `LocationState.geohashStateFlow` (raise its hardcoded 5-char
+     precision to 8 so we can truncate to each level), list the six cells with
+     `LoadCityName` + a Join/Open button.
+  2. **Manual geohash** text field (validate against the base32 alphabet).
+  3. **Teleport** → the map picker (Phase E).
+- Join = `account.geohashList.follow(geohash)` then `nav.nav(Route.GeohashChat)`.
+- Reuse `LocationAsHash`/`ILocationGrabber` for the permission flow.
+
+### Geohash-list management (the kind-10081 add/remove UI)
+
+Today the **only** way to add to the kind-10081 list is the Follow toggle on the
+kind-1 `GeoHashScreen` — you must already be viewing that cell. Followed cells
+then appear as read-only feed chips in the Home top-nav (`TopNavFilterState`).
+There is **no** screen to view the list, remove entries, or add an *arbitrary*
+geohash. This builder is that missing "add" UI (it writes via
+`account.geohashList.follow`, the same path). Round it out with a small manage
+screen:
+
+- `NewGeohashChatScreen` doubles as the **add** surface (current-location levels /
+  manual / map).
+- Add a lightweight **"My location channels"** list (its own route, or a section
+  in the builder): render `account.geohashList.flow` with `LoadCityName` per cell,
+  a remove (`unfollowGeohash`) swipe/menu, and an "add" button into the builder.
+  This is also what Phase B's Messages rows and Phase D's Home bubble read from,
+  so it's the one management surface for the whole feature.
+
+## Phase D — Home "live near you" bubble
+
+- New feed state `homeGeohashLive` in `AccountFeedContentStates.kt` (parallel to
+  `homeLive`; different signal source, so not folded into `HomeLiveFilter`).
+  Sources: joined cells with recent activity (LocalCache, post Phase A) + the
+  current-location cell.
+- `home/live/RenderGeohashBubble.kt` — a bubble showing the cell name, a
+  liveliness dot (reuse `LiveStatusIndicator` pattern; "online" = recent presence),
+  and social proof from **geo-notes**: "N follows posted near · M chatting"
+  (follows-near count = `GeoHashFeedFilter` authors ∩ `kind3FollowList`).
+- `HomeScreen.kt` `DisplayLiveBubbles` — add the `GeohashChatChannel` (or a
+  synthetic geohash item) case to the type dispatch; click → `Route.GeohashChat`.
+
+## Phase E — Teleport + map
+
+- `LocationPickerMap.kt` — extend the display-only osmdroid `LocationPreviewMap`
+  with a `MapEventsOverlay`/`MapEventsReceiver` so long-press/tap drops a pin and
+  yields a coordinate → `GeoHash.encode(lat, lon, level)`. osmdroid (Apache-2.0)
+  already supports this; only the wiring is new.
+- Teleport screen (or a mode in `NewGeohashChatScreen`): pick a point on the map,
+  show the resulting cell name + level selector, Open → `Route.GeohashChat`.
+- **Auto-teleport flag:** in `GeohashChatViewModel`, compare the channel's geohash
+  to the current-location cell (`LocationState`); when they differ (or no
+  permission), pass `teleported = true` to the already-plumbed
+  `sendMessage(..., teleported)`. Add a manual override toggle in the composer.
+- Optional: forward geocoding (place-name search) via
+  `Geocoder.getFromLocationName` — none exists today; small addition for a
+  "search a place" box.
+
+## Phase F — Privacy, presence, polish
+
+- **"Post as my real account" opt-in** (global or per-channel, with a
+  location-exposure warning). This is also the *only* way a follow becomes
+  visible in the chat itself — relevant to the Home social-proof story.
+- **Presence heartbeats:** emit kind 20001 periodically while a channel is open
+  (`GeohashChatViewModel.announcePresence` already exists; schedule it).
+- **Privacy note:** subscribing to a cell reveals interest in that location to
+  its relays (via the `#g` REQ from your IP); Tor mitigates. The kind-10081 list
+  can stay NIP-44-private.
+- Extract hardcoded screen strings to `strings.xml` (`<plurals>` for the counts —
+  see `res/CLAUDE.md`); desktop `GeohashChatScreen` equivalent.
+
+## Open decisions (need a call)
+
+1. **Joined list:** reuse kind-10081 geohash follow list (recommended, private,
+   already wired) vs. a separate local ephemeral joined-set (closer to Bitchat).
+2. **LocalCache integration depth:** full (Phase A — enables Messages/Home/unread,
+   bigger) vs. keep the self-contained screen and only add the builder + a
+   Home bubble fed by geo-notes (smaller, but not truly "in the Messages list").
+3. **Default identity in these rooms:** stays anonymous per-cell (recommended);
+   the real-account opt-in is Phase F.
+
+## Verification
+
+- Unit: `GeohashChannelLevel` bucketing, the joined-list ↔ subscription wiring,
+  the geo-note follow-intersection count.
+- `amy geochat` remains the wire-level interop check against a real Bitchat cell.
+- Drive the app: join a cell from the "+" chooser, confirm it appears in Messages,
+  post/receive, teleport via the map and confirm the `["t","teleport"]` tag, and
+  confirm the Home bubble reflects a follow's kind-1 geo-note near you.

amethyst/plans/2026-07-16-nip46-signer-device-checklist.md

@@ -0,0 +1,184 @@
+# NIP-46 Signer — device verification checklist
+
+Everything below is behavior that JVM unit tests **cannot** exercise: interactive
+consent dialogs, the foreground service, real relay traffic, deep links, and
+cross-app interop. The protocol/authorization logic underneath is covered by
+`quartz` (`NostrConnectSignerServiceTest`) and `commons`
+(`Nip46PermissionAuthorizerTest`, `Nip46ConsentIntegrationTest`) unit tests; this
+list is the manual pass that earns "first-class" on a real device.
+
+Run as the signer on one device/account ("bunker"); use a second app/account as
+the client.
+
+## Pairing
+- [ ] **Bunker flow**: Settings → Nostr Signer → turn on → scan/copy the
+      `bunker://` QR into a client (nsec.app, Coracle, Nostrudel, or a second
+      Amethyst via `amy login bunker://…`). Client resolves your npub via
+      `get_public_key`.
+- [ ] **NostrConnect flow**: client shows a `nostrconnect://` code → "Scan a
+      code" on the signer screen pairs it and the signer turns on.
+- [ ] **NostrConnect informed consent**: pairing a `nostrconnect://` offer that
+      carries `perms=` shows a connect sheet listing the app's requested
+      permissions (e.g. "Sign notes (kind 1)", "Decrypt messages") + a trust
+      picker BEFORE anything is granted. Approving pre-grants exactly those ops
+      (unless Paranoid); Cancel/Block declines and nothing is registered. A
+      re-pair of a known app skips the sheet and keeps prior decisions.
+      Repro: `amy login --nostrconnect --perms sign_event:1,nip44_encrypt`
+      prints an offer that carries exactly those perms (see CLI interop driver).
+- [ ] **Global scanner**: scan a `nostrconnect://` from the profile/search
+      camera → lands on the signer screen and pairs.
+- [ ] **Deep link**: tap a `nostrconnect://` link (web/other app) → Amethyst
+      opens the signer screen and pairs (cold start AND already-running).
+
+## Note preview in the sign dialog (device-only)
+- [ ] A `sign_event`/publish request renders the unsigned event as a **NoteCompose
+      preview** (text + media + mentions, authored by the signing account), with
+      the "Show event" JSON toggle still available below it.
+- [ ] Works for both a NIP-46 remote app and a napplet Publish/SignEvent.
+- [ ] When the main Activity is gone (app fully backgrounded, only the signer
+      foreground service alive → `CallSessionBridge.accountViewModel` is null),
+      the dialog falls back to the plain content quote + JSON without crashing.
+- [ ] **Risk to watch:** NoteCompose is feed UI rendered inside a standalone
+      dialog Activity; if it reads a CompositionLocal only provided by the main
+      scaffold it could crash at runtime (compiles fine). Verify on device; if it
+      misbehaves, the JSON fallback path is one boolean away.
+
+## Entry point + connected-apps management (2026-07-16)
+- [ ] **Drawer entry**: the signer opens from the left drawer's "You" section, directly
+      under Wallet (moved out of Settings). It's also available as a bottom-bar favorite.
+- [ ] **Dedicated apps screen**: "Manage connected apps" on the signer screen opens a
+      NIP-46-only list (name, npub, relay count, last-used, trust chip), separate from the
+      napplet/nsite/browser Connected Apps screen. NIP-46 apps no longer appear there.
+- [ ] **Idle auto-forget**: an app left unused for 7 days is dropped on the next signer
+      start (its background relay subscription goes with it); an app still signing is kept.
+
+## Comes-to-front on a request (2026-07-16)
+- [ ] **Backgrounded surfacing**: with Amethyst fully backgrounded (Android 12+), a client
+      signing/connect request pops the consent dialog — via a full-screen-intent notification
+      on the high-importance "Signing requests" channel (the `startActivity` fast path is
+      BAL-blocked when backgrounded). On a locked screen it launches straight to the dialog;
+      while actively on another app it shows a heads-up prompt to tap.
+- [ ] **Foreground**: with Amethyst in the foreground the dialog opens directly (no extra
+      notification — `SignerConsentNotifier` no-ops when `foregroundTracker.isForeground`).
+- [ ] **Android 14+ caveat**: `USE_FULL_SCREEN_INTENT` is restricted for non-calling apps,
+      so the FSI may degrade to a heads-up rather than auto-launch — verify the prompt still
+      arrives and is tappable. Requires notification permission (already needed for the
+      always-on service).
+
+## Consent (Tier 1)
+- [ ] **First-connect trust picker**: a bunker-flow connect with a valid secret
+      shows the trust-level dialog (Full trust / Reasonable / Paranoid) BEFORE any
+      signing; choosing a level records it in Connected Apps.
+- [ ] **Cancel/Block**: dismissing the connect dialog rejects the connection (no
+      silent grant).
+- [ ] **Per-op ASK**: with a REASONABLE app, ask the client to sign a
+      **kind 0 / kind 3 / delete (5)** or **decrypt a DM** → the per-op dialog
+      appears (these are excluded from the auto-allowed set).
+- [ ] **Remember variants**: "allow for this op" stops re-prompting; "session"
+      stops until the signer restarts; "24h/30d" expire; "deny for op" sticks.
+- [ ] **PARANOID app** prompts on every request; **FULL_TRUST** never prompts.
+- [ ] **Timeout**: ignore a per-op dialog for 2 minutes → the request fails
+      closed (deny) and the signer keeps serving later requests (not wedged).
+
+## Anti-spam rotation (already shipped)
+- [ ] "New address" → confirm dialog → old `bunker://` goes dark, connected apps
+      drop, QR updates; re-pairing a legit app keeps its trust level.
+
+## Visibility (Tier 2)
+- [ ] Signer screen shows "Signing as npub1…", a live "Recent activity" feed
+      (signed kind N / encrypted / decrypted / shared pubkey, green/red dot,
+      relative time), and per-app history on the Connected-App detail screen.
+- [ ] The Connected-App detail screen for a remote client shows its name/url,
+      not a raw `nip46:` coordinate.
+
+## Reliability (Tier 3)
+- [ ] **Relay health**: kill connectivity → status shows "X of N relays
+      connected"; restore → "all connected".
+- [ ] **Boot restart**: enable the signer, reboot the device → the foreground
+      service comes back and the signer answers a request without reopening the
+      app. (Same for an app update via `MY_PACKAGE_REPLACED`.)
+- [ ] **Doze/background**: after ~30 min idle in Doze, a request still gets
+      serviced (may lag by a relay reconnect).
+
+## Interop matrix
+Pair + sign + nip44 encrypt/decrypt + logout against each:
+- [ ] nsec.app
+- [ ] Coracle
+- [ ] Nostrudel
+- [ ] snort / other NIP-46 client
+
+## CLI interop driver (`amy`) — added 2026-07-17
+The `cli` module (`amy`) drives the same quartz/commons code, so it plays either
+side of every NIP-46 flow for reproducible interop tests without a second phone.
+All of it reuses `Nip46PermissionAuthorizer.parsePerms` / `toSignerOp` — no
+protocol logic in `cli`. See `amy --help` (the `Remote signing (NIP-46)` block).
+
+Amy as the **client** (Amethyst is the signer):
+- `amy login bunker://…` — pair against Amethyst's advertised `bunker://`, then
+  every `amy` signing verb routes through it. Surfaces `auth_url` challenges to
+  stderr, so it completes even when Amethyst defers consent.
+- `amy login --nostrconnect [--perms sign_event:1,nip44_encrypt,…]` — mint an
+  offer for Amethyst to scan. `--perms` is what exercises the app's
+  **informed-consent** sheet (the offer carries the declared ops).
+
+Amy as the **signer** (Amethyst, or any client, is the client):
+- `amy bunker` — headless auto-approve signer for the operator's own key.
+- `amy bunker --perms sign_event:1,nip44_encrypt` — restricted signer: allows
+  only the listed ops, **rejects** the rest. Use to test how the app-as-client
+  handles a signer that says no.
+- `amy bunker --interactive` — keeps listening and prompts `y/N` per request on
+  the terminal (TTY-only, default-deny, prompts serialized). Composes with
+  `--perms` (auto-allow the listed ops, prompt for the rest = the "Reasonable"
+  policy on the CLI).
+
+## Audit findings — known limitations (2026-07-16)
+
+An adversarial review of the signer logic surfaced these. The head-of-line
+issues below share one root cause: `authorize()`/`onConnect()` run **inline** in
+`NostrConnectSignerService`'s single-consumer loop, and relay-set changes restart
+that loop via `collectLatest`.
+
+- **FIXED — unbounded first-connect prompt.** `Nip46ConsentBridge.requestConnect`
+  now has the same 120s `withTimeoutOrNull` as `requestOp`, so an ignored
+  first-connect dialog can no longer wedge the loop forever.
+- **FIXED — consent no longer blocks other clients (needs on-device
+  validation).** The service now fans each request out into a child coroutine
+  under a `Semaphore(maxConcurrentHandles=16)`; dedup/staleness/rate-limit stay on
+  the single consumer, only `handle()` runs concurrently. So a request awaiting a
+  prompt no longer stalls auto-allowed traffic, and several prompts can be pending
+  at once. Two guards keep this safe: (1) the identity signer's crypto is
+  serialized by `BunkerRequestProcessor.cryptoLock` — authorization (the prompt)
+  runs UNLOCKED, only the sign/encrypt/decrypt holds the lock — so an external
+  NIP-55 app never sees concurrent IPC ops; (2) first-connect consent is
+  serialized by `Nip46PermissionAuthorizer.connectLock` so two connects can't stack
+  dialogs. Per-op prompts batch: the shared `SignerConsentCoordinator.pending`
+  flow drives one dialog (1 pending) or a checkbox list (>1). Covered by
+  `BunkerRequestProcessorConcurrencyTest`, but the on-device paths below still need
+  a real run:
+  - [ ] **Burst batching:** a client fires several dangerous-kind requests at once
+        → one batched sheet with checkboxes + select-all, Allow/Deny selected,
+        "Remember" toggle. Approving a subset leaves the rest pending.
+  - [ ] **Auto-allowed keeps flowing:** while a prompt sits open, a REASONABLE
+        auto-allowed request from another app still gets signed and answered.
+  - [ ] **No concurrent external-signer ops:** with a NIP-55 external signer, two
+        approved requests do not drive overlapping IPC (they serialize).
+  - [ ] **Fail-closed on dismiss:** backing out of the batched sheet denies every
+        still-open request (not just the selected ones).
+- **Relay-set change cancels in-flight work.** A `logout` (or a new nostrconnect
+  pairing) mutates the listen set → `collectLatest` restarts the service →
+  cancels the in-flight `handle()`. Practical impact is low (a logout ACK is lost
+  but the client is leaving; a pairing-time cancel makes other clients retry).
+  Proper fix: manage subscriptions incrementally (diff add/remove) instead of a
+  full restart. Deferred (same reason).
+- **Low-severity, left as-is:** activity-log records an O(capacity) list copy per
+  serviced request (negligible under rate-limiting); the per-author rate limiter
+  evicts by insertion order rather than LRU (the 3-arg `accessOrder`
+  `LinkedHashMap` isn't in KMP commonMain); first-time transport-key/secret mint
+  is unsynchronized (practically serialized on the UI thread).
+
+## Deliberately NOT changed
+The always-on foreground **notification** was left as-is: it is shared with the
+relay/DM always-on service, so retitling it "Signing for N apps" or deep-linking
+it to the signer screen would be wrong when the service is up for another reason.
+Interactive consent uses its own dedicated dialog Activity, so it needs no
+notification actions.

amethyst/plans/2026-07-18-nip29-group-chat-subscriptions.md

@@ -0,0 +1,201 @@
+# NIP-29 group-chat subscriptions: split *state* (always-on) from *content* (paginated)
+
+**Status:** proposed · **Date:** 2026-07-18 · **Module:** `amethyst` (+ `commons` model, reuses `commons`/`quartz` paging)
+
+## Problem
+
+NIP-29 relay-group ("RelayGroup") chat is served today by **six** overlapping
+REQ assemblers, each keyed differently and each re-deriving the same two queries:
+
+| Query shape | Emitted by (today) |
+|---|---|
+| Metadata `#d` (39000–39005 + pins) | Warmup, ChannelPublic (open), MyJoinedGroups (roster subset), OnRelay (directory) |
+| Content `#h` (kind 9 + poll) | MyJoinedGroups (limit 50), Warmup (limit 50), ChannelPublic-open (limit 200) |
+| My-own `#h` (`authors=[me]`) | ChannelFromUser — **redundant for groups** (the all-authors `#h` window already returns my messages; a group is pinned to one host relay) |
+| Threads `#h` (11 + 1111) | Warmup, ThreadFeed |
+
+Two concrete defects fall out of this shape:
+
+1. **Slow / partial first load** (the reported bug). Content is fetched in **fixed
+   windows** (limit 50 / 200) gated by a *shared per-relay* `since`
+   (`RelayGroupMyJoinedGroupsSubAssembler` is keyed by `Account`, so its `since`
+   collapses to one map per relay, not per group). A group joined or surfaced
+   after that relay's `since` advanced never backfills; opening it waits a full
+   relay round-trip.
+2. **We can miss messages.** A fixed `limit=200` window has no way to reach older
+   history, and no demand-driven paging: scroll up past 200 and there is nothing
+   behind it. There is also a **serving-relay keying hazard** (see below) where a
+   referenced group message lands in a channel the UI never reads.
+
+Every *other* chat surface in the app already solved this with a **two-subscription
+model** — an always-on live tail + an on-demand backward history pager — and there
+is a reusable framework for it. Group chat is the outlier that never adopted it.
+
+## Goal
+
+Split group chat into the same shape every other chat uses, and delete the
+duplication:
+
+- **State** (metadata / roster / roles / pins) — small replaceable events →
+  **one always-on account subscription**, gated on the NIP-29 settings toggle.
+  The cache is always current; no per-screen metadata re-fetch.
+- **Content** (kind 9 chat + polls) — high volume → **live tail + backward history
+  pager**, exactly like NIP-04 DMs and Concord channels. Gap-proof (`RelayLoadingCursors`
+  handles cache-prune rewind), demand-driven by the visible feed, reconnect-safe.
+
+No message path that delivers a group message today may be dropped.
+
+## Reused framework (do not reimplement)
+
+Mapped end-to-end from the NIP-04 DM stack and the **Concord channel** stack, which
+is the closest existing template (a public group channel already paged this way):
+
+| Piece | Location | Role |
+|---|---|---|
+| `BackwardRelayPager(name, pageLimit, liveTailSeconds)` | `commons/.../relayClient/paging/` | single-active per-relay backward orchestrator |
+| `RelayLoadingCursors` | `quartz/.../relay/client/paging/` | per-relay `until`/`reached`/`done` cursors + `rewindTo` (prune realign) — **one instance per group scope** |
+| `WindowLoadTracker` + `trackingListener` | `commons/.../relayClient/paging/` | live-tail "all relays settled" indicator |
+| `PagingStatus`, `RelayPagingProgress` | paging pkg / quartz | atomic display snapshot |
+| `RelayReachCursor` / `RelayReachSentinels` / `RelayReachMarkers` | `commons/.../ui/feeds/RelayReachMarker.kt` | viewport-driven "load older" markers |
+| `DmHistoryLoadingCard`, `RefreshingChatroomFeedView(olderBoundary, markersInGap, sentinels)` | `amethyst/.../chats/feed/ChatFeedView.kt` | shared feed hooks |
+| `DmHistoryTuning.recentBoundary()` | `commons/.../model/privateChats/` | shared live-tail floor (7 days) |
+
+**Direct templates to copy:**
+`ConcordChannelHistorySubAssembler` + `ConcordChannelHistoryFilterAssembler` +
+`ConcordChannelHistorySubscription` + `ConcordChannelScreen`'s
+`ConcordBackfillHistoryToWindow`; and `ChatroomNip04SubAssembler` (live tail) /
+`ConcordChannelFilterAssembler` (batched always-on live).
+
+## Target architecture
+
+Four concerns, mirroring the DM stack (rooms-list tail + per-conversation tail +
+per-conversation history) plus a groups-only always-on state sub.
+
+1. **`RelayGroupStateSubAssembler`** — *always-on*, account-keyed.
+   Roster `#d` (39000/39001/39002/39003/39005) batched one filter per host relay
+   across the joined set. Keeps `since` (tiny replaceable events; reconnect just
+   re-confirms). Mounted at `LoggedInPage` (like `AccountFilterAssemblerSubscription`),
+   gated on `ChatFeedType.NIP29`. **This is today's `RelayGroupMyJoinedGroups` roster
+   path, promoted to always-on and stripped of content.**
+
+2. **`RelayGroupPreviewTailSubAssembler`** — *always-on*, account-keyed, batched.
+   Content `#h` (kind 9 + poll) across **all** `liveRelayGroupList` group ids,
+   `since = recentBoundary()`, **no per-group limit** (a time floor bounds it, so it
+   batches into one filter per relay). `WindowLoadTracker`. Drives Messages-list
+   previews and keeps joined groups' recent chat live app-wide. **Replaces
+   `RelayGroupMyJoinedGroups` content path (A).** Batching + time-floor `since`
+   eliminates both the per-group-`since` bug and the reconnect re-download.
+
+3. **`RelayGroupChatTailSubAssembler`** — per-open-`GroupId`, live tail for the
+   *currently open* group: content `#h` (9 + poll), `since = recentBoundary()`, host
+   relay. Covers recent + live updates for **any** open group, **including non-joined**
+   groups opened by link (which the batched preview tail — joined-only — doesn't cover).
+   Mirrors the DM per-conversation live tail.
+
+4. **`RelayGroupChatHistorySubAssembler`** — per-open-`GroupId`, `BackwardRelayPager`
+   (`liveTailSeconds` = 7d floor; the tails cover above it), cursors on
+   `RelayGroupChannel.history`, content `#h` (9 + poll, **all authors**) `until`+`limit`
+   on the host relay. Demand-driven by the feed markers; eager `advanceAll()` backfill
+   to a window target on open. **Replaces ChannelPublic-open content (C) and
+   ChannelFromUser (D).** All-authors, so it re-materializes my own history too.
+
+`ChannelFeedFilter` is unchanged — it reads `channel.notes`, so every path that fills
+the cache surfaces. (It has **no `limit()`**, so it already renders whatever is cached.)
+
+## Message-coverage proof (can't-miss-messages checklist)
+
+Every current content-delivery path and what covers it after:
+
+| Path (today) | Kinds / scope | After |
+|---|---|---|
+| **A** MyJoined content (50) | 9,poll `#h` joined | **Preview tail (batched `#h`, since=window)** for previews + **chat tail** when open |
+| **B** Warmup content (50) | 9,poll,11,1111 `#h` card | **KEEP** — non-joined cards/discovery aren't in the joined tail (screen-dependent, per design) |
+| **C** ChannelPublic-open content (200) | 9,poll `#h` open | **Chat tail (recent) + history pager (older, gap-proof)** |
+| **D** ChannelFromUser (`authors=me`) | 9,poll `#h` me | **History pager (all-authors) + tail + optimistic-send attach + host echo** → redundant |
+| **E** ThreadFeed | 11,1111 `#h` | **KEEP** (Threads screen; separate `threadNotes` feed). Pager adoption is a follow-up. |
+| **F** Notifications | 7,9,1111,1068,… `#h`+`#p=me` | **KEEP** — always-on, p-tags-me; unchanged bonus |
+| §3 by-id (`filterMissingEvents`) | ids | **KEEP** — quotes/replies/mentions; **+ serving-relay fix below** |
+| §3 pinned by-id backfill | ids `filterMetadataToRelayGroup` | **KEEP** (host relay; older-than-window pins) |
+| §3 replies/reactions `#e/#q` | 1111 etc. | **KEEP** — comments never attach to timeline (by design) |
+
+**Serving-relay keying hazard (real, pre-existing — fix as part of "can't miss").**
+`attachToRelayGroupIfScoped` keys the channel by `GroupId(groupId, servingRelay)`.
+All subscriptions here are host-pinned, so they're safe. But `filterMissingEvents`
+can deliver a referenced group message from a **non-host** relay, filing it under a
+different channel object than the host-keyed one the UI reads → cached but invisible.
+Fix: when attaching a group-scoped content event, if exactly one existing
+`RelayGroupChannel` carries that `groupId` (the joined/host one), attach there
+instead of minting a `(groupId, servingRelay)` channel — reusing the existing
+`singleOrNull`-by-groupId resolution already used for the `relay == null` optimistic
+branch. Ambiguous ids (the relay-wide `_` group joined on several relays) keep
+serving-relay keying.
+
+## File-by-file changes
+
+**New (`commons` model):**
+- `RelayGroupChannel`: add `val history = RelayLoadingCursors()` (mirror `ConcordChannel.history`).
+
+**New (`amethyst` datasource, per templates):**
+- `RelayGroupStateFilterAssembler` (+ SubAssembler) — always-on roster.
+- `RelayGroupPreviewTailFilterAssembler` (+ SubAssembler) — batched preview tail.
+- `RelayGroupChatTailFilterAssembler` (+ SubAssembler) — per-open live tail.
+- `RelayGroupChatHistoryFilterAssembler` (+ SubAssembler) — per-open history pager.
+- Subscription composables for each (`*Subscription`), copying the Concord ones.
+
+**Modified:**
+- `RelaySubscriptionsCoordinator`: register the four new assemblers; drop the retired ones (see below).
+- `LoggedInPage`: mount `RelayGroupStateSubscription` + `RelayGroupPreviewTailSubscription` (always-on, gated).
+- `RelayGroupChannelView`: mount chat-tail + history subscriptions; wire
+  `RefreshingChatroomFeedView(olderBoundary, markersInGap, sentinels)` + a
+  `BackfillHistoryToWindow` (copy `ConcordBackfillHistoryToWindow`).
+- `MessagesSinglePane`/`MessagesTwoPane`: drop `RelayGroupMyJoinedGroupsSubscription`
+  (its roster role moves to the always-on state sub; previews come from the tail).
+- `LocalCache.attachToRelayGroupIfScoped`: host-relay normalization (serving-relay fix).
+- `AccountViewModel.dataSources()`: expose the four new assemblers; remove retired handles.
+
+**Retired:**
+- `RelayGroupMyJoinedGroupsFilterAssembler` **content path** → deleted; the file's
+  roster role becomes `RelayGroupStateFilterAssembler` (rename/replace).
+- `ChannelPublicFilterSubAssembler` **`RelayGroupChannel` branch** (`filterMessagesToRelayGroup`
+  + `filterMetadataToRelayGroup`) → removed; metadata now always-on, content now tail+pager.
+  (Keep `filterMetadataToRelayGroup`'s **pinned-id backfill** — re-home it on the chat-tail or a
+  small pin sub so older-than-window pins still resolve.)
+- `ChannelFromUserFilterSubAssembler` **`RelayGroupChannel` branch** (`filterMyMessagesToRelayGroup`) → removed.
+- Keep `RelayGroupWarmup*` (non-joined cards), `RelayGroupsOnRelay*` (directory),
+  `RelayGroupsDiscovery*` (discover feed), `RelayGroupThreadFeed*` (threads), and the
+  notifications path unchanged.
+
+## Rollout order (additive first, retire last — never a window where messages drop)
+
+1. **Additive, no removals:** add `RelayGroupChannel.history`; add the four new
+   assemblers + subscriptions + coordinator/dataSources handles + `LoggedInPage`
+   and `RelayGroupChannelView` wiring. New content now flows through tail+pager
+   **alongside** the old A/C/D (harmless dedup by id). Compile + smoke.
+2. **Serving-relay normalization** in `LocalCache` (independent correctness fix).
+3. **Retire** A-content, C-relay-group-branch, D-relay-group-branch; move roster to
+   the always-on state sub; drop the Messages-pane `MyJoinedGroups` mount. Compile.
+4. Re-home the pinned-id backfill; delete now-dead code; `spotlessApply`; full suite.
+
+## Edge cases
+
+- **Quiet group** (newest message older than the 7-day tail): won't appear in the
+  preview tail; its Messages row falls back to cached / placeholder (same as NIP-04).
+  Opening it → the history pager's eager backfill loads it. Optional: a one-shot
+  newest-1 per quiet joined group in the state sub's initial snapshot.
+- **Non-joined open group:** covered by the per-open chat tail + history pager
+  (both per-`GroupId`, no joined-list dependency).
+- **Reconnect:** tails carry `since=recentBoundary()` (time floor, shared-safe,
+  incremental); history is `until`-based (position, not reconnect-sensitive);
+  `FiltersChanged` already ignores `since`-only changes → no full replay.
+- **Threads:** unchanged this pass; a follow-up can point `RelayGroupThreadFeed` at
+  a second `BackwardRelayPager` on `RelayGroupChannel` for kind 11/1111.
+
+## Testing
+
+- Unit: preview-tail filter batches one `#h` filter per relay with
+  `since=recentBoundary()` and no per-group limit; history filter emits only for
+  armed relays at their `requestedUntil`; state filter emits roster `#d` per relay.
+- Cursor behavior is already covered by `RelayLoadingCursors` tests (reused).
+- Manual (amy / device): join a group after session start → open → history backfills;
+  scroll up past the window → older pages load; reconnect → no full re-download;
+  quote a group message from a non-host relay → it appears in the group.

amethyst/plans/2026-07-18-nip29-group-chat-test-plan.md

@@ -0,0 +1,177 @@
+# NIP-29 group-chat loading — test plan (per screen × per assembler)
+
+**For:** an AI validating branch `claude/nip29-group-load-perf-wz4yca` before trusting the
+state-vs-content refactor (see `2026-07-18-nip29-group-chat-subscriptions.md`).
+**Question this answers:** *does the correct data load on every screen, and can we ever miss a message?*
+
+**Implemented on this branch (all headless-runnable tiers):**
+- **Tier B — filter shapes, every assembler.**
+  - Assemblers 1–6 + card-warmup joined-skip + reconnect stability (`needsToResendRequest`) + directory: `amethyst/src/test/.../relayGroup/datasource/RelayGroupFilterBuildersTest.kt` (tests the pure `RelayGroupFilterBuilders.kt` the assemblers now delegate to).
+  - #9 ChannelPublic relay-group branch (state+pins, no message window): `.../publicChannels/datasource/subassemblies/FilterRelayGroupStateTest.kt`.
+  - #10 group notifications (`#p`+`#h`): `.../service/relayClient/reqCommand/account/nip01Notifications/FilterGroupNotificationsToPubkeyTest.kt`.
+  - #8 discovery `#p` roster augmentation: `.../relayGroup/datasource/subassemblies/FilterRelayGroupsByAuthorsTest.kt`.
+- **Tier C — serves-the-shape, against the in-process `geode` relay** (`quartz/src/jvmAndroidTest/.../nip29RelayGroups/RelayGroupFilterServingRelayTest.kt`): C1 state `#d`, C2 batched preview tail, C5 threads, C6 pinned-body-below-window by id, C7 notification `#p`+`#h`, C8 directory.
+- **Tier C3 / E1 — can't-miss + resilience** (`quartz/src/jvmAndroidTest/.../paging/RelayGroupHistoryPagingRelayTest.kt`): backward `#h` walk covers every message once + stops on empty page; same-relay group isolation with overlapping `createdAt`; the **production `RelayLoadingCursors`** driven to the bottom over the wire; short-page-≠-exhaustion.
+
+**Deliberately not duplicated (already covered generically at the unit level):** echo-newest→done and rewind/prune are in `RelayLoadingCursorsTest`; no-EOSE watchdog in `WindowLoadTrackerIdleTest`; auth-CLOSED/stall/cannot-connect in `BackwardRelayPagerTest`. E1's remaining hostile-relay faults (ignore-`since`, out-of-order, AUTH-CLOSE, silence) are those same state-machine paths — re-asserting them under NIP-29 naming adds no coverage since the cursor/pager never sees the `#h` filter, only `onEvent(createdAt)`/`onEose`.
+
+**Not headless-runnable in this environment (flagged for a human):**
+- **Tier D** (Android emulator/device, per screen) — needs a device; each row must be run and any unrun row flagged.
+- **Tier E2** (conformance against a *real* third-party NIP-29 relay in a container) — non-deterministic + needs a container image; geode/strfry are generic and can't surface a real NIP-29 relay's bugs.
+
+## What is / isn't verifiable headless
+
+| Layer | Harness | Covers |
+|---|---|---|
+| Filter **shapes** each assembler builds | amethyst JVM unit tests (new) | the REQ is correct for the screen's job |
+| Relay **serves** those filters; **ingest** into `LocalCache`→`RelayGroupChannel.notes`; paging framework | **`amy` + `geode`/`amy serve`** (drives the same quartz+commons client) | the reused machinery + filter shapes work against a real relay |
+| **Screen loading** (mount → subscribe → feed renders); UI marker/sentinel→`advance`; always-on mounting; backfill-to-window loop | **Android emulator/device** | the amethyst wiring end-to-end |
+
+The amethyst *assemblers* are Android-module, so `amy` cannot invoke them directly — it validates the
+**framework + filter shapes + ingest** they depend on. The **screen** rows below therefore have a
+headless part (unit + amy) and a device part; do both, and mark any device row you couldn't run.
+
+## The assemblers under test (all of them)
+
+| # | Assembler | Mounts on | Must load |
+|---|---|---|---|
+| 1 | `RelayGroupJoinedState` (always-on) | LoggedInPage → every screen | joined groups' 39000/1/2/3/5 → name, roster, roles, pins, my membership |
+| 2 | `RelayGroupJoinedChatTail` (always-on) | LoggedInPage → Messages | joined groups' recent chat (`#h` since=window) → true newest-message previews |
+| 3 | `RelayGroupOpenChatTail` | open group chat screen | the open group's recent chat + live (incl. **non-joined**) |
+| 4 | `RelayGroupOpenChatHistory` | open group chat screen | older chat on demand (`#h` until+limit), gap-proof |
+| 5 | `RelayGroupOpenThreads` | Threads tab | kind-11/1111 threads |
+| 6 | `RelayGroupCardWarmup` | discovery cards, relay channel-list, members/metadata/parent screens | a **non-joined** card's metadata + preview; **skips joined** groups |
+| 7 | `RelayGroupsOnRelay` | relay channel-list, subgroups bar, parent picker | a host relay's whole group directory |
+| 8 | `RelayGroupsDiscovery` | Discovery screen | cross-relay discovery feed (by follows / global) |
+| 9 | `ChannelPublicFilter` (relay-group branch) | open group chat screen | open group metadata + **pinned-id backfill** (incl. non-joined; pins older than window) |
+| 10 | `filterGroupNotificationsToPubkey` (always-on notifications) | account-level | group content that **p-tags me**, even if I never opened the group |
+
+## Harness setup (headless)
+
+```bash
+./gradlew :cli:installDist            # build amy
+RELAY=ws://127.0.0.1:7447
+amy serve --port 7447 &               # embedded relay (geode); or run :geode directly
+# Identities: one "relay/operator" key (signs 39xxx), a few member keys, and "me".
+# Seed a group G on the relay:
+amy relaygroup create --relay $RELAY --gid G --name "Test" ...   # 39000/39001/39002
+# Seed chat spanning the live-tail boundary (7d): messages older AND newer than now-7d.
+for t in <timestamps old→new>; do amy publish --relay $RELAY --kind 9 --tag h=G --created-at $t "msg $t"; done
+# Seed: kind-11 thread + kind-1111 reply (h=G); a pinned kind-9 older than 7d + 39005 pin list;
+#       one kind-9 that p-tags "me"; a SECOND group G2 on the same relay (batching); a group on a
+#       second relay R2 (multi-relay); a group with <LIMIT total messages (small-group path).
+```
+Discover exact flags with `amy <verb> --help` (`fetch`/`subscribe`/`publish`/`relaygroup`).
+`amy fetch --json` gives machine-checkable output for assertions.
+
+---
+
+## Tier A — baseline (must stay green)
+```bash
+./gradlew :amethyst:compilePlayDebugKotlin
+./gradlew :quartz:jvmTest :commons:jvmTest :amethyst:testPlayDebugUnitTest :cli:test
+./gradlew spotlessCheck
+```
+
+## Tier B — new amethyst unit tests (filter shapes per assembler)
+
+Construct a minimal `Account` with `relayGroupList.liveRelayGroupList` = {G@R, G2@R} (+ a mock
+`INostrClient`). If wiring a full `Account` is too heavy, **first refactor the filter construction out
+of each `updateFilter` into a pure function** (`buildJoinedChatTailFilters(joinedTags, since)`,
+`buildOpenChatHistoryFilters(groupId, armed, until, limit)`, …) and test those — this is itself a
+worthwhile testability change. Assert, per assembler:
+
+- **1 State:** one `#d` filter per host relay; kinds = 39000/39001/39002/39003/39005; `d` = all joined ids on that relay; `since` = shared per-relay EOSE. Disabled when NIP-29 toggle off / joined empty.
+- **2 JoinedChatTail:** one `#h` filter per host relay; kinds = [9,poll]; `h` = all joined ids on that relay; `since = recentBoundary()`; **no per-group `limit`**. Two groups on one relay ⇒ **one** filter.
+- **3 OpenChatTail:** one `#h` filter, host relay, kinds [9,poll], `since = recentBoundary()`, the single open group id.
+- **4 OpenChatHistory:** with no relay armed ⇒ empty; after `advance(relay)` ⇒ one `#h` filter at `requestedUntilFor(relay)`, `limit = pageLimit`, **all authors** (no `authors`).
+- **5 OpenThreads:** `#h`, kinds [11,1111], host relay.
+- **6 CardWarmup:** a **joined** group ⇒ `emptyList()`; a **non-joined** group ⇒ metadata (unless contentOnly) + `#h` content (9,poll,11,1111) `limit`.
+- **7 OnRelay:** directory `#`-less filter, kinds 39000-39003, `limit 500`, that relay.
+- **8 Discovery:** by-follows + host-relay `#p` roster augmentation (see `RelayGroupsDiscoverySubAssembler`); global variant.
+- **9 ChannelPublic relay-group branch:** returns **only** `filterRelayGroupState` (metadata + pin ids) — **no** message-window filter.
+- **Reconnect stability:** re-run each `updateFilter` after a simulated EOSE; assert `FiltersChanged.needsToResendRequest(old,new)` is **false** for the tails/state (a `since`-only bump) — i.e. no full replay.
+
+## Tier C — `amy` + relay integration (framework, ingest, can't-miss)
+
+Issue the **exact filter shapes** from Tier B against the seeded relay and assert results:
+
+- **C1 State load:** `amy fetch --kind 39000,39001,39002,39003,39005 --tag d=G --json` returns the seeded state. (screen-1)
+- **C2 Preview/tail:** `amy fetch --kind 9 --tag h=G --since <now-7d> --json` returns only in-window messages; the newest equals the true newest. Batched: `--tag h=G --tag h=G2` returns both groups' recent in one query. (screens 2,3)
+- **C3 History paging (CAN'T-MISS — the crown jewel):** seed **N=120** messages (older than 7d, spread over months). Starting `until=now`, repeatedly `amy fetch --kind 9 --tag h=G --until <cursor> --limit 50 --json`, setting the next `until = oldest.created_at - 1`, until an empty page. Assert the **union of all pages = all 120 ids, no gaps, no infinite loop** (mirror `RelayLoadingCursors.advance/onEose`). Then confirm a relay that returns the same newest events on a repeat page terminates (the `onEose` "not strictly older ⇒ done" guard). (screen-4)
+- **C4 Ingest:** drive `amy subscribe`/`fetch` so events flow through the real client, then assert they land in a `RelayGroupChannel` keyed by `GroupId(G, R)` and surface via the `ChannelFeedFilter` predicate (kind 9/poll in, 1111 out). (screens 2,3)
+- **C5 Threads:** `--kind 11,1111 --tag h=G` returns thread + reply; confirm 1111 attaches to threads, not the chat timeline. (screen-5)
+- **C6 Pins:** a pinned kind-9 older than the window is **not** returned by C2 but **is** by `amy fetch --ids <pinnedId>` — proving the pinned-id backfill path still reaches it. (screen-9)
+- **C7 Notifications:** `--kind 9 --tag h=G --tag p=<me>` returns the me-tagged message. (screen-10)
+- **C8 Directory / discovery:** `--kind 39000 --limit 500` on R lists G+G2; a `#p=<follow>` roster query on the host relay surfaces a follow's group (the discovery augmentation). (screens 7,8)
+- **C9 Multi-relay + reconnect:** repeat C2 against R and R2; drop and re-issue the subscription and confirm (via `--json` counts / relay logs) that a `since`-carrying re-REQ returns only the tail, not a full replay.
+
+## Tier D — Android app, per screen (emulator/device; flag if unrunnable)
+
+Boot `:amethyst:installDebug` against the seeded relay (point the account's relay list at `$RELAY`).
+Watch logcat: `adb logcat | grep -E "DMPagination|relayGroup"`.
+
+For **each screen**, the pass criteria:
+
+- **D1 Messages list (1,2):** cold start with app already having joined G → the G row shows its **true newest** message (not a stale/scattered one), and its name/avatar (state). Join **G2 mid-session** (don't restart) → within seconds G2 appears with a real preview — *this is the original bug; it must now pass.*
+- **D2 Open joined group (3,4,9 + backfill):** tap G → lands on a populated first screen (~50, the backfill-to-window), name/pins present. **Scroll up** past the window → older pages load, the reach marker advances, the "loading older" card shows then flips to "all caught up" at the bottom. No duplicate rows.
+- **D3 Open non-joined group by link (3,4,9):** open a `naddr`/link to a group you have **not** joined → recent chat + live updates load (OpenChatTail) and scroll-up pages (OpenChatHistory), even though it's absent from the joined tail.
+- **D4 Threads tab (5):** open Threads → kind-11 threads list; open one → its 1111 replies.
+- **D5 Discovery (8,6):** open Discovery → groups list; a card fills name+activity (CardWarmup for non-joined). A **joined** group shown in "My Groups" still renders (from cache) though CardWarmup emits nothing for it.
+- **D6 Relay channel-list / browse (7,6):** browse a relay → its directory lists groups; tapping one warms + opens.
+- **D7 Members / Metadata screens (6/1):** roster + roles render.
+- **D8 Reconnect (2,3,4):** toggle airplane mode on the open group and Messages → on reconnect, logcat shows incremental `since`/`until` REQs, **not** a full page replay; no missing or duplicated messages.
+- **D9 Notifications (10):** with G *not* open, have another key post a message p-tagging me → it appears in notifications / unread.
+- **D10 Quiet group:** a group whose newest message is older than 7d → Messages row falls back to cached/placeholder (documented limitation), and opening it backfills via the pager.
+
+## Tier E — relay-behavior resilience & third-party conformance
+
+Tiers C/D run against geode/`amy serve` — a **compliant relay we control**. Real NIP-29 groups live on
+relays managed by other people, which have bugs and quirks. Two distinct concerns:
+
+### E1 — client resilience to a MISBEHAVING relay (deterministic, mock)
+Build a scriptable WebSocket relay (reuse the quartz relay-server + `RelayClientTestFakes`) that injects
+one fault per run; assert the tail/pager still **converge** — all messages ingested, no infinite
+`advance`, no hang, correct terminal state (`done` vs `stalled`), no duplicate rows:
+- ignores `since` (returns everything) → tail must **dedup**, not duplicate.
+- ignores / partial `until` → pager makes progress or marks done, **never loops**.
+- **short page** (returns < `limit` though more exist) → NOT exhaustion (only an *empty* page ends a relay).
+- **echoes the same newest events every page** → `RelayLoadingCursors.onEose` "not strictly older ⇒ done" fires.
+- out-of-order / duplicate events → cursor takes `min(createdAt)`; dedup by id.
+- EOSE before any event, or **no EOSE at all** → `WindowLoadTracker` idle/abs-cap; pager silence watchdog → `stalled`.
+- **AUTH-required → CLOSED("auth-required")** → relay `stalled`-but-kept; re-`advance` retries; **not silently dropped**.
+- mid-stream socket drop → resubscribe with `since`/`until`, **no full replay, no gap** (`rewindTo` on prune).
+- relay result cap below `limit` → treated like a short page.
+
+`UntilLimitPagingRelayTest` + `BackwardRelayPagerTest` already cover the empty-page / until-limit-walk /
+echo-newest cases for the **generic** pager. E1 is to (a) re-run them against the NIP-29 `#h` filter
+shapes and (b) add the not-yet-covered faults (ignore-since, out-of-order, AUTH-CLOSE, silence, reorder).
+
+### E2 — conformance against REAL NIP-29 relay implementations (surfaces THEIR bugs)
+geode / strfry / nostr-rs-relay are **generic** (store+serve by tag; no NIP-29 semantics), so they can't
+surface a real NIP-29 relay's bugs. Point the harness (reuse relayBench's `RelayUnderTest` adapter) at an
+actual NIP-29 relay (e.g. relay29, chorus, a self-hosted groups relay) in a **container**, seed a group
+via `amy relaygroup`, and run C1–C9 + E1's corpus. A failure is a **relay** bug or a client/relay
+mismatch — a NIP-29 conformance report the operator can act on. Cover the behaviors only a real NIP-29
+relay has:
+- **AUTH gating** on closed/private groups (39002 membership): does the client AUTH and then receive the `#h` timeline?
+- **relay-signed 39xxx** (the relay's own key) → the `isRelaySignedGroupEvent` gate.
+- **`previous`-tag fork rejection** on send (a relay rejecting an event whose `previous` refs it doesn't recognise).
+- the relay's actual **`since`/`until` inclusivity** and **result caps / rate limits** on the `#h` timeline.
+
+Public relays are non-deterministic (live data): use a containerized instance for CI, a public one only
+for exploratory runs. **E1 hardens our client against buggy relays; E2 tells us which third-party relay
+is buggy** — both are needed before trusting "loads correctly" in the wild.
+
+## Cross-cutting invariants (assert throughout)
+
+- **No missed messages:** the union of tail + history + pins + notifications = the full timeline; C3 is the decisive test. Also exercise `RelayLoadingCursors.rewindTo` — trim the cache below the window, page again, confirm the pruned band re-loads.
+- **No double-download on reconnect** (C9/D8).
+- **Retirement left no gap:** with `RelayGroupMyJoinedGroups` deleted and `ChannelPublic`/`ChannelFromUser` relay-group content removed, D1/D2/D3 still load — proving the tail+pager replaced them.
+- **CardWarmup joined-skip** (Tier B #6 / D5): a joined card issues no warmup REQ.
+- **Serving-relay hazard (FIXED):** a group message fetched from a **non-host** relay (e.g. `filterMissingEvents` quote resolution) used to be filed under `GroupId(G, otherR)` and lost. `LocalCache.attachToRelayGroupIfScoped`/`attachThreadToRelayGroupIfScoped` now redirect a stray (no channel for the serving relay) to the group's single confirmed **host** channel via `redirectStrayRelayGroupContent`, keyed off `RelayGroupChannel.hasRelaySignedState()` (a phantom never has relay-signed state, so the redirect only ever lands on a real host — strictly safe, the common host-pinned path is an untouched O(1) fast path). Covered by `RelayGroupContentRoutingTest`. **Device-untested:** the pure router + channel signal are unit-tested; the LocalCache wiring is a guarded fast-path/slow-path swap that still needs a device pass (Tier D) to confirm end-to-end.
+
+## Exit criteria
+- Tier A green; Tier B all assertions pass; Tier C1–C9 pass (esp. **C3**).
+- Tier D1–D9 pass on device, or each unrun row is explicitly flagged for a human.
+- Known-failing by design until follow-ups: the serving-relay hazard row and (if unadopted) a threads pager.

amethyst/plans/2026-07-20-v1.13.0-release-qa.md

@@ -0,0 +1,190 @@
+# v1.13.0 release QA — coverage, open findings, and recipes
+
+One extended testing session against v1.13.0 (~2011 commits since v1.12.6). Fixes landed on
+`fix/napplet-account-isolation-and-consent` (30 commits); each commit message carries its own
+root-cause reasoning and is the better reference for *why* a given change looks the way it does.
+
+This document records what that session **could not** capture in commit messages: what was actually
+exercised, what was not, what we chose to leave broken, and how to reproduce the setups.
+
+**Device under test:** Samsung SM-T220 tablet, Android 14, `sw600dp`, `play`/`benchmark`, arm64.
+Everything below is that one configuration unless stated.
+
+---
+
+## 1. Coverage
+
+### Exercised on device
+
+| Area | Notes |
+|---|---|
+| Upgrade path | install over a month-old build; migrations survived, ~880 ms cold start |
+| Napplet / web app per-account isolation | leak found and fixed; each account now has its own jar |
+| Embedded tab rebuild on account switch | blank-tab bug found and fixed; verified both directions + a forced-failure A/B |
+| Launch-account signing binding | desync reproduced end to end, then verified fixed |
+| NIP-46 remote signer | 13 checks, all passing (pairing gate, 22242 prompt, decrypt counterparty/plaintext/narrow grant/scoping) |
+| Concord | invite consent gate, private/voice rename, role rank gate, revoke gate |
+| NIP-29 relay groups | directory browse (crash found), naddr deep-link join, membership resolution |
+| Breadth sweep | Messages, NIP-29, Git, Podcasts, Blossom list, Location, Theming |
+| Location | map picker + teleport, before/after on 4 symptoms, composer path |
+| Notifications | tab showed ~3 items; root-caused to a `since` deadlock and fixed — feed now scrolls back 16 months |
+| Concord role grants | picker built and device-verified (rank gating, preselection, survives the fold) |
+
+### Fixed but **only unit-verified** — never run on a device
+
+Concord rollback floor · stranded recovery · member-set gap · invite expiry · moderation head ·
+**chain-poisoning fix** · community-list unknown-key preservation · V4V fee clamp · Cashu SSRF
+validator · Blossom 402 (cap / re-prompt / double-spend / `X-Reason`) · amountless-invoice display ·
+**napplet consent diff dialog** (never seen rendered) · connect-dialog capability disclosure ·
+`identity.watch` DENY · DM ciphertext previews and the `User` metadata race · chat date separators ·
+podcast duplicate description · Concord leave affordance · the three revocation wirings.
+
+### Never opened at all
+
+Nests / audio rooms (`quic` + MoQ) · Marmot / MLS · **the entire Desktop app** (where Privacy Lock
+actually ships) · Blossom "Sync all" (skipped deliberately — uploads to real servers) · podcast
+chapters / transcripts / credits · Git branch switching · Messages live-typing and per-type toggles ·
+real payments (zaps, V4V streaming, Cashu redeem) · push notifications · search · Calendar, Chess,
+Polls, Marketplace, Workouts, Badges, Follow Packs, Emojis, HLS Upload, App Store, Live Streams.
+
+NIP-29 admin: the menu is reachable and renders, but Edit metadata, invite creation, subgroups and
+pinned messages were never exercised.
+
+### Platform gaps
+
+- **Android 14 only.** `targetSdk` is 37; Android 15+ forces edge-to-edge and that path is untested.
+  An emulator makes this cheap and it is the highest-value remaining gap.
+- **Tablet only** — no phone layout. **`play` only** — no fdroid. **`benchmark` only** — the real
+  `release` (full R8) has never been built or run. **arm64 only.**
+- **Amber / NIP-55** external signer never tested, including a known decrypt double-prompt risk.
+- **Tor-on paths** — Tor was disabled for untrusted relays mid-session and not restored.
+
+---
+
+## 2. Open findings (known, deliberately not fixed)
+
+**Release mechanics**
+- `appCode` still `454` and `app` still `1.12.6` — Play hard-rejects a duplicate versionCode.
+- Firebase `TransportRuntime` cannot schedule (`JobInfoSchedulerService` missing from the merged
+  manifest). If this reproduces in `release`, **Crashlytics delivery is broken** and the release
+  ships blind.
+
+**Correctness / UX**
+- Tor settings do not take effect until app restart, with no indication.
+- An unreachable relay is reported as "No groups on this relay yet" — indistinguishable from empty.
+- NIP-29: a stale "Requested" join state is never reconciled against an arriving 39002 roster.
+- Concord: leaving does not unpin from the bottom bar, leaving a dead tab.
+- Read-only accounts render nothing for a kind:4 chatroom body (better than ciphertext, still wrong).
+- Modal geohash picker header is overdrawn by the MapView (pre-existing).
+- `amy relaygroup create` reports success on relays that silently reject it — always verify with `info`.
+- `amy login bunker://…` hangs and never delivers a `connect`.
+
+**Security / protocol**
+- NIP-46 "Generate a new address" claims to disconnect every app; it rotates the transport key and
+  revokes nothing.
+- WebView storage profiles are never deleted on logout — a removed account's cookies persist.
+  Requires a broker message so `:napplet` can call `ProfileStore.deleteProfile`.
+- Control-plane *edit* paths (`editConcordMetadata`, `grant`, channel edits) still drop unknown JSON
+  keys; only the community list was fixed.
+- **CORD-05: `community_id` does not commit to `community_root`**, so a crafted invite can carry a
+  real community's identity with an attacker's root. **Armada has the identical gap** — this needs a
+  spec conversation, not a unilateral fix.
+- **CORD-04: the BANLIST is not rank-gated, so any BAN holder can ban anyone — including the owner.**
+  Role/grant editions are rank-gated (`canActOn`), but a banlist edition is a single *whole-list*
+  entity, so no client rank-checks its contents; the gate is the author's BAN bit alone. A rank-5
+  moderator's ban of a rank-1 admin is therefore **accepted** by the fold, and the admin then loses
+  every permission (`hasPermission` is `!isBanned && …`). **Armada has the identical gap** — its
+  `banlistGate` calls the rank-blind `isAuthorized(.., Permissions.BAN)` while its role path uses
+  the rank-aware `canActOnPosition`.
+  **This is a conformance bug, NOT a spec gap** — an earlier note here said the opposite and was
+  wrong. CORD-04 §3 is explicit and normative: "One hard rule binds every action: the actor must
+  hold the required bit **and** *strictly* outrank its target — equal cannot act on equal (an admin
+  cannot ban a peer admin)", restated as step 3 of §5. Only §4, the section that defines the
+  Banlist, omits the rank half — and both independent implementations read §4 in isolation and made
+  the same mistake. Spec: <https://github.com/concord-protocol/concord> (`04.md`).
+  **FIXED and shipping** — `AuthorityResolver` now enforces §3 as a *delta rule* (an edition may only
+  add/remove npubs its signer strictly outranks; the owner is never a valid target; unpermitted
+  entries are ignored rather than rejecting the edition, so a bulk-ban survives). The UI and the
+  ban/unban write path route through it too — `ConcordModeration.currentBanned` now reads the
+  *honored* banlist via the resolver instead of decoding the raw head, which also closes a
+  laundering path where our own next ban would re-publish an unauthorized entry under our signature.
+  **Known consequence: Armada has not shipped this, so banlists can differ between clients** —
+  we ignore a ban Armada honors when the signer did not outrank the target. Deliberate.
+  Write-up to send upstream: `docs/concord-banlist-rank-conformance.md`.
+  Still open, both covered in the write-up: a banned member holding BAN can lift their own ban (the
+  gate reads role-derived permissions, so bans do not stick against any BAN holder — this one is a
+  genuine fixpoint-ordering question and needs a spec ruling), and a forked ban survives an unban
+  that does not chain onto it.
+- Notification cards whose target note isn't in `LocalCache` render "Event is loading or can't be
+  found in your relay list" (seen on old zaps). `tagsAnEventByUser` needs the reacted-to note
+  loaded, so deep history stays partially unresolved. Cosmetic, pre-existing.
+
+---
+
+## 3. Setup recipes
+
+**`amy` with an isolated identity** (never touch the maintainer's real one):
+
+```
+AMY=$(pwd)/cli/build/install/amy/bin/amy
+H=/tmp/qa-home; mkdir -p $H
+HOME=$H $AMY --account qa login <nsec> --secret-backend plaintext
+```
+`amy` scopes by `$HOME`, not a flag. `init` prompts for a passphrase and hangs without a TTY — use
+`--secret-backend plaintext` for throwaway identities.
+
+**NIP-29 test group.** `relaygroup create` on `communities.nos.social` and `relay.groups.nip29.com`
+returned success but published nothing; `groups.0xchat.com` worked. Always confirm with
+`relaygroup info`. To reach a group in a 1000+ entry directory, skip the UI and deep-link:
+`adb shell am start -a android.intent.action.VIEW -d "nostr:<naddr>"`, encoded via
+`amy encode naddr --pubkey <relay-nip11-pubkey> --kind 39000 --identifier <groupId> --relay <url>`.
+To make a device account an admin, have it join first, read its pubkey from `relaygroup info`, then
+`put-user … --role admin`.
+
+**Proving "no network before consent."** Run a local relay (`amy serve`), expose it with
+`adb reverse tcp:7777`, and make it the *only* relay in the artefact under test. Count events before
+and after the user action — that turns "I didn't see traffic" into an actual measurement.
+
+---
+
+## 4. Patterns worth acting on
+
+These recurred often enough to be process problems rather than individual bugs.
+
+**Tests that assert the bug.** At least five encoded the buggy behaviour as intended — a NIP-46 test
+named `getPublicKeyReturnsUserPubKeyWithoutAuthorization`, a V4V invariant only ever run on
+well-formed input, a napplet session test that never crossed accounts. *Always verify a new
+regression test fails without the fix* — and beware that **Gradle will serve a stale up-to-date
+`jvmTest` and report BUILD SUCCESSFUL**, which makes that check silently lie. Use `--rerun-tasks`.
+
+**Implemented-but-unreachable capabilities.** Five found: `leaveConcordCommunity`,
+`ConcordInviteBundle.isExpired`, `NappletPermissionLedger.endSession`, `grantConcordRole`, and
+`NappletBroker.revokeSessionGrants`. Each made a feature look complete to anyone reading the model
+while being unreachable to users, and the first one actually invoked turned out to be **broken as
+written**. A lint for "public capability with no caller outside its declaring file" would catch the
+whole class cheaply.
+
+**A narrow query window can deadlock against its own paging.** The Notifications tab asked relays
+for 7 days, and its backward-paging fallback only armed once the feed held a *full page* — so a
+quiet inbox could never fill a page, and therefore never widened the window. The EOSE `since` map
+is in-memory, so every cold start re-pinned it. Look for this shape wherever a "load more" boundary
+is gated on a full page: the empty state is self-sustaining. Note also that the relay-side `limit`
+already bounds these queries, which is what makes dropping the time floor safe.
+
+**Hypotheses need measurement, not plausibility.** Four confident diagnoses were wrong: the "npub in
+title" bug was a `User` lazy-init data race, not a display bug; chat date separators were a
+`reverseLayout` misconception, not bubble grouping; the map picker had no tile problem at all; and
+NIP-29 membership was a *relay rejecting the REQ* (`blocked: it's not allowed to mix metadata kinds
+with others`), not membership modelling. Instrument first.
+
+**Check the reference implementation.** Reading Armada changed the answer three times out of three —
+it corrected an owner-rotation rule that would have stranded owners, stopped an invite-binding "fix"
+that was both interop-breaking and ineffective, and supplied the chain-poisoning design (gate *after*
+folding, not before). Armada is **AGPLv3** and Amethyst is MIT: read for semantics, copy nothing.
+
+**Comments encoding constraints are load-bearing.** The synchronous SharedPreferences read looks like
+an obvious StrictMode fix; its comment records that an async hydrate reopens a settings-clobber race.
+Removing it would have been a confident, review-passing regression.
+
+**Beware concurrent agents and `git add -A`.** Two commits were contaminated, and one silently
+committed another worker's temporary revert. Stage explicit paths, always.

amethyst/plans/README.md

@@ -0,0 +1,36 @@
+# amethyst plans
+
+_Audited 2026-06-30. 21 plans: 19 shipped (archived), 1 in-progress, 1 queued, 0 abandoned._
+
+## In progress
+| Plan | Summary |
+| ---- | ------- |
+| [2026-05-24-ios-support.md](2026-05-24-ios-support.md) | Incremental KMP-to-iOS port; quartz/commons iOS targets are configured (Phase 1) but no `iosApp` module exists yet. |
+
+## Queued
+| Plan | Summary |
+| ---- | ------- |
+| [2026-06-20-napplet-inter-applet.md](2026-06-20-napplet-inter-applet.md) | NAP-INC / NAP-INTENT inter-applet messaging — deferred; prerequisites (multi-applet hosting, archetype registry, `MESSAGING` capability) not yet built. |
+
+## Archived (shipped)
+| Plan | Summary |
+| ---- | ------- |
+| [archive/2026-05-14-onchain-zaps.md](archive/2026-05-14-onchain-zaps.md) | NIP-BC (kind 8333) onchain Bitcoin zaps — hand-rolled `quartz/nipBCOnchainZaps/` consensus layer plus Android send/receive/display. |
+| [archive/2026-05-25-appfunctions-signer-prompts.md](archive/2026-05-25-appfunctions-signer-prompts.md) | How AppFunctions write verbs acquire signatures across the three signer types; write verbs now ship. |
+| [archive/2026-05-26-appfunctions-gemini-discovery.md](archive/2026-05-26-appfunctions-gemini-discovery.md) | Verifying Gemini-side discovery of Amethyst's AppFunctions; description-based (`isDescribedByKDoc`) discovery shipped. |
+| [archive/2026-05-26-appfunctions-screens-as-verbs.md](archive/2026-05-26-appfunctions-screens-as-verbs.md) | Map every Amethyst screen's feed filter to an AppFunction/MCP verb; 46 verbs now ship. |
+| [archive/2026-05-26-avif-implementation-plan.md](archive/2026-05-26-avif-implementation-plan.md) | Task-by-task plan for AVIF support via a `MediaMimeTypes` helper across the upload pipeline. |
+| [archive/2026-05-26-avif-support.md](archive/2026-05-26-avif-support.md) | Comprehensive design making AVIF a first-class image format on every Amethyst surface. |
+| [archive/2026-05-27-avif-instrumented-tests-design.md](archive/2026-05-27-avif-instrumented-tests-design.md) | Design for on-device AVIF upload-pipeline regression tests with committed fixtures. |
+| [archive/2026-05-27-avif-instrumented-tests-plan.md](archive/2026-05-27-avif-instrumented-tests-plan.md) | Implementation plan for the AVIF instrumented + JVM unit tests and their fixtures. |
+| [archive/2026-06-01-dm-live-tail-and-history-slices.md](archive/2026-06-01-dm-live-tail-and-history-slices.md) | DM loading split into a fixed live tail plus per-relay backward history paging (`WindowLoadTracker` / `RelayLoadingCursors`). |
+| [archive/2026-06-19-napplet-sandbox-host.md](archive/2026-06-19-napplet-sandbox-host.md) | Keyless `:napplet`-process WebView host with brokered, consent-gated capabilities for NIP-5A/5D content. |
+| [archive/2026-06-20-napplet-ecosystem-audit.md](archive/2026-06-20-napplet-ecosystem-audit.md) | Audit of our napplet shell against the upstream `@napplet` SDK; wire-compat gaps subsequently closed. |
+| [archive/2026-06-21-napplet-code-audit.md](archive/2026-06-21-napplet-code-audit.md) | Code audit of the napplet subsystem recording correctness/perf/refactor fixes and deferred items. |
+| [archive/2026-06-21-napplet-sdk-conformance-audit.md](archive/2026-06-21-napplet-sdk-conformance-audit.md) | Feature-by-feature SDK conformance audit; the four conformance breakers were fixed and pinned by tests. |
+| [archive/2026-06-22-napplet-nsite-security.md](archive/2026-06-22-napplet-nsite-security.md) | Security review of the nsite/napplet attack surface; launch-token identity and per-applet origins landed. |
+| [archive/2026-06-23-napplet-nap-theme-notify-inc.md](archive/2026-06-23-napplet-nap-theme-notify-inc.md) | Add the `theme`, `notify`, and `inc` NAP domains so demo napplets boot; capabilities + `NappletIncBus` shipped. |
+| [archive/2026-06-24-napplet-embedded-tabs.md](archive/2026-06-24-napplet-embedded-tabs.md) | Embedded warm bottom-bar napplet/nsite/browser tabs via `SurfaceControlViewHost`, in the new `:nappletHost` module. |
+| [archive/2026-06-25-embed-text-selection-native-parity.md](archive/2026-06-25-embed-text-selection-native-parity.md) | Host-drawn text selection (handles, magnifier, toolbar, IME proxy) for embedded sandboxed surfaces. |
+| [archive/2026-06-25-web-app-naming.md](archive/2026-06-25-web-app-naming.md) | Naming overhaul for web-app / nApplet / nSite / favorite surfaces (route, screen, controller renames). |
+| [archive/2026-06-26-nsite-napplet-favorite-icons.md](archive/2026-06-26-nsite-napplet-favorite-icons.md) | Derive favorited nSite/nApplet bottom-nav icons from verified manifest blobs (`NappletIconPath`). |

amethyst/plans/archive/2026-05-14-onchain-zaps.md

@@ -1,5 +1,8 @@
 # Onchain Zaps in Amethyst
 
+> **Status:** shipped — Full `quartz/nipBCOnchainZaps/` consensus + builder + verify layer ships with Android model/UI wiring (`OnchainZapResolver`, `OnchainZapEvent` view, `ReusableZapButton`).
+> _Audited 2026-06-30._
+
 **Date:** 2026-05-14
 **Status:** Active
 

amethyst/plans/archive/2026-05-25-appfunctions-signer-prompts.md

@@ -1,5 +1,8 @@
 # AppFunctions signer prompts — design
 
+> **Status:** shipped — `AmethystAppFunctions.kt` ships 46 `@AppFunction` verbs including write verbs that acquire signatures across signer types.
+> _Audited 2026-06-30._
+
 **Date:** 2026-05-25
 **Status:** Draft — no code yet
 

amethyst/plans/archive/2026-05-26-appfunctions-gemini-discovery.md

@@ -1,5 +1,8 @@
 # Verifying Gemini-side AppFunctions discovery
 
+> **Status:** shipped — Verification doc; verbs ship with `@AppFunction(isDescribedByKDoc = true)` description-based discovery as the doc concludes.
+> _Audited 2026-06-30._
+
 **Date:** 2026-05-26
 **Status:** Active — answers the open question from
 `2026-05-25-appfunctions-signer-prompts.md`

amethyst/plans/archive/2026-05-26-appfunctions-screens-as-verbs.md

@@ -1,5 +1,8 @@
 # All Amethyst screens as AppFunctions / MCP endpoints
 
+> **Status:** shipped — 46 `@AppFunction` verbs ship in `AmethystAppFunctions.kt`, exceeding the screen-to-verb surface this plan proposed.
+> _Audited 2026-06-30._
+
 **Date:** 2026-05-26
 **Status:** Active — informs the v1 read-verb surface and guides
 future MCP work

amethyst/plans/archive/2026-05-26-avif-implementation-plan.md

@@ -1,5 +1,8 @@
 # AVIF Support Implementation Plan
 
+> **Status:** shipped — `service/uploads/MediaMimeTypes.kt` and the rest of the AVIF upload pipeline are present in `amethyst/`.
+> _Audited 2026-06-30._
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** Make AVIF (still and animated) work as a first-class image format in Amethyst across every user-visible surface — uploads (Blossom + NIP-96), feeds, profiles, DMs, emoji packs, reactions, gallery, and caching — with graceful no-crash fallback on Android API < 31.

amethyst/plans/archive/2026-05-26-avif-support.md

@@ -1,5 +1,8 @@
 # AVIF support — comprehensive design
 
+> **Status:** shipped — AVIF upload/display support landed — `MediaMimeTypes.kt` plus the compressor/stripper/preview changes are in tree.
+> _Audited 2026-06-30._
+
 **Issue:** [vitorpamplona/amethyst#837](https://github.com/vitorpamplona/amethyst/issues/837)
 **Date:** 2026-05-26
 **Branch:** `feat/avif-support` (based on `d1610bf97`, origin/main = upstream/main)

amethyst/plans/archive/2026-05-27-avif-instrumented-tests-design.md

@@ -1,5 +1,8 @@
 # Design — AVIF instrumented tests
 
+> **Status:** shipped — The designed test files and AVIF fixtures exist under `amethyst/src/androidTest/` and `src/test/`.
+> _Audited 2026-06-30._
+
 **Date:** 2026-05-27
 **Status:** Design (pre-implementation)
 **Owning module:** `amethyst/`

amethyst/plans/archive/2026-05-27-avif-instrumented-tests-plan.md

@@ -1,5 +1,8 @@
 # AVIF Instrumented Tests — Implementation Plan
 
+> **Status:** shipped — `AvifUploadPipelineInstrumentedTest.kt`, `MediaMimeTypesTest.kt`, and the three `.avif` fixtures are committed.
+> _Audited 2026-06-30._
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** Add an Android on-device test layer that catches regressions in the AVIF upload pipeline and the Phase E bugs fixed manually (`C2`–`C8` plus follow-ups in commits `df84475d4`, `5a760c046`, `b9112550b`, `1db110cdf`).

amethyst/plans/archive/2026-06-01-dm-live-tail-and-history-slices.md

@@ -1,5 +1,8 @@
 # DM loading: live tail + per-relay history paging
 
+> **Status:** shipped — Live-tail + per-relay history layers exist (`WindowLoadTracker`, `RelayLoadingCursors`, `AccountGiftWrapsHistoryEoseManager`); doc marks itself authoritative-as-of-code.
+> _Audited 2026-06-30._
+
 > **Status:** authoritative as of 2026-06-05. The "Current architecture"
 > section below describes the code as it actually stands. The original
 > time-slice design and the round-model history are kept at the bottom under

amethyst/plans/archive/2026-06-19-napplet-sandbox-host.md

@@ -0,0 +1,274 @@
+# Napplet / nsite sandbox host — design
+
+> **Status:** shipped — Keyless sandbox host shipped: `:nappletHost` module, `NappletBrokerService`, `NappletLaunchRegistry` all present (rendering half superseded by embedded-tabs).
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-19
+**Status:** Core (commons) implemented + tested; Android host (`:napplet` process, WebView, broker IPC, consent, DataStore) implemented and compiling — needs on-device verification
+**Companion:** `quartz/plans/2026-06-19-napplet-nip5a-resolver.md` (the bottom half — manifest parsing + verified Blossom resolution — already landed in `quartz`).
+
+> **Update (2026-06-24):** the *rendering* model below (full-screen-only
+> `NappletHostActivity`, host living in `amethyst/androidMain/.../napplet/`) has
+> moved on. The sandbox runtime now lives in its own **`:nappletHost`** module and
+> renders three ways — full-screen, embedded warm bottom-bar tabs, and an arbitrary-URL
+> browser — with a cross-process `SurfaceControlViewHost`, a soft-keyboard IME proxy,
+> and per-site Tor routing. See **`amethyst/plans/2026-06-24-napplet-embedded-tabs.md`**
+> for the current architecture. The **trust model** in this doc (keyless `:napplet`
+> process, brokered consent-gated capabilities, verified-blob serving) is unchanged.
+
+## Goal
+
+Render NIP-5A static sites (nsites) and NIP-5D napplets *inside* Amethyst, with
+the applet's HTML/CSS/JS running behind a **hard trust boundary**: it must never
+be able to read the user's `nsec` or any other secret, read app storage,
+`LocalCache`, or other accounts' data, or sign / encrypt / publish / zap without
+explicit per-applet user consent. A napplet is untrusted third-party code served
+from an untrusted Blossom CDN; we treat it accordingly.
+
+## Threat model
+
+**Adversary:** the applet bundle (HTML/CSS/JS), authored by an untrusted party,
+delivered from an untrusted CDN.
+
+It must NOT be able to:
+
+1. Read the `nsec` / any `NostrSigner`-held secret, or decrypted key material.
+2. Read app private storage, `LocalCache`, DataStore, other accounts, or another
+   applet's sandboxed storage.
+3. Sign, encrypt/decrypt, publish, subscribe, or zap without explicit consent.
+4. Escalate to native code, other installed apps, or the file system.
+5. Reach the network directly to exfiltrate or fingerprint (network is a *brokered
+   capability*, default-deny).
+6. Forge content past the signed manifest (already handled by `StaticSiteResolver`:
+   manifest is authority, CDN is untrusted, every blob is sha256-verified).
+
+**Trusted:** the main Amethyst process, the broker, the consent UI, quartz
+verification. **Assumption:** the Android System WebView (Chromium) renderer
+sandbox is sound — and we add an OS-process boundary on top so that even a full
+WebView/renderer escape lands in a process that holds no secrets.
+
+## Why a separate OS process is the load-bearing decision
+
+Android processes have isolated address spaces. The decrypted `privKey`, the
+`KeyPair`, and the `NostrSigner` instance live **only in the main process heap**.
+The applet host runs in a separate process (`android:process=":napplet"`) that:
+
+- never constructs a `NostrSigner`, never touches `SecureKeyStorage`/Keystore,
+  never holds an `Account` or `LocalCache`;
+- only holds an IPC handle to *request operations*, whose **results carry no key
+  material** (a signed event, a ciphertext, a pubkey — never the private key).
+
+So even arbitrary code execution inside the WebView renderer (already its own
+sandboxed process) or inside the `:napplet` app process cannot read the main
+process's memory where the secret lives. This is the guarantee the same-process
+approach cannot make.
+
+## Process & component model
+
+```
+┌─────────────────────────────────────────┐        ┌───────────────────────────────────┐
+│  Main process  (com.vitorpamplona.amethyst)│        │  Applet process  (…:napplet)       │
+│                                            │        │                                    │
+│  Account · NostrSigner · SecureKeyStorage  │        │  NappletHostActivity               │
+│  LocalCache · NostrClient · Blossom · NWC  │        │   └─ WebView                       │
+│                                            │        │       ├─ shell page (trusted,      │
+│  NappletBrokerService (bound, not exported)│◀──AIDL─▶│       │   app-asset origin)        │
+│   └─ commons NappletBroker                 │ Binder │       │   exposes bridge → broker  │
+│       └─ NappletPermissionLedger           │  (UID  │       └─ <iframe sandbox=          │
+│                                            │ checked)│           "allow-scripts">        │
+│  NappletConsentActivity (consent UI)       │        │             = applet, opaque origin│
+└─────────────────────────────────────────┘        └───────────────────────────────────┘
+         holds secrets                                       holds NO secrets
+```
+
+### Three transport hops (each a trust step-down)
+
+1. **applet iframe ↔ shell page** — `postMessage` with strict origin checks. The
+   shell injects a tiny `window.napplet.*` client shim into the applet that wraps
+   postMessage calls into promises (request-id correlation). This is the NIP-5D
+   capability surface the applet codes against.
+2. **shell page ↔ `:napplet` native** — exactly one audited bridge,
+   `WebView.addWebMessageListener` restricted to the **shell origin only** (the
+   applet's opaque-origin iframe cannot reach it). The shell forwards validated
+   requests.
+3. **`:napplet` process ↔ main-process broker** — AIDL/`Messenger`. The broker
+   checks `Binder.getCallingUid() == Process.myUid()` (reject anything not from
+   our own app), consults the permission ledger, runs the operation with the real
+   signer/client, returns only the result.
+
+### WebView hardening (`:napplet`)
+
+- Shell document served from app assets via `WebViewAssetLoader` at a fixed
+  internal origin (`https://napplet.localhost/`). The applet lives in a child
+  `<iframe sandbox="allow-scripts">` **without `allow-same-origin`** → unique
+  opaque origin: no access to the shell DOM, cookies, `localStorage`,
+  `IndexedDB`, or the bridge.
+- Applet resources are served by `shouldInterceptRequest` from an **in-memory map
+  of already-verified blob bytes** (resolved + sha256-checked by
+  `StaticSiteResolver` *before* the WebView loads). Only manifest-declared paths
+  resolve; everything else → 404. No `file://`, no `content://`.
+- `WebSettings`: `allowFileAccess=false`, `allowContentAccess=false`,
+  `allowFileAccessFromFileURLs=false`, `allowUniversalAccessFromFileURLs=false`,
+  `setGeolocationEnabled(false)`, `mediaPlaybackRequiresUserGesture=true`,
+  `safeBrowsingEnabled=true`, no insecure mixed content. `domStorageEnabled`
+  only for a partitioned per-applet store (or off in v1).
+- **CSP**: the shell injects `connect-src 'none'` for the applet by default — the
+  applet has *no direct network*. Relay/Blossom/identity all go through the
+  broker. Direct network is itself a capability (`net`) that widens `connect-src`
+  to user-approved origins only.
+- External navigation blocked in `shouldOverrideUrlLoading`; links open in the
+  system browser only after consent.
+
+## Capability / NAP-domain model
+
+`NappletManifest.requires()` already yields the bare NAP domains
+(`identity`, `relay`, `storage`, …; see `quartz/.../tags/RequiresTag.kt`). Map
+each to a `NappletCapability` with the concrete broker operations it unlocks:
+
+| NAP domain | Capability | Broker operations |
+|---|---|---|
+| `identity` | `IDENTITY` | `getPublicKey`, `signEvent`, `nip04/44 encrypt/decrypt` |
+| `relay`    | `RELAY`    | `publish`, scoped `subscribe` (read) |
+| `value` / `wallet` | `WALLET` | NIP-57 zap request / invoice; NWC pay (stricter, separate grant) |
+| `storage`  | `STORAGE`  | per-applet sandboxed KV store, namespaced by applet identity — **never** app storage |
+| `net`      | `NET`      | widen CSP `connect-src` to approved origins |
+| *(unknown)* | — | **denied by default**, surfaced to the user |
+
+**Applet identity for the ledger** = author pubkey + `d` identifier (the
+addressable coordinate), *not* the blob hash, so grants survive updates. We still
+record the manifest aggregate hash (`computeAggregateHash()`) so a user who picks
+"ask again on code change" is re-prompted when the bundle changes.
+
+## Permission ledger
+
+`NappletPermissionLedger` — per-applet-identity grants, each
+`NappletCapability → GrantState` (`ASK` / `ALLOW_ONCE` / `ALLOW_SESSION` /
+`ALLOW_ALWAYS` / `DENY`), persisted via a `NappletPermissionStore` interface
+(DataStore actual on Android). The broker consults it on every request:
+
+- `DENY` → immediate `Denied` response.
+- `ALLOW_*` → execute.
+- `ASK` → suspend, launch `NappletConsentActivity` (main process), await the
+  user's decision, optionally persist, then execute or deny.
+
+Consent UI reuses the signer-prompt design
+(`amethyst/plans/2026-05-25-appfunctions-signer-prompts.md`) and
+`commons/.../ui/signing`.
+
+### Capability-aware consent policy
+
+The uniform "once / session / always / deny" is refined per capability:
+
+- **Payments (`WALLET`)** — `requiresPerUseConsent = true`: every `payInvoice`
+  re-prompts with the decoded sats amount; the dialog never offers "Always allow"
+  and a stray always/session grant is downgraded to one-shot so nothing persists.
+- **Identity (`IDENTITY`)** — gated by us **only when Amethyst holds the key**
+  (`NostrSignerInternal`). For remote (NIP-46) / external (NIP-55) signers the
+  broker defers to the signer's own per-request consent (no double-prompt), while
+  still honoring a standing per-napplet `DENY` and the `requires` declaration. The
+  sign prompt shows a kind + content preview.
+- **Foreground-only execution** — the napplet WebView's JS/timers are paused when
+  the host isn't resumed (`onPause`/`onResume`), so a backgrounded applet cannot
+  fire a sign/decrypt/pay request whose prompt would surface over — and be
+  confused with — Amethyst's own UI. This is the precondition that makes deferring
+  identity to an external signer safe.
+
+## Module placement
+
+- **`quartz`** — protocol done. (Optional later: a canonical `NapDomain` constant
+  set once the upstream NAP list stabilizes — an open question in the resolver
+  plan.)
+- **`commons/commonMain`** — new CLI-safe `napplet/` feature package:
+  - `napplet/NappletCapability.kt` — NAP-domain ↔ capability mapping.
+  - `napplet/protocol/` — `NappletRequest` / `NappletResponse` sealed families + JSON codec.
+  - `napplet/permissions/` — `NappletPermissionLedger`, `GrantState`, `NappletPermissionStore`.
+  - `napplet/NappletBroker.kt` — platform-agnostic broker: `(NostrSigner +
+    relay/blossom/zap handles + ledger) → (NappletRequest → NappletResponse)`.
+    The heart of the boundary; **fully unit-testable on the JVM**.
+  - `napplet/ui/` — shared consent composables.
+- **`amethyst/androidMain`** —
+  - `NappletHostActivity` (`:napplet`) + WebView + `WebViewAssetLoader` + the
+    shell HTML/JS shim asset.
+  - `NappletBrokerService` (main process, bound, `exported=false`) wrapping the
+    commons broker; `Binder` UID check.
+  - `NappletConsentActivity` (main process) using the commons consent UI.
+  - AIDL/`Messenger` plumbing; OkHttp `BlobFetcher` wiring (the resolver plan's
+    named follow-up).
+  - AndroidManifest: `:napplet` process declaration, the bound service, the
+    consent activity.
+- **`desktopApp`** — out of scope for v1 (the `:napplet` process model is
+  Android-specific; desktop needs a separate child-process/WebView strategy).
+
+## Inter-applet communication (v2)
+
+Napplets' differentiator is talking to each other. Model: applets address each
+other by napplet coordinate; `napplet.send(target, msg)` is **routed through the
+broker** (shell→broker→shell) so two opaque-origin iframes never share an origin
+or memory, and the user (or a manifest-declared allowlist) consents to the link.
+Deferred to v2; v1 nails the single-applet boundary first.
+
+## Testing & verification
+
+- **commons (now, JVM):** broker decision logic per capability
+  (granted/denied/ask), ledger state transitions + persistence semantics,
+  protocol JSON round-trips, and security cases — unknown NAP domain denied,
+  request for an undeclared path 404s without fetching, signer responses never
+  contain key bytes.
+- **Android (needs emulator):** instrumented tests for the WebView host, the
+  opaque-origin iframe isolation, and the process boundary — flagged as on-device
+  verification.
+
+## Phasing (within the "full napplet" milestone)
+
+1. **Core (commons, tested)** — protocol + capability model + ledger + broker. ✅ done.
+2. **Android host** — `:napplet` process + WebView + verified-blob serving via
+   `shouldInterceptRequest` + CSP. ✅ implemented (`NappletHostActivity`).
+3. **Broker IPC + `identity` + `relay`** — Messenger broker
+   (`NappletBrokerService`), `window.napplet.*` shim, consent UI
+   (`NappletConsentActivity`), DataStore ledger. ✅ implemented.
+4. **Capabilities beyond identity/publish:**
+   - **`relay` read** — `QueryEvents`: bounded live relay fetch (`fetchAll`,
+     EOSE/timeout) merged with `LocalCache`, newest-first. ✅
+   - **`storage`** — per-applet sandboxed KV store (`DataStoreNappletStorage`). ✅
+   - **`value`/`wallet`** — `PayInvoice` wired to the user's NWC wallet
+     (`sendZapPaymentRequestFor`); consent shows the decoded sats amount; throws
+     (→ `Failed`) on no-wallet/error/timeout. ✅ (needs on-device verification)
+   - **`net`** — CSP widening to approved origins. ⏳
+5. **Capability enforcement** — the broker refuses any request whose capability is
+   not in the manifest's `requires` (passed host→broker as `declared`), before any
+   consent prompt. ✅
+6. **Inter-applet (NAP-INC / NAP-INTENT)** — deferred; design + prerequisites in
+   `2026-06-20-napplet-inter-applet.md`. **`net`** capability and an install-style
+   up-front capability grant UI also remain. ⏳
+
+### Implemented Android components (amethyst `…/napplet/`)
+
+| File | Process | Role |
+|---|---|---|
+| `NappletHostActivity` | `:napplet` | WebView host: hardened settings, opaque-origin iframe, verified-blob `shouldInterceptRequest`, CSP, `window.napplet` shim, Messenger client |
+| `NappletBrokerService` | main | Bound Messenger service; runs the commons `NappletBroker` against the live account; `exported=false` + UID check |
+| `NappletConsentActivity` / `NappletConsentCoordinator` | main | Capability-consent dialog + suspend bridge to the broker |
+| `DataStoreNappletPermissionStore` | main | Persistent grant store (`NappletPermissionStore` actual) |
+| `NappletProtocolJson` / `NappletIpc` | both | JSON codec + Messenger wire contract |
+| `NappletLauncher` | caller | Packs a verified manifest into the host Intent |
+| `assets/napplet/shell.html` | `:napplet` | Trusted shell page that sandboxes the applet iframe and relays messages |
+
+### Remaining before user-facing ship
+
+- **On-device verification (needs emulator/device):** opaque-origin iframe really
+  excludes the bridge; CSP `connect-src 'none'` blocks fetch/XHR/WebSocket; a real
+  napplet renders and round-trips a `getPublicKey` / `signEvent` through consent.
+- ✅ **UI entry point:** a "Napplets" drawer item → `NappletsScreen` that lists
+  cached napplet manifests (kinds 15129/35129) and launches the host.
+- ✅ **Process isolation:** `Amethyst.onCreate` now skips `AppModules` entirely in
+  the `:napplet` process, so the account/signer are never loaded there. (Previously
+  `initiate()` loaded the account in every process — a real hole, now closed.)
+- ✅ **Privacy:** the host routes blob fetches through the user's Tor SOCKS proxy
+  when active; the port is passed in by the launcher (main process) so the sandbox
+  process never touches the account-bound HTTP stack.
+- ✅ **Relay discovery:** `NappletsFilterAssembler` (registered in
+  `RelaySubscriptionsCoordinator`, invoked by `NappletsScreen`) REQs kinds
+  15129/35129 from the user's read relays while the screen is open, so manifests
+  flow into `LocalCache` for the list to render.
+- **Consent UX:** reuse `commons/.../ui/signing` styling; show the manifest title
+  and a per-capability rationale; batch-grant on first run.

amethyst/plans/archive/2026-06-20-napplet-ecosystem-audit.md

@@ -0,0 +1,277 @@
+# Napplet implementation audit vs the upstream SDK / demo runtimes
+
+> **Status:** shipped — Audit doc; the wire-compatibility gaps it identified were subsequently closed (shell handshake, keys, upload now in the broker/codec).
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-20
+**Sources:** `github.com/napplet/naps` (NAP specs), `github.com/napplet/web`
+(`@napplet/shim` SDK), `github.com/kehto/web` + `kehto.github.io/web/playground`
+(reference runtime). Audited against our branch `claude/awesome-pasteur-xwiwad`.
+
+## TL;DR
+
+Our shell is a **correct and security-hardened NIP-5A/5D renderer + capability
+broker** — process isolation, verified-blob serving, default-deny CSP,
+capability-aware + signer-aware consent, foreground-only, permissions UI. Those
+are *shell-quality* properties the demo runtimes don't even specify, and we're
+ahead there.
+
+**But it is not wire-compatible with the napplet ecosystem.** Real napplets are
+built against `@napplet/shim`, which exposes a **namespaced** `window.napplet.*`
+and a **`{type:"domain.action", id}`** postMessage envelope. We inject a **flat**
+`window.napplet.*` and use a **`{id, payload:{op}}`** envelope. A napplet from the
+kehto playground calling `window.napplet.relay.publish(...)` or
+`window.napplet.shell.supports("relay")` hits `undefined` on our shell. So today:
+**0 real ecosystem napplets run as-is.**
+
+## Reference: the upstream surface
+
+`window.napplet` namespaces (from `@napplet/web`):
+
+| Namespace | Methods (upstream) |
+|---|---|
+| `shell` | `supports(domain)` — **required of every runtime** |
+| `identity` | `getPublicKey()`, `onChanged(handler)` |
+| `keys` | signing / NIP-04 / NIP-44 (separate domain from `identity`) |
+| `relay` | `subscribe(filters)` (live), `publish(event)`, `query(filters)`, `publishEncrypted` |
+| `storage` | `get(key)`, `set(key, value)`, `remove(key)` |
+| `inc` | `emit(type, payload)`, `on(type, handler)` (inter-napplet) |
+| `resource` | `bytes(url)`, `bytesAsObjectURL(url)` — fetch https/blossom/nostr/data |
+| `value` | shell-mediated value transfer + zaps (depends on `relay`) |
+| `upload` | shell-mediated file/blob upload (Blossom; depends on `relay`) |
+| `intent` | invoke a napplet by archetype |
+| `theme`, `notify`, `media`, `config`, `outbox`, `ifc`, `cvm` | further domains |
+
+**Envelope:** `{ type: "<domain>.<action>", id, ...payload }` →
+result `{ type: "<domain>.<action>.result", id, ok, ... }`.
+**Sandbox:** `iframe sandbox="allow-scripts"` only (no `allow-same-origin`) — **we
+match this exactly.**
+
+## Coverage scorecard (our broker vs upstream domains)
+
+| Domain | Status | Notes |
+|---|---|---|
+| `shell` | ✗ **missing** | `supports()` is foundational; without it well-behaved napplets bail early |
+| `identity` | ◐ | `getPublicKey` ✓; `onChanged` ✗ (no push) |
+| `keys` (sign/nip04/nip44) | ◐ | implemented, but lumped under our `IDENTITY` capability, not a `keys` domain |
+| `relay` | ◐ | `publish` ✓, `query` ✓ (now live); `subscribe` (live) ✗, `publishEncrypted` ✗ |
+| `storage` | ✓ | get/set/remove — shape matches (wire differs) |
+| `value` | ◐ | we do `payInvoice` via NWC; upstream `value` is zaps/value-transfer (depends on relay) — different method shape |
+| `resource` | ✗ | no `bytes(url)`; we only serve manifest subresources |
+| `upload` | ✗ | no Blossom upload |
+| `inc` | ✗ | deferred (see inter-applet plan) |
+| `intent` | ✗ | deferred |
+| `theme` `notify` `media` `config` `outbox` `ifc` `cvm` | ✗ | not modeled |
+
+Our extra `NET` domain has **no upstream equivalent** — upstream fetching is
+`resource`. Our `fromNapDomain` recognizes `identity/relay/value/storage/net`;
+everything else (`shell`, `resource`, `upload`, `inc`, `intent`, `keys`, …) maps
+to *unknown → denied*. So a manifest `requires: ["relay","shell","resource"]`
+would have two of three flagged unknown — and `shell` is mandatory.
+
+## The two interop blockers
+
+1. **Envelope.** Real napplets send `{type:"relay.publish", id, event}` and await
+   `{type:"relay.publish.result", id, ok}`. We expect `{id, payload:{op:"publish"}}`
+   and reply `{id, response:{type:"published"}}`. Incompatible.
+2. **API surface.** Upstream is namespaced (`relay.publish`, `identity.getPublicKey`,
+   `keys.signEvent`, `shell.supports`, `resource.bytes`). Ours is flat
+   (`getPublicKey`, `signEvent`, `publish`, `queryEvents`, `payInvoice`) + a
+   namespaced `storage`. Only `storage` lines up.
+
+Both live in our **edge layer** (the injected JS shim + `NappletProtocolJson` +
+`NappletIpc`) and the capability enum — *not* in the security core (broker,
+ledger, process model), which is dialect-agnostic. So aligning is an edge rewrite,
+not an architecture change.
+
+## What we have that the demos don't
+
+- Separate-OS-process sandbox (`:napplet`), not just an iframe.
+- Verified-blob serving (manifest-authoritative, per-blob sha256) with default-deny
+  CSP (`connect-src 'none'`) and Tor-routed fetch.
+- Capability **declaration enforcement** (manifest `requires` gate), **per-use**
+  payment consent, **signer-aware** identity deferral, **foreground-only** execution.
+- A persisted permission ledger + a permissions-management UI.
+
+These are real-shell concerns the reference runtimes leave to the implementer; we
+should keep them.
+
+## Recommended path to ecosystem compatibility (priority order)
+
+1. **Adopt the upstream envelope** `{type:"domain.action", id}` / `…​.result` in the
+   shim + `NappletProtocolJson` + `NappletIpc`. (Unblocks everything.)
+2. **Re-shape the injected shim** to the namespaced `window.napplet.*` and add
+   **`shell.supports(domain)`** (cheap; derive from the granted capability set).
+3. **Split capabilities** to match domains: `keys` (sign/nip04/nip44) distinct from
+   `identity` (getPublicKey/onChanged); rename `NET`→`resource`; add `SHELL`,
+   `UPLOAD`, `VALUE` semantics (zap-by-target, not raw invoice).
+4. **Add the push channel**: `relay.subscribe` (live events), `identity.onChanged`,
+   later `inc.on` — the host already holds a `JavaScriptReplyProxy` we can push
+   unsolicited `…event` messages through.
+5. **`resource.bytes`** (consented fetch of https/blossom/nostr/data) and
+   **`upload`** (Blossom), both brokered + consent-gated.
+6. Lower priority / app-specific: `theme`, `notify`, `media`, `config`, `outbox`,
+   `intent`, `inc`, `ifc`, `cvm`.
+
+## Update (2026-06-20): ecosystem alignment landed
+
+Acted on #1–#5. The dialect mismatch is resolved:
+
+- **Envelope** is now `{type:"<domain>.<action>", id}` → `{type:"…​.result", id, ok, …}`,
+  matching upstream (codec + host shuttle + shim rewritten; round-trip unit-tested).
+- **Namespaced `window.napplet.*`** shim: `shell.supports`, `identity.getPublicKey`
+  (+`onChanged` stub), `keys.{signEvent,nip04*,nip44*}`, `relay.{publish,query,subscribe}`,
+  `storage.{get,set,remove}`, `value.payInvoice`, `resource.{bytes,bytesAsObjectURL}`,
+  `upload.blob`. The applet's own SDK-targeted code now runs unchanged.
+- **`shell.supports(domain)`** implemented (no consent; reflects declared+brokered domains).
+- **Capabilities split** to the domain model: `SHELL`, `IDENTITY`, `KEYS`, `RELAY`,
+  `STORAGE`, `VALUE`, `RESOURCE`, `UPLOAD` (was `IDENTITY/RELAY/WALLET/STORAGE/NET`).
+- **`resource.bytes`** implemented for `https`/`data` (broker-fetched, Tor-routed,
+  consent-gated); `blossom:`/`nostr:` are a follow-up.
+
+## Update (2026-06-21): return shapes verified against `@napplet/nap@0.15.0`
+
+Pulled the canonical message types (`@napplet/nap` `*/types.d.ts` + `value-types`) and corrected
+the result field names — several were wrong guesses. The authoritative wire:
+
+| Method | Request `type` | Result field(s) |
+|---|---|---|
+| `identity.getPublicKey` | `identity.getPublicKey` | `pubkey: string` |
+| `identity.getProfile` | `identity.getProfile` | `profile: ProfileData \| null` |
+| `identity.getRelays` | `identity.getRelays` | `relays: Record<url, {read,write}>` |
+| `identity.getFollows`/`getMutes`/`getBlocked` | same | `pubkeys: string[]` |
+| `identity.getList` | `identity.getList` | `entries: string[]` |
+| `identity.getZaps` / `getBadges` | same | `zaps[]` / `badges[]` |
+| `storage.getItem/setItem/removeItem/keys` | **`storage.get`/`set`/`remove`/`keys`** | `value` / — / — / `keys: string[]` |
+| `relay.publish` / `publishEncrypted` | same | template in the **`event`** field; result `{ok, event, eventId}` |
+| `relay.query` | `relay.query` | `events: NostrEvent[]` |
+| `resource.bytes` | `resource.bytes` | `blob: Blob`, `mime: string` |
+
+`ProfileData` is `{ name?, displayName?, about?, picture?, banner?, nip05?, lud16?, website? }` —
+note **`displayName`** (camelCase), so the shell maps kind-0 `display_name` → `displayName` rather
+than dumping raw content. Corrected in code: identity reads now emit method-specific fields;
+`storage.*` wire types fixed (the *function* is `getItem`, the *envelope* is `storage.get`);
+`storage.keys` returns `keys`; `relay.publish`/`publishEncrypted` read the template from `event`;
+`getProfile` builds a `ProfileData` object. Locked by `NappletProtocolJsonTest`.
+
+**Transport: structured-clone objects + subscription push — landed.** `@napplet/core` posts
+**structured-clone objects** (not JSON strings) via `target.postMessage(obj)` and validates
+cloneability — that is how `resource.bytes` returns a real `Blob`, and why a stock napplet's
+object messages were dropped before (our shell only forwarded strings). Fixed:
+
+- **`shell.html` bridges object↔string both ways.** applet→native serializes object envelopes to
+  the string the native bridge carries (requests carry no Blobs); native→applet parses the reply
+  to an object and posts a **structured-clone object** (what the SDK reads via `e.data.type`), not
+  a string. The injected shim accepts either form.
+- **`resource.bytes` Blob.** The shell rebuilds a real `Blob` from the host's base64 `bytes`+`mime`
+  before delivering, so both the SDK and our shim resolve to a `Blob`.
+- **`relay.subscribe` push channel.** Subscriptions are answered with `relay.event` (one per match)
+  then `relay.eose`, keyed by `subId` — no `.result`, matching the SDK. A new `MSG_PUSH` IPC frame
+  lets the broker push unsolicited envelopes the host forwards verbatim; `relay.close` is a
+  fire-and-forget no-op. Today this delivers the **initial snapshot then EOSE**.
+
+Still open: a **live subscription tail** (push as events arrive, not just the snapshot) plus
+`identity.onChanged`/`inc.on`; multi-`filters` queries (we use the first filter); the Blossom
+`upload` gateway; and **on-device verification** — the shell/shim changes are JS and not exercised
+by the JVM unit tests.
+
+## Update (2026-06-21, even later): feed surfacing + nsite runtime hardening
+
+- **Feed surfacing (sandbox-preserving).** Napplets gained an inline feed card (nsites already had
+  one), both render via `NoteCompose`, are indexed in `LocalCache`, and a profile **"Apps & Sites"**
+  tab lists a user's manifests. The cards are inert (`Text`+`Button`, no WebView); execution begins
+  only on explicit tap, in the `:napplet` process.
+- **SPA route fallback** — a document navigation (Accept: text/html) to a route not in the manifest
+  serves the verified `index.html`; missing sub-resources still 404.
+- **External-link handoff** — a user-tapped off-origin http(s) link opens in the system browser
+  (gesture-gated so a hostile site can't auto-redirect); the sandbox WebView never navigates away.
+- **`resource.bytes` `blossom:` scheme** — `blossom:<sha256>` fetches from the user's kind:10063
+  Blossom servers and verifies the hash before returning. `nostr:` stays deferred (unspecified).
+- **Content-type byte-sniffing** — when a manifest path has no/unknown extension, the resolver
+  sniffs magic bytes; text/markup is never sniffed, so HTML detection stays extension-driven.
+  Unit-tested in quartz.
+- **kind:10063 fallback** — the launcher augments the manifest's `servers` with the author's
+  published Blossom list (best-effort); every blob is still sha256-verified.
+- **Blob caching** — the host OkHttp client caches blobs on disk (forced-immutable, since they're
+  content-addressed); the resolver re-verifies every served blob, so a stale entry can't be served.
+
+Remaining: live subscription tail + `identity.onChanged`/`inc.on`, the Blossom `upload` gateway,
+`getList`/`getZaps`/`getBadges`, the `nostr:` resource scheme, multi-`filters` queries — and
+**on-device verification** of all the WebView-host behavior.
+
+## Update (2026-06-20, later): verified against `@napplet/shim@0.16.0` and corrected
+
+Pulled the authoritative SDK (`@napplet/shim` v0.16.0, npm/unpkg) and corrected the
+implementation to its real contract. Commit `5ca44e27` had carried several wrong guesses; the
+verified surface is:
+
+| Namespace | Verified methods (v0.16.0) |
+|---|---|
+| `shell` | `supports(domain, protocol?)` (sync), `ready()`, `onReady(cb)`, `services` |
+| `identity` | `getPublicKey()`, `onChanged(h)`, + read API (`getRelays/getProfile/getFollows/getList/getZaps/getMutes/getBlocked/getBadges`) |
+| `keys` | **keyboard/command actions** — `registerAction/unregisterAction/onAction` (NOT signing) |
+| `relay` | `publish(template, options?)` → signed `NostrEvent`, `publishEncrypted(template, recipient, encryption?)`, `query(filters)`, `subscribe(filters, onEvent, onEose, options?)` |
+| `storage` | `getItem/setItem/removeItem/keys` (512 KB quota; `instance.*` variant) |
+| `resource` | `bytes(url)` → `Blob`, `bytesAsObjectURL(url)` |
+| `inc` | `emit(topic, extraTags?, content?)`, `on(topic, cb)` |
+
+Crucial design fact, quoted: **"signing and encryption are mediated by the shell via
+`relay.publish()` and `relay.publishEncrypted()`"** and *"no cryptographic dependencies — the
+shim sends JSON envelope messages and the shell handles identity"*. **There is no `sign()` and no
+raw nip04/44 in the napplet surface.** There is **no `value` or `upload` domain** in v0.16.0.
+
+Corrections landed (this commit):
+
+- **Signing model fixed (the big one).** Dropped the bogus `keys.signEvent` / `keys.nip04*` /
+  `keys.nip44*` napplet ops. `relay.publish` now takes an **unsigned template** (`kind/tags/content`)
+  and the broker signs it as the user and returns the signed event — exactly the upstream contract.
+  Added `relay.publishEncrypted` (broker encrypts to recipient with nip44/nip04, then signs +
+  publishes). The broker still defers the per-signature prompt to remote/external signers
+  (`signsAsUser` + non-internal signer) and honors standing DENY.
+- **`keys` re-pointed to keyboard actions** (`registerAction/unregisterAction/onAction`),
+  implemented as client-side no-op stubs (not yet wired to the host keyboard) so action-using
+  napplets don't crash. They never cross the broker boundary.
+- **`storage` renamed** to `getItem/setItem/removeItem` and **`storage.keys`** added end-to-end
+  (protocol + broker + DataStore + shim), matching upstream.
+- **`resource.bytes` now returns a `Blob`** (shim builds it from `{bytes, mime}`); wire field
+  renamed `contentType`→`mime`.
+- **`shell.supports(domain, protocol?)`** gained the optional protocol arg; added `shell.ready()`,
+  `onReady`, `services` stubs.
+- **`relay.subscribe`** wired (initial matches; live tail still a follow-up).
+- `value.payInvoice` and `upload.blob` are **kept as clearly-marked Amethyst-specific extensions**
+  (no upstream equivalent in v0.16.0) — a real `@napplet/shim` napplet never calls them, so they
+  can't conflict.
+
+Verified off-device: `commons:jvmTest` (broker + capability + ledger) and the amethyst codec
+round-trip test (`NappletProtocolJsonTest`) both green.
+
+Still open (documented, not blocking basic napplets):
+- **`upload`** — wired end-to-end (protocol/shim/capability) but the Android Blossom
+  gateway is unprovided (`Unsupported`): a correct upload needs a content Uri + signed
+  auth event + server selection, which needs on-device verification.
+- **Live push** — `relay.subscribe` returns initial matches via `query`; a live tail and
+  `identity.onChanged`/`inc.on` need a push channel over the existing reply proxy.
+- **Underspecified domains** — `inc`, `intent`, `theme`, `notify`, `media`, `config`,
+  `outbox`, `ifc`, `cvm` remain unknown→denied (no method spec available to build to).
+- **Method-name fidelity** — ✅ resolved. All standard method names/shapes are now confirmed
+  against `@napplet/shim@0.16.0` (see the later update above), not guessed.
+- **Identity read API** — ✅ partly landed. `identity.getProfile` (kind-0 content), `getRelays`
+  (NIP-65 read/write map), `getFollows` (kind-3 authors), `getMutes` and `getBlocked` (NIP-51
+  decrypted user tags) now read from the active `Account` and return JSON, gated by the IDENTITY
+  consent (and deferred to remote/external signers). `getList`/`getZaps`/`getBadges` route through
+  but degrade to `Unsupported` for now; `identity.onChanged` is still a client-side no-op (needs
+  the live push channel). Return shapes still want on-device verification against a real napplet.
+- **On-device verification** of the whole round-trip with a real playground napplet.
+
+Revised ecosystem-compatibility estimate: **~80%** — real request/response napplets using
+identity(getPublicKey)/relay(publish/publishEncrypted/query/subscribe)/storage/resource +
+`shell.supports` now run against the *verified* contract; remaining gaps are the identity read
+API, keyboard-action wiring, live subscription tails, the niche domains, and device verification.
+
+## Verdict (original assessment, pre-update)
+
+- **As a secure NIP-5A/5D renderer + broker:** ~85% — the hard, security-critical
+  parts are done and tested; gaps are on-device verification and breadth of ops.
+- **As an ecosystem-compatible napplet host (runs real napplets):** ~25% — blocked
+  by the envelope + namespaced-API mismatch and missing `shell`/`resource`. Until
+  #1–#2 land, existing napplets won't run regardless of how solid the core is.

amethyst/plans/archive/2026-06-21-napplet-code-audit.md

@@ -0,0 +1,65 @@
+# Napplet subsystem code audit — bugs, performance, refactor, placement
+
+> **Status:** shipped — Audit recording completed fixes (LiveSub teardown, broker caching, shim extraction); referenced files exist.
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-21. Scope: the napplet/nsite subsystem (`amethyst/.../napplet/`,
+`commons/.../napplet/`, `quartz/.../nip5aStaticWebsites` + `nip5dNapplets`).
+
+## Fixed in this pass
+
+| # | Category | Issue | Fix |
+|---|---|---|---|
+| 1 | 🐛 correctness | **Live subscription unsubscribed from the wrong client after an account switch** — `closeLiveSubscription`/`onDestroy` used the *current* account's client, leaking the sub on the original. | `LiveSub` holder stores the exact `INostrClient` that opened the sub; teardown uses it. |
+| 2 | 🐛 correctness | **Multi-relay subscriptions emitted N `relay.eose`** (one per relay) — the SDK expects one. | An `eoseSent` latch (`compareAndSet`) emits a single `relay.eose`. |
+| 3 | ⚡ perf | **Broker rebuilt on every request** (new gateways/prompt each call). | `broker()` caches per account (reference identity), rebuilt only on switch. |
+| 4 | ⚡ perf | **A fresh `OkHttpClient` per blob fetch** (no connection pooling). | `blobHttpClient()` caches the client keyed by Tor port (`@Synchronized`). |
+| 5 | ♻️ refactor | **105-line `SHIM_JS` string constant** in `NappletHostActivity.kt` (no highlighting, hard to edit). | Moved to `assets/napplet/shim.js`, loaded once like `shell.html`. |
+| 6 | 📝 docs | Stale shim comments (`onChanged` "follow-up", `subscribe` "snapshot…follow-up"). | Rewritten to match reality (no-op onChanged; live tail). |
+
+All compile; `commons:jvmTest` + the amethyst napplet suite stay green.
+
+## Deferred — with rationale (not silently dropped)
+
+- **Duplicate events across relays** — the same event id can arrive from multiple relays, so
+  `relay.event` is pushed more than once. Deduping needs a per-subscription seen-id set (unbounded
+  memory for long subs); napplets already dedupe by id. Left as-is; documented.
+- **Background teardown of live subscriptions** — a backgrounded-but-alive napplet keeps its relay
+  subscription open (the WebView is paused, but the service keeps streaming). It is *not* a
+  permanent leak: the service is bind-only, so closing the napplet → `unbindService` → service
+  `onDestroy` → all subs torn down. A proper pause/resume (unsubscribe on background, re-`REQ` on
+  foreground) is a real optimization but needs an IPC pause/resume signal + device verification.
+- **Request ordering** — requests are handled concurrently (`scope.launch` per message), so
+  `storage.set` then `storage.get` aren't guaranteed in-order. Matches the SDK's async model;
+  serializing would hurt throughput. Documented, not changed.
+- **`runBlocking` in `shouldInterceptRequest`** — this runs on a WebView *background* worker thread
+  (not the UI thread), so blocking there during a blob fetch is acceptable; WebView fans out
+  resource loads across workers. Left as-is.
+- **Over-flags from the sweep that aren't real:** `pendingRequests` / `bridgeReplyProxy` "races" —
+  both the `WebMessageListener` callback and the reply `Handler` run on the **main looper**, so
+  there is no cross-thread access. A null `bridgeReplyProxy` only drops a reply to an
+  already-gone WebView (the applet is gone too) — harmless.
+
+## Recommended moves to commons / quartz
+
+- **quartz (protocol-only): correct as-is.** NIP-5A/5D events, `NappletManifest`,
+  `StaticSiteResolver` + `StaticSitePathLookup` (`sniffContentType`), `SiteAggregateHash` are all in
+  `commonMain`. No app policy leaked in.
+- **commons (shared logic): mostly correct.** Broker, capability, identity, request/response,
+  permissions ledger/store, and gateway interfaces are in `commonMain` — right home.
+- **DONE: `NappletProtocolJson` → `commons/jvmAndroid`.** Moved to
+  `commons/.../napplet/protocol/` (next to the types it marshals) so the future **desktop** host
+  reuses the exact wire codec. Its tests stay in `amethyst` (JUnit4) for now and still exercise it
+  via the commons dependency; converting them to `kotlin.test` and moving to commons `jvmTest` is a
+  small follow-up. See `desktopApp/plans/2026-06-21-napplet-desktop-host.md`.
+- **amethyst (Android-only): correctly platform-bound.** `NappletHostActivity` (WebView/process),
+  `NappletBrokerService` (Service/Messenger/account), the gateway *implementations* (account,
+  `BlossomUploader`, DataStore, NWC), `NappletLauncher`, consent UI, `NappletIpc`, and the screens
+  all belong here.
+
+## Lower-priority refactors (not done)
+
+- Extract a shared Tor-aware OkHttp builder (host `buildHttpClient` vs service `blobHttpClient`
+  duplicate the proxy logic) into a small util.
+- `summaryFor`'s long `when` could become a per-request-type method, and `encodeResponse`'s big
+  `when` is repetitive — both are readability, not correctness.

amethyst/plans/archive/2026-06-21-napplet-sdk-conformance-audit.md

@@ -0,0 +1,131 @@
+# Napplet SDK conformance audit — feature by feature
+
+> **Status:** shipped — Conformance audit; the four breakers are marked fixed and pinned by `NappletSdkConformanceTest`.
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-21
+**Authoritative sources (verified, not from memory):**
+`@napplet/nap@0.15.0` (`dist/<domain>/types.d.ts` — the canonical wire message types),
+`@napplet/shim@0.16.0` (the SDK napplets bundle), `@napplet/core@0.15.0` (base envelope +
+shell handshake). Audited against branch `claude/awesome-pasteur-xwiwad`.
+
+Our edge layer: `NappletProtocolJson` (codec), `NappletRequest`/`NappletResponse` (commons),
+`NappletHostActivity` (`SHIM_JS` + `shell.html` relay), `NappletBroker`, `NappletBrokerService`.
+
+## Update — the four 🔴 breakers are now implemented
+
+All four conformance breakers below are fixed (codec pinned by `NappletSdkConformanceTest`):
+
+1. **Shell handshake** — the host answers `shell.ready` with `shell.init { capabilities:{domains,
+   protocols}, services }` built from the declared domains (`NappletProtocolJson.encodeShellInit`),
+   so a stock napplet's cached environment is populated and `supports()` works.
+2. **Id-less messages** — `onShellMessage` no longer drops messages without an `id`: `shell.ready`
+   is answered locally, and other fire-and-forget messages get a synthetic id so they reach the broker.
+3. **keys** — `keys.registerAction`/`keys.unregisterAction` decode and the broker acknowledges them
+   (declared-gated, no consent) so `registerAction()` resolves; the shim dispatches the `keys.action`
+   push. (The actual global-key binding is still a follow-up — `keys.action` isn't emitted yet.)
+4. **upload** — realigned to `upload.upload { request:{ data, mimeType, filename } }` → rich
+   `UploadResult { ok, uploadId, status, url, sha256, size, mimeType }`; `shell.html` inlines the
+   request `Blob` as base64 so it survives the bridge; the gateway uploads via the app's
+   `BlossomUploader` to the user's kind:10063 server with a signed auth event.
+
+Also now implemented (the ◐ follow-ups):
+- **Live subscription tail** — `relay.subscribe` opens a real `client.subscribe` whose listener
+  streams `relay.event` (stored + live), `relay.eose`, and `relay.closed` pushes by `subId`;
+  `relay.close` unsubscribes (tracked in `liveSubs`, torn down in `onDestroy`).
+- **Multi-`filters`** — `relay.query`/`subscribe` honor every filter in the `filters[]` array,
+  not just the first (`decodeFilterList`, gateway `query(List<Filter>)`).
+- **`resource.cancel`** — accepted at the host edge as a no-op `Done`.
+
+Still open: identity `getList`/`getZaps`/`getBadges` + `onChanged` (object shapes / list-type
+semantics underspecified), the `keys.action` push (needs a host command-palette UI to *trigger*
+actions — registration already conforms), the `resource` `nostr:` scheme (unspecified bytes),
+`inc`/`intent`/the niche domains, and **on-device verification** of the host/shell behavior.
+
+## Base envelope & error convention (verified)
+
+- `NappletMessage` carries only **`type`** (`"domain.action"`). **There is no universal `id`** —
+  request/response pairs add `id`; fire-and-forget and handshake/push messages have **no `id`**.
+- **No universal `ok`.** Each domain picks its own: `relay.publish`/`publishEncrypted`,
+  `outbox.publish`, `upload`, `intent` use `ok: boolean`; identity/storage/query results omit `ok`
+  and signal success by the data field's presence + an optional `error?: string`. The SDK shim
+  rejects when `error` is present and otherwise reads the domain's data field.
+  - **Ours:** we set `ok` on *every* result. Harmless (the SDK reads the data field and ignores the
+    extra `ok`), and our own injected shim relies on `ok`. ✅ compatible, ⚠️ non-canonical.
+
+## Transport (verified) — two architectural gaps
+
+1. **Structured-clone objects, not strings.** `@napplet/core` posts cloneable **objects**. Our
+   `shell.html` now bridges object↔string both ways (done earlier). ✅
+2. **🔴 The host drops id-less messages.** `NappletHostActivity.onShellMessage` does
+   `id = optString("id").ifEmpty { return }` — so every message **without an `id`** is dropped:
+   `shell.ready`, `inc.emit`, `keys.unregisterAction`. This silently breaks the shell handshake and
+   all fire-and-forget messages. **Must fix** to forward/handle id-less messages.
+3. **🔴 Blob-carrying requests can't cross.** `upload.upload`'s request payload contains a `Blob`
+   (`data: Blob | ArrayBuffer`). Our applet→native bridge does `JSON.stringify`, which turns a Blob
+   into `{}`. Real-napplet uploads lose their bytes. Needs a Blob-aware request path.
+
+## Shell handshake (verified) — 🔴 not implemented
+
+The SDK does **not** send a `shell.supports` message. Instead:
+- napplet posts **`shell.ready`** (no payload), and
+- the shell replies **once** with **`shell.init`** = `{ capabilities: { domains: string[],
+  protocols: Record<string,string[]> }, services: string[] }`.
+- `shell.supports(capability, protocol?)` is then answered **synchronously and locally** from that
+  cached environment.
+
+**Ours:** we implement a `shell.supports` *request* (`ShellSupports` → `Supported`) and our injected
+shim calls it async. A real napplet never sends `shell.supports`; it sends `shell.ready` — which our
+host **drops** (no id) — so its cached environment stays empty and `supports()` returns `false` for
+everything, likely making well-behaved napplets bail early. **Highest-impact gap.**
+Fix: host answers `shell.ready` with a `shell.init` carrying the declared domains.
+
+## Per-domain conformance matrix
+
+Legend: ✅ conformant · ◐ partial · 🔴 mismatch/missing · ➖ not modeled.
+
+| Domain | SDK surface (wire) | Ours | Verdict |
+|---|---|---|---|
+| **shell** | `shell.ready`→`shell.init{capabilities,services}`; `supports()` local | `shell.supports` request→`{supported}` | 🔴 wrong model (no handshake) |
+| **identity** | `getPublicKey`→`{pubkey}`; `getProfile`→`{profile}`; `getRelays`→`{relays}`; `getFollows`/`getMutes`/`getBlocked`→`{pubkeys}`; `getList`→`{entries}`; `getZaps`→`{zaps}`; `getBadges`→`{badges}`; `onChanged` push | getPublicKey ✅; profile/relays/follows/mutes/blocked ✅ (exact fields); getList/getZaps/getBadges → Unsupported; onChanged no-op | ◐ reads ✅, push/3 methods missing |
+| **relay** | `publish{event}`→`{ok,event,eventId}`; `publishEncrypted{event,recipient,encryption}`; `query{filters[]}`→`{events}`; `subscribe{subId,filters,relay?}`; `close{subId}`; pushes `relay.event{subId,event,resources?}`, `relay.eose{subId}`, `relay.closed{subId,reason?}` | publish/publishEncrypted ✅ (read `event`); query ◐ (first filter only); subscribe ✅ + event/eose push ✅ (snapshot); close ✅ (no-op); `relay.closed` not emitted | ◐ strong; multi-filter + live tail + `relay.closed` open |
+| **storage** | `get`→`{value}`; `set`; `remove`; `keys`→`{keys}` (512 KB quota) | ✅ exact (`get/set/remove/keys`, `value`/`keys` fields) | ✅ (quota not enforced) |
+| **resource** | `bytes{url}`→`{blob,mime}`; `cancel`; https/blossom/nostr/data | bytes ✅ (shell builds Blob); https/data/blossom ✅; nostr ➖; cancel ➖ | ◐ nostr + cancel missing |
+| **keys** | `registerAction{action}`→`{actionId,binding?}`; `unregisterAction{actionId}`; pushes `keys.action{actionId}`, `keys.bindings{bindings[]}` | client-side no-op stubs only; **host rejects** `keys.*` (decodes to null) | 🔴 real napplets' `registerAction` rejects |
+| **upload** | `upload.upload{request:{data:Blob,mimeType?,...}}`→`{ok,uploadId,status,url?,sha256?,...}`; `upload.status` | type `upload` + `{bytes(base64),contentType}`→`{url}`; gateway null→Unsupported | 🔴 wrong type + shape + Blob transport |
+| **inc** | `inc.emit`; `inc.subscribe`/`.result`; `inc.unsubscribe`; `inc.event` push; channel mode (`inc.channel.*`) | ➖ (deferred; maps to null→denied) | ➖ not modeled |
+| **intent** | invoke a napplet by archetype | ➖ | ➖ |
+| **theme/notify/media/config/outbox/ifc/cvm** | further domains | ➖ | ➖ |
+
+## Inconsistencies, ranked
+
+1. **🔴 Shell handshake missing** (`shell.ready`→`shell.init`). Real napplets get an empty
+   capability environment → `supports()` false → likely bail. *Fix: host emits `shell.init`.*
+2. **🔴 Id-less messages dropped** by the host. Breaks the handshake + every fire-and-forget
+   (`inc.emit`, `keys.unregisterAction`). *Fix: forward/handle id-less messages.*
+3. **🔴 `keys.*` rejects** for real napplets (we only stub client-side). *Fix: decode
+   `keys.registerAction`/`unregisterAction`, answer a stub `{actionId}`; later wire `keys.action`.*
+4. **🔴 `upload` non-conformant** (`upload` vs `upload.upload`, flat base64 vs `request:{data:Blob}}`,
+   `{url}` vs rich `UploadResult`) AND the Blob can't cross our string bridge. *Fix: realign the
+   wire + a Blob-aware request path when the gateway lands.*
+5. **◐ `relay.query`/`subscribe` use only the first of `filters[]`.** Multi-filter napplets get
+   partial results. *Fix: honor all filters.*
+6. **◐ Identity `getList`/`getZaps`/`getBadges` + `onChanged`** unimplemented.
+7. **◐ `resource` `nostr:` scheme + `resource.cancel`** unimplemented.
+8. **◐ `relay.closed` push** not emitted; **live subscription tail** absent (snapshot only).
+9. **⚠️ Non-canonical `ok` on every result** (harmless, but not how the SDK signals success for
+   identity/storage/query).
+
+## What the conformance tests assert
+
+`NappletSdkConformanceTest` (amethyst, JVM) pins the codec to the **exact SDK wire** for the
+methods we support, so a regression that drifts from `@napplet/nap` fails CI:
+
+- **Requests:** the SDK's exact envelope (`relay.publish{event}`, `storage.get`, `identity.*`,
+  `resource.bytes`, multi-`filters`) decodes to the right `NappletRequest`.
+- **Results:** `encodeResponse` emits the SDK's exact field names (`pubkey`, `profile`, `relays`,
+  `pubkeys`, `entries`, `value`, `keys`, `events`, `event`/`eventId`, `bytes`/`mime`).
+- **Pushes:** `relay.event{subId,event}` / `relay.eose{subId}` match the SDK push shapes.
+- **Gap guards:** tests that *document current behavior* for the known gaps (`shell.ready`,
+  `keys.registerAction`, `upload.upload`, `inc.emit` currently decode to `null`), each annotated
+  with the audit item so the day we fix them the guard flips intentionally.

amethyst/plans/archive/2026-06-22-napplet-nsite-security.md

@@ -0,0 +1,114 @@
+# Napplet / nsite security review (2026-06-22)
+
+> **Status:** shipped — Security review recording completed hardening; `NappletLaunchRegistry` token model and per-applet origins are in tree.
+> _Audited 2026-06-30._
+
+A review of the attack surface for NIP-5A static sites (nsites) and NIP-5D napplets,
+the protections in place, and the residual risks — with what was fixed in this pass
+and what remains as future work.
+
+## Trust model (what holds)
+
+- **Keys never enter the sandbox.** The `:napplet` process holds no account/signer.
+  Signing happens only in the main process (`signer` fixes `pubkey`, host clock
+  prevents backdating). *"Even a full WebView/renderer escape into this process yields
+  no secret."*
+- **Content integrity.** Every blob is sha256-verified against the **signed** manifest
+  before serving (`StaticSiteResolver`); cache is content-addressed + re-verified, so a
+  poisoned/stale cache can't be served. nsites launch with **zero** capabilities.
+- **Network containment.** App CSP `connect-src 'none'`; egress only via the brokered,
+  consent-gated `resource.bytes`, Tor-routed. Bridge is origin-restricted + main-frame.
+- **IPC binding** is `exported=false` + same-UID (`onBind` UID check). Payments always
+  prompt per-use with the amount.
+
+## Fixed in this pass
+
+1. **Cross-napplet identity/storage spoofing (was: per-message identity).** The broker
+   used to trust `author`/`identifier`/`declared` sent on **every** IPC message from the
+   `:napplet` process. A WebView→native escape could forge another napplet's coordinate
+   and read/act as it. Now the **main process** mints a random launch token
+   (`NappletLaunchRegistry`), hands only that token to the sandbox, and the broker
+   resolves it back to the trusted identity + declared set. A compromised sandbox can act
+   as nothing but the napplet it was launched as (it holds only its own token).
+
+2. **Private mute/block leak via `identity.getMutes`/`getBlocked`.** These read
+   `muteList.flow` / `blockPeopleList.flow`, which contain **decrypted private** entries.
+   Now they read the events' **public** tags only (`MuteListEvent.publicMutes()`,
+   `PeopleListEvent.publicUsersIdSet()`).
+
+3. **Silent "allow-always" actions + UI-redress.** Added persistent **trusted chrome**
+   (a sandbox bar the applet can't draw over: shield + name + tap-to-see "what it can
+   access") and a **live toast** when a granted RELAY/UPLOAD/VALUE op runs — so an
+   allow-always grant can't act completely silently. Also fixes the host drawing under
+   the status/navigation bars (edge-to-edge insets).
+
+4. **Real per-applet storage origin (was: opaque sandbox → broken apps).** The applet
+   ran in an `allow-scripts`-only iframe served under `napplet.local/app/`, i.e. an
+   **opaque ("null") origin**. That has no `localStorage`/`IndexedDB`/service worker
+   (reads throw `SecurityError`), and module scripts / asset fetches are CORS-blocked, so
+   essentially every bundled SPA rendered **blank** or **crash-looped** ("cache version
+   0 → reset → reload" forever, because IndexedDB never persisted the version). Each
+   applet now loads on its **own** internal origin `https://<id>.napplet.local` —
+   `id = sha256(author + ":" + identifier)`, truncated + letter-prefixed to a DNS label —
+   with `allow-scripts allow-same-origin`, served at the **origin root** (bundlers emit
+   absolute `/assets/...` URLs). A real origin restores DOM storage / IndexedDB / SW and
+   makes the applet's own assets same-origin (no CORS shim needed). **Isolation is
+   preserved precisely because the applet origin is distinct from the shell's:** the
+   bridge stays origin-restricted to the shell (`napplet.local`), so the cross-origin
+   applet still cannot reach it or read the shell DOM — it talks only via `postMessage`,
+   which the shell relays. Per-applet subdomains keep applets' storage isolated from one
+   another; CSP `connect-src 'none'` is unchanged; the app CSP was **tightened** to
+   `'self'` (it no longer grants the shell origin).
+
+## Residual risks / future work
+
+- **`allow-same-origin` is safe only while the applet origin ≠ the shell/bridge origin.**
+  A frame carrying *both* `allow-scripts` and `allow-same-origin` can strip its own
+  sandbox **iff it is same-origin with its embedder**; here it never is (applet on a
+  per-applet subdomain, shell on `napplet.local`), so it cannot. **Load-bearing
+  invariant — do not break:** never serve the applet on the shell origin, and never add
+  an applet origin (`*.napplet.local`) to the bridge's `addWebMessageListener` allowlist
+  (kept to `setOf(ORIGIN)`). Collapsing the two origins would hand the applet the bridge.
+- **Persistent client storage is now a persistence/exfil surface.** The applet keeps
+  `localStorage`/`IndexedDB` across launches (origin-scoped, per applet, key-free and
+  isolated from other applets). A consented applet can build durable local state and,
+  combined with allow-always RESOURCE, a durable profile. Tie to the session-scoped-grant
+  proposal above; consider a "clear this applet's data" affordance.
+- **Per-applet origin id.** `sha256(author:identifier)` is stable per applet and
+  collision-resistant; root/replaceable applets (kinds 15128/15129, no `d` tag) collapse
+  to one origin per author — fine, since there's one root per author. Changing the id
+  scheme later resets an applet's storage (new origin); acceptable.
+- **Service workers are reachable but unwired.** With a real origin the applet *can* now
+  register a service worker; the host does not yet route SW fetches
+  (`ServiceWorkerControllerCompat`), so registration currently fails gracefully (a
+  warning, not a crash). If SW support is wired later, SW-originated fetches MUST go
+  through the same verified content server, never the network.
+
+- **Coarse, persistent grants.** Non-payment capabilities persist as ALLOW_ALWAYS. A
+  consented napplet can still, thereafter, publish as you (RELAY), read your social graph
+  (IDENTITY), and make arbitrary network calls (RESOURCE) without re-prompting. The new
+  chrome + toasts make this *visible*, but the model is still allow-forever. **Proposed:**
+  a session-scoped grant ("Allow while open", cleared on close) in `GrantState` +
+  consent dialog, defaulted for RESOURCE/RELAY; and per-origin consent for cross-origin
+  `resource.bytes` https fetches.
+- **`resource.bytes` as exfil channel.** Once RESOURCE is allow-always, the applet can
+  encode data into arbitrary https URLs through the Tor proxy. Tor hides the IP, not the
+  payload. Tie to the per-origin/session proposal above.
+- **`'unsafe-inline'` in app `script-src`.** Required to inject the shim; the applet is
+  the author's own (content sha256-pinned), so it's not an escalation. `connect-src
+  'none'` remains the real boundary. Residual, accepted.
+- **Trust pivots on the author key.** A compromised author key lets an attacker push a
+  new *signed* manifest and own the app — expected Nostr trust model. Aggregate `x` hash
+  is enforced when present (only *recommended* by the spec); per-path hashes always
+  protect.
+- **Sandbox isolation is now structural.** The `:napplet` runtime
+  (`NappletHostActivity`, content server, IPC, key actions) lives in its own
+  `:nappletHost` module that depends only on `:commons` + `:quartz` — so it is
+  *compile-time incapable* of importing `Amethyst`/`LocalCache`/`Account`. The
+  broker-side (signer, gateways, `NappletLaunchRegistry`) stays in `:amethyst`;
+  the activity binds the broker service by class-name string and the two halves
+  communicate only over Messenger IPC.
+- **Launch-token lifecycle.** Tokens are capped (LRU, 128) rather than explicitly
+  unregistered on sandbox close (the sandbox is a separate process and can't reach the
+  main-process registry). A long-backgrounded napplet whose token was evicted would need
+  relaunch. Acceptable; revisit if it bites.

amethyst/plans/archive/2026-06-23-napplet-nap-theme-notify-inc.md

@@ -0,0 +1,55 @@
+# Napplet NAP domains: theme, notify, inc
+
+> **Status:** shipped — `NappletCapability` has `THEME`/`NOTIFY`/`INC` and `NappletIncBus` is wired into `NappletBrokerService`.
+> _Audited 2026-06-30._
+
+Date: 2026-06-23
+Status: in progress
+
+## Problem
+
+Real-world demo napplets (e.g. kehto/web's `apps/playground/napplets/*`) hard-gate
+their own boot: each reads `window.napplet.shell.supports(<domain>)` for every
+domain in its manifest `requires` and aborts ("unavailable") if any is missing.
+**Every** kehto demo `requires: theme`; most also need `inc`; toaster needs
+`notify`. Amethyst's `fromNapDomain` returns `null` for `theme/notify/inc/cvm`,
+so `shell.supports()` is false for them and all demos fail at boot.
+
+These are real NAP service domains (kehto ships reference handlers). We add the
+three the demos need (theme, notify, inc); `cvm` is deferred (its own design).
+
+## Wire contracts (verified against kehto reference services + demos)
+
+- **theme** — `theme.get` → `theme.get.result { theme: { colors: { background, text, primary } } }`.
+  Optional host push `theme.changed { theme }` (we skip the push for v1; the
+  app theme rarely changes while a napplet is foreground). Read-only, **no consent**.
+- **notify** — `notify.create { title, body }` → `notify.created { id }` (past-tense,
+  **not** the generic `.result`), `notify.list` → `notify.listed { notifications }`,
+  `notify.dismiss { notificationId }` fire-and-forget. Consent-gated (ask once).
+  Host shows a system notification + tracks a per-coordinate store for list/dismiss.
+- **inc** — a topic pub/sub bus. `inc.emit { topic, args, payload }` (fire-and-forget)
+  delivers `inc.event { topic, payload }` to **other** subscribed napplet sessions
+  (no echo to the sender). `inc.subscribe`/`inc.unsubscribe` register interest.
+  Gated on the INC declaration at the router edge (like `identity.watch`), no
+  per-call consent. NOTE: Amethyst runs napplets **foreground-only, one at a time**,
+  so cross-napplet delivery is usually a no-op in practice — but the bus is correct
+  if/when multiple sessions overlap, and it lets the demos boot + emit without error.
+
+## Capability mapping & consent
+
+`NappletCapability` gains `THEME`, `NOTIFY`, `INC`; `fromNapDomain` maps the bare
+domains. `requiresConsent` is false for `SHELL` and `THEME` (negotiation/cosmetic),
+true otherwise. INC is authorized at the router (declared-only) and never reaches
+the broker consent path.
+
+## Touch points
+
+- commons: `NappletCapability`, `NappletRequest`, `NappletResponse`,
+  `NappletBrokerCollaborators` (new gateways), `NappletBroker`,
+  `protocol/NappletProtocolJson` (decode + custom reply types + inc/theme pushes),
+  `NappletRequestRouter` (inc edge ops).
+- amethyst: `gateways/AccountNappletGateways` (+ theme/notify gateways), an
+  app-wide `NappletIncBus`, and `NappletBrokerService` wiring (notify store + inc
+  push transport, like `NappletLiveSubscriptions`/`NappletIdentityWatch`).
+
+Staged commits: (1) theme, (2) notify, (3) inc.

amethyst/plans/archive/2026-06-24-napplet-embedded-tabs.md

@@ -0,0 +1,183 @@
+# Embedded napplet / nsite / browser tabs — final architecture
+
+> **Status:** shipped — `EmbeddedTabLayer` and the `:nappletHost` module exist; embedded warm-tab + browser render paths are implemented (PR #3348).
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-24
+**Status:** Implemented on `claude/webview-menu-custom-url-ikrgbz` (PR #3348); needs on-device verification.
+**Supersedes the rendering half of** `amethyst/plans/2026-06-19-napplet-sandbox-host.md`
+(full-screen-only `NappletHostActivity` in `amethyst/androidMain`). The trust
+model is unchanged and still governed by
+`amethyst/plans/2026-06-22-napplet-nsite-security.md`.
+
+## What changed since the sandbox-host plan
+
+The 2026-06-19 design rendered a napplet/nsite **only** full-screen, in its own
+`:napplet` Activity/task. This branch adds:
+
+1. A second, **embedded** render path: warm bottom-bar "favorite" tabs that live
+   inside the main Amethyst window, swapped in place with no relaunch — built on
+   a cross-process `SurfaceControlViewHost` surface.
+2. A **browser** host: the same keyless `:napplet` sandbox now also renders an
+   arbitrary user-typed URL (not just a verified-blob nsite/napplet), as both a
+   full-screen activity and an embedded tab.
+3. A working **soft keyboard** inside the embedded surface (the cross-process
+   surface window cannot itself be an IME target).
+4. The sandbox runtime extracted into its **own `:nappletHost` module** (depends
+   only on `:commons` + `:quartz`; cannot import `Amethyst`/`LocalCache`/`Account`).
+5. **Per-site Tor / open-web** routing memory, and a startup **preloader** that
+   warms every bottom-bar favorite so the first tap is instant.
+
+The keyless-sandbox guarantee is preserved throughout: keys live only in the main
+process, every NIP-07 / `window.napplet` call is brokered + consent-gated, and the
+embedded surface is z-ordered **below** the client window.
+
+## Two render paths, one sandbox
+
+| | Full-screen | Embedded tab |
+|---|---|---|
+| Container | `NappletHostActivity` / `NappletBrowserActivity` (`:napplet` task) | `SandboxedSdkView` in `EmbeddedTabLayer` (main window) |
+| Surface | the Activity's own window | `SurfaceControlViewHost` shipped to the host `SandboxedSdkView` |
+| Chrome (pull-down) | `NappletControlSheet` (native Android `View`s) | `TopControlSheet` (Compose) |
+| Soft keyboard | the Activity's own window (native) | `RemoteImeView` proxy in the **main** window |
+| Lifecycle | one session per task | many warm sessions, parked off-screen |
+
+Both paths run the **same** `NappletHostService` / `NappletBrowserService` and the
+same `shell.html` + `shim.js`; only the host/embedding differs.
+
+## Persistent warm-surface layer (embedded)
+
+`EmbeddedTabLayer` is mounted once in the app shell, below the drawer/dialogs. It
+renders **every** warm session's `SandboxedSdkView` and keeps it attached:
+
+- `EmbeddedTabHost` (object) owns the set of warm `sessions`, the active id, and
+  the reserved `contentBounds`. `setActive(id)` returns a token; `clearActiveIfOwner(token)`
+  only clears if the caller still owns it (so a fast tab A→B→A swap can't have B's
+  teardown clear A's just-set active id). `retainOnly(ids)` warm-keeps the
+  bottom-bar favorites (+ the momentarily-active tab) and evicts the rest.
+- The active session is offset over the current tab's bounds; **inactive warm tabs
+  keep the same size and are merely shifted ~10 000 dp off-screen** (never resized
+  to 1 dp). Parking by translation rather than resize is what avoids the ~1 s black
+  flash on every tab switch (a resize forces a surface re-render).
+- The surface is z-below, so Compose draws over it — that's how `TopControlSheet`
+  sits on top. Each surface is wrapped in `EmbeddedSurfaceTouchHolder` so a scroll
+  gesture isn't stolen by a host-side ancestor (the cross-process WebView can't
+  `requestDisallowInterceptTouchEvent` for itself).
+
+`EmbeddedTabFactory` builds/acquires the per-app controller (`EmbeddedBrowserController`
+/ `EmbeddedNappletController`, both `EmbeddedSurfaceController` + `EmbeddedImeBridge`)
+and gates preloading on Tor (won't warm a Tor-routed site over clearnet while Tor is
+still connecting).
+
+## Per-session services (the multi-tab refactor)
+
+`NappletHostService` / `NappletBrowserService` are **single shared instances** (same
+bind `Intent`); per-tab state lives in a `NappletTab` / `BrowserTab` map keyed by the
+client-stamped `KEY_SESSION_ID` (`NappletEmbedContract` / `NappletBrowserContract`).
+Each tab carries its **own** reply `Messenger`, so broker responses + pushes route to
+the right tab (the broker echoes `replyTo`). Critical correctness rules baked in:
+
+- `contentServer` is `@Volatile` (read on the WebView worker thread in
+  `shouldInterceptRequest`, written on main).
+- broker-reply delivery drops a reply whose tab was replaced (`tabs[id] !== tab`)
+  and wraps `postMessage` in `runCatching` (a torn-down WebView can't crash the relay).
+- session close / `onDestroy` tears down **that tab's** content server + WebView only
+  (an earlier bug destroyed sibling tabs' WebViews → "open A, switch to B, back to A =
+  black").
+
+## Embedded soft keyboard (IME proxy)
+
+The embedded surface is a `SurfaceControlViewHost` window: in z-below mode it forwards
+touch but **cannot be an IME target**, so a focused field would get no keyboard. The fix
+mirrors Flutter's `TextInputPlugin`:
+
+- `RemoteImeView` — an invisible, focusable `EditText` in the **main** app window takes
+  the keyboard. A real local `Editable` is the source of truth (the platform handles
+  composing regions, suggestions, autofill); edits are **coalesced across batch edits**
+  and the whole **editing state** (text + selection + composing) is shipped — not
+  individual ops. It flushes **synchronously** at the outermost `endBatchEdit` so a
+  compose-then-commit in one frame preserves the composing region.
+- `shim.js` IME agent (gated on `window.__nappletImeProxy`) applies that state to the
+  focused field and synthesizes the matching DOM `input`/composition events so web
+  frameworks react as if typed natively. It is surrogate-pair-safe (emoji / CJK-supplement
+  never split into a lone surrogate) and supports `contenteditable` via Range-mapped char
+  offsets (in-place replacement, not a `textContent` overwrite), with selection-echo dedup.
+- `EmbeddedTabLayer` shrinks the active surface to clear the keyboard using the **snapped**
+  `WindowInsets.imeAnimationTarget` (not the per-frame animated `ime`), so the expensive
+  cross-process surface resize happens once, not every animation frame.
+
+State + ops cross over `MSG_IME_EVENT` / `MSG_IME_OP` (`EmbeddedImeBridge`). Full-screen
+hosts set neither IME flag (they have a native keyboard).
+
+## Per-site network routing
+
+`WebUrlNetworkRegistry` (keyed by site host) and `NappletNetworkRegistry` (keyed by
+`author:identifier`) remember whether a site routes through **Tor** (default) or the
+**open web** — some servers reject Tor exits, so a user can opt one out and it must
+survive relaunch. Both hydrate from DataStore asynchronously and now expose
+`awaitReady()`; the preloader awaits hydration **before** its first routing decision so a
+cold start can't route an open-web-pinned site through Tor. Live in the **main** process
+only; the keyless sandbox never reads them (the launcher stamps the choice into the
+launch intent).
+
+## The two control-sheet twins
+
+`TopControlSheet` (Compose, `:amethyst`, drawn in the main process over the z-below
+surface) and `NappletControlSheet` (hand-built Android `View`s, `:nappletHost`, in the
+keyless sandbox process) are deliberate twins: the sandbox module is Compose-free and
+can't depend on `:amethyst`, so the composable can't be shared. They are kept visually
+identical by hand — same 10 dp row rhythm, same muted-icon + framework `Switch` Tor row.
+Both are a top-center pull-down (collapsed = a small grabber out of the corner where a
+site puts its own avatar/menu): route over Tor, reload, "what it can access" (sandboxed
+apps), open full screen.
+
+## Bottom bar
+
+Built-ins and favorites are one ordered list (`BottomBarEntry`, polymorphic with
+`@SerialName("builtIn")` / `@SerialName("favorite")`). `UISharedPreferences.decodeBottomBarItems`
+migrates the old persisted discriminator (the kotlinx default fully-qualified class name)
+to the short names, falling back to `DefaultBottomBarEntries` — fixing the one-time bottom
+bar reset the `@SerialName` change would otherwise have caused.
+
+The **Browser** launcher (`BrowserScreen`) is an omnibox + the shared `FavoriteAppsGrid`;
+each opened URL lands in its own full-screen `NappletBrowserActivity`. When the Browser is
+reached from the drawer (pushed) rather than as a bottom-bar tab, its omnibox shows a back
+arrow — the standard `nav.canPop()` rule (mirrors `NappletsTopBar`).
+
+## File map (final)
+
+**`:nappletHost`** (`com.vitorpamplona.amethyst.napplethost`, `:napplet` process):
+`NappletHostService` / `NappletBrowserService` (per-session WebView hosts),
+`NappletHostActivity` / `NappletBrowserActivity` (full-screen),
+`NappletHostUiAdapter` / `NappletBrowserUiAdapter` (`SandboxedUiAdapter` for the embedded
+surface), `NappletControlSheet` (native pull-down), `NappletContentServer` +
+`NappletBlobHttp` + `NappletBlobCache` + `NappletBlobPrefetcher` (verified-blob serving,
+Tor-routed, content-addressed), `NappletEmbedContract` / `NappletBrowserContract` /
+`NappletHostContract` (Messenger wire keys), `NappletIpc`, `NappletKeyActions`,
+`NappletWebViewInsets`.
+
+**`:amethyst` embed** (`ui/screen/loggedIn/embed`): `EmbeddedTabLayer`, `EmbeddedTabHost`,
+`EmbeddedTabFactory`, `EmbeddedTabChrome`, `EmbeddedSurfaceController`,
+`EmbeddedSurfaceTouchHolder`, `EmbeddedImeBridge`, `RemoteImeView`, `TopControlSheet`,
+`EmbeddedTabPreloader`, `TorToggleButton`.
+
+**`:amethyst` main-process napplet** (`napplet/`): `NappletBrokerService`,
+`NappletLauncher`, `NappletLaunchRegistry`, `WebUrlNetworkRegistry`,
+`NappletNetworkRegistry`, `SandboxForegroundHold`, consent (`NappletConsent*`), gateways,
+DataStore stores.
+
+**`:amethyst` launchers/screens**: `BrowserScreen`, `FavoriteWebAppScreen`,
+`FavoriteNappletScreen`, `FavoriteAppsScreen` + `FavoriteAppsGrid`.
+
+**`:commons`**: `shell.html`, `shim.js` (`composeResources/files/napplet/`),
+`FavoriteApp`/`FavoriteAppIcon`, `BottomBarEntry`.
+
+## Residual / on-device verification
+
+- All embedded-surface behavior (IME, scroll-gesture claiming, warm-keep across swaps, the
+  Tor shrink) needs emulator/device verification — `SurfaceControlViewHost` + the IME proxy
+  can't be unit-tested.
+- The IME proxy runs a host-window `EditText`; it ships only editing **state** to the page,
+  never to any key material — the keyless-sandbox boundary is unaffected.
+- Launch-token lifecycle, coarse persistent grants, and the `resource.bytes` exfil channel
+  remain as tracked in the 2026-06-22 security review.

amethyst/plans/archive/2026-06-25-embed-text-selection-native-parity.md

@@ -0,0 +1,259 @@
+# Embedded text selection — native-Android parity
+
+> **Status:** shipped — Doc states core feature-complete; host-drawn selection (handles, magnifier, IME proxy) landed in `EmbeddedTabLayer`/`RemoteImeView`.
+> _Audited 2026-06-30._
+
+**Status:** core feature-complete. The working set landed in `fix(embed): IME typing +
+host-drawn text selection for embedded surfaces` (commit `e0a2a9ab81`); subsequent
+sessions added the magnifier, the `SelectionUiState` refactor, hybrid word+char
+handle-extend, and a run of polish/bug fixes (below). **The one open platform bug —
+full-screen round-trip kills selection paint — is now FIXED** (root cause was
+process-global `pauseTimers()` + an attached `WebView.destroy()`; see that section).
+
+**2026-06-26 fixes (branch `fix/embed-ime-selection`):**
+- **No-blink word-select** — the overlay handles + toolbar blinked 2–3× on long-press
+  word-select; cause was the shim's selection-*reveal* scrolls (a `<textarea>` auto-
+  scrolling to show a forming/re-asserted range) tripping the hide-on-scroll path. The
+  shim now timestamps selection activity (`lastSelActivityAt`) and treats a scroll within
+  350 ms as a reveal-scroll (reposition, don't hide, don't re-arm the timer). Plus a
+  `RemoteImeView` range-lost debounce as a safety net. (#2, #3)
+- **Page selection clears on field focus** — focusing a field left the page-text handles
+  + Copy bar up (the shim's page `selectionchange` is muted once a field is focused), and
+  being z-above they STOLE the field handle's drag. Fixed: `focusin` emits `pagesel:false`
+  (+ resets the scroll state); host `ImeEvent.Focus` also drops the page overlay. (#2)
+- **Caret handle drag** moved the loupe but not the caret — the unified `awaitEachGesture`
+  did `change.consume()` BEFORE `change.positionChange()`, and `positionChange()` returns
+  `Offset.Zero` once consumed, so `fp` never accumulated. Fixed with
+  `positionChangeIgnoreConsumed()` (also immune to the sandbox surface consuming the move). (#10)
+- **Hybrid word+char handle-extend** completed (#5, below).
+- **Full-screen round-trip corruption FIXED** (was the open bug; see section).
+- **Embed WebViews follow the APP theme** — separate from selection, but same surfaces:
+  see `embed-webview-prefers-color-scheme-limitation` memo / `EmbedWebViewTheme.kt`.
+
+## Why we draw selection ourselves
+
+Editable fields inside an embedded napplet/nsite/browser tab live in the keyless
+`:napplet` process and render through `SurfaceControlViewHost` /
+`SandboxedSdkView` (privacy-sandbox UI). A WebView rendered into an off-window
+surface like this **cannot host the soft keyboard and cannot present Chrome's
+own text-selection UI** (handles, the floating action-mode toolbar, the
+magnifier). Chrome detects it has nowhere to put that UI and collapses the
+selection to the focus endpoint.
+
+So, exactly like Flutter's `TextInputPlugin` did for its virtual-display era, we
+relay editing to the main process: an invisible `EditText` (`RemoteImeView`)
+hosts the keyboard, `shim.js` mirrors DOM selection/caret geometry out over the
+Messenger channel, and `EmbeddedTabLayer` draws the selection UI in Compose on
+top of the surface. Everything we want for parity, we draw — the platform gives
+us nothing here.
+
+## What native Android gives a text field (the parity target)
+
+This is the full feature inventory we are cloning, with activation/deactivation
+rules, so we can check off coverage. Native impl lives in `android.widget.Editor`
+(+ `SelectionActionModeHelper`, `android.widget.Magnifier`,
+`PopupTouchHandleDrawable` on the Chrome side).
+
+| # | Native feature | Activates | Deactivates | Our status |
+|---|----------------|-----------|-------------|------------|
+| 1 | **Insertion handle** (the teardrop "blob" under the caret) | tap in editable text; tap again to re-show | typing, scroll start, focus loss, ~4s inactivity timeout | ✅ `InsertionHandle`. **Native availability rule now matched (2026-06-25):** only shown when the field is NON-EMPTY (`Editor` gates the handle behind `text.length() > 0`, via `SelectionUiState.fieldHasText`) — fixes it popping up on focus of an empty box; hides on typing (`onEdited`), scroll (`scrolling`), focus loss, and ~4s inactivity (`hideCaret` timeout), re-showing on the next tap — via an explicit `ime.carettap` shim signal (DOM `click`), so a tap that doesn't move the caret still re-shows it. Device-verified. |
+| 2 | **Selection handles** (asymmetric left/right teardrops) | long-press word, double-tap word, drag-extend | tap-collapse, typing, new selection | ✅ `SelectionHandle(isStart)` + drag-to-extend, for BOTH plain page text (`pageExtend`) AND in-field `<input>`/`<textarea>` selections (`fieldExtend`, 2026-06-25). The shim reports the selection's caret feet (`sx/sb`,`ex/eb`, flagged `rng`) via the same mirror-div as the caret; the host holds the range geometry separately so Chrome's transient collapse-to-caret (the re-assert fight) doesn't yank the handles to the field edges. **Tap-to-collapse (2026-06-25):** a single tap inside a selection dismisses it to a caret at the tapped offset + insertion handle — the shim's `click` handler collapses explicitly via `offsetFromPoint` (off-window Chrome doesn't do it itself). Device-verified. |
+| 3 | **Floating toolbar** (Cut/Copy/Paste/Select-All/Share/…) | selection made, or tap insertion handle (Paste/Select-All) | scroll/fling (hides, returns on settle), handle drag (hides), tap-collapse | ⚠️ `EmbeddedSelectionToolbar` (Cut/Copy/Paste/Select-All). **Hide-during-handle-drag ✅ device-verified.** Hide-during-scroll via `SelectionUiState.scrolling` (shim `ime.scroll` + re-report on settle). **2026-06-26: the scroll path was hardened** — selection-*reveal* scrolls (forming/re-asserting a range auto-scrolls a `<textarea>`) are no longer treated as user scrolls (they blinked the overlays); the shim guards them via `lastSelActivityAt` and the hide self-heals instead of re-arming. (User content-scroll-hide still wants a clean on-device pass.) Still missing: overflow, Share/Web-Search/process-text. |
+| 4 | **Magnifier / loupe** (the zoom bubble above the finger while dragging a handle or the caret) | finger down + moving on a handle or the caret | finger up | ✅ **Built (2026-06-25).** `Magnifier` bubble in [EmbeddedMagnifier.kt] follows the dragged caret/selection handle, showing live magnified page pixels captured in the `:napplet` provider and shipped over IPC ([EmbeddedMagnifierProbe], option B). Both embed paths wired (browser + napplet); verified on device for the browser path. Capture Y is locked to the caret/selection line (X follows the finger). Possible further polish: RGB_565 to cut encode, themed crosshair, clamp capture X to the line so a fast drag past EOL doesn't show blank. |
+| 5 | **Word-granularity long-press** then char-extend | long-press | — | ✅ HYBRID word+char in-field handle-extend (2026-06-25, completed): `fieldExtend` keeps per-drag state (`fieldDragWordEnd`/`fieldDragWordStart`, reset on a >250ms gap or edge switch). The drag baselines at the current selection edge; sweeping PAST that word's far boundary snaps to the next whole word (`wordEndAt`/`wordStartAt`), while moving within/back from the furthest-reached word gives CHARACTER precision — so you can fine-tune to a single character (the previously-missing "then char" mode). Page-text extend stays char (no offset model). |
+| 6 | **Double-tap = word, long-press = word, (triple-tap/drag = paragraph)** | tap count | — | ✅ double-tap + long-press both select a word (2026-06-25). Chrome word-selects on the 2nd tap, then abandons it by collapsing to the end (off-window quirk); the host re-assert restores it. The shim `click` handler DEFERS its tap-to-collapse ~300ms and the real `dblclick` cancels that timer, so the word selection survives (a timing-only guard was flaky ~40%). Triple-tap/paragraph not done. |
+| 7 | **Smart selection / entity expansion** (`TextClassifier`: phone, URL, address, date → entity actions in toolbar) | selection lands on an entity | — | ❌ not built (low priority) |
+| 8 | **Drag selected text** (long-press a selection → drag-and-drop to move) | long-press on existing selection | drop | ❌ not built (low priority) |
+| 9 | **Auto-scroll while dragging to a viewport edge** | handle dragged near top/bottom edge | finger leaves edge / up | ✅ works (2026-06-25, user-confirmed). The drag driver (`onMagnify`) detects the finger in the surface's top/bottom edge zone and sends `ime.autoscroll`; the shim scrolls the textarea (else the window) and re-reports geometry, flagged so the hide-on-scroll path doesn't fire. Scrolls per drag-move in the edge zone (not on a perfectly-held finger). **Fixed alongside:** the nav drawer's left-edge swipe was hijacking the edge drag — `EmbeddedSelectionDrag.dragging` (set by `onMagnify`) now suspends the drawer's `gesturesEnabled` while a handle is dragged. |
+| 10 | **Caret snapping to character boundaries** | always during caret/handle drag | — | ✅ via `offsetFromPoint` binary search + Y-clamp. **2026-06-26 fix:** the insertion-handle drag stopped moving the caret (loupe showed, caret frozen) — the unified `awaitEachGesture` consumed the pointer change BEFORE reading `positionChange()`, which returns `Offset.Zero` once consumed, so the accumulated finger position never advanced. Now reads `positionChangeIgnoreConsumed()` first. |
+| 11 | **Themed handle/caret drawables + blink** | always | — | ✅/⚠️ The host-drawn handles use `colorScheme.primary` — which IS the native `textSelectHandle`/accent color — so the handle drawables are themed (the actionable part). The caret bar + selection-highlight are drawn by Chrome inside the off-window surface: the caret already blinks natively, and theming its color/the highlight would mean injecting CSS into arbitrary third-party pages (intrusive; `::selection` was already ruled out as non-painting), so those are intentionally left to Chrome. |
+| 12 | **Insertion-handle Paste/Select-All mini-popup** | tap the insertion handle | tap elsewhere | ✅ built (2026-06-25). Tapping the bare insertion handle toggles a Paste/Select-All bar above the caret (`SelectionUiState.insertionPopup`, toggled from the handle's unified tap/drag gesture); tap-elsewhere/typing/blur/selection/scroll dismiss it. Fixed a latent bug: toolbar items now consume the *down* (not just the up) so the tap doesn't bleed through to the surface and blur the field. Device-verified (Select-all selects all text, field stays focused). |
+
+Legend: ✅ done · ⚠️ partial · ❌ missing.
+
+### Activation/deactivation is the hard part
+
+Most of the bugs we already fixed were activation-timing bugs (cursor-jumps-to-end,
+collapse-on-tap, focus-transfer races). The remaining features each carry their
+own state machine.
+
+**Done (2026-06-25): `SelectionUiState`** (`SelectionUiState.kt`) now centralizes
+what used to be scattered flags in `EmbeddedTabLayer` (`showInsertionHandle`,
+`showSelectionToolbar`, `fieldGeometry`, `rangeFieldGeometry`, `pageSelection`).
+It holds the three mutually-exclusive contexts (insertion caret / in-field range /
+page-text range) plus the transient modifiers `dragging` and `scrolling`, and
+exposes derived visibility (`insertionHandle`, `fieldHandles`, `fieldToolbar`,
+`pageHandles`, `pageToolbar`) so the rules are expressed once:
+- **toolbar hides while a handle is dragged** (`dragging`, set from the same
+  `OnMagnify` lifecycle that drives the loupe) — the dragged handle also hides its
+  own teardrop (the loupe stands in), like Android; the other handle stays.
+- **all overlays hide while scrolling** (`scrolling`, from the shim's `ime.scroll`);
+  the shim re-reports geometry just before `active=false` so they reappear
+  repositioned.
+Still emergent / TODO: insertion-handle auto-timeout, tap-to-re-show.
+
+**Selection-blink fix (2026-06-25).** A field selection — especially in a `<textarea>` —
+flickered: off-window Chrome abandons the selection by collapsing the caret to an
+endpoint every ~25 ms, and the FIELD re-assert round-tripped through the host EditText
+(`RemoteImeView.onPageState` → `ime.set` → page), leaving a visible collapsed frame each
+cycle. Fix: re-assert field selections **synchronously in the shim's `selectionchange`
+handler** (mirror of the page-text path that never blinked) — `lastFieldRange`/`lastFieldAt`
+tracked via `noteSel()`, and a collapse-to-endpoint within 1500 ms is reverted with `setSel`
+(guarded, not re-reported) so it reverts before paint. The host re-assert stays as a
+fallback. Device-verified: textarea selection is stable; input select still works.
+
+## Priority order for parity work
+
+1. **Magnifier (#4).** Biggest perceived gap. We already report caret/handle
+   geometry; the magnifier needs a *magnified pixel view of the surface* at the
+   drag point. Options:
+   - **A. Compose-side zoom of a surface snapshot. ❌ RULED OUT (spiked 2026-06-25).**
+     The surface is a `SurfaceControlViewHost` — we can't trivially `Bitmap`-grab a
+     remote surface from the main process. We spiked `PixelCopy.request(SurfaceView, …)`
+     against the live embedded surface (`SurfaceMagnifierProbe`, wired into
+     `EmbeddedTabLayer` behind `BuildConfig.DEBUG`, fired on field focus). The capture
+     target is the privacysandbox `ContentView extends SurfaceView` — the only real
+     child of `SandboxedSdkView` once the session opens. **Result on a clearly-painted
+     surface (1080×2088): every capture returns `ERROR_SOURCE_NO_DATA`** (center
+     region, repeated 3×). Cause: the WebView pixels live in a *child* `SurfaceControl`
+     reparented under the SurfaceView via `ContentView.setChildSurfacePackage(...)`; the
+     host SurfaceView's *own* buffer is never drawn into, so `PixelCopy` on the parent
+     reads an empty buffer. Host-side pixel capture of the sandboxed content is not
+     available. (A `PixelCopy.request(Window, …)` against the host window would also
+     miss it — the sandbox layer is a *separate* SurfaceControl z-ordered below the
+     window.)
+   - **B. Capture in `:napplet` and ship the loupe content. ✅ SPIKED & VIABLE
+     (2026-06-25).** Inside the keyless provider the WebView IS a real in-window view, so
+     `WebView.draw(Canvas)` into a software bitmap renders real DOM pixels. Spike added
+     `MSG_MAGNIFIER_REQUEST`/`MSG_MAGNIFIER_FRAME` to `NappletBrowserContract`:
+     `NappletBrowserService.onMagnifierRequest` draws a zoomed slice
+     (`canvas.scale(zoom); translate(-(cx-box/2), -(cy-box/2)); webView.draw(canvas)`),
+     PNG-encodes it, and ships the bytes back; `EmbeddedBrowserController` (now also an
+     `EmbeddedMagnifierProbe`) requests on focus and `EmbeddedTabLayer` logs the result.
+     **10-frame burst, 160px source × 1.5× zoom → 240×240 PNG, center `#FF111111`
+     (real opaque content):** provider draw 0.7–1.2 ms steady (≈5 ms cold), provider
+     total draw+PNG 3–4 ms steady (≈12 ms cold), client round-trip 4–8 ms steady
+     (occasional ~18 ms), payload 8–15 KB (far under the 1 MB Binder limit). Comfortably
+     within a frame budget if throttled to ~30 fps.
+
+     **✅ Real loupe shipped (2026-06-25).** `MagnifierUiState` + `Magnifier`
+     (`EmbeddedMagnifier.kt`); the caret/selection handles call an `OnMagnify` callback
+     on drag start/move/end; `EmbeddedTabLayer` tracks the drag point, throttles capture
+     requests to one in flight (100 ms timeout), decodes each `MagnifierFrame` to an
+     `ImageBitmap`, and floats the bubble above the finger (clamped, flips below near the
+     top). Capture mirrored onto BOTH embed paths (browser:
+     `NappletBrowserContract`/`NappletBrowserService`/`EmbeddedBrowserController`;
+     napplet: `NappletEmbedContract`/`NappletHostService`/`EmbeddedNappletController`).
+     Verified on device (browser): drag → bubble shows live magnified "ello world" with
+     the caret, centered on the line → follows finger → hides on release. The dead
+     Option-A probe (`SurfaceMagnifierProbe`) was removed. **Polish done (2026-06-25):**
+     capture Y is locked to the authoritative caret/selection line (the handles pass a
+     `lineHalfPx` so the box centers on the line, not the finger or the caret foot); X
+     still follows the finger. Remaining nice-to-haves: RGB_565/raw to cut PNG encode,
+     themed crosshair, clamp capture X to the line so a fast drag past EOL isn't blank,
+     reuse one off-screen bitmap.
+   - **Gesture-routing caveat (found during the spike).** The host-drawn handles'
+     drag is fragile: the sandbox `ContentView.onTouchEvent` always returns `true`, so
+     via Compose's `AndroidView` interop it consumes the drag-move pointer and cancels
+     the overlay handle's `detectDragGestures` (synthetic `adb` drags on the handle
+     never produced an `onDrag`). The magnifier trigger should ride the existing
+     caret/selection-move path (which already round-trips through the shim), not a fresh
+     Compose drag layered over the surface.
+2. **Toolbar state rules (#3 hide-during-drag/scroll) + insertion-handle popup
+   (#12).** Pure Compose/state work, no platform unknowns. Do alongside the
+   `SelectionUiState` refactor.
+3. **Handle inactivity timeout + tap-to-re-show (#1).** Small.
+4. **Double-tap-to-select (#6)** and **word-granularity drag (#5).**
+5. **Auto-scroll (#9), themed drawables/blink (#11).**
+6. Defer: smart selection (#7), drag-to-move (#8).
+
+## ✅ FIXED — full-screen round-trip corrupted the embedded WebViews (2026-06-26)
+
+**Symptom (was).** Open an embedded field's page in its own full-screen activity,
+then `back` to the embedded version. From then on **every** embedded surface in the
+`:napplet` process was broken — and it was far more than the selection highlight: DOM
+reads returned empty (a field that visibly showed text reported `value == ""`, so typing
+prepended at offset 0 and backspace did nothing), DNS died (`ERR_NAME_NOT_RESOLVED`), the
+selection highlight stopped painting, and IME broke. The page showed a stale last frame
+over a functionally-dead renderer.
+
+**Root cause — two process-global defects in the full-screen hosts** corrupting the
+shared multiprocess WebView state the embedded surfaces rely on. (Diagnosed with temporary
+logging: page console → logcat, all `onReceivedError`/`onReceivedHttpError`, and the shim's
+focused-field type/caret. The user's own insight — "the activity is gone but the service
+doesn't come back; am I using something from the activity?" — pointed straight at it.)
+
+1. **`pauseTimers()`/`resumeTimers()` are PROCESS-GLOBAL** (they pause JS, layout and
+   parsing timers for *every* WebView in the process). `NappletBrowserActivity` /
+   `NappletHostActivity` `onPause`/`onResume` and `NappletHostService`'s embed
+   pause/resume all called them on their own lifecycle — so returning from full-screen
+   *froze* the embedded surfaces, which had no resume of their own. **Fix:** removed ALL
+   process-global timer calls; rely only on per-WebView `onPause()`/`onResume()` (which
+   pause just that surface's JS/DOM — still meets the napplet background-security goal).
+2. **`WebView.destroy()` while still attached to the window** corrupts the shared
+   multiprocess renderer (`cr_AwContents: "WebView.destroy() called while WebView is still
+   attached to window"`). **Fix:** `stopLoading()` + `(parent as ViewGroup).removeView(...)`
+   before `destroy()` in both full-screen activities' `onDestroy`.
+
+Device-verified: the round-trip no longer corrupts the embeds. This supersedes the old
+"recreate the session on return" hypothesis and the ruled-out attempts (`::selection` CSS,
+surface resize, focus-cycle, `MSG_WAKE`) — none were the real cause.
+
+## ✅ Embed WebViews follow the app theme (2026-06-26, separate concern)
+
+Not text-selection, but the same off-window surfaces: embedded (and full-screen) WebViews
+rendered web content in the *device* theme, ignoring the app's DARK/LIGHT preference.
+**Root cause:** WebView's dark decision (`prefers-color-scheme` via algorithmic darkening)
+reads the context's **theme** (`?android:attr/isLightTheme`), NOT just `Configuration.uiMode`
+— and the off-window `SurfaceControlViewHost` surface context carries neither. The old
+`applyNightMode` used `UiModeManager.setNightMode` (permission-gated no-op). **Fix:** build
+every WebView from `nightThemedContext()` — `ContextThemeWrapper(createConfigurationContext(
+<night|day>), Theme.DeviceDefault.DayNight)` for the resolved theme — shared in
+`nappletHost/.../EmbedWebViewTheme.kt`, used by both embed services + both full-screen
+activities. The full debugging arc (config-only context fails; `setForceDark` gone at
+targetSdk 37; `setApplicationNightMode` does nothing; it's the unthemed context, not the
+process boundary) is in the `embed-webview-prefers-color-scheme-limitation` memo. Upstream
+WebView is still buggy here (a cross-process SCVH WebView ignores `uiMode`); the
+theme-wrapper is the app-side workaround.
+
+## How to test
+
+The on-device harness lives at **`tools/ime-test/`** (`index.html` + `README.md`).
+It's a single page with an `<input>`, a `<textarea>`, and an on-page log that
+timestamps focus/selection/input/composition events, **paint latency**,
+long-tasks, and main-thread blocks — the instrumentation that pinned the erase,
+caret-jump, and first-letter-freeze bugs, and exactly what we'll want when
+profiling the magnifier.
+
+Run it (full details in `tools/ime-test/README.md`):
+
+1. `cd tools/ime-test && python3 -m http.server 8765`
+2. Reach it: emulator → `http://10.0.2.2:8765`; USB device →
+   `adb reverse tcp:8765 tcp:8765` then `http://localhost:8765`.
+3. Open that URL in the **in-app browser** to load it as an *embedded* tab. (Opening
+   the same URL full-screen and pressing `back` used to reproduce the
+   highlight/corruption bug — now fixed; it's still the regression test for it.)
+
+Console log lines are tagged `[ImeDiag]` and surface in `adb logcat` (the
+`:napplet` process owns the WebView console). This is a dev tool — nothing under
+`tools/` ships, which is why those diagnostic strings are kept out of `src/`.
+
+## Key files
+
+- `commons/src/commonMain/composeResources/files/napplet/shim.js` — DOM bridge.
+  Geometry sources: `caretCoords` (287), `offsetFromPoint` (318), `fieldGeom`
+  (336), `reportState` (360), `pageGeom` (462), `sendPageSel` (470), `pageExtend`
+  (494). A magnifier built via option B would add a loupe-render here.
+- `amethyst/.../embed/EmbeddedTabLayer.kt` — the Compose overlay. `InsertionHandle`
+  (557), `SelectionHandle` (496), `EmbeddedSelectionToolbar` (616),
+  `PageSelectionOverlay` (460), the `showInsertionHandle`/`showSelectionToolbar`
+  state to be folded into a `SelectionUiState`. Magnifier popup (option A) lands
+  here.
+- `amethyst/.../embed/RemoteImeView.kt` — invisible host `EditText`; selection
+  re-assert + copy/cut/paste/select-all + edit callbacks.
+- `amethyst/.../embed/EmbeddedImeBridge.kt` — `SelectionGeometry` (caret + handle
+  feet + viewport), `ImeEvent.{Focus,State,PageSelection}`, `parseSelectionGeometry`.
+- `amethyst/.../{browser/EmbeddedBrowserController,favorites/EmbeddedNappletController}.kt`
+  — parse `ime.pagesel` + geometry off the Messenger channel.
+- Context: `amethyst/plans/2026-06-19-napplet-sandbox-host.md`,
+  `2026-06-24-napplet-embedded-tabs.md`.

amethyst/plans/archive/2026-06-25-web-app-naming.md

@@ -0,0 +1,66 @@
+# Web-app naming overhaul (favorites / browser / app surfaces)
+
+> **Status:** shipped — Renames applied — `WebAppScreen`, `NostrAppScreen`, `EmbeddedWebAppController`, `FavoriteAppsScreen` all present.
+> _Audited 2026-06-30._
+
+## Problem
+
+The in-app "app" surfaces had colliding, sometimes inaccurate names:
+
+- `software_apps` (NIP-89 native Android apps, an install-from-a-store flow) showed as
+  **"Apps"** — colliding with the in-app favorites, which showed as **"Favorite apps"**.
+- The **host screens** that render a single web client / nSite / nApplet were named
+  `FavoriteWebAppScreen` / `FavoriteNappletScreen`. But they open *any* url/coordinate,
+  favorited or not — "Favorite" described how they happened to be reached (a pinned
+  bottom-bar tab), not what they are. And `FavoriteNappletScreen` also renders **nSites**
+  (website-mode), so "Napplet" was narrower than reality.
+- Three vocabularies for two model cases: model `WebUrl`/`NostrApp`, route
+  `FavoriteWebApp`/`FavoriteNostrApp`, screen `FavoriteWebApp`/`FavoriteNapplet`.
+
+## Taxonomy (decided with maintainer)
+
+User-facing terms, now distinct:
+
+| Concept | User-facing | What it is |
+|---|---|---|
+| Native app store | **App Store** | NIP-89 native Android apps you install off-device |
+| Nostr web client | **Web app** | an `https://` client that runs in-app (WebView) |
+| nApplet | **nApplet** | NIP-5D sandboxed JS app |
+| nSite | **nSite** | NIP-5A static website |
+| Pinned set | **Favorite** | a cross-cutting attribute (the star), *not* a screen |
+
+Code axis (favorites / route / screen / embedded-controller layer): **`WebApp`** (url-based,
+no nostr identity) and **`NostrApp`** (coordinate-based nSite *or* nApplet). The cross-process
+sandbox infra (`napplet/`, `nappletHost/`, `NappletHostService`, `NappletEmbedContract`)
+keeps **"Napplet"** — that process genuinely is the napplet host (it serves nSites in
+website-mode too, but the host *is* the napplet runtime).
+
+"Favorite" is reserved for the **grid of pinned apps** (`FavoriteAppsScreen` /
+`Route.FavoriteApps`) and the star toggle — the only things that are actually about favorites.
+
+## Renames
+
+Routes: `FavoriteWebApp(url)` → `WebApp(url)`; `FavoriteNostrApp(coordinate)` → `NostrApp(coordinate)`.
+Screens: `FavoriteWebAppScreen` → `WebAppScreen`; `FavoriteNappletScreen` → `NostrAppScreen`.
+Controllers: `EmbeddedBrowserController` → `EmbeddedWebAppController`;
+`EmbeddedNappletController` → `EmbeddedNostrAppController`.
+Factory: `acquireBrowser`/`browserId` → `acquireWebApp`/`webAppId`;
+`acquireNapplet`/`nappletId` → `acquireNostrApp`/`nostrAppId`.
+Model: `FavoriteApp.WebUrl` → `FavoriteApp.WebApp`. Registry: `WebUrlNetworkRegistry` →
+`WebAppNetworkRegistry`.
+
+Strings: `software_apps` "Apps" → "App Store"; `favorite_apps_empty` reworded to name
+nApplet/nSite.
+
+## Stable (do NOT change — persistence / wire compat)
+
+- Favorite `id` prefixes `"url:"` / `"nostr:"` (persisted dedup + bottom-bar keys).
+- DataStore names `"favorite_apps"`, `"weburl_network"`; serialized type tags `"url"` / `"nostr"`.
+- `napplet/` + `nappletHost/` sandbox infra names and IPC contracts.
+
+## Follow-ups (not in this pass)
+
+- Move `NostrAppScreen` + `EmbeddedNostrAppController` out of the `ui/...favorites/`
+  package (they are no longer favorites-specific) into a host package alongside the web side.
+- Recent nApplets / nSites (parallel to the browser's recent web apps), surfaced on the
+  discovery screens.

amethyst/plans/archive/2026-06-26-nsite-napplet-favorite-icons.md

@@ -0,0 +1,80 @@
+# nSite / nApplet favorite icons
+
+> **Status:** shipped — `quartz/.../NappletIconPath.kt` and `amethyst/.../favorites/NappletFavoriteIcon.kt` are in tree.
+> _Audited 2026-06-30._
+
+**Date:** 2026-06-26
+**Status:** implemented (pending on-device verification of the blob image-load path)
+
+## Problem
+
+When a user favorites a plain web app and pins it to the bottom nav, the generic globe
+icon is replaced by the **site's favicon**. Favorited nSites (NIP-5A) and nApplets
+(NIP-5D) did not get the same treatment — they fell back to the generic grid glyph.
+
+## Why the webapp trick doesn't carry over
+
+The webapp favicon is **captured live** from the WebView that loads the page
+(`NappletBrowserActivity.onReceivedIcon` → IPC `MSG_RECORD_ICON` →
+`BrowserIconRegistry`, keyed by host). That works because, for a plain webapp, the site
+**is** the WebView's main frame.
+
+nSites/nApplets render differently: they always load inside a **cross-origin sandboxed
+iframe** under a trusted shell document (`commons/.../composeResources/files/napplet/shell.html`,
+`iframe.src = '__APP_ORIGIN__/'`). `WebChromeClient.onReceivedIcon` only reports the
+**main frame's** favicon — i.e. the shell (`<title>Napplet</title>`, no icon), never the
+applet's iframe. So the live-capture approach is structurally blind to the app's own
+favicon here, and mirroring it would silently show nothing.
+
+## Approach: derive the icon from the manifest's own bundled blobs
+
+An nSite/nApplet ships its files as `path → sha256` (`path` tags). Its icon is almost
+always one of those blobs (a conventional `/favicon.png`, `/icon.png`,
+`/apple-touch-icon.png`, …). We already download + sha256-verify every manifest blob into
+a shared, content-addressed cache (`NappletBlobCache` / `NappletBlobPrefetcher`,
+Tor-routed). So the icon can be resolved from the manifest itself — no WebView, no iframe
+problem, content-addressed and verifiable, on the same private network path as everything
+else.
+
+### Resolution priority (per favorite)
+
+1. **Captured/bundled blob** (`iconModel`) — the conventional icon path picked from the
+   manifest's blobs, loaded from the verified cache as a `file://` model.
+2. **Manifest `icon` tag** (`FavoriteApp.iconUrl`) — the publisher-declared icon URL
+   (already wired before this change).
+3. **Type glyph** — grid (nostr app) / globe (web), already the fallback in
+   `FavoriteAppIcon`.
+
+Blob beats the `icon` URL deliberately: the blob is verified and rides the site's
+Tor-routed path, whereas a remote `icon` URL would be a clearnet fetch by Coil. Both still
+beat the glyph.
+
+## Changes
+
+- **quartz** `nip5aStaticWebsites/NappletIconPath.kt` (new) — pure, unit-tested heuristic
+  that picks the best icon `PathTag` from a manifest's `path` tags (priority list of
+  conventional names + a loose raster fallback; prefers shallower paths; raster formats
+  over `.ico`/`.svg`). Tests in `NappletIconPathTest.kt`.
+- **quartz** — `NappletManifest.iconBlob()` (covers nApplet kinds) and
+  `RootSiteEvent.iconBlob()` / `NamedSiteEvent.iconBlob()` (nSite kinds) delegate to it.
+- **amethyst** `favorites/NappletFavoriteIcon.kt` (new) — `rememberNappletIconModel(coordinate)`:
+  re-resolves the live event from `LocalCache`, picks its icon blob, ensures it's in the
+  shared cache (prefetching on demand, off the composition thread), and returns a `file://`
+  Coil model. Returns null until the blob is on disk (icon appears on next recomposition).
+- **amethyst** — `AppBottomBar` and `FavoriteAppsScreen` now resolve that model for
+  `FavoriteApp.NostrApp` and pass it as `iconModel`, exactly as they already did with the
+  captured favicon for `FavoriteApp.WebApp`.
+
+`FavoriteApp` is unchanged (no persistence migration): the icon is resolved from the live
+manifest at render time, consistent with the existing rule that a `NostrApp` favorite is
+only usable while its event is resolvable in `LocalCache`.
+
+## Follow-ups / not done
+
+- **On-device verification** of the blob → Coil image load (the heuristic + wiring are
+  verified by unit tests + compilation; the actual image render needs a device).
+- **HTML `<link rel="icon">` parsing.** The heuristic matches by conventional file name.
+  A future pass could fetch + parse the index blob to honor a non-conventional icon path.
+- **`.svg` / `.ico` decoding.** Listed as low-priority candidates; if Coil can't decode
+  them the `FavoriteAppIcon` error fallback shows the glyph, so it's harmless but not
+  guaranteed to render.

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/CashuBTest.kt

@@ -21,8 +21,8 @@
 package com.vitorpamplona.amethyst
 
 import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.vitorpamplona.amethyst.commons.ui.components.GenericLoadable
 import com.vitorpamplona.amethyst.service.cashu.CashuParser
-import com.vitorpamplona.amethyst.ui.components.GenericLoadable
 import com.vitorpamplona.quartz.nip60Cashu.token.CashuToken
 import kotlinx.collections.immutable.ImmutableList
 import kotlinx.coroutines.runBlocking

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/ImageUploadTesting.kt

@@ -22,6 +22,7 @@ package com.vitorpamplona.amethyst
 
 import android.graphics.Bitmap
 import android.graphics.Color
+import androidx.core.graphics.createBitmap
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.platform.app.InstrumentationRegistry
 import com.vitorpamplona.amethyst.model.AccountSettings
@@ -81,7 +82,7 @@ class ImageUploadTesting {
             .build()
 
     private fun getBitmap(): ByteArray {
-        val bitmap = Bitmap.createBitmap(200, 300, Bitmap.Config.ARGB_8888)
+        val bitmap = createBitmap(200, 300)
         for (x in 0 until bitmap.width) {
             for (y in 0 until bitmap.height) {
                 bitmap.setPixel(x, y, Color.rgb(Random.nextInt(), Random.nextInt(), Random.nextInt()))

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/NotificationFeedFilterModeOverrideTest.kt

@@ -67,13 +67,16 @@ class NotificationFeedFilterModeOverrideTest {
 
         private val client =
             NostrClient(
-                OkHttpWebSocket.Builder {
-                    OkHttpClient
-                        .Builder()
-                        .followRedirects(true)
-                        .followSslRedirects(true)
-                        .build()
-                },
+                OkHttpWebSocket.Builder(
+                    httpClient = {
+                        OkHttpClient
+                            .Builder()
+                            .followRedirects(true)
+                            .followSslRedirects(true)
+                            .build()
+                    },
+                    canDial = { true },
+                ),
                 scope,
             )
 

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/ThreadDualAxisChartAssemblerTest.kt

@@ -58,13 +58,16 @@ class ThreadDualAxisChartAssemblerTest {
 
         val client =
             NostrClient(
-                OkHttpWebSocket.Builder {
-                    OkHttpClient
-                        .Builder()
-                        .followRedirects(true)
-                        .followSslRedirects(true)
-                        .build()
-                },
+                OkHttpWebSocket.Builder(
+                    httpClient = {
+                        OkHttpClient
+                            .Builder()
+                            .followRedirects(true)
+                            .followSslRedirects(true)
+                            .build()
+                    },
+                    canDial = { true },
+                ),
                 scope,
             )
 

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/service/images/ThumbnailDiskCacheInstrumentedTest.kt

@@ -21,6 +21,7 @@
 package com.vitorpamplona.amethyst.service.images
 
 import android.graphics.Bitmap
+import androidx.core.graphics.createBitmap
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.platform.app.InstrumentationRegistry
 import org.junit.After
@@ -44,7 +45,7 @@ class ThumbnailDiskCacheInstrumentedTest {
         cacheDir = File(appContext.cacheDir, "thumbnail-test-${UUID.randomUUID()}")
         cache = ThumbnailDiskCache(cacheDir)
         sourceFile = File(appContext.cacheDir, "source-${UUID.randomUUID()}.jpg")
-        val bitmap = Bitmap.createBitmap(64, 64, Bitmap.Config.ARGB_8888)
+        val bitmap = createBitmap(64, 64)
         sourceFile.outputStream().use { bitmap.compress(Bitmap.CompressFormat.JPEG, 90, it) }
         bitmap.recycle()
     }

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/relays/eventsync/EventSyncTest.kt

@@ -97,7 +97,7 @@ class EventSyncTest {
                             RelayAuthenticator(
                                 newClient,
                                 appScope,
-                                signWithAllLoggedInUsers = { authTemplate ->
+                                signWithAllLoggedInUsers = { _, authTemplate, _ ->
                                     listOf(signer.sign(authTemplate))
                                 },
                             )

amethyst/src/main/AndroidManifest.xml

@@ -54,6 +54,7 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
     <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
 
     <!-- Phone calls -->
@@ -105,7 +106,6 @@
         android:supportsRtl="true"
         android:theme="@style/Theme.Amethyst"
         android:largeHeap="true"
-        android:usesCleartextTraffic="true"
         android:networkSecurityConfig="@xml/network_security_config"
         android:hardwareAccelerated="true"
         android:localeConfig="@xml/locales_config"
@@ -152,6 +152,14 @@
                 <data android:scheme="amethyst+walletconnect" />
             </intent-filter>
 
+            <!-- NIP-46: an app's `nostrconnect://` offer opens the signer screen, which pairs it. -->
+            <intent-filter android:label="Amethyst">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="nostrconnect" />
+            </intent-filter>
+
             <intent-filter android:label="New Post">
                 <action android:name="android.intent.action.SEND" />
                 <category android:name="android.intent.category.DEFAULT" />
@@ -194,6 +202,16 @@
                 <data android:host="iris.to" />
             </intent-filter>
 
+            <!-- Concord community invite links: https://amethyst.social/invite/<naddr>#<fragment> -->
+            <intent-filter android:label="Amethyst">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" />
+                <data android:host="amethyst.social" />
+                <data android:pathPrefix="/invite/" />
+            </intent-filter>
+
             <intent-filter android:label="zap.stream">
                 <action android:name="android.intent.action.VIEW" />
                 <category android:name="android.intent.category.DEFAULT" />
@@ -347,6 +365,24 @@
             android:stopWithTask="true"
             android:exported="false" />
 
+        <!-- Keeps the NIP-13 mining queue schedulable after the user leaves the
+             app: shortService gives a ~3 min guaranteed window with no special
+             permission. Jobs are persisted, so a timeout only defers them. -->
+        <service
+            android:name=".service.pow.PowMiningForegroundService"
+            android:foregroundServiceType="shortService"
+            android:stopWithTask="false"
+            android:exported="false" />
+
+        <!-- Keeps the "sync all blobs to all servers" (BUD-04) sweep alive while backgrounded.
+             dataSync is the correct type for an upload/download/sync; it must be started from the
+             foreground, which "Sync all" (user-initiated in the manager) satisfies. -->
+        <service
+            android:name=".service.uploads.blossom.BlossomSyncForegroundService"
+            android:foregroundServiceType="dataSync"
+            android:stopWithTask="false"
+            android:exported="false" />
+
         <provider
             android:name="androidx.core.content.FileProvider"
             android:authorities="${applicationId}.provider"
@@ -366,6 +402,17 @@
                 android:value="Persistent real-time messaging relay connection for Nostr protocol. Maintains WebSocket connections to user-configured inbox relays for immediate notification delivery of direct messages, zaps, and mentions." />
         </service>
 
+        <service
+            android:name=".service.notifications.NotificationServiceTileService"
+            android:icon="@drawable/amethyst_service"
+            android:label="@string/always_on_notif_tile_label"
+            android:permission="android.permission.BIND_QUICK_SETTINGS_TILE"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.service.quicksettings.action.QS_TILE" />
+            </intent-filter>
+        </service>
+
         <receiver
             android:name=".service.notifications.BootCompletedReceiver"
             android:exported="false">
@@ -402,6 +449,71 @@
             android:name=".service.call.CallNotificationReceiver"
             android:exported="false" />
 
+        <!-- Sandboxed napplet/nsite host. Runs in an isolated process that holds no keys. -->
+        <activity
+            android:name="com.vitorpamplona.amethyst.napplethost.NappletHostActivity"
+            android:process=":napplet"
+            android:exported="false"
+            android:autoRemoveFromRecents="true"
+            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboardHidden|keyboard|uiMode|navigation|fontScale|density"
+            android:launchMode="singleTask"
+            android:theme="@style/Theme.Amethyst" />
+
+        <!-- Direct-WebView browser for a single web client. Runs in the isolated, keyless `:napplet`
+             process and hosts the WebView directly (not a streamed surface), so scroll/zoom/keyboard work
+             natively. adjustResize shrinks the window for the soft keyboard. Its own task/recents entry. -->
+        <activity
+            android:name="com.vitorpamplona.amethyst.napplethost.NappletBrowserActivity"
+            android:process=":napplet"
+            android:exported="false"
+            android:autoRemoveFromRecents="true"
+            android:documentLaunchMode="intoExisting"
+            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboardHidden|keyboard|uiMode|navigation|fontScale|density"
+            android:windowSoftInputMode="adjustResize"
+            android:theme="@style/Theme.Amethyst" />
+
+        <!-- Capability-consent dialog. Runs in the main process (the only side trusted to grant). -->
+        <activity
+            android:name=".napplet.NappletConsentActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:launchMode="singleTop"
+            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+        <!-- First-connect "Connect to Nostr" dialog. -->
+        <activity
+            android:name=".connectedApps.consent.SignerConnectActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:launchMode="singleTop"
+            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+        <!-- Per-operation signer consent dialog. -->
+        <activity
+            android:name=".connectedApps.consent.SignerConsentActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:launchMode="singleTop"
+            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+
+        <!-- Main-process broker: holds the signer and brokers capabilities for the sandbox. -->
+        <service
+            android:name=".napplet.NappletBrokerService"
+            android:exported="false" />
+
+        <!-- Embedded-browser provider: hosts the in-app browser WebView in the isolated, keyless
+             process and ships its rendered surface to the main app (SurfaceControlViewHost). -->
+        <service
+            android:name="com.vitorpamplona.amethyst.napplethost.NappletBrowserService"
+            android:process=":napplet"
+            android:exported="false" />
+
+        <!-- Embedded nsite/napplet provider: hosts the verified-blob WebView in the isolated, keyless
+             process and ships its surface to the main app, so a favorited nsite/napplet can render as
+             an in-app tab instead of taking over the screen. Same trust model as NappletHostActivity. -->
+        <service
+            android:name="com.vitorpamplona.amethyst.napplethost.NappletHostService"
+            android:process=":napplet"
+            android:exported="false" />
+
     </application>
 
 

amethyst/src/main/java/com/vitorpamplona/amethyst/Amethyst.kt

@@ -21,11 +21,39 @@
 package com.vitorpamplona.amethyst
 
 import android.app.Application
+import android.content.ComponentCallbacks2
+import android.os.Build
+import com.vitorpamplona.amethyst.favorites.BrowserHistoryRegistry
+import com.vitorpamplona.amethyst.favorites.BrowserIconRegistry
+import com.vitorpamplona.amethyst.favorites.FavoriteAppsRegistry
+import com.vitorpamplona.amethyst.napplet.WebAppNetworkRegistry
 import com.vitorpamplona.amethyst.service.logging.Logging
 import com.vitorpamplona.amethyst.service.nests.AppForegroundRecycleHook
+import com.vitorpamplona.amethyst.ui.screen.loggedIn.embed.EmbeddedTabHost
 import com.vitorpamplona.quartz.utils.Log
 import com.vitorpamplona.quartz.utils.LogLevel
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import java.io.File
 
+/**
+ * The Android [Application]. **Heads-up: this app runs in TWO OS processes**, and Android
+ * instantiates this same class in each of them:
+ *
+ * - **main** — the normal app (UI, account, signer, `LocalCache`, relay client). [instance]
+ *   ([AppModules]) is built here in [onCreate].
+ * - **`:napplet`** — the sandboxed WebView host for NIP-5D napplets / NIP-5A nSites
+ *   (`NappletHostActivity`, declared `android:process=":napplet"`). It holds **no** account or keys.
+ *   [onCreate] early-returns here, so [instance] is **left unset** and any access throws.
+ *
+ * There is no per-process Application in Android — `android:name` is one class for the whole package —
+ * so the process-name guard ([isNappletSandbox]) is how the two are kept apart.
+ *
+ * **Processes don't share memory:** every `object`/companion/`static` (e.g. `LocalCache`,
+ * `NappletLaunchRegistry`) is a *separate copy per process*. Don't assume [instance] exists off the
+ * main process, and don't try to share state via a singleton across the boundary — use Messenger IPC.
+ */
 class Amethyst : Application() {
     init {
         Log.minLevel = if (BuildConfig.DEBUG) LogLevel.DEBUG else LogLevel.ERROR
@@ -37,11 +65,47 @@ class Amethyst : Application() {
             private set
     }
 
+    /**
+     * Android instantiates this single Application class in EVERY process (there's no per-process
+     * Application in the manifest). The sandboxed napplet host runs in `:napplet`, where we must not
+     * build [AppModules] — so this is computed once and gates every lifecycle callback that would
+     * otherwise touch the unset [instance].
+     */
+    private val isNappletSandbox by lazy { isNappletSandboxProcess() }
+
     override fun onCreate() {
         super.onCreate()
         Log.d("AmethystApp") { "onCreate $this" }
+
+        // Application.onCreate runs in every process. The sandboxed napplet host
+        // (`:napplet`) must NOT build AppModules — that would load the account and
+        // construct the signer in the very process we keep secret-free. The host
+        // is self-contained (WebView + IPC), so we skip all app init there and
+        // leave `instance` unset; any accidental use fails fast.
+        if (isNappletSandbox) {
+            Log.d("AmethystApp") { "Skipping AppModules init in sandbox process" }
+            return
+        }
+
         instance = AppModules(this)
 
+        // Hydrate the device-local favorite-apps list (main process only; the sandbox never reads it).
+        FavoriteAppsRegistry.init(this)
+
+        // Hydrate the device-local browser visit history (main process only; feeds the omnibox suggestions).
+        BrowserHistoryRegistry.init(this)
+
+        // Index device-local captured favicons (main process only; decorates favorites + suggestions).
+        BrowserIconRegistry.init(this)
+
+        // Warm the global-settings prefs off-main so the first (deliberately synchronous) read of
+        // them does not hit disk on the main thread. See LocalPreferences.warmGlobalSettings.
+        CoroutineScope(Dispatchers.IO).launch { LocalPreferences.warmGlobalSettings() }
+
+        // Hydrate the per-web-client Tor routing preferences so a site opted out of Tor (some reject Tor
+        // exits) starts on the open web without first flashing a failed Tor load.
+        WebAppNetworkRegistry.init(this)
+
         // After-background foreground recycle: when the app returns to
         // the foreground after spending more than ~5 s in the
         // background, publish a network-change event so every active
@@ -53,6 +117,10 @@ class Amethyst : Application() {
         // kdoc for the threshold rationale.
         registerActivityLifecycleCallbacks(AppForegroundRecycleHook())
 
+        // Foreground signal for the resource-usage ledger (fg/bg attribution
+        // of bytes and connection-time). Main process only.
+        registerActivityLifecycleCallbacks(instance.foregroundTracker)
+
         if (isDebug) {
             Logging.setup()
             // Auto-enable the Nests session-trace recorder in debug
@@ -66,9 +134,22 @@ class Amethyst : Application() {
         instance.initiate(this)
     }
 
+    /** True when this process is the isolated `:napplet` WebView host (see AndroidManifest). */
+    private fun isNappletSandboxProcess(): Boolean {
+        val name =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                getProcessName()
+            } else {
+                runCatching { File("/proc/self/cmdline").readText().substringBefore('\u0000').trim() }.getOrNull()
+            }
+        return name?.endsWith(":napplet") == true
+    }
+
     override fun onTerminate() {
         super.onTerminate()
         Log.d("AmethystApp") { "onTerminate $this" }
+        // The sandbox process never built AppModules; `instance` is unset there.
+        if (isNappletSandbox) return
         instance.terminate(this)
     }
 
@@ -80,6 +161,18 @@ class Amethyst : Application() {
     override fun onTrimMemory(level: Int) {
         super.onTrimMemory(level)
         Log.d("AmethystApp") { "onTrimMemory $level" }
-        instance.trim()
+        // onTrimMemory IS delivered to the `:napplet` process on real devices, where `instance`
+        // was never initialized — guard so a trim callback can't crash the sandbox.
+        if (isNappletSandbox) return
+        instance.trim(level)
+        // Drop warm embedded tab sessions under genuine memory pressure (decision: keep warm until the
+        // user or Android reclaims them). Since API 34 the OS only delivers UI_HIDDEN and BACKGROUND:
+        // BACKGROUND means the process is on the system LRU list (real reclaim pressure), while UI_HIDDEN
+        // fires on every app switch — so evict only at BACKGROUND and above, letting a pinned tab survive
+        // a plain backgrounding. R+ only.
+        val pressure = level >= ComponentCallbacks2.TRIM_MEMORY_BACKGROUND
+        if (pressure && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            EmbeddedTabHost.evictAll()
+        }
     }
 }

amethyst/src/main/java/com/vitorpamplona/amethyst/AppModules.kt

@@ -20,14 +20,24 @@
  */
 package com.vitorpamplona.amethyst
 
+import android.content.ComponentCallbacks2
 import android.content.Context
+import android.os.BatteryManager
 import androidx.security.crypto.EncryptedSharedPreferences
 import coil3.disk.DiskCache
 import coil3.memory.MemoryCache
 import com.vitorpamplona.amethyst.commons.model.NoteState
+import com.vitorpamplona.amethyst.commons.napplet.permissions.NappletPermissionLedger
+import com.vitorpamplona.amethyst.commons.relayClient.BlockedRelayFilteringClient
+import com.vitorpamplona.amethyst.commons.richtext.CachedRichTextParser
 import com.vitorpamplona.amethyst.commons.robohash.CachedRobohash
+import com.vitorpamplona.amethyst.commons.scheduledposts.ScheduledPostStore
 import com.vitorpamplona.amethyst.commons.service.lnurl.OkHttpLnurlEndpointResolver
+import com.vitorpamplona.amethyst.commons.service.pow.PoWPolicy
+import com.vitorpamplona.amethyst.commons.service.pow.PoWPublishQueue
 import com.vitorpamplona.amethyst.commons.tor.TorSettings
+import com.vitorpamplona.amethyst.connectedApps.DataStoreNostrSignerPermissionStore
+import com.vitorpamplona.amethyst.connectedApps.nip46.DataStoreNip46ClientStore
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.UiSettings
@@ -43,6 +53,9 @@ import com.vitorpamplona.amethyst.model.preferences.UiSharedPreferences
 import com.vitorpamplona.amethyst.model.privacyOptions.RoleBasedHttpClientBuilder
 import com.vitorpamplona.amethyst.model.torState.AccountsTorStateConnector
 import com.vitorpamplona.amethyst.model.torState.TorRelayState
+import com.vitorpamplona.amethyst.napplet.DataStoreNappletPermissionStore
+import com.vitorpamplona.amethyst.service.calendar.CalendarReminderPrefs
+import com.vitorpamplona.amethyst.service.calendar.CalendarReminderWorker
 import com.vitorpamplona.amethyst.service.cast.CastRegistry
 import com.vitorpamplona.amethyst.service.connectivity.ConnectivityManager
 import com.vitorpamplona.amethyst.service.connectivity.ConnectivityStatus
@@ -60,24 +73,44 @@ import com.vitorpamplona.amethyst.service.okhttp.DualHttpClientManager
 import com.vitorpamplona.amethyst.service.okhttp.DualHttpClientManagerForRelays
 import com.vitorpamplona.amethyst.service.okhttp.EncryptionKeyCache
 import com.vitorpamplona.amethyst.service.okhttp.OkHttpWebSocket
-import com.vitorpamplona.amethyst.service.okhttp.SurgeDns
-import com.vitorpamplona.amethyst.service.okhttp.SurgeDnsStore
+import com.vitorpamplona.amethyst.service.okhttp.OnionLocationCache
 import com.vitorpamplona.amethyst.service.playback.diskCache.VideoCache
 import com.vitorpamplona.amethyst.service.playback.diskCache.VideoCacheFactory
 import com.vitorpamplona.amethyst.service.playback.pip.BackgroundMedia
 import com.vitorpamplona.amethyst.service.playback.service.PlaybackServiceClient
+import com.vitorpamplona.amethyst.service.pow.PowJobRestorer
+import com.vitorpamplona.amethyst.service.pow.PowJobStore
+import com.vitorpamplona.amethyst.service.pow.PowMiningForegroundService
 import com.vitorpamplona.amethyst.service.relayClient.CacheClientConnector
 import com.vitorpamplona.amethyst.service.relayClient.RelayProxyClientConnector
 import com.vitorpamplona.amethyst.service.relayClient.TorCircuitHealthTracker
 import com.vitorpamplona.amethyst.service.relayClient.authCommand.model.AuthCoordinator
+import com.vitorpamplona.amethyst.service.relayClient.diagnostics.BootRelayDiagnostics
 import com.vitorpamplona.amethyst.service.relayClient.notifyCommand.model.NotifyCoordinator
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.RelaySubscriptionsCoordinator
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.event.EventFinderQueryState
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.user.UserFinderQueryState
 import com.vitorpamplona.amethyst.service.relayClient.speedLogger.RelaySpeedLogger
+import com.vitorpamplona.amethyst.service.resourceusage.BatteryDrainSampler
+import com.vitorpamplona.amethyst.service.resourceusage.ForegroundTimeIntegrator
+import com.vitorpamplona.amethyst.service.resourceusage.ForegroundTracker
+import com.vitorpamplona.amethyst.service.resourceusage.HttpUsageMeter
+import com.vitorpamplona.amethyst.service.resourceusage.MeteringNostrSigner
+import com.vitorpamplona.amethyst.service.resourceusage.ProcessCpuSampler
+import com.vitorpamplona.amethyst.service.resourceusage.RadioBurstEstimator
+import com.vitorpamplona.amethyst.service.resourceusage.RelayConnectionTimeIntegrator
+import com.vitorpamplona.amethyst.service.resourceusage.RelayUsageListener
+import com.vitorpamplona.amethyst.service.resourceusage.ResourceUsageAccountant
+import com.vitorpamplona.amethyst.service.resourceusage.ResourceUsageStore
+import com.vitorpamplona.amethyst.service.resourceusage.ScreenTimeIntegrator
+import com.vitorpamplona.amethyst.service.resourceusage.SessionTimeIntegrator
+import com.vitorpamplona.amethyst.service.resourceusage.UsageCountingInterceptor
+import com.vitorpamplona.amethyst.service.resourceusage.UsageKeys
 import com.vitorpamplona.amethyst.service.safeCacheDir
-import com.vitorpamplona.amethyst.service.scheduledposts.ScheduledPostStore
+import com.vitorpamplona.amethyst.service.scheduledposts.ScheduledPostWorkGate
 import com.vitorpamplona.amethyst.service.scheduledposts.ScheduledPostWorker
+import com.vitorpamplona.amethyst.service.uploads.blossom.BlossomMirrorQueue
+import com.vitorpamplona.amethyst.service.uploads.blossom.BlossomSyncForegroundService
 import com.vitorpamplona.amethyst.service.uploads.blossom.bud10.BlossomServerResolver
 import com.vitorpamplona.amethyst.service.uploads.blossom.bud10.LocalBlossomCacheProbe
 import com.vitorpamplona.amethyst.service.uploads.nip95.Nip95CacheFactory
@@ -87,13 +120,20 @@ import com.vitorpamplona.amethyst.ui.screen.AccountState
 import com.vitorpamplona.amethyst.ui.screen.UiSettingsState
 import com.vitorpamplona.amethyst.ui.tor.TorManager
 import com.vitorpamplona.amethyst.ui.tor.TorService
+import com.vitorpamplona.amethyst.ui.tor.TorServiceStatus
 import com.vitorpamplona.quartz.nip01Core.core.Address
+import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.relay.client.INostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.RelayLogger
 import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.RelayOfflineTracker
+import com.vitorpamplona.quartz.nip01Core.relay.client.limits.RelayLimitsTracker
 import com.vitorpamplona.quartz.nip01Core.relay.client.reqs.stats.RelayReqStats
 import com.vitorpamplona.quartz.nip01Core.relay.client.stats.RelayStats
+import com.vitorpamplona.quartz.nip01Core.relay.commands.toClient.CachingEventDecoder
+import com.vitorpamplona.quartz.nip01Core.relay.filters.Filter
+import com.vitorpamplona.quartz.nip01Core.relay.sockets.okhttp.SurgeDns
+import com.vitorpamplona.quartz.nip01Core.relay.sockets.okhttp.SurgeDnsStore
 import com.vitorpamplona.quartz.nip03Timestamp.VerificationStateCache
 import com.vitorpamplona.quartz.nip03Timestamp.okhttp.OkHttpBitcoinExplorer
 import com.vitorpamplona.quartz.nip03Timestamp.ots.OtsBlockHeightCache
@@ -110,19 +150,29 @@ import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.NamecoinBackend
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.NamecoinCoreRpcClient
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.NamecoinNameResolver
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.TOR_ELECTRUMX_SERVERS
+import com.vitorpamplona.quartz.nip19Bech32.decodePublicKeyAsHexOrNull
+import com.vitorpamplona.quartz.nip52Calendar.appt.day.CalendarDateSlotEvent
+import com.vitorpamplona.quartz.nip52Calendar.appt.tags.RSVPStatusTag
+import com.vitorpamplona.quartz.nip52Calendar.appt.time.CalendarTimeSlotEvent
+import com.vitorpamplona.quartz.nip52Calendar.rsvp.CalendarRSVPEvent
 import com.vitorpamplona.quartz.nipB7Blossom.BlossomServersEvent
 import com.vitorpamplona.quartz.nipBCOnchainZaps.chain.CachingOnchainBackend
 import com.vitorpamplona.quartz.nipBCOnchainZaps.chain.EsploraBackend
 import com.vitorpamplona.quartz.utils.Log
+import com.vitorpamplona.quartz.utils.TimeUtils
 import kotlinx.coroutines.CoroutineExceptionHandler
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.async
 import kotlinx.coroutines.cancel
+import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.collectLatest
+import kotlinx.coroutines.flow.conflate
 import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.drop
 import kotlinx.coroutines.flow.filterNotNull
@@ -148,6 +198,9 @@ class AppModules(
 
     val applicationIOScope = CoroutineScope(Dispatchers.IO + SupervisorJob() + exceptionHandler)
 
+    private val _trimLevelEvents = MutableSharedFlow<Int>(extraBufferCapacity = 1, onBufferOverflow = BufferOverflow.DROP_OLDEST)
+    val trimLevelEvents = _trimLevelEvents.asSharedFlow()
+
     // Pre-load both preference DataStores in parallel on IO threads.
     // Both constructors use runBlocking internally, so starting them concurrently
     // reduces total blocking time from (torPrefs + uiPrefs) to ~max(torPrefs, uiPrefs).
@@ -190,7 +243,7 @@ class AppModules(
     // App services that should be run as soon as there are subscribers to their flows
     val locationManager by lazy {
         Log.d("AppModules", "LocationManager Init")
-        LocationState(appContext, applicationIOScope)
+        LocationState(appContext, applicationIOScope, onListening = { locationSession.setActive(it) })
     }
     val connManager = ConnectivityManager(appContext, applicationIOScope)
 
@@ -199,7 +252,8 @@ class AppModules(
         UiSettingsState(uiPrefs.value, connManager.isMobileOrFalse, applicationIOScope)
     }
 
-    val torManager = TorManager(torPrefs, TorService(appContext), applicationIOScope)
+    private val torService = TorService(appContext)
+    val torManager = TorManager(torPrefs, torService, applicationIOScope)
 
     // Network identity change (wifi↔cellular, regained from offline, captive portal
     // cleared) — the old network's guards/circuits are dead, and Arti's in-memory
@@ -232,6 +286,109 @@ class AppModules(
     // path on first lookup. Stored in cacheDir — pure perf data, OK if the OS evicts it.
     val dnsStore = SurgeDnsStore(File(appContext.safeCacheDir(), SurgeDnsStore.FILE_NAME), surgeDns)
 
+    // Network identity change (same trigger as Tor's onNetworkChange above), but for DNS
+    // the response is deliberately SOFT: most cached answers are still correct on the new
+    // network, so staleAll() keeps serving every one of them and merely re-verifies —
+    // positives revalidate in the background on next use, negatives (e.g. hosts that only
+    // failed because the OLD network / captive portal couldn't resolve them) get re-tried
+    // on first touch instead of waiting out their TTL. Nothing is dropped, nothing blocks.
+    init {
+        applicationIOScope.launch {
+            connManager.status
+                .map { (it as? ConnectivityStatus.Active)?.networkId }
+                .filterNotNull()
+                .distinctUntilChanged()
+                .drop(1)
+                .collect { surgeDns.staleAll() }
+        }
+    }
+
+    // Shared cache populated by OnionLocationInterceptor from any HTTP/WebSocket
+    // response carrying an Onion-Location header. Consulted by OnionUrlRewriteInterceptor
+    // on Tor-enabled clients to transparently redirect to .onion addresses.
+    val onionLocationCache = OnionLocationCache()
+
+    // ---- Resource-usage ledger (battery/data accounting) ----
+    // Passive on-device counters (bytes per subsystem x network x visibility,
+    // relay connection-time, wakelock time, worker runs). Never transmitted;
+    // the user can review them in Settings and explicitly DM a report to the
+    // developers. See amethyst/plans/2026-07-12-resource-usage-ledger.md.
+    val foregroundTracker = ForegroundTracker()
+
+    val resourceUsageStore = ResourceUsageStore(File(appContext.filesDir, ResourceUsageStore.FILE_NAME))
+
+    val resourceUsage = ResourceUsageAccountant(resourceUsageStore, applicationIOScope)
+
+    // Estimates radio wake-ups from HTTP burst patterns — bytes alone don't
+    // predict battery; scattered small requests each pay the radio ramp+tail.
+    private val radioBurstEstimator =
+        RadioBurstEstimator(
+            accountant = resourceUsage,
+            isMobile = { connManager.isMobileOrFalse.value },
+            isForeground = { foregroundTracker.isForeground.value },
+        )
+
+    // Single catch-all counter on the shared non-relay HTTP client: role
+    // wrappers only relabel via request tags, so no HTTP traffic (including
+    // direct getHttpClient users like the napplet broker) escapes the ledger.
+    private val httpUsageInterceptor =
+        UsageCountingInterceptor(
+            accountant = resourceUsage,
+            isMobile = { connManager.isMobileOrFalse.value },
+            isForeground = { foregroundTracker.isForeground.value },
+            bursts = radioBurstEstimator,
+        )
+
+    private val httpUsageMeter = HttpUsageMeter()
+
+    // Session-time counters for the app's long-running battery consumers.
+    // All timer-free segment integrators: services and status flows flip them
+    // on/off, so tracking costs one counter write per transition.
+    val alwaysOnSession = SessionTimeIntegrator(resourceUsage, UsageKeys.ALWAYS_ON_MS, UsageKeys.ALWAYS_ON_STARTS).also { it.registerFlushHook() }
+    val callSession = SessionTimeIntegrator(resourceUsage, UsageKeys.CALL_MS, UsageKeys.CALL_SESSIONS).also { it.registerFlushHook() }
+    val nestsSession = SessionTimeIntegrator(resourceUsage, UsageKeys.NESTS_MS, UsageKeys.NESTS_SESSIONS).also { it.registerFlushHook() }
+    private val powSession = SessionTimeIntegrator(resourceUsage, UsageKeys.POW_MS, UsageKeys.POW_SESSIONS).also { it.registerFlushHook() }
+    private val torSession = SessionTimeIntegrator(resourceUsage, UsageKeys.TOR_MS, UsageKeys.TOR_STARTS).also { it.registerFlushHook() }
+    private val locationSession = SessionTimeIntegrator(resourceUsage, UsageKeys.LOCATION_MS).also { it.registerFlushHook() }
+
+    // Time-per-screen (route base names only — arguments never reach the
+    // ledger). Fed by the navigation listener in AppNavigation; foreground
+    // gating means backgrounding on a screen closes its segment.
+    val screenTime = ScreenTimeIntegrator(resourceUsage)
+
+    init {
+        screenTime.start(applicationIOScope, foregroundTracker.isForeground)
+    }
+
+    // In-app (Arti) Tor uptime. Watches the raw TorService status — NOT
+    // TorManager.status, whose upstream is WhileSubscribed and calls
+    // service.start() when collected, so a permanent ledger subscription
+    // there would keep Tor's control flow alive on its own. External Tor
+    // (Orbot) is deliberately untracked: its battery belongs to Orbot.
+    init {
+        applicationIOScope.launch {
+            torService.status
+                .map { it is TorServiceStatus.Active }
+                .distinctUntilChanged()
+                .collect { torSession.setActive(it) }
+        }
+    }
+
+    // Measured battery drain (percent while discharging, fg/bg) — the ground
+    // truth the app counters get correlated against. One binder read per
+    // ledger flush, nothing while idle.
+    init {
+        val batteryManager = appContext.getSystemService(Context.BATTERY_SERVICE) as? BatteryManager
+        if (batteryManager != null) {
+            BatteryDrainSampler(
+                accountant = resourceUsage,
+                capacityPct = { batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY).takeIf { it in 1..100 } },
+                isCharging = { batteryManager.isCharging },
+                isForeground = { foregroundTracker.isForeground.value },
+            ).register()
+        }
+    }
+
     // manages all the other connections separately from relays.
     val okHttpClients: DualHttpClientManager =
         DualHttpClientManager(
@@ -250,10 +407,12 @@ class AppModules(
                 val profileOnly = settings?.localBlossomCacheProfilePicturesOnly?.value ?: false
                 master && !profileOnly && localBlossomCacheProbe.available.value
             },
+            onionCache = onionLocationCache,
+            usageInterceptor = httpUsageInterceptor,
         )
 
     // Offers easy methods to know when connections are happening through Tor or not
-    val roleBasedHttpClientBuilder = RoleBasedHttpClientBuilder(okHttpClients, torPrefs.value)
+    val roleBasedHttpClientBuilder = RoleBasedHttpClientBuilder(okHttpClients, torPrefs.value, httpUsageMeter)
 
     val electrumXClient by lazy {
         Log.d("AppModules", "ElectrumXClient Init")
@@ -424,6 +583,7 @@ class AppModules(
             isMobileDataProvider = connManager.isMobileOrNull,
             scope = applicationIOScope,
             dns = surgeDns,
+            onionCache = onionLocationCache,
         )
 
     // Connects the INostrClient class with okHttp
@@ -479,8 +639,26 @@ class AppModules(
             OkHttpLnurlEndpointResolver(roleBasedHttpClientBuilder::okHttpClientForMoney)
     }
 
-    // Provides a relay pool
-    val client: INostrClient = NostrClient(websocketBuilder, applicationIOScope)
+    // Provides a relay pool. The caching decoder skips re-parsing EVENT frames
+    // that arrive again via another subscription or relay (14-57% of frames in
+    // production measurements).
+    //
+    // Wrapped in BlockedRelayFilteringClient so the active account's NIP-51
+    // kind:10006 blocked relay list is enforced centrally on every REQ, COUNT
+    // and publish (relay targeting is otherwise distributed across dozens of
+    // feed/loader/finder/broadcast sites, most of which don't subtract it).
+    // The blocked set is read per-call from the logged-in account.
+    val client: INostrClient =
+        BlockedRelayFilteringClient(
+            NostrClient(websocketBuilder, applicationIOScope, CachingEventDecoder()),
+            blockedRelays = {
+                sessionManager
+                    .loggedInAccount()
+                    ?.blockedRelayList
+                    ?.flow
+                    ?.value ?: emptySet()
+            },
+        )
 
     // Self-heals the "Tor Active but every circuit dead" state the lifecycle watchdogs can't
     // see (they only arm while Connecting). Watches Tor-routed relay outcomes and, when enough
@@ -509,8 +687,44 @@ class AppModules(
     // Verifies and inserts in the cache from all relays, all subscriptions
     val cacheClientConnector = CacheClientConnector(client, cache)
 
-    // Show messages from the Relay and controls their dismissal
-    val notifyCoordinator = NotifyCoordinator(client)
+    // Show messages from the Relay and controls their dismissal. Attributes each NOTIFY to the
+    // account whose AUTH the relay rejected (accountsCache is declared below; the lambda reads it
+    // lazily at NOTIFY time, long after init).
+    val notifyCoordinator = NotifyCoordinator(client) { pubkey -> accountsCache.accounts.value[pubkey] }
+
+    // Per-relay NIP-42 ALLOW/DENY overrides are now per-account (Account.relayAuthPermissions,
+    // backed by a file under accounts/<pubkey>/), so there is no app-wide store here anymore.
+
+    /**
+     * The account every napplet/web-app grant and byte of storage is scoped to. Read lazily on each
+     * call (never captured) so an account switch immediately moves embedded apps to the new account's
+     * namespace: an app authorized by one npub is never authorized under another.
+     */
+    val nappletAccountScope: () -> String = { sessionManager.loggedInAccount()?.pubKey ?: "" }
+
+    // Singleton stores for napplet permissions — DataStore v1 enforces one instance per file.
+    val nappletPermissionStore by lazy { DataStoreNappletPermissionStore(appContext, nappletAccountScope) }
+
+    /**
+     * The one napplet permission ledger for the main process. Its persistent half is just the store
+     * above, but it also holds the in-memory ALLOW_SESSION grants — and *those* only work if every
+     * caller shares this instance. The broker service and the Connected Apps screens used to build
+     * a ledger each, so a "Forget"/revoke tapped in the UI cleared the screen's own (always empty)
+     * session map while the grants the broker was actually consulting lived on untouched.
+     *
+     * Session lifetime is bounded by [com.vitorpamplona.amethyst.napplet.NappletBrokerService]'s
+     * onDestroy (all applet/browser surfaces gone), which calls `endSession()`.
+     */
+    val nappletPermissionLedger by lazy { NappletPermissionLedger(nappletPermissionStore, nappletAccountScope) }
+
+    // NOT account-scoped here on purpose: this store is shared with NIP-46, whose coordinates already
+    // carry their owning account (`nip46:<signer>:<client>`) and whose sessions run for a specific
+    // account rather than the active one. The napplet path namespaces its own coordinate the same way
+    // (see NappletBroker.signerCoordinateFor) instead.
+    val signerPermissionStore by lazy { DataStoreNostrSignerPermissionStore(appContext) }
+
+    // Display + relay info for connected NIP-46 remote-signer clients.
+    val nip46ClientStore by lazy { DataStoreNip46ClientStore(appContext) }
 
     // Authenticates with relays.
     val authCoordinator = AuthCoordinator(client, applicationIOScope)
@@ -529,6 +743,36 @@ class AppModules(
     // Captures statistics about relays
     val relayStats = RelayStats(client)
 
+    // Caches the latest LIMITS (rights + limits) each relay advertises.
+    val relayLimits = RelayLimitsTracker(client)
+
+    // Resource-usage ledger: relay traffic/reconnect + connection-time,
+    // foreground-time, process-CPU, and signature-verification collectors.
+    init {
+        client.addConnectionListener(
+            RelayUsageListener(
+                accountant = resourceUsage,
+                isMobile = { connManager.isMobileOrFalse.value },
+                isForeground = { foregroundTracker.isForeground.value },
+            ),
+        )
+        RelayConnectionTimeIntegrator(
+            connectedCount = client.connectedRelaysFlow().map { it.size },
+            isMobile = connManager.isMobileOrNull,
+            isForeground = foregroundTracker.isForeground,
+            accountant = resourceUsage,
+        ).start(applicationIOScope)
+        ForegroundTimeIntegrator(
+            isForeground = foregroundTracker.isForeground,
+            accountant = resourceUsage,
+        ).start(applicationIOScope)
+        ProcessCpuSampler(resourceUsage).register()
+        cache.verifyMeter = { elapsedNanos, _ ->
+            resourceUsage.add(UsageKeys.VERIFY_COUNT, 1)
+            resourceUsage.add(UsageKeys.VERIFY_US, elapsedNanos / 1_000)
+        }
+    }
+
     // Logs debug messages when needed
     val detailedLogger = if (isDebug) RelayLogger(client, debugSending = false, debugReceiving = false) else null
     val relayReqStats = if (isDebug) RelayReqStats(client) else null
@@ -537,6 +781,10 @@ class AppModules(
     // Focused timeline for the DM / gift-wrap loading path (tag: DMPagination).
     // val dmDiagnostics = if (isDebug) DmRelayDiagnosticsLogger(client) else null
 
+    // Per-relay cold-start census: connection outcome by cause, REQ/EOSE/CLOSED accounting,
+    // and which relays actually carried the boot (tag: BootRelayDiag).
+    val bootDiagnostics = if (isDebug) BootRelayDiagnostics(client) else null
+
     // Coordinates all subscriptions for the Nostr Client
     val sources: RelaySubscriptionsCoordinator =
         RelaySubscriptionsCoordinator(
@@ -547,6 +795,50 @@ class AppModules(
             applicationIOScope,
         )
 
+    // fire-and-forget NIP-13 mining: posts queue here and publish when mined.
+    // One job mines at a time, racing half the cores over disjoint nonce
+    // slices — same total CPU budget as the old 2-job pool, but each post
+    // finishes ~minerThreads× sooner and the other half of the cores stays
+    // free for the UI. Template jobs checkpoint to disk (restored on login)
+    // and every enqueue raises the shortService shield so backgrounding
+    // doesn't freeze a miner.
+    val powJobStore by lazy {
+        PowJobStore(File(appContext.filesDir, PowJobStore.FILE_NAME), applicationIOScope)
+    }
+
+    val powPublishQueue by lazy {
+        PoWPublishQueue(
+            scope = applicationIOScope,
+            maxConcurrent = 1,
+            minerThreads = PoWPolicy.minerWorkers(Runtime.getRuntime().availableProcessors()),
+            persistence = powJobStore,
+            onQueueActive = { PowMiningForegroundService.start(appContext) },
+        ).also { queue ->
+            // Resource ledger: mining burns half the cores flat-out for as
+            // long as it runs — without this, PoW shows up in cpu.ms as an
+            // unattributed mystery. Wired inside the lazy so the ledger never
+            // forces the queue to initialize.
+            applicationIOScope.launch {
+                queue.jobs
+                    .map { jobs -> jobs.any { it.isMining } }
+                    .distinctUntilChanged()
+                    .collect { powSession.setActive(it) }
+            }
+        }
+    }
+
+    /** App-level BUD-04 mirror sweep, so "sync all" keeps running as the user navigates. */
+    val blossomMirrorQueue by lazy {
+        BlossomMirrorQueue(
+            scope = applicationIOScope,
+            onActive = { BlossomSyncForegroundService.start(appContext) },
+        )
+    }
+
+    val powJobRestorer by lazy {
+        PowJobRestorer(powPublishQueue, powJobStore, scheduledPostStore)
+    }
+
     // keeps all accounts live
     val accountsCache =
         AccountCacheState(
@@ -560,6 +852,10 @@ class AppModules(
             cache = cache,
             client = client,
             rootFilesDir = { appContext.filesDir },
+            powQueue = { powPublishQueue },
+            meterSigner = { MeteringNostrSigner(it, resourceUsage) },
+            signerPermissionStore = signerPermissionStore,
+            nip46ClientStore = nip46ClientStore,
         )
 
     val sessionManager =
@@ -638,7 +934,11 @@ class AppModules(
     // Observes LocalCache for notification-relevant events and routes them to
     // EventNotificationConsumer. Sources: FCM, UnifiedPush, Pokey, active relay
     // subscriptions, and NotificationRelayService.
-    val notificationDispatcher = NotificationDispatcher(appContext, applicationIOScope)
+    val notificationDispatcher =
+        NotificationDispatcher(appContext, applicationIOScope) { heldMs ->
+            resourceUsage.add(UsageKeys.WAKELOCK_NOTIF_MS, heldMs)
+            resourceUsage.add(UsageKeys.WAKELOCK_NOTIF_COUNT, 1)
+        }
 
     // Local store for posts the user has scheduled to publish later. Backed by a
     // single JSON file under the app's private filesDir; read by ScheduledPostWorker.
@@ -711,7 +1011,9 @@ class AppModules(
             diskCache = { diskCache },
             memoryCache = { memoryCache },
             blossomServerResolver = { blossomResolver },
-            callFactory = { okHttpClients.getHttpClient(roleBasedHttpClientBuilder.shouldUseTorForImageDownload(it)) },
+            // Through the role builder (not raw getHttpClient) so Coil's image
+            // traffic carries the "image" ledger tag. Same Tor decision inside.
+            callFactory = { roleBasedHttpClientBuilder.okHttpClientForImage(it) },
             thumbnailCache = thumbnailDiskCache,
             backgroundScope = applicationIOScope,
         )
@@ -722,6 +1024,10 @@ class AppModules(
     fun initiate(appContext: Context) {
         Thread.setDefaultUncaughtExceptionHandler(UnexpectedCrashSaver(crashReportCache, applicationIOScope))
 
+        // Ledger: count process starts — high counts reveal WorkManager/restart
+        // churn that cold-starts the whole app graph repeatedly.
+        resourceUsage.add(UsageKeys.APP_STARTS, 1)
+
         // Restore the persisted DNS cache before any networking starts. Lookups that fire
         // before this completes fall through to the sync resolver path (existing behavior);
         // once restored, every previously-seen host hits the stale-while-revalidate path
@@ -744,6 +1050,18 @@ class AppModules(
             sessionManager.loginWithDefaultAccountIfLoggedOff()
         }
 
+        // One-time hygiene: remove per-account directories (MLS/Marmot stores) left behind
+        // by accounts that are no longer saved — account deletion historically didn't clean
+        // them up, so they leaked disk across every add/remove.
+        applicationIOScope.launch {
+            val keep =
+                LocalPreferences
+                    .allSavedAccounts()
+                    .mapNotNull { decodePublicKeyAsHexOrNull(it.npub) }
+                    .toSet()
+            accountsCache.pruneOrphanAccountDirs(keep)
+        }
+
         // forces initialization of uiPrefs in the main thread to avoid blinking themes
         uiPrefs
 
@@ -765,35 +1083,96 @@ class AppModules(
             resourceCacheInit()
         }
 
+        // Initialize napplet permission stores on an IO thread to avoid StrictMode violations
+        // when ConnectedAppsScreen first accesses them on the main thread.
+        applicationIOScope.launch {
+            nappletPermissionStore
+            signerPermissionStore
+        }
+
         // registers to receive events
         pokeyReceiver.register(appContext)
 
         // starts observing LocalCache for notification-worthy events
         notificationDispatcher.start()
 
-        // Schedule the scheduled-posts worker (periodic + one-time catch-up).
-        // Runs independently of the always-on notification setting so scheduled
-        // posts still fire when always-on notifications are disabled.
-        ScheduledPostWorker.schedule(appContext)
-        ScheduledPostWorker.scheduleCatchUp(appContext)
+        // Keep the scheduled-posts worker (15-min periodic + one-time catch-up)
+        // enqueued exactly while the store holds a PENDING post — see
+        // ScheduledPostWorkGate. Runs independently of the always-on
+        // notification setting so scheduled posts still fire when always-on
+        // notifications are disabled.
+        ScheduledPostWorkGate(
+            store = scheduledPostStore,
+            scope = applicationIOScope,
+            onPendingWork = {
+                ScheduledPostWorker.schedule(appContext)
+                ScheduledPostWorker.scheduleCatchUp(appContext)
+            },
+            onNoPendingWork = { ScheduledPostWorker.cancelPeriodic(appContext) },
+        ).start()
 
-        // Periodic scan that posts "starting soon" notifications for NIP-52 appointments the
-        // user has RSVP'd to as ACCEPTED. 15-minute cadence matches both the WorkManager
-        // periodic minimum and the lead-time window.
-        com.vitorpamplona.amethyst.service.calendar.CalendarReminderWorker
-            .schedule(appContext)
+        // "Starting soon" reminders for NIP-52 appointments the user RSVP'd to as
+        // ACCEPTED. The 15-min periodic scanner is only scheduled while it can
+        // plausibly fire: this observer enqueues it when an accepted RSVP lands in
+        // LocalCache, and the worker cancels its own chain when the cache holds
+        // nothing that could still start. LocalCache is memory-only, so the
+        // unconditional schedule this replaces could never fire from a WorkManager
+        // cold start anyway — it only cost battery.
+        applicationIOScope.launch {
+            LocalCache
+                .observeNewEvents<CalendarRSVPEvent>(Filter(kinds = listOf(CalendarRSVPEvent.KIND)))
+                .collect { rsvp ->
+                    if (rsvp.status() == RSVPStatusTag.STATUS.ACCEPTED) {
+                        CalendarReminderWorker.schedule(appContext)
+                    }
+                }
+        }
 
-        // Watch for account login and start/stop always-on notification service
+        // A rescheduled appointment must also re-arm the chain: the worker
+        // cancels itself when every known target is in the past, and a
+        // kind-31922/31923 update (the organizer moving the event) arrives
+        // WITHOUT any new RSVP — the user's existing RSVP still points at the
+        // same address, and observeNewEvents never re-fires for it. conflate +
+        // delay bounds the cache rescan to one per 30s while event feeds
+        // stream slot events; the scan only runs for users with reminders on.
+        applicationIOScope.launch {
+            LocalCache
+                .observeNewEvents<Event>(
+                    Filter(kinds = listOf(CalendarDateSlotEvent.KIND, CalendarTimeSlotEvent.KIND)),
+                ).conflate()
+                .collect {
+                    if (CalendarReminderPrefs(appContext).isEnabled() &&
+                        CalendarReminderWorker.couldStillFire(CalendarReminderWorker.acceptedRsvpsInCache(), TimeUtils.now())
+                    ) {
+                        CalendarReminderWorker.schedule(appContext)
+                    }
+                    delay(30_000)
+                }
+        }
+
+        // Watch for account login and start/stop always-on notification service.
+        // The manager gates on the global master switch + each account's participation
+        // (not the active account), so it only needs to run while someone is logged in.
         applicationIOScope.launch {
             sessionManager.accountContent.collectLatest { state ->
                 if (state is AccountState.LoggedIn) {
-                    alwaysOnNotificationServiceManager.watchAccount(state.account)
+                    alwaysOnNotificationServiceManager.start()
                 } else {
                     alwaysOnNotificationServiceManager.stop()
                 }
             }
         }
 
+        // Resume PoW mining jobs that were checkpointed before a process death,
+        // for EVERY loaded account (the always-on service preloads non-active
+        // accounts, whose pending posts must not stay stranded on disk).
+        // Idempotent (the queue dedupes by job id), so re-emissions are safe.
+        applicationIOScope.launch {
+            accountsCache.accounts.collect { loaded ->
+                loaded.values.forEach { powJobRestorer.restore(it) }
+            }
+        }
+
         // Evict the BlossomServerResolver URL cache whenever either local-cache
         // toggle flips or the probe transitions up/down so stale entries don't
         // outlive the underlying decision.
@@ -852,12 +1231,48 @@ class AppModules(
         accountsCache.clear()
     }
 
-    fun trim() {
+    fun trim(level: Int) {
+        _trimLevelEvents.tryEmit(level)
+        // Backgrounding is a natural moment to flush the usage ledger too.
+        resourceUsage.flushAsync()
         applicationIOScope.launch {
             // Backgrounding is a natural moment to flush the DNS cache.
             dnsStore.save()
             val loggedIn = accountsCache.accounts.value.values
-            trimmingService.run(loggedIn, LocalPreferences.allSavedAccounts())
+            trimmingService.run(loggedIn, LocalPreferences.allSavedAccounts(), level)
+            // Trim in-process caches proportional to OS memory pressure.
+            //
+            // Since API 34 the OS only ever delivers two trim levels (the foreground
+            // RUNNING_* levels and the deeper MODERATE/COMPLETE background tiers were
+            // deprecated because apps are no longer notified of them):
+            //   BACKGROUND(40) — process is on the system LRU list: real reclaim
+            //                    pressure, and the strongest signal we still get.
+            //   UI_HIDDEN (20) — just backgrounded, no pressure yet. Fires on EVERY
+            //                    app switch.
+            //
+            // So we key off exactly those two. UI_HIDDEN is frequent, so it only trims
+            // images (bitmaps are the largest allocations) and keeps the CPU-heavy
+            // caches (Robohash SVG assembly, rich-text parsing) warm — clearing them
+            // would force a full rebuild on every resume and cause visible jank.
+            // BACKGROUND trims hard but keeps a small working set: it means "on the LRU
+            // list" (real reclaim pressure), not the imminent kill that COMPLETE used to
+            // signal — so leave just enough warm to redraw the screen the user left on.
+            when {
+                level >= ComponentCallbacks2.TRIM_MEMORY_BACKGROUND -> {
+                    // On the LRU list under real pressure: trim hard, but keep a small
+                    // working set so a returning user doesn't rebuild the visible screen
+                    // from scratch. memoryCache is byte-sized (Coil), the rest are entry counts.
+                    memoryCache.trimToSize(memoryCache.maxSize / 10)
+                    CachedRichTextParser.trimToSize(10)
+                    CachedRobohash.trimToSize(20)
+                    nip11Cache.trimToSize(10)
+                }
+                level >= ComponentCallbacks2.TRIM_MEMORY_UI_HIDDEN -> {
+                    // Just backgrounded, no pressure yet: trim images but keep the
+                    // parsed-text and avatar caches warm so resuming is instant.
+                    memoryCache.trimToSize(memoryCache.maxSize / 2)
+                }
+            }
         }
     }
 }

amethyst/src/main/java/com/vitorpamplona/amethyst/DebugUtils.kt

@@ -37,6 +37,58 @@ import kotlin.time.measureTimedValue
 @Suppress("SENSELESS_COMPARISON")
 val isDebug = BuildConfig.DEBUG || BuildConfig.BUILD_TYPE == "benchmark"
 
+data class MemorySnapshot(
+    val heapUsedMb: Long,
+    val heapMaxMb: Long,
+    val nativeHeapUsedMb: Long,
+    val imageCacheUsedMb: Long,
+    val imageCacheMaxMb: Long,
+    val imageDiskUsedMb: Long,
+    val imageDiskMaxMb: Long,
+    val noteCount: Int,
+    val userCount: Int,
+    val addressableCount: Int,
+    val chatroomCount: Int,
+    val memoryClassMb: Int,
+) {
+    val heapFraction: Float get() = heapUsedMb.toFloat() / heapMaxMb.coerceAtLeast(1L).toFloat()
+}
+
+fun collectMemorySnapshot(context: Context): MemorySnapshot {
+    val rt = Runtime.getRuntime()
+    val heapUsedMb = (rt.totalMemory() - rt.freeMemory()) / 1_048_576L
+    val heapMaxMb = rt.maxMemory() / 1_048_576L
+    val nativeHeapUsedMb = Debug.getNativeHeapAllocatedSize() / 1_048_576L
+
+    val app = Amethyst.instance
+    val imageCacheUsedMb = app.memoryCache.size / 1_048_576L
+    val imageCacheMaxMb = app.memoryCache.maxSize / 1_048_576L
+    val imageDiskUsedMb = app.diskCache.size / 1_048_576L
+    val imageDiskMaxMb = app.diskCache.maxSize / 1_048_576L
+
+    val activityManager: ActivityManager? = context.getSystemService()
+    val isLargeHeap = (context.applicationInfo.flags and ApplicationInfo.FLAG_LARGE_HEAP) != 0
+    val memoryClassMb =
+        activityManager?.let {
+            if (isLargeHeap) it.largeMemoryClass else it.memoryClass
+        } ?: 0
+
+    return MemorySnapshot(
+        heapUsedMb = heapUsedMb,
+        heapMaxMb = heapMaxMb,
+        nativeHeapUsedMb = nativeHeapUsedMb,
+        imageCacheUsedMb = imageCacheUsedMb,
+        imageCacheMaxMb = imageCacheMaxMb,
+        imageDiskUsedMb = imageDiskUsedMb,
+        imageDiskMaxMb = imageDiskMaxMb,
+        noteCount = LocalCache.notes.size(),
+        userCount = LocalCache.users.size(),
+        addressableCount = LocalCache.addressables.size(),
+        chatroomCount = LocalCache.chatroomList.size(),
+        memoryClassMb = memoryClassMb,
+    )
+}
+
 private const val STATE_DUMP_TAG = "STATE DUMP"
 
 fun debugState(context: Context) {

amethyst/src/main/java/com/vitorpamplona/amethyst/LocalPreferences.kt

@@ -25,17 +25,23 @@ import android.content.Context
 import android.content.SharedPreferences
 import androidx.compose.runtime.Immutable
 import androidx.core.content.edit
+import com.vitorpamplona.amethyst.commons.model.chats.ChatFeedType
 import com.vitorpamplona.amethyst.commons.model.clink.ClinkDebitWalletEntry
+import com.vitorpamplona.amethyst.commons.model.concord.ConcordViewMode
+import com.vitorpamplona.amethyst.commons.model.nip29RelayGroups.RelayGroupViewMode
 import com.vitorpamplona.amethyst.commons.model.nip47WalletConnect.NwcWalletEntry
 import com.vitorpamplona.amethyst.commons.model.nip47WalletConnect.NwcWalletEntryNorm
+import com.vitorpamplona.amethyst.commons.relayauth.RelayAuthPolicy
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.TopFilter
 import com.vitorpamplona.amethyst.model.UiSettings
 import com.vitorpamplona.amethyst.service.checkNotInMainThread
 import com.vitorpamplona.amethyst.ui.actions.mediaServers.DEFAULT_MEDIA_SERVERS
 import com.vitorpamplona.amethyst.ui.actions.mediaServers.ServerName
+import com.vitorpamplona.quartz.concord.cord02Community.ConcordCommunityListEvent
 import com.vitorpamplona.quartz.experimental.ephemChat.list.EphemeralChatListEvent
 import com.vitorpamplona.quartz.experimental.nipA3.PaymentTargetsEvent
+import com.vitorpamplona.quartz.marmot.mip00KeyPackages.KeyPackageRelayListEvent
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.core.JsonMapper
@@ -51,6 +57,7 @@ import com.vitorpamplona.quartz.nip28PublicChat.list.ChannelListEvent
 import com.vitorpamplona.quartz.nip37Drafts.privateOutbox.PrivateOutboxRelayListEvent
 import com.vitorpamplona.quartz.nip47WalletConnect.Nip47WalletConnect
 import com.vitorpamplona.quartz.nip50Search.SearchRelayListEvent
+import com.vitorpamplona.quartz.nip51Lists.favoriteAlgoFeedsList.FavoriteAlgoFeedsListEvent
 import com.vitorpamplona.quartz.nip51Lists.geohashList.GeohashListEvent
 import com.vitorpamplona.quartz.nip51Lists.hashtagList.HashtagListEvent
 import com.vitorpamplona.quartz.nip51Lists.muteList.MuteListEvent
@@ -58,6 +65,7 @@ import com.vitorpamplona.quartz.nip51Lists.relayLists.BlockedRelayListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.IndexerRelayListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.RelayFeedsListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.TrustedRelayListEvent
+import com.vitorpamplona.quartz.nip51Lists.simpleGroupList.SimpleGroupListEvent
 import com.vitorpamplona.quartz.nip65RelayList.AdvertisedRelayListEvent
 import com.vitorpamplona.quartz.nip72ModCommunities.follow.CommunityListEvent
 import com.vitorpamplona.quartz.nip78AppData.AppSpecificDataEvent
@@ -67,6 +75,7 @@ import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.async
 import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withContext
@@ -90,6 +99,11 @@ data class AccountInfo(
 
 private object PrefKeys {
     const val CURRENT_ACCOUNT = "currently_logged_in_account"
+
+    // Global (non-account) master switch for the always-on notification service.
+    // When off, the service is suppressed for every account regardless of each
+    // account's own participation flag. Persisted so it survives restarts/crashes.
+    const val NOTIFICATION_SERVICE_ENABLED = "notification_service_enabled"
     const val SAVED_ACCOUNTS = "all_saved_accounts"
     const val NOSTR_PRIVKEY = "nostr_privkey"
     const val NOSTR_PUBKEY = "nostr_pubkey"
@@ -98,14 +112,24 @@ private object PrefKeys {
     const val STRIP_LOCATION_ON_UPLOAD = "stripLocationOnUpload"
     const val USE_LOCAL_BLOSSOM_CACHE = "useLocalBlossomCache"
     const val LOCAL_BLOSSOM_CACHE_PROFILE_PICTURES_ONLY = "localBlossomCacheProfilePicturesOnly"
+    const val MIRROR_UPLOADS_TO_ALL_SERVERS = "mirrorUploadsToAllServers"
+    const val OPTIMIZE_MEDIA_ON_UPLOAD = "optimizeMediaOnUpload"
     const val HIDE_COMMUNITY_RULES_VIOLATIONS = "hideCommunityRulesViolations"
+    const val NIP46_SIGNER_ENABLED = "nip46SignerEnabled"
+    const val NIP46_BUNKER_SECRET = "nip46BunkerSecret"
+    const val NIP46_TRANSPORT_KEY = "nip46TransportKey"
+    const val NIP46_SEEN_IDS = "nip46SeenRequestIds"
     const val DEFAULT_HOME_FOLLOW_LIST = "defaultHomeFollowList"
     const val DEFAULT_STORIES_FOLLOW_LIST = "defaultStoriesFollowList"
     const val DEFAULT_NOTIFICATION_FOLLOW_LIST = "defaultNotificationFollowList"
     const val DEFAULT_DISCOVERY_FOLLOW_LIST = "defaultDiscoveryFollowList"
     const val DEFAULT_POLLS_FOLLOW_LIST = "defaultPollsFollowList"
     const val DEFAULT_PICTURES_FOLLOW_LIST = "defaultPicturesFollowList"
+    const val DEFAULT_RELAY_GROUPS_DISCOVERY_FOLLOW_LIST = "defaultRelayGroupsDiscoveryFollowList"
+    const val DEFAULT_NAPPLETS_FOLLOW_LIST = "defaultNappletsFollowList"
+    const val DEFAULT_NSITES_FOLLOW_LIST = "defaultNsitesFollowList"
     const val DEFAULT_WORKOUTS_FOLLOW_LIST = "defaultWorkoutsFollowList"
+    const val DEFAULT_GIT_REPOSITORIES_FOLLOW_LIST = "defaultGitRepositoriesFollowList"
     const val DEFAULT_CALENDARS_FOLLOW_LIST = "defaultCalendarsFollowList"
     const val DEFAULT_PRODUCTS_FOLLOW_LIST = "defaultProductsFollowList"
     const val DEFAULT_SHORTS_FOLLOW_LIST = "defaultShortsFollowList"
@@ -123,6 +147,7 @@ private object PrefKeys {
     const val DEFAULT_BROWSE_EMOJI_SETS_FOLLOW_LIST = "defaultBrowseEmojiSetsFollowList"
     const val DEFAULT_COMMUNITIES_FOLLOW_LIST = "defaultCommunitiesFollowList"
     const val DEFAULT_FOLLOW_PACKS_FOLLOW_LIST = "defaultFollowPacksFollowList"
+    const val DEFAULT_APP_RECOMMENDATIONS_FOLLOW_LIST = "defaultAppRecommendationsFollowList"
     const val ZAP_PAYMENT_REQUEST_SERVER = "zapPaymentServer" // legacy, kept for migration
     const val NWC_WALLETS = "nwcWallets"
     const val DEFAULT_NWC_WALLET_ID = "defaultNwcWalletId" // legacy, migrated into DEFAULT_PAYMENT_SOURCE_ID
@@ -145,13 +170,29 @@ private object PrefKeys {
     const val LATEST_HASHTAG_LIST = "latestHashtagList"
     const val LATEST_GEOHASH_LIST = "latestGeohashList"
     const val LATEST_EPHEMERAL_LIST = "latestEphemeralChatList"
+    const val LATEST_RELAY_GROUP_LIST = "latestRelayGroupList"
+    const val LATEST_CONCORD_LIST = "latestConcordList"
     const val LATEST_TRUST_PROVIDER_LIST = "latestTrustProviderList"
+    const val LATEST_KEY_PACKAGE_RELAY_LIST = "latestKeyPackageRelayList"
+    const val LATEST_FAVORITE_ALGO_FEEDS_LIST = "latestFavoriteAlgoFeedsList"
     const val CALLS_ENABLED = "calls_enabled"
     const val HIDE_DELETE_REQUEST_DIALOG = "hide_delete_request_dialog"
     const val HIDE_BLOCK_ALERT_DIALOG = "hide_block_alert_dialog"
     const val HIDE_NIP_17_WARNING_DIALOG = "hide_nip24_warning_dialog" // delete later
     const val ALWAYS_ON_NOTIFICATION_SERVICE = "always_on_notification_service"
+    const val DEFAULT_RELAY_AUTH_POLICY = "default_relay_auth_policy"
+    const val RELAY_GROUP_VIEW_MODE = "relay_group_view_mode"
+    const val CONCORD_VIEW_MODE = "concord_view_mode"
+
+    // Stores the DISABLED chat feed types (comma-joined codes) so absence = all-on and any newly
+    // added type defaults enabled for accounts that customized before it existed.
+    const val DISABLED_CHAT_FEEDS = "disabled_chat_feeds"
+    const val RELAY_AUTH_TRUST_MY_RELAYS = "relay_auth_trust_my_relays_and_venues"
+    const val RELAY_AUTH_TRUST_READ_FOLLOWS = "relay_auth_trust_read_follows"
+    const val RELAY_AUTH_TRUST_MESSAGE_FOLLOWS = "relay_auth_trust_message_follows"
+    const val RELAY_AUTH_TRUST_MESSAGE_STRANGERS = "relay_auth_trust_message_strangers"
     const val SPLIT_NOTIFICATIONS_ENABLED = "split_notifications_enabled"
+    const val SHOW_MESSAGES_IN_NOTIFICATIONS = "show_messages_in_notifications"
 
     // One-shot stamp: set once an account has gone through the notifications
     // Global -> Selected (Curated) migration (or was created after it shipped).
@@ -179,8 +220,57 @@ object LocalPreferences {
 
     private var currentAccount: String? = null
     private val savedAccounts: MutableStateFlow<List<AccountInfo>?> = MutableStateFlow(null)
+
+    // Guards the one-time lazy population of [savedAccounts]. Without it, concurrent callers
+    // of savedAccounts() (e.g. the account-load path, the always-on notification service, and
+    // the orphan-dir sweep, all launched at startup) would each see a null value, run the IO
+    // read in parallel, and the migration branch could double-write ALL_ACCOUNT_INFO.
+    private val savedAccountsMutex = Mutex()
     private val cachedAccounts: MutableMap<String, AccountSettings?> = mutableMapOf()
 
+    // Global master switch for the always-on notification service ("Background
+    // notification service"). Default ON: existing users keep current behavior, and
+    // per-account participation decides who actually stays active.
+    //
+    // Stored in PLAIN (non-encrypted) SharedPreferences on purpose. It is a non-sensitive
+    // global boolean, and — unlike encryptedPreferences(), which asserts non-main — plain
+    // prefs can be read synchronously on ANY thread. The restart-layer gate
+    // (NotificationRelayService.isEnabled) is synchronous and runs in fresh processes (boot
+    // receiver, WorkManager), so it MUST read the persisted value without a suspend hop;
+    // otherwise a saved OFF would be missed on cold boot and the service would resurrect.
+    // The flow is lazily seeded from disk once (synchronous, main-safe) and is thereafter
+    // the source of truth, so there is no async hydrate that could clobber a user toggle.
+    private fun globalSettingsPrefs(): SharedPreferences = Amethyst.instance.appContext.getSharedPreferences("amethyst_global_settings", Context.MODE_PRIVATE)
+
+    /**
+     * Loads the global-settings prefs file into SharedPreferences' in-memory cache, off the main
+     * thread, so the first synchronous read below hits memory rather than disk.
+     *
+     * The read itself is deliberately synchronous — see [setNotificationServiceEnabled]: an async
+     * hydrate reintroduces a window where a late disk read clobbers a user's toggle. So this warms
+     * the cache instead of deferring the read. Best-effort: if a main-thread reader wins the race it
+     * simply pays the disk hit once, exactly as before.
+     */
+    fun warmGlobalSettings() {
+        globalSettingsPrefs().getBoolean(PrefKeys.NOTIFICATION_SERVICE_ENABLED, true)
+    }
+
+    private val notificationServiceEnabled: MutableStateFlow<Boolean> by lazy {
+        MutableStateFlow(globalSettingsPrefs().getBoolean(PrefKeys.NOTIFICATION_SERVICE_ENABLED, true))
+    }
+
+    fun notificationServiceEnabledFlow(): StateFlow<Boolean> = notificationServiceEnabled
+
+    fun isNotificationServiceEnabled(): Boolean = notificationServiceEnabled.value
+
+    fun setNotificationServiceEnabled(enabled: Boolean) {
+        // In-memory update is the source of truth (main-safe); plain-prefs edit{} persists
+        // asynchronously via apply(), also main-safe. No suspend/hydrate hop, so no window
+        // where a late disk read can clobber this write.
+        notificationServiceEnabled.value = enabled
+        globalSettingsPrefs().edit { putBoolean(PrefKeys.NOTIFICATION_SERVICE_ENABLED, enabled) }
+    }
+
     suspend fun currentAccount(): String? {
         if (currentAccount == null) {
             currentAccount =
@@ -208,41 +298,46 @@ object LocalPreferences {
     }
 
     private suspend fun savedAccounts(): List<AccountInfo> {
-        if (savedAccounts.value == null) {
-            withContext(Dispatchers.IO) {
-                with(encryptedPreferences()) {
-                    val newSystemOfAccounts =
-                        getString(PrefKeys.ALL_ACCOUNT_INFO, "[]")?.let {
-                            JsonMapper.fromJson<List<AccountInfo>>(it)
-                        }
+        // Fast path: already populated, no lock needed.
+        savedAccounts.value?.let { return it }
 
-                    if (!newSystemOfAccounts.isNullOrEmpty()) {
-                        savedAccounts.emit(newSystemOfAccounts)
-                    } else {
-                        val oldAccounts = getString(PrefKeys.SAVED_ACCOUNTS, null)?.split(COMMA) ?: listOf()
+        return savedAccountsMutex.withLock {
+            // Re-check under the lock: another coroutine may have populated it while we waited.
+            savedAccounts.value ?: loadSavedAccountsFromStorage().also { savedAccounts.emit(it) }
+        }
+    }
 
-                        val migrated =
-                            oldAccounts.map { npub ->
-                                AccountInfo(
-                                    npub,
-                                    encryptedPreferences(npub).getBoolean(PrefKeys.LOGIN_WITH_EXTERNAL_SIGNER, false),
-                                    (encryptedPreferences(npub).getString(PrefKeys.NOSTR_PRIVKEY, "") ?: "").isNotBlank(),
-                                    false,
-                                )
-                            }
-
-                        savedAccounts.emit(migrated)
-
-                        edit {
-                            putString(PrefKeys.ALL_ACCOUNT_INFO, JsonMapper.toJson(migrated))
-                        }
+    private suspend fun loadSavedAccountsFromStorage(): List<AccountInfo> =
+        withContext(Dispatchers.IO) {
+            with(encryptedPreferences()) {
+                val newSystemOfAccounts =
+                    getString(PrefKeys.ALL_ACCOUNT_INFO, "[]")?.let {
+                        JsonMapper.fromJson<List<AccountInfo>>(it)
                     }
+
+                if (!newSystemOfAccounts.isNullOrEmpty()) {
+                    newSystemOfAccounts
+                } else {
+                    val oldAccounts = getString(PrefKeys.SAVED_ACCOUNTS, null)?.split(COMMA) ?: listOf()
+
+                    val migrated =
+                        oldAccounts.map { npub ->
+                            AccountInfo(
+                                npub,
+                                encryptedPreferences(npub).getBoolean(PrefKeys.LOGIN_WITH_EXTERNAL_SIGNER, false),
+                                (encryptedPreferences(npub).getString(PrefKeys.NOSTR_PRIVKEY, "") ?: "").isNotBlank(),
+                                false,
+                            )
+                        }
+
+                    edit {
+                        putString(PrefKeys.ALL_ACCOUNT_INFO, JsonMapper.toJson(migrated))
+                    }
+
+                    migrated
                 }
             }
         }
-        // it's always not null when it gets here.
-        return savedAccounts.value!!
-    }
 
     fun accountsFlow() = savedAccounts
 
@@ -340,7 +435,27 @@ object LocalPreferences {
         }
     }
 
-    suspend fun setDefaultAccount(accountSettings: AccountSettings) {
+    /**
+     * Make [accountSettings] the current account, persisting + caching it. Returns the settings that
+     * actually became current — normally [accountSettings] itself, but see the downgrade guard below.
+     */
+    suspend fun setDefaultAccount(accountSettings: AccountSettings): AccountSettings {
+        val npub = accountSettings.keyPair.pubKey.toNpub()
+
+        // Downgrade guard: adding a read-only npub for a pubkey we already hold a SIGNING account for
+        // must not clobber that account. Accounts dedup by npub, so saving fresh read-only settings
+        // here would overwrite the signing account's per-npub file — wiping its cached follow/relay/
+        // mute lists and flipping hasPrivKey off, which silently disables its push notifications. A
+        // signing account already does everything the read-only one would, so keep it and just make
+        // it current instead of degrading it.
+        if (!accountSettings.isWriteable()) {
+            val existing = loadAccountConfigFromEncryptedStorage(npub)
+            if (existing != null && existing.isWriteable()) {
+                setCurrentAccount(existing)
+                return existing
+            }
+        }
+
         // Save the per-npub file before emitting onto the savedAccounts flow.
         // Otherwise a collector (e.g. AlwaysOnNotificationServiceManager) can race in
         // and call loadAccountConfigFromEncryptedStorage(npub) before NOSTR_PUBKEY is
@@ -348,9 +463,9 @@ object LocalPreferences {
         // rest of the session — making every later switch to this account land on
         // LoggedOff instead of LoggedIn.
         saveToEncryptedStorage(accountSettings)
-        val npub = accountSettings.keyPair.pubKey.toNpub()
         mutex.withLock { cachedAccounts.put(npub, accountSettings) }
         setCurrentAccount(accountSettings)
+        return accountSettings
     }
 
     suspend fun allSavedAccounts(): List<AccountInfo> = savedAccounts()
@@ -379,7 +494,13 @@ object LocalPreferences {
                     putBoolean(PrefKeys.STRIP_LOCATION_ON_UPLOAD, settings.stripLocationOnUpload)
                     putBoolean(PrefKeys.USE_LOCAL_BLOSSOM_CACHE, settings.useLocalBlossomCache.value)
                     putBoolean(PrefKeys.LOCAL_BLOSSOM_CACHE_PROFILE_PICTURES_ONLY, settings.localBlossomCacheProfilePicturesOnly.value)
+                    putBoolean(PrefKeys.MIRROR_UPLOADS_TO_ALL_SERVERS, settings.mirrorUploadsToAllServers.value)
+                    putBoolean(PrefKeys.OPTIMIZE_MEDIA_ON_UPLOAD, settings.optimizeMediaOnUpload.value)
                     putBoolean(PrefKeys.HIDE_COMMUNITY_RULES_VIOLATIONS, settings.hideCommunityRulesViolations.value)
+                    putBoolean(PrefKeys.NIP46_SIGNER_ENABLED, settings.nip46SignerEnabled.value)
+                    putString(PrefKeys.NIP46_BUNKER_SECRET, settings.nip46BunkerSecret.value)
+                    putString(PrefKeys.NIP46_TRANSPORT_KEY, settings.nip46TransportKey.value)
+                    putStringSet(PrefKeys.NIP46_SEEN_IDS, settings.nip46SeenRequestIds.value)
 
                     putString(PrefKeys.DEFAULT_HOME_FOLLOW_LIST, JsonMapper.toJson(settings.defaultHomeFollowList.value))
                     putString(PrefKeys.DEFAULT_STORIES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultStoriesFollowList.value))
@@ -388,7 +509,11 @@ object LocalPreferences {
 
                     putString(PrefKeys.DEFAULT_POLLS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultPollsFollowList.value))
                     putString(PrefKeys.DEFAULT_PICTURES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultPicturesFollowList.value))
+                    putString(PrefKeys.DEFAULT_RELAY_GROUPS_DISCOVERY_FOLLOW_LIST, JsonMapper.toJson(settings.defaultRelayGroupsDiscoveryFollowList.value))
+                    putString(PrefKeys.DEFAULT_NAPPLETS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultNappletsFollowList.value))
+                    putString(PrefKeys.DEFAULT_NSITES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultNsitesFollowList.value))
                     putString(PrefKeys.DEFAULT_WORKOUTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultWorkoutsFollowList.value))
+                    putString(PrefKeys.DEFAULT_GIT_REPOSITORIES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultGitRepositoriesFollowList.value))
                     putString(PrefKeys.DEFAULT_CALENDARS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultCalendarsFollowList.value))
                     putString(PrefKeys.DEFAULT_PRODUCTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultProductsFollowList.value))
                     putString(PrefKeys.DEFAULT_SHORTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultShortsFollowList.value))
@@ -406,6 +531,7 @@ object LocalPreferences {
                     putString(PrefKeys.DEFAULT_BROWSE_EMOJI_SETS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultBrowseEmojiSetsFollowList.value))
                     putString(PrefKeys.DEFAULT_COMMUNITIES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultCommunitiesFollowList.value))
                     putString(PrefKeys.DEFAULT_FOLLOW_PACKS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultFollowPacksFollowList.value))
+                    putString(PrefKeys.DEFAULT_APP_RECOMMENDATIONS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultAppRecommendationsFollowList.value))
 
                     val walletEntries = settings.nwcWallets.value.mapNotNull { it.denormalize() }
                     if (walletEntries.isNotEmpty()) {
@@ -456,7 +582,11 @@ object LocalPreferences {
                     putOrRemove(PrefKeys.LATEST_HASHTAG_LIST, settings.backupHashtagList)
                     putOrRemove(PrefKeys.LATEST_GEOHASH_LIST, settings.backupGeohashList)
                     putOrRemove(PrefKeys.LATEST_EPHEMERAL_LIST, settings.backupEphemeralChatList)
+                    putOrRemove(PrefKeys.LATEST_RELAY_GROUP_LIST, settings.backupRelayGroupList)
+                    putOrRemove(PrefKeys.LATEST_CONCORD_LIST, settings.backupConcordList)
                     putOrRemove(PrefKeys.LATEST_TRUST_PROVIDER_LIST, settings.backupTrustProviderList)
+                    putOrRemove(PrefKeys.LATEST_KEY_PACKAGE_RELAY_LIST, settings.backupKeyPackageRelayList)
+                    putOrRemove(PrefKeys.LATEST_FAVORITE_ALGO_FEEDS_LIST, settings.backupFavoriteAlgoFeedsList)
                     putOrRemove(PrefKeys.LATEST_PAYMENT_TARGETS, settings.backupNipA3PaymentTargets)
                     putOrRemove(PrefKeys.LATEST_CASHU_WALLET, settings.backupCashuWallet)
                     putOrRemove(PrefKeys.LATEST_NUTZAP_INFO, settings.backupNutzapInfo)
@@ -466,7 +596,16 @@ object LocalPreferences {
                     putBoolean(PrefKeys.HIDE_BLOCK_ALERT_DIALOG, settings.hideBlockAlertDialog)
                     putBoolean(PrefKeys.CALLS_ENABLED, settings.callsEnabled.value)
                     putBoolean(PrefKeys.ALWAYS_ON_NOTIFICATION_SERVICE, settings.alwaysOnNotificationService.value)
+                    putString(PrefKeys.DEFAULT_RELAY_AUTH_POLICY, settings.defaultRelayAuthPolicy.value.name)
+                    putString(PrefKeys.RELAY_GROUP_VIEW_MODE, settings.relayGroupViewMode.value.name)
+                    putString(PrefKeys.CONCORD_VIEW_MODE, settings.concordViewMode.value.name)
+                    putString(PrefKeys.DISABLED_CHAT_FEEDS, ChatFeedType.encode(ChatFeedType.ALL - settings.enabledChatFeeds.value))
+                    putBoolean(PrefKeys.RELAY_AUTH_TRUST_MY_RELAYS, settings.relayAuthTrustMyRelaysAndVenues.value)
+                    putBoolean(PrefKeys.RELAY_AUTH_TRUST_READ_FOLLOWS, settings.relayAuthTrustReadFollows.value)
+                    putBoolean(PrefKeys.RELAY_AUTH_TRUST_MESSAGE_FOLLOWS, settings.relayAuthTrustMessageFollows.value)
+                    putBoolean(PrefKeys.RELAY_AUTH_TRUST_MESSAGE_STRANGERS, settings.relayAuthTrustMessageStrangers.value)
                     putBoolean(PrefKeys.SPLIT_NOTIFICATIONS_ENABLED, settings.splitNotificationsEnabled.value)
+                    putBoolean(PrefKeys.SHOW_MESSAGES_IN_NOTIFICATIONS, settings.showMessagesInNotifications.value)
                     // Any account that reaches a save has its notification filter in its
                     // post-split meaning, so stamp it as migrated. This keeps the one-shot
                     // Global -> Selected rewrite from ever touching it again and preserves a
@@ -575,13 +714,31 @@ object LocalPreferences {
                     val stripLocationOnUpload = getBoolean(PrefKeys.STRIP_LOCATION_ON_UPLOAD, true)
                     val useLocalBlossomCache = getBoolean(PrefKeys.USE_LOCAL_BLOSSOM_CACHE, true)
                     val localBlossomCacheProfilePicturesOnly = getBoolean(PrefKeys.LOCAL_BLOSSOM_CACHE_PROFILE_PICTURES_ONLY, false)
+                    val mirrorUploadsToAllServers = getBoolean(PrefKeys.MIRROR_UPLOADS_TO_ALL_SERVERS, true)
+                    val optimizeMediaOnUpload = getBoolean(PrefKeys.OPTIMIZE_MEDIA_ON_UPLOAD, false)
                     val hideCommunityRulesViolations = getBoolean(PrefKeys.HIDE_COMMUNITY_RULES_VIOLATIONS, false)
+                    val nip46SignerEnabled = getBoolean(PrefKeys.NIP46_SIGNER_ENABLED, false)
+                    val nip46BunkerSecret = getString(PrefKeys.NIP46_BUNKER_SECRET, "") ?: ""
+                    val nip46TransportKey = getString(PrefKeys.NIP46_TRANSPORT_KEY, "") ?: ""
+                    val nip46SeenRequestIds = getStringSet(PrefKeys.NIP46_SEEN_IDS, null) ?: setOf()
                     val hideDeleteRequestDialog = getBoolean(PrefKeys.HIDE_DELETE_REQUEST_DIALOG, false)
                     val hideBlockAlertDialog = getBoolean(PrefKeys.HIDE_BLOCK_ALERT_DIALOG, false)
                     val hideNIP17WarningDialog = getBoolean(PrefKeys.HIDE_NIP_17_WARNING_DIALOG, false)
                     val callsEnabled = getBoolean(PrefKeys.CALLS_ENABLED, true)
                     val alwaysOnNotificationService = getBoolean(PrefKeys.ALWAYS_ON_NOTIFICATION_SERVICE, false)
+                    val defaultRelayAuthPolicy =
+                        getString(PrefKeys.DEFAULT_RELAY_AUTH_POLICY, null)
+                            ?.let { runCatching { RelayAuthPolicy.valueOf(it) }.getOrNull() }
+                            ?: RelayAuthPolicy.CUSTOM
+                    val relayGroupViewMode = RelayGroupViewMode.fromName(getString(PrefKeys.RELAY_GROUP_VIEW_MODE, null))
+                    val concordViewMode = ConcordViewMode.fromName(getString(PrefKeys.CONCORD_VIEW_MODE, null))
+                    val enabledChatFeeds = ChatFeedType.ALL - ChatFeedType.decode(getString(PrefKeys.DISABLED_CHAT_FEEDS, null))
+                    val relayAuthTrustMyRelays = getBoolean(PrefKeys.RELAY_AUTH_TRUST_MY_RELAYS, true)
+                    val relayAuthTrustReadFollows = getBoolean(PrefKeys.RELAY_AUTH_TRUST_READ_FOLLOWS, true)
+                    val relayAuthTrustMessageFollows = getBoolean(PrefKeys.RELAY_AUTH_TRUST_MESSAGE_FOLLOWS, true)
+                    val relayAuthTrustMessageStrangers = getBoolean(PrefKeys.RELAY_AUTH_TRUST_MESSAGE_STRANGERS, false)
                     val splitNotificationsEnabled = getBoolean(PrefKeys.SPLIT_NOTIFICATIONS_ENABLED, false)
+                    val showMessagesInNotifications = getBoolean(PrefKeys.SHOW_MESSAGES_IN_NOTIFICATIONS, true)
                     val hasDonatedInVersion = getStringSet(PrefKeys.HAS_DONATED_IN_VERSION, null) ?: setOf()
                     val dismissedPollNoteIds = getStringSet(PrefKeys.DISMISSED_POLL_NOTE_IDS, null) ?: setOf()
                     val viewedPollResultNoteIdsStr = getString(PrefKeys.VIEWED_POLL_RESULT_NOTE_IDS, null)
@@ -614,7 +771,11 @@ object LocalPreferences {
                     val latestHashtagListStr = getString(PrefKeys.LATEST_HASHTAG_LIST, null)
                     val latestGeohashListStr = getString(PrefKeys.LATEST_GEOHASH_LIST, null)
                     val latestEphemeralListStr = getString(PrefKeys.LATEST_EPHEMERAL_LIST, null)
+                    val latestRelayGroupListStr = getString(PrefKeys.LATEST_RELAY_GROUP_LIST, null)
+                    val latestConcordListStr = getString(PrefKeys.LATEST_CONCORD_LIST, null)
                     val latestTrustProviderListStr = getString(PrefKeys.LATEST_TRUST_PROVIDER_LIST, null)
+                    val latestKeyPackageRelayListStr = getString(PrefKeys.LATEST_KEY_PACKAGE_RELAY_LIST, null)
+                    val latestFavoriteAlgoFeedsListStr = getString(PrefKeys.LATEST_FAVORITE_ALGO_FEEDS_LIST, null)
                     val latestPaymentTargetsStr = getString(PrefKeys.LATEST_PAYMENT_TARGETS, null)
                     val latestCashuWalletStr = getString(PrefKeys.LATEST_CASHU_WALLET, null)
                     val latestNutzapInfoStr = getString(PrefKeys.LATEST_NUTZAP_INFO, null)
@@ -673,7 +834,11 @@ object LocalPreferences {
                     val latestHashtagList = async { parseEventOrNull<HashtagListEvent>(latestHashtagListStr) }
                     val latestGeohashList = async { parseEventOrNull<GeohashListEvent>(latestGeohashListStr) }
                     val latestEphemeralList = async { parseEventOrNull<EphemeralChatListEvent>(latestEphemeralListStr) }
+                    val latestRelayGroupList = async { parseEventOrNull<SimpleGroupListEvent>(latestRelayGroupListStr) }
+                    val latestConcordList = async { parseEventOrNull<ConcordCommunityListEvent>(latestConcordListStr) }
                     val latestTrustProviderList = async { parseEventOrNull<TrustProviderListEvent>(latestTrustProviderListStr) }
+                    val latestKeyPackageRelayList = async { parseEventOrNull<KeyPackageRelayListEvent>(latestKeyPackageRelayListStr) }
+                    val latestFavoriteAlgoFeedsList = async { parseEventOrNull<FavoriteAlgoFeedsListEvent>(latestFavoriteAlgoFeedsListStr) }
                     val latestPaymentTargets = async { parseEventOrNull<PaymentTargetsEvent>(latestPaymentTargetsStr) }
                     val latestCashuWallet =
                         async {
@@ -693,23 +858,75 @@ object LocalPreferences {
 
                     Log.d("LocalPreferences") { "Load account from file $npub - asyncs created" }
 
+                    // Resolve every parallel parse into a local before constructing AccountSettings.
+                    // Awaiting inside the 70-argument constructor expression below would place ~27
+                    // suspension points in the middle of a single huge operand stack, forcing the
+                    // coroutine state machine to spill/restore every partially-evaluated argument at
+                    // each point. That bloats the generated method past the compiler's per-method
+                    // instruction limit ("Method exceeds compiler instruction limit"). Awaiting into
+                    // vals first keeps each suspension point at a statement boundary (near-empty
+                    // operand stack) and leaves the constructor as straight-line, suspension-free code.
+                    val nwcWalletsResolved = nwcWalletsLoaded.await()
+                    val clinkDebitsResolved = clinkDebitsLoaded.await()
+                    val defaultFileServerResolved = defaultFileServer.await()
+                    val viewedPollResultNoteIdsResolved = viewedPollResultNoteIds.await()
+                    val pendingAttestationsResolved = pendingAttestations.await()
+                    val lastReadPerRouteResolved = lastReadPerRoute.await()
+                    val latestUserMetadataResolved = latestUserMetadata.await()
+                    val latestContactListResolved = latestContactList.await()
+                    val latestDmRelayListResolved = latestDmRelayList.await()
+                    val latestNip65RelayListResolved = latestNip65RelayList.await()
+                    val latestSearchRelayListResolved = latestSearchRelayList.await()
+                    val latestIndexRelayListResolved = latestIndexRelayList.await()
+                    val latestRelayFeedsListResolved = latestRelayFeedsList.await()
+                    val latestBlockedRelayListResolved = latestBlockedRelayList.await()
+                    val latestTrustedRelayListResolved = latestTrustedRelayList.await()
+                    val latestMuteListResolved = latestMuteList.await()
+                    val latestPrivateHomeRelayListResolved = latestPrivateHomeRelayList.await()
+                    val latestAppSpecificDataResolved = latestAppSpecificData.await()
+                    val latestChannelListResolved = latestChannelList.await()
+                    val latestCommunityListResolved = latestCommunityList.await()
+                    val latestHashtagListResolved = latestHashtagList.await()
+                    val latestGeohashListResolved = latestGeohashList.await()
+                    val latestEphemeralListResolved = latestEphemeralList.await()
+                    val latestRelayGroupListResolved = latestRelayGroupList.await()
+                    val latestConcordListResolved = latestConcordList.await()
+                    val latestTrustProviderListResolved = latestTrustProviderList.await()
+                    val latestKeyPackageRelayListResolved = latestKeyPackageRelayList.await()
+                    val latestFavoriteAlgoFeedsListResolved = latestFavoriteAlgoFeedsList.await()
+                    val latestPaymentTargetsResolved = latestPaymentTargets.await()
+                    val latestCashuWalletResolved = latestCashuWallet.await()
+                    val latestNutzapInfoResolved = latestNutzapInfo.await()
+
+                    Log.d("LocalPreferences") { "Load account from file $npub - asyncs resolved" }
+
                     return@with AccountSettings(
                         keyPair = keyPair,
                         transientAccount = false,
                         externalSignerPackageName = externalSignerPackageName,
                         localRelayServers = MutableStateFlow(localRelayServers),
-                        defaultFileServer = defaultFileServer.await(),
+                        defaultFileServer = defaultFileServerResolved,
                         stripLocationOnUpload = stripLocationOnUpload,
                         useLocalBlossomCache = MutableStateFlow(useLocalBlossomCache),
                         localBlossomCacheProfilePicturesOnly = MutableStateFlow(localBlossomCacheProfilePicturesOnly),
+                        mirrorUploadsToAllServers = MutableStateFlow(mirrorUploadsToAllServers),
+                        optimizeMediaOnUpload = MutableStateFlow(optimizeMediaOnUpload),
                         hideCommunityRulesViolations = MutableStateFlow(hideCommunityRulesViolations),
+                        nip46SignerEnabled = MutableStateFlow(nip46SignerEnabled),
+                        nip46BunkerSecret = MutableStateFlow(nip46BunkerSecret),
+                        nip46TransportKey = MutableStateFlow(nip46TransportKey),
+                        nip46SeenRequestIds = MutableStateFlow(nip46SeenRequestIds),
                         defaultHomeFollowList = MutableStateFlow(followListPrefs.home),
                         defaultStoriesFollowList = MutableStateFlow(followListPrefs.stories),
                         defaultNotificationFollowList = MutableStateFlow(followListPrefs.notification),
                         defaultDiscoveryFollowList = MutableStateFlow(followListPrefs.discovery),
                         defaultPollsFollowList = MutableStateFlow(followListPrefs.polls),
                         defaultPicturesFollowList = MutableStateFlow(followListPrefs.pictures),
+                        defaultRelayGroupsDiscoveryFollowList = MutableStateFlow(followListPrefs.relayGroupsDiscovery),
+                        defaultNappletsFollowList = MutableStateFlow(followListPrefs.napplets),
+                        defaultNsitesFollowList = MutableStateFlow(followListPrefs.nsites),
                         defaultWorkoutsFollowList = MutableStateFlow(followListPrefs.workouts),
+                        defaultGitRepositoriesFollowList = MutableStateFlow(followListPrefs.gitRepositories),
                         defaultCalendarsFollowList = MutableStateFlow(followListPrefs.calendars),
                         defaultProductsFollowList = MutableStateFlow(followListPrefs.products),
                         defaultShortsFollowList = MutableStateFlow(followListPrefs.shorts),
@@ -727,47 +944,61 @@ object LocalPreferences {
                         defaultBrowseEmojiSetsFollowList = MutableStateFlow(followListPrefs.browseEmojiSets),
                         defaultCommunitiesFollowList = MutableStateFlow(followListPrefs.communities),
                         defaultFollowPacksFollowList = MutableStateFlow(followListPrefs.followPacks),
-                        nwcWallets = MutableStateFlow(nwcWalletsLoaded.await().first),
-                        clinkDebitWallets = MutableStateFlow(clinkDebitsLoaded.await()),
+                        defaultAppRecommendationsFollowList = MutableStateFlow(followListPrefs.appRecommendations),
+                        nwcWallets = MutableStateFlow(nwcWalletsResolved.first),
+                        clinkDebitWallets = MutableStateFlow(clinkDebitsResolved),
                         // Prefer the new unified default; migrate from the legacy NWC default;
                         // else fall back to the first configured source (NWC before debits).
                         defaultPaymentSourceId =
                             MutableStateFlow(
                                 defaultPaymentSourceIdStr
-                                    ?: nwcWalletsLoaded.await().second
-                                    ?: clinkDebitsLoaded.await().firstOrNull()?.id,
+                                    ?: nwcWalletsResolved.second
+                                    ?: clinkDebitsResolved.firstOrNull()?.id,
                             ),
                         hideDeleteRequestDialog = hideDeleteRequestDialog,
                         hideBlockAlertDialog = hideBlockAlertDialog,
                         hideNIP17WarningDialog = hideNIP17WarningDialog,
                         alwaysOnNotificationService = MutableStateFlow(alwaysOnNotificationService),
+                        defaultRelayAuthPolicy = MutableStateFlow(defaultRelayAuthPolicy),
+                        relayGroupViewMode = MutableStateFlow(relayGroupViewMode),
+                        concordViewMode = MutableStateFlow(concordViewMode),
+                        enabledChatFeeds = MutableStateFlow(enabledChatFeeds),
+                        relayAuthTrustMyRelaysAndVenues = MutableStateFlow(relayAuthTrustMyRelays),
+                        relayAuthTrustReadFollows = MutableStateFlow(relayAuthTrustReadFollows),
+                        relayAuthTrustMessageFollows = MutableStateFlow(relayAuthTrustMessageFollows),
+                        relayAuthTrustMessageStrangers = MutableStateFlow(relayAuthTrustMessageStrangers),
                         splitNotificationsEnabled = MutableStateFlow(splitNotificationsEnabled),
-                        backupUserMetadata = latestUserMetadata.await(),
-                        backupContactList = latestContactList.await(),
-                        backupNIP65RelayList = latestNip65RelayList.await(),
-                        backupDMRelayList = latestDmRelayList.await(),
-                        backupSearchRelayList = latestSearchRelayList.await(),
-                        backupIndexRelayList = latestIndexRelayList.await(),
-                        backupRelayFeedsList = latestRelayFeedsList.await(),
-                        backupBlockedRelayList = latestBlockedRelayList.await(),
-                        backupTrustedRelayList = latestTrustedRelayList.await(),
-                        backupPrivateHomeRelayList = latestPrivateHomeRelayList.await(),
-                        backupMuteList = latestMuteList.await(),
-                        backupAppSpecificData = latestAppSpecificData.await(),
-                        backupChannelList = latestChannelList.await(),
-                        backupCommunityList = latestCommunityList.await(),
-                        backupHashtagList = latestHashtagList.await(),
-                        backupGeohashList = latestGeohashList.await(),
-                        backupEphemeralChatList = latestEphemeralList.await(),
-                        backupTrustProviderList = latestTrustProviderList.await(),
-                        lastReadPerRoute = MutableStateFlow(lastReadPerRoute.await()),
+                        showMessagesInNotifications = MutableStateFlow(showMessagesInNotifications),
+                        backupUserMetadata = latestUserMetadataResolved,
+                        backupContactList = latestContactListResolved,
+                        backupNIP65RelayList = latestNip65RelayListResolved,
+                        backupDMRelayList = latestDmRelayListResolved,
+                        backupSearchRelayList = latestSearchRelayListResolved,
+                        backupIndexRelayList = latestIndexRelayListResolved,
+                        backupRelayFeedsList = latestRelayFeedsListResolved,
+                        backupBlockedRelayList = latestBlockedRelayListResolved,
+                        backupTrustedRelayList = latestTrustedRelayListResolved,
+                        backupPrivateHomeRelayList = latestPrivateHomeRelayListResolved,
+                        backupMuteList = latestMuteListResolved,
+                        backupAppSpecificData = latestAppSpecificDataResolved,
+                        backupChannelList = latestChannelListResolved,
+                        backupCommunityList = latestCommunityListResolved,
+                        backupHashtagList = latestHashtagListResolved,
+                        backupGeohashList = latestGeohashListResolved,
+                        backupEphemeralChatList = latestEphemeralListResolved,
+                        backupRelayGroupList = latestRelayGroupListResolved,
+                        backupConcordList = latestConcordListResolved,
+                        backupTrustProviderList = latestTrustProviderListResolved,
+                        backupKeyPackageRelayList = latestKeyPackageRelayListResolved,
+                        backupFavoriteAlgoFeedsList = latestFavoriteAlgoFeedsListResolved,
+                        lastReadPerRoute = MutableStateFlow(lastReadPerRouteResolved),
                         hasDonatedInVersion = MutableStateFlow(hasDonatedInVersion),
                         dismissedPollNoteIds = MutableStateFlow(dismissedPollNoteIds),
-                        viewedPollResultNoteIds = MutableStateFlow(viewedPollResultNoteIds.await()),
-                        pendingAttestations = MutableStateFlow(pendingAttestations.await()),
-                        backupNipA3PaymentTargets = latestPaymentTargets.await(),
-                        backupCashuWallet = latestCashuWallet.await(),
-                        backupNutzapInfo = latestNutzapInfo.await(),
+                        viewedPollResultNoteIds = MutableStateFlow(viewedPollResultNoteIdsResolved),
+                        pendingAttestations = MutableStateFlow(pendingAttestationsResolved),
+                        backupNipA3PaymentTargets = latestPaymentTargetsResolved,
+                        backupCashuWallet = latestCashuWalletResolved,
+                        backupNutzapInfo = latestNutzapInfoResolved,
                         callsEnabled = MutableStateFlow(callsEnabled),
                     )
                 }
@@ -797,7 +1028,11 @@ object LocalPreferences {
         val discovery: TopFilter,
         val polls: TopFilter,
         val pictures: TopFilter,
+        val relayGroupsDiscovery: TopFilter,
+        val napplets: TopFilter,
+        val nsites: TopFilter,
         val workouts: TopFilter,
+        val gitRepositories: TopFilter,
         val calendars: TopFilter,
         val products: TopFilter,
         val shorts: TopFilter,
@@ -815,6 +1050,7 @@ object LocalPreferences {
         val browseEmojiSets: TopFilter,
         val communities: TopFilter,
         val followPacks: TopFilter,
+        val appRecommendations: TopFilter,
     )
 
     /**
@@ -849,7 +1085,11 @@ object LocalPreferences {
             discovery = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_DISCOVERY_FOLLOW_LIST, null), TopFilter.Global),
             polls = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_POLLS_FOLLOW_LIST, null), TopFilter.Global),
             pictures = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_PICTURES_FOLLOW_LIST, null), TopFilter.Global),
+            relayGroupsDiscovery = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_RELAY_GROUPS_DISCOVERY_FOLLOW_LIST, null), TopFilter.Mine),
+            napplets = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_NAPPLETS_FOLLOW_LIST, null), TopFilter.Global),
+            nsites = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_NSITES_FOLLOW_LIST, null), TopFilter.Global),
             workouts = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_WORKOUTS_FOLLOW_LIST, null), TopFilter.Global),
+            gitRepositories = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_GIT_REPOSITORIES_FOLLOW_LIST, null), TopFilter.Global),
             calendars = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_CALENDARS_FOLLOW_LIST, null), TopFilter.Global),
             products = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_PRODUCTS_FOLLOW_LIST, null), TopFilter.AroundMe),
             shorts = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_SHORTS_FOLLOW_LIST, null), TopFilter.Global),
@@ -867,6 +1107,7 @@ object LocalPreferences {
             browseEmojiSets = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_BROWSE_EMOJI_SETS_FOLLOW_LIST, null), TopFilter.Global),
             communities = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_COMMUNITIES_FOLLOW_LIST, null), TopFilter.AllFollows),
             followPacks = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_FOLLOW_PACKS_FOLLOW_LIST, null), TopFilter.Global),
+            appRecommendations = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_APP_RECOMMENDATIONS_FOLLOW_LIST, null), TopFilter.Global),
         )
 
     private inline fun <reified T : Any> parseOrNull(value: String?): T? {

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/DataStoreNostrSignerPermissionStore.kt

@@ -0,0 +1,196 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.PreferenceDataStoreFactory
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.AppSignerPolicy
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.NostrOpDecision
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.NostrSignerOp
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.NostrSignerPermissionStore
+import com.vitorpamplona.quartz.utils.cache.LargeCache
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.withContext
+import java.io.File
+import java.security.MessageDigest
+
+/**
+ * Per-coordinate DataStore-backed [NostrSignerPermissionStore]. One small `.preferences_pb`
+ * file per app (keyed by a SHA-256 prefix of the coordinate) so loading or saving one app's
+ * permissions never touches another app's data — essential at scale with 1000s of apps.
+ *
+ * The coordinate is stored inside each file under [KEY_COORDINATE] so [allPolicies] can
+ * reverse-map file → coordinate without scanning the filesystem.
+ */
+class DataStoreNostrSignerPermissionStore(
+    private val filesDir: File,
+) : NostrSignerPermissionStore {
+    constructor(context: Context) : this(context.applicationContext.filesDir)
+
+    private val cache = LargeCache<String, DataStore<Preferences>>()
+
+    private fun storeFor(coordinate: String): DataStore<Preferences> {
+        val file = File(filesDir, "datastore/nsp_${hash(coordinate)}.preferences_pb")
+        return cache.getOrCreate(file.absolutePath) {
+            PreferenceDataStoreFactory.create(produceFile = { file })
+        }
+    }
+
+    override suspend fun loadPolicy(coordinate: String): AppSignerPolicy? {
+        val raw = storeFor(coordinate).data.first()[KEY_POLICY] ?: return null
+        return runCatching { AppSignerPolicy.valueOf(raw) }.getOrNull()
+    }
+
+    override suspend fun storePolicy(
+        coordinate: String,
+        policy: AppSignerPolicy,
+    ) {
+        storeFor(coordinate).edit {
+            it[KEY_COORDINATE] = coordinate
+            it[KEY_POLICY] = policy.name
+        }
+    }
+
+    override suspend fun clearPolicy(coordinate: String) {
+        storeFor(coordinate).edit { it.remove(KEY_POLICY) }
+    }
+
+    override suspend fun loadOpDecision(
+        coordinate: String,
+        op: NostrSignerOp,
+    ): NostrOpDecision? {
+        val raw = storeFor(coordinate).data.first()[opKey(op)] ?: return null
+        return runCatching { NostrOpDecision.valueOf(raw) }.getOrNull()
+    }
+
+    override suspend fun storeOpDecision(
+        coordinate: String,
+        op: NostrSignerOp,
+        decision: NostrOpDecision,
+    ) {
+        storeFor(coordinate).edit {
+            it[KEY_COORDINATE] = coordinate
+            it[opKey(op)] = decision.name
+        }
+    }
+
+    override suspend fun clearOpDecision(
+        coordinate: String,
+        op: NostrSignerOp,
+    ) {
+        storeFor(coordinate).edit { it.remove(opKey(op)) }
+    }
+
+    override suspend fun allPolicies(): Map<String, AppSignerPolicy> =
+        // Enumerates the datastore directory + reads each file — blocking disk IO, so keep it off the
+        // caller's thread (callers invoke this from Compose LaunchedEffects on the main dispatcher).
+        withContext(Dispatchers.IO) {
+            val dir = File(filesDir, "datastore")
+            if (!dir.exists()) return@withContext emptyMap()
+            val result = mutableMapOf<String, AppSignerPolicy>()
+            for (file in dir.listFiles { f -> f.name.startsWith("nsp_") } ?: emptyArray()) {
+                val ds =
+                    cache.getOrCreate(file.absolutePath) {
+                        PreferenceDataStoreFactory.create(produceFile = { file })
+                    }
+                val coordinate = ds.data.first()[KEY_COORDINATE] ?: continue
+                val policy = loadPolicy(coordinate) ?: continue
+                result[coordinate] = policy
+            }
+            result
+        }
+
+    override suspend fun allOpDecisions(coordinate: String): Map<String, NostrOpDecision> {
+        val prefs = storeFor(coordinate).data.first()
+        val result = mutableMapOf<String, NostrOpDecision>()
+        for ((key, value) in prefs.asMap()) {
+            val name = key.name
+            if (!name.startsWith(OP_PREFIX)) continue
+            // Skip expiry metadata keys — they end with the expiry suffix
+            if (name.endsWith(OP_EXPIRY_SUFFIX)) continue
+            val opKey = name.removePrefix(OP_PREFIX)
+            val decision = runCatching { NostrOpDecision.valueOf(value as String) }.getOrNull() ?: continue
+            result[opKey] = decision
+        }
+        return result
+    }
+
+    override suspend fun loadOpExpiry(
+        coordinate: String,
+        op: NostrSignerOp,
+    ): Long? {
+        val raw = storeFor(coordinate).data.first()[opExpiryKey(op)] ?: return null
+        return raw.toLongOrNull()
+    }
+
+    override suspend fun storeOpExpiry(
+        coordinate: String,
+        op: NostrSignerOp,
+        expiresAt: Long,
+    ) {
+        storeFor(coordinate).edit { it[opExpiryKey(op)] = expiresAt.toString() }
+    }
+
+    override suspend fun clearOpExpiry(
+        coordinate: String,
+        op: NostrSignerOp,
+    ) {
+        storeFor(coordinate).edit { it.remove(opExpiryKey(op)) }
+    }
+
+    override suspend fun loadLastUsed(coordinate: String): Long? {
+        val raw = storeFor(coordinate).data.first()[KEY_LAST_USED] ?: return null
+        return raw.toLongOrNull()
+    }
+
+    override suspend fun storeLastUsed(
+        coordinate: String,
+        epochSeconds: Long,
+    ) {
+        storeFor(coordinate).edit { it[KEY_LAST_USED] = epochSeconds.toString() }
+    }
+
+    override suspend fun clearAll(coordinate: String) {
+        storeFor(coordinate).edit { it.clear() }
+    }
+
+    private fun opKey(op: NostrSignerOp) = stringPreferencesKey("$OP_PREFIX${op.key}")
+
+    private fun opExpiryKey(op: NostrSignerOp) = stringPreferencesKey("$OP_PREFIX${op.key}$OP_EXPIRY_SUFFIX")
+
+    companion object {
+        private val KEY_COORDINATE = stringPreferencesKey("coordinate")
+        private val KEY_POLICY = stringPreferencesKey("policy")
+        private val KEY_LAST_USED = stringPreferencesKey("lastused")
+        private const val OP_PREFIX = "op:"
+        private const val OP_EXPIRY_SUFFIX = ":exp"
+
+        private fun hash(coordinate: String): String {
+            val digest = MessageDigest.getInstance("SHA-256").digest(coordinate.toByteArray())
+            return digest.take(8).joinToString("") { "%02x".format(it) }
+        }
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/consent/ConnectedAccountRow.kt

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.consent
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import com.vitorpamplona.amethyst.ui.components.RobohashFallbackAsyncImage
+
+/**
+ * The account a signer request acts as — avatar + display name — so it's clear WHICH logged-in
+ * identity is approving/signing/encrypting/decrypting. Shown in both consent dialogs in place of a
+ * raw pubkey. Falls back to a robohash avatar seeded on [pubKey] when there's no [picture].
+ */
+@Composable
+fun ConnectedAccountRow(
+    name: String,
+    picture: String?,
+    pubKey: String?,
+) {
+    Row(
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        RobohashFallbackAsyncImage(
+            robot = pubKey ?: name,
+            model = picture,
+            contentDescription = null,
+            modifier = Modifier.size(26.dp).clip(CircleShape),
+            loadProfilePicture = true,
+            loadRobohash = true,
+        )
+        Text(
+            name,
+            style = MaterialTheme.typography.labelLarge,
+            color = MaterialTheme.colorScheme.onSurface,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+        )
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/consent/SignerConnectActivity.kt

@@ -0,0 +1,328 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.consent
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.Dialog
+import androidx.compose.ui.window.DialogProperties
+import com.vitorpamplona.amethyst.R
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.AppConnectResult
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.AppSignerPolicy
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteApp
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteAppIcon
+import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
+import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbol
+import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
+import com.vitorpamplona.amethyst.ui.theme.AmethystTheme
+
+class SignerConnectActivity : ComponentActivity() {
+    private var token: String? = null
+    private var decided = false
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val token = intent.getStringExtra(SignerConnectCoordinator.EXTRA_TOKEN)
+        this.token = token
+        val info = token?.let { SignerConnectCoordinator.infoFor(it) }
+        if (token == null || info == null) {
+            finish()
+            return
+        }
+
+        setContent {
+            AmethystTheme {
+                SignerConnectScreen(
+                    info = info,
+                    onConnect = { policy ->
+                        decided = true
+                        SignerConnectCoordinator.complete(token, AppConnectResult.Connected(policy))
+                        finish()
+                    },
+                    onBlock = {
+                        decided = true
+                        SignerConnectCoordinator.complete(token, AppConnectResult.Blocked)
+                        finish()
+                    },
+                    onCancel = {
+                        decided = true
+                        SignerConnectCoordinator.complete(token, AppConnectResult.Cancelled)
+                        finish()
+                    },
+                )
+            }
+        }
+    }
+
+    override fun finish() {
+        if (!decided) token?.let { SignerConnectCoordinator.cancel(it) }
+        super.finish()
+    }
+}
+
+@Composable
+private fun SignerConnectScreen(
+    info: SignerConnectInfo,
+    onConnect: (AppSignerPolicy) -> Unit,
+    onBlock: () -> Unit,
+    onCancel: () -> Unit,
+) {
+    var selected by remember { mutableStateOf(AppSignerPolicy.REASONABLE) }
+    val maxHeight = LocalConfiguration.current.screenHeightDp.dp * 0.9f
+
+    Dialog(
+        onDismissRequest = onCancel,
+        properties = DialogProperties(usePlatformDefaultWidth = false),
+    ) {
+        Surface(
+            modifier =
+                Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 16.dp)
+                    .heightIn(max = maxHeight),
+            shape = MaterialTheme.shapes.extraLarge,
+            color = MaterialTheme.colorScheme.surface,
+            tonalElevation = 6.dp,
+        ) {
+            Column(
+                modifier =
+                    Modifier
+                        .verticalScroll(rememberScrollState())
+                        .padding(vertical = 24.dp),
+            ) {
+                // Centered header: icon + app name + connect subtitle
+                Column(
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    verticalArrangement = Arrangement.spacedBy(8.dp),
+                ) {
+                    val isBrowser = info.coordinate.startsWith("browser:")
+                    FavoriteAppIcon(
+                        app =
+                            if (isBrowser) {
+                                FavoriteApp.WebApp(info.coordinate.substringAfter(':'), info.appletTitle, 0L, info.iconUrl)
+                            } else {
+                                FavoriteApp.NostrApp(info.coordinate, info.appletTitle, 0L, info.iconUrl)
+                            },
+                        tint = MaterialTheme.colorScheme.onPrimaryContainer,
+                        modifier = Modifier.size(56.dp),
+                    )
+                    Text(
+                        info.appletTitle,
+                        style = MaterialTheme.typography.titleLarge,
+                        textAlign = TextAlign.Center,
+                    )
+                    Text(
+                        stringResource(R.string.napplet_connect_subtitle),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        textAlign = TextAlign.Center,
+                    )
+                    // Show WHICH account is being connected (avatar + name), not a raw pubkey.
+                    if (info.accountName != null) {
+                        ConnectedAccountRow(info.accountName, info.accountPicture, info.accountPubKey)
+                    } else {
+                        Text(
+                            info.domain,
+                            style = MaterialTheme.typography.labelSmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            textAlign = TextAlign.Center,
+                        )
+                    }
+                }
+
+                // What the app declared it needs (nostrconnect `perms`) — so consent is informed,
+                // not a silent grant. Approving connects and pre-grants exactly these.
+                if (info.requestedPermissions.isNotEmpty()) {
+                    Spacer(Modifier.height(16.dp))
+                    Surface(
+                        modifier = Modifier.padding(horizontal = 24.dp).fillMaxWidth(),
+                        color = MaterialTheme.colorScheme.surfaceVariant,
+                        shape = MaterialTheme.shapes.medium,
+                    ) {
+                        Column(modifier = Modifier.padding(14.dp), verticalArrangement = Arrangement.spacedBy(6.dp)) {
+                            Text(
+                                stringResource(R.string.nip46_connect_requests_title),
+                                style = MaterialTheme.typography.labelLarge,
+                            )
+                            info.requestedPermissions.forEach { perm ->
+                                Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                                    Icon(
+                                        MaterialSymbols.Check,
+                                        contentDescription = null,
+                                        tint = MaterialTheme.colorScheme.primary,
+                                        modifier = Modifier.size(16.dp),
+                                    )
+                                    Text(perm, style = MaterialTheme.typography.bodySmall)
+                                }
+                            }
+                        }
+                    }
+                }
+
+                Spacer(Modifier.height(16.dp))
+                HorizontalDivider()
+                Spacer(Modifier.height(12.dp))
+
+                Text(
+                    stringResource(R.string.napplet_connect_how_handle),
+                    style = MaterialTheme.typography.bodyMedium,
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                )
+                Spacer(Modifier.height(8.dp))
+
+                // Trust level options
+                Column(
+                    modifier = Modifier.padding(horizontal = 24.dp),
+                    verticalArrangement = Arrangement.spacedBy(8.dp),
+                ) {
+                    PolicyOption(
+                        selected = selected == AppSignerPolicy.FULL_TRUST,
+                        symbol = MaterialSymbols.LockOpen,
+                        label = stringResource(R.string.napplet_policy_full_trust),
+                        description = stringResource(R.string.napplet_policy_full_trust_desc),
+                        onClick = { selected = AppSignerPolicy.FULL_TRUST },
+                    )
+                    PolicyOption(
+                        selected = selected == AppSignerPolicy.REASONABLE,
+                        symbol = MaterialSymbols.Shield,
+                        label = stringResource(R.string.napplet_policy_reasonable),
+                        description = stringResource(R.string.napplet_policy_reasonable_desc),
+                        onClick = { selected = AppSignerPolicy.REASONABLE },
+                    )
+                    PolicyOption(
+                        selected = selected == AppSignerPolicy.PARANOID,
+                        symbol = MaterialSymbols.Lock,
+                        label = stringResource(R.string.napplet_policy_paranoid),
+                        description = stringResource(R.string.napplet_policy_paranoid_desc),
+                        onClick = { selected = AppSignerPolicy.PARANOID },
+                    )
+                }
+
+                Spacer(Modifier.height(16.dp))
+                HorizontalDivider()
+                Spacer(Modifier.height(8.dp))
+
+                Row(
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    OutlinedButton(onClick = onCancel, modifier = Modifier.weight(1f)) {
+                        Text(stringResource(R.string.cancel))
+                    }
+                    Button(onClick = { onConnect(selected) }, modifier = Modifier.weight(1f)) {
+                        Text(stringResource(R.string.napplet_connect_button))
+                    }
+                }
+
+                OutlinedButton(
+                    onClick = onBlock,
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    colors = ButtonDefaults.outlinedButtonColors(contentColor = MaterialTheme.colorScheme.error),
+                ) {
+                    Text(
+                        stringResource(R.string.napplet_connect_block, info.domain),
+                        style = MaterialTheme.typography.bodyMedium,
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun PolicyOption(
+    selected: Boolean,
+    symbol: MaterialSymbol,
+    label: String,
+    description: String,
+    onClick: () -> Unit,
+) {
+    val borderColor = if (selected) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.outline.copy(alpha = 0.3f)
+    val bgColor = if (selected) MaterialTheme.colorScheme.primaryContainer.copy(alpha = 0.2f) else MaterialTheme.colorScheme.surface
+
+    Surface(
+        modifier =
+            Modifier
+                .fillMaxWidth()
+                .border(width = if (selected) 2.dp else 1.dp, color = borderColor, shape = RoundedCornerShape(12.dp))
+                .clickable(onClick = onClick),
+        shape = RoundedCornerShape(12.dp),
+        color = bgColor,
+    ) {
+        Row(
+            modifier = Modifier.padding(16.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            Icon(
+                symbol = symbol,
+                contentDescription = null,
+                tint = if (selected) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.size(26.dp),
+            )
+            Column(modifier = Modifier.weight(1f)) {
+                Text(label, style = MaterialTheme.typography.titleSmall, color = MaterialTheme.colorScheme.onSurface)
+                Text(description, style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant)
+            }
+            if (selected) {
+                Icon(
+                    symbol = MaterialSymbols.Check,
+                    contentDescription = null,
+                    tint = MaterialTheme.colorScheme.primary,
+                )
+            }
+        }
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/consent/SignerConnectCoordinator.kt

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.consent
+
+import android.content.Context
+import android.content.Intent
+import com.vitorpamplona.amethyst.R
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.AppConnectResult
+import kotlinx.coroutines.CompletableDeferred
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+
+/** Everything the "Connect to Nostr" dialog needs to render. */
+data class SignerConnectInfo(
+    val appletTitle: String,
+    val coordinate: String,
+    val domain: String,
+    val iconUrl: String? = null,
+    /**
+     * The account the app is connecting to, shown as an avatar + name instead of a raw pubkey. When
+     * [accountName] is null (e.g. napplet/browser paths that don't resolve it) the dialog falls back
+     * to [domain]. [accountPubKey] seeds the robohash avatar fallback when there's no picture.
+     */
+    val accountName: String? = null,
+    val accountPicture: String? = null,
+    val accountPubKey: String? = null,
+    /**
+     * Human-readable permissions the app declared it needs (from a `nostrconnect://…?perms=` offer),
+     * shown so the user gives INFORMED consent before those ops are pre-granted. Empty for flows that
+     * carry no declaration (bunker connect), which just show the trust picker.
+     */
+    val requestedPermissions: List<String> = emptyList(),
+)
+
+/**
+ * Bridges the broker to the "Connect to Nostr" first-connect UI. Suspends in [requestConnect];
+ * the Activity resolves the deferred with the user's choice.
+ * A dismissed dialog resolves to [AppConnectResult.Cancelled] — fails closed, no silent grant.
+ */
+object SignerConnectCoordinator {
+    private class Pending(
+        val info: SignerConnectInfo,
+        val deferred: CompletableDeferred<AppConnectResult>,
+    )
+
+    private val pending = ConcurrentHashMap<String, Pending>()
+
+    suspend fun requestConnect(
+        context: Context,
+        info: SignerConnectInfo,
+    ): AppConnectResult {
+        val token = UUID.randomUUID().toString()
+        val deferred = CompletableDeferred<AppConnectResult>()
+        pending[token] = Pending(info, deferred)
+
+        // Fast path when Amethyst already owns the foreground; the full-screen-intent notification
+        // below is what surfaces the dialog when a connect request arrives while backgrounded (see
+        // SignerConsentNotifier). Wrapped because a BAL-blocked launch can throw on some OEMs.
+        runCatching {
+            context.startActivity(
+                Intent(context, SignerConnectActivity::class.java)
+                    .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+                    .putExtra(EXTRA_TOKEN, token),
+            )
+        }
+
+        val notificationId =
+            SignerConsentNotifier.show(
+                context = context,
+                activityClass = SignerConnectActivity::class.java,
+                extraKey = EXTRA_TOKEN,
+                token = token,
+                titleRes = R.string.nip46_signer_notif_connect_title,
+            )
+
+        return try {
+            deferred.await()
+        } finally {
+            pending.remove(token)
+            SignerConsentNotifier.cancel(context, notificationId)
+        }
+    }
+
+    fun infoFor(token: String): SignerConnectInfo? = pending[token]?.info
+
+    fun complete(
+        token: String,
+        result: AppConnectResult,
+    ) {
+        pending[token]?.deferred?.complete(result)
+    }
+
+    fun cancel(token: String) {
+        pending[token]?.deferred?.complete(AppConnectResult.Cancelled)
+    }
+
+    const val EXTRA_TOKEN = "napplet_connect_token"
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/consent/SignerConsentActivity.kt

@@ -0,0 +1,591 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.consent
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.horizontalScroll
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.text.selection.SelectionContainer
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.Checkbox
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.res.pluralStringResource
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.Dialog
+import androidx.compose.ui.window.DialogProperties
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.vitorpamplona.amethyst.R
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.SignerOpGrant
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteApp
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteAppIcon
+import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
+import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
+import com.vitorpamplona.amethyst.model.LocalCache
+import com.vitorpamplona.amethyst.service.call.CallSessionBridge
+import com.vitorpamplona.amethyst.ui.components.RobohashFallbackAsyncImage
+import com.vitorpamplona.amethyst.ui.navigation.navs.EmptyNav
+import com.vitorpamplona.amethyst.ui.note.NoteCompose
+import com.vitorpamplona.amethyst.ui.theme.AmethystTheme
+import com.vitorpamplona.quartz.nip01Core.core.Event
+import com.vitorpamplona.quartz.nip59Giftwrap.rumors.RumorAssembler
+import com.vitorpamplona.quartz.utils.TimeUtils
+
+class SignerConsentActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            AmethystTheme {
+                // The signer services requests concurrently, so more than one may await consent. We never
+                // mix accounts in one sheet: render only the requests for the OLDEST-pending account as a
+                // group. When that account's group clears, the next account's requests render (a fresh
+                // per-account sheet). One request → the rich dialog; several → a batched list. When the
+                // whole queue empties, close.
+                val pending by SignerConsentCoordinator.pending.collectAsStateWithLifecycle()
+                val group =
+                    run {
+                        val account = pending.firstOrNull()?.info?.accountPubKey
+                        pending.filter { it.info.accountPubKey == account }
+                    }
+                LaunchedEffect(pending.isEmpty()) { if (pending.isEmpty()) finish() }
+                when {
+                    group.isEmpty() -> Unit
+                    group.size == 1 -> {
+                        val p = group.first()
+                        SignerConsentDialog(
+                            info = p.info,
+                            onGrant = { SignerConsentCoordinator.complete(p.token, it) },
+                            onDismiss = { SignerConsentCoordinator.complete(p.token, SignerOpGrant.DenyOnce) },
+                        )
+                    }
+                    else ->
+                        BatchedConsentDialog(
+                            pending = group,
+                            onResolve = { tokens, grant -> SignerConsentCoordinator.completeAll(tokens, grant) },
+                            // Dismissing denies only THIS account's group; other accounts' requests stay
+                            // pending and render next as their own sheet.
+                            onDismiss = { SignerConsentCoordinator.completeAll(group.map { it.token }, SignerOpGrant.DenyOnce) },
+                        )
+                }
+            }
+        }
+    }
+    // Dismissal is failed-closed at the source: each dialog's onDismissRequest (back / tap-outside)
+    // denies its own request(s). We deliberately do NOT deny-all in onDestroy — a request arriving as
+    // this Activity finishes is owned by a freshly-launched instance, and denying it here would race
+    // that instance and reject a legitimate request. A process kill falls back to the bridge's 120s
+    // timeout, which also fails closed.
+}
+
+@Composable
+private fun SignerConsentDialog(
+    info: SignerConsentInfo,
+    onGrant: (SignerOpGrant) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    var showMoreOptions by remember { mutableStateOf(false) }
+    val scrollState = rememberScrollState()
+    val maxHeight = LocalConfiguration.current.screenHeightDp.dp * 0.85f
+
+    Dialog(
+        onDismissRequest = onDismiss,
+        properties = DialogProperties(usePlatformDefaultWidth = false),
+    ) {
+        Surface(
+            modifier =
+                Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 16.dp)
+                    .heightIn(max = maxHeight),
+            shape = MaterialTheme.shapes.extraLarge,
+            color = MaterialTheme.colorScheme.surface,
+            tonalElevation = 6.dp,
+        ) {
+            Column(
+                modifier =
+                    Modifier
+                        .verticalScroll(scrollState)
+                        .padding(vertical = 24.dp),
+            ) {
+                // Centered header: icon + title + description
+                Column(
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    verticalArrangement = Arrangement.spacedBy(8.dp),
+                ) {
+                    val isBrowser = info.coordinate.startsWith("browser:")
+                    FavoriteAppIcon(
+                        app =
+                            if (isBrowser) {
+                                FavoriteApp.WebApp(info.coordinate.substringAfter(':'), info.appletTitle, 0L, info.iconUrl)
+                            } else {
+                                FavoriteApp.NostrApp(info.coordinate, info.appletTitle, 0L, info.iconUrl)
+                            },
+                        tint = MaterialTheme.colorScheme.onPrimaryContainer,
+                        modifier = Modifier.size(56.dp),
+                    )
+                    Text(
+                        info.appletTitle,
+                        style = MaterialTheme.typography.titleLarge,
+                        textAlign = TextAlign.Center,
+                    )
+                    Text(
+                        stringResource(R.string.napplet_consent_wants_to, info.operationSummary),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        textAlign = TextAlign.Center,
+                    )
+                    // Show WHICH account would sign/encrypt/decrypt (avatar + name), not the coordinate hex.
+                    if (info.accountName != null) {
+                        ConnectedAccountRow(info.accountName, info.accountPicture, info.accountPubKey)
+                    }
+                    // For a decrypt request, WHOSE conversation is being read is the decision. Show
+                    // that person as an avatar + name, never as nothing.
+                    if (info.counterpartyName != null) {
+                        Text(
+                            stringResource(R.string.nip46_signer_messages_with),
+                            style = MaterialTheme.typography.labelSmall,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                        ConnectedAccountRow(info.counterpartyName, info.counterpartyPicture, info.counterpartyPubKey)
+                    }
+                }
+
+                Spacer(Modifier.height(12.dp))
+                Box(modifier = Modifier.padding(horizontal = 24.dp)) {
+                    SignerConsentPreview(info)
+                }
+
+                Spacer(Modifier.height(16.dp))
+                HorizontalDivider()
+                Spacer(Modifier.height(8.dp))
+
+                // Primary: the NARROWEST "remember" available. For decrypt that is "always allow for
+                // Alice" — one broad decrypt grant would otherwise hand over every conversation
+                // forever, and scoping the op itself would mean a prompt per conversation.
+                val narrowOp = info.narrowOp
+                if (narrowOp != null && info.narrowOpLabel != null) {
+                    Button(
+                        onClick = { onGrant(SignerOpGrant.AllowForOp(narrowOp)) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(info.narrowOpLabel)
+                    }
+                    // The broad grant stays available, but demoted below the scoped one.
+                    OutlinedButton(
+                        onClick = { onGrant(SignerOpGrant.AllowForOp(info.op)) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(stringResource(R.string.napplet_consent_allow_always))
+                    }
+                } else {
+                    Button(
+                        onClick = { onGrant(SignerOpGrant.AllowForOp(info.op)) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(stringResource(R.string.napplet_consent_allow_always))
+                    }
+                }
+
+                // Secondary: allow just once
+                OutlinedButton(
+                    onClick = { onGrant(SignerOpGrant.AllowOnce) },
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                ) {
+                    Text(stringResource(R.string.napplet_signer_allow_once))
+                }
+
+                // "More options" toggle: session and time-bound grants
+                TextButton(
+                    onClick = { showMoreOptions = !showMoreOptions },
+                    modifier = Modifier.fillMaxWidth(),
+                    contentPadding = PaddingValues(horizontal = 24.dp, vertical = 8.dp),
+                ) {
+                    Row(
+                        verticalAlignment = Alignment.CenterVertically,
+                        horizontalArrangement = Arrangement.spacedBy(4.dp),
+                    ) {
+                        Text(
+                            if (showMoreOptions) {
+                                stringResource(R.string.napplet_consent_fewer_options)
+                            } else {
+                                stringResource(R.string.napplet_consent_more_options)
+                            },
+                            style = MaterialTheme.typography.bodyMedium,
+                        )
+                        Icon(
+                            if (showMoreOptions) MaterialSymbols.ExpandLess else MaterialSymbols.ExpandMore,
+                            contentDescription = null,
+                            modifier = Modifier.size(18.dp),
+                        )
+                    }
+                }
+
+                if (showMoreOptions) {
+                    OutlinedButton(
+                        onClick = { onGrant(SignerOpGrant.AllowForSession(info.op)) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(stringResource(R.string.napplet_signer_allow_session))
+                    }
+                    OutlinedButton(
+                        onClick = { onGrant(SignerOpGrant.AllowUntil(info.op, TimeUtils.now() + 86_400L)) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(stringResource(R.string.napplet_signer_allow_24h))
+                    }
+                    OutlinedButton(
+                        onClick = { onGrant(SignerOpGrant.AllowUntil(info.op, TimeUtils.now() + 30L * 86_400L)) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(stringResource(R.string.napplet_signer_allow_30d))
+                    }
+                    OutlinedButton(
+                        onClick = { onGrant(SignerOpGrant.AllowAll) },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    ) {
+                        Text(stringResource(R.string.napplet_signer_allow_all))
+                    }
+                }
+
+                Spacer(Modifier.height(4.dp))
+                HorizontalDivider()
+                Spacer(Modifier.height(8.dp))
+
+                OutlinedButton(
+                    onClick = { onGrant(SignerOpGrant.DenyOnce) },
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    colors = ButtonDefaults.outlinedButtonColors(contentColor = MaterialTheme.colorScheme.error),
+                ) {
+                    Text(stringResource(R.string.napplet_signer_deny_once))
+                }
+                OutlinedButton(
+                    onClick = { onGrant(SignerOpGrant.DenyForOp(info.op)) },
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    colors = ButtonDefaults.outlinedButtonColors(contentColor = MaterialTheme.colorScheme.error),
+                ) {
+                    Text(stringResource(R.string.napplet_signer_deny_op, info.operationSummary))
+                }
+            }
+        }
+    }
+}
+
+/**
+ * The "what you're acting on" block: the unsigned event rendered as a real NoteCompose (what it will
+ * look like once signed) with a JSON toggle for sign/publish, or the raw content / decrypted plaintext
+ * for encrypt/decrypt. Shared by the single-request dialog and each expanded batch row so a user can
+ * always inspect exactly what they are signing/encrypting/decrypting. Best-effort: if the main Activity
+ * is gone (only the foreground signer service alive) the NoteCompose is skipped and the JSON stands in.
+ */
+@Composable
+private fun SignerConsentPreview(info: SignerConsentInfo) {
+    var showRawData by remember(info) { mutableStateOf(false) }
+    val accountViewModel = remember { CallSessionBridge.accountViewModel }
+    val previewNav = remember { EmptyNav() }
+    val previewNote =
+        remember(info, accountViewModel) {
+            val template = info.previewTemplate
+            val author = info.accountPubKey ?: accountViewModel?.account?.signer?.pubKey
+            if (template != null && author != null && accountViewModel != null) {
+                runCatching {
+                    val unsigned = RumorAssembler.assembleRumor<Event>(author, template)
+                    accountViewModel.createTempDraftNote(unsigned, LocalCache.getOrCreateUser(author))
+                }.getOrNull()
+            } else {
+                null
+            }
+        }
+
+    val hasContent = previewNote != null || info.contentPreview.isNotBlank() || info.rawData.isNotBlank()
+    if (!hasContent) return
+    Surface(
+        modifier = Modifier.fillMaxWidth(),
+        color = MaterialTheme.colorScheme.surfaceVariant,
+        shape = MaterialTheme.shapes.medium,
+    ) {
+        Column(modifier = Modifier.padding(12.dp)) {
+            if (previewNote != null && accountViewModel != null) {
+                NoteCompose(
+                    baseNote = previewNote,
+                    isQuotedNote = true,
+                    quotesLeft = 0,
+                    accountViewModel = accountViewModel,
+                    nav = previewNav,
+                )
+            } else if (info.contentPreview.isNotBlank()) {
+                Text("“${info.contentPreview}”", style = MaterialTheme.typography.bodySmall)
+            }
+            if (info.rawData.isNotBlank()) {
+                if (showRawData) {
+                    Spacer(Modifier.height(8.dp))
+                    Box(modifier = Modifier.horizontalScroll(rememberScrollState())) {
+                        SelectionContainer {
+                            Text(
+                                info.rawData,
+                                style = MaterialTheme.typography.labelSmall.copy(fontFamily = FontFamily.Monospace),
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                                softWrap = false,
+                            )
+                        }
+                    }
+                }
+                TextButton(
+                    onClick = { showRawData = !showRawData },
+                    contentPadding = PaddingValues(horizontal = 4.dp, vertical = 0.dp),
+                ) {
+                    Text(
+                        if (showRawData) {
+                            stringResource(R.string.napplet_consent_hide_event)
+                        } else {
+                            stringResource(R.string.napplet_consent_show_event)
+                        },
+                        style = MaterialTheme.typography.labelSmall,
+                    )
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Shown when more than one request is awaiting consent at once (the signer services requests
+ * concurrently). Lists each with a checkbox — all selected by default — and resolves the selected
+ * ones together as Allow or Deny. "Remember" makes an Allow persist per-op ([SignerOpGrant.AllowForOp]);
+ * off is a one-time [SignerOpGrant.AllowOnce]. Requests left unselected stay pending and re-render
+ * (as this list, or the single-request dialog once one remains).
+ */
+@Composable
+private fun BatchedConsentDialog(
+    pending: List<PendingConsent>,
+    onResolve: (tokens: List<String>, grant: SignerOpGrant) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    val maxHeight = LocalConfiguration.current.screenHeightDp.dp * 0.85f
+    val tokens = pending.map { it.token }.toSet()
+    // Seed all-selected ONCE for the initial batch the user opened. The signer services requests
+    // concurrently, so `tokens` can change under an open sheet; reconcile incrementally instead of
+    // re-seeding — drop resolved tokens but KEEP the user's deselections, and never auto-select a
+    // newly-arrived request. Otherwise a request landing (or resolving) mid-decision would silently
+    // re-check everything, and an "Allow selected" tap would grant ops the user deselected or never saw.
+    var selected by remember { mutableStateOf(tokens) }
+    LaunchedEffect(tokens) { selected = selected intersect tokens }
+    var rememberChoice by remember { mutableStateOf(false) }
+    // Tokens whose full preview (rendered event + JSON, or encrypt/decrypt plaintext) is expanded.
+    var expanded by remember { mutableStateOf(emptySet<String>()) }
+
+    Dialog(
+        onDismissRequest = onDismiss,
+        properties = DialogProperties(usePlatformDefaultWidth = false),
+    ) {
+        Surface(
+            modifier =
+                Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 16.dp)
+                    .heightIn(max = maxHeight),
+            shape = MaterialTheme.shapes.extraLarge,
+            color = MaterialTheme.colorScheme.surface,
+            tonalElevation = 6.dp,
+        ) {
+            Column(modifier = Modifier.padding(vertical = 20.dp)) {
+                // The sheet is single-account (grouped upstream), so the account is a header, not a
+                // per-row label. It says WHO every request in this sheet would act as.
+                val account = pending.first().info
+                Row(
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(10.dp),
+                ) {
+                    account.accountName?.let { name ->
+                        RobohashFallbackAsyncImage(
+                            robot = account.accountPubKey ?: name,
+                            model = account.accountPicture,
+                            contentDescription = null,
+                            modifier = Modifier.size(34.dp).clip(CircleShape),
+                            loadProfilePicture = true,
+                            loadRobohash = true,
+                        )
+                    }
+                    Column(modifier = Modifier.weight(1f)) {
+                        Text(
+                            pluralStringResource(R.plurals.nip46_signer_batch_title, pending.size, pending.size),
+                            style = MaterialTheme.typography.titleLarge,
+                        )
+                        account.accountName?.let { name ->
+                            Text(
+                                stringResource(R.string.nip46_signer_batch_signing_as, name),
+                                style = MaterialTheme.typography.labelMedium,
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                                maxLines = 1,
+                                overflow = TextOverflow.Ellipsis,
+                            )
+                        }
+                    }
+                }
+                TextButton(
+                    onClick = {
+                        selected = if (selected.size == pending.size) emptySet() else pending.map { it.token }.toSet()
+                    },
+                    contentPadding = PaddingValues(horizontal = 20.dp, vertical = 2.dp),
+                ) {
+                    Text(
+                        stringResource(
+                            if (selected.size == pending.size) R.string.nip46_signer_batch_select_none else R.string.nip46_signer_batch_select_all,
+                        ),
+                        style = MaterialTheme.typography.labelLarge,
+                    )
+                }
+
+                Column(
+                    modifier =
+                        Modifier
+                            .weight(1f, fill = false)
+                            .verticalScroll(rememberScrollState()),
+                ) {
+                    pending.forEach { p ->
+                        val isExpanded = p.token in expanded
+                        Column(modifier = Modifier.fillMaxWidth()) {
+                            Row(
+                                modifier =
+                                    Modifier
+                                        .fillMaxWidth()
+                                        .clickable {
+                                            expanded = if (isExpanded) expanded - p.token else expanded + p.token
+                                        }.padding(horizontal = 12.dp, vertical = 4.dp),
+                                verticalAlignment = Alignment.CenterVertically,
+                                horizontalArrangement = Arrangement.spacedBy(4.dp),
+                            ) {
+                                // Checkbox handles its own tap (select); tapping elsewhere on the row expands.
+                                Checkbox(
+                                    checked = p.token in selected,
+                                    onCheckedChange = { on -> selected = if (on) selected + p.token else selected - p.token },
+                                )
+                                Column(modifier = Modifier.weight(1f)) {
+                                    Text(
+                                        "${p.info.appletTitle} · ${p.info.operationSummary}",
+                                        style = MaterialTheme.typography.bodyMedium,
+                                        maxLines = 1,
+                                    )
+                                    if (p.info.contentPreview.isNotBlank()) {
+                                        Text(
+                                            p.info.contentPreview,
+                                            style = MaterialTheme.typography.bodySmall,
+                                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                                            maxLines = 1,
+                                        )
+                                    }
+                                }
+                                Icon(
+                                    if (isExpanded) MaterialSymbols.ExpandLess else MaterialSymbols.ExpandMore,
+                                    contentDescription = null,
+                                    tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                                    modifier = Modifier.size(20.dp),
+                                )
+                            }
+                            if (isExpanded) {
+                                Box(modifier = Modifier.padding(start = 12.dp, end = 12.dp, bottom = 8.dp)) {
+                                    SignerConsentPreview(p.info)
+                                }
+                            }
+                        }
+                    }
+                }
+
+                Row(
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp, vertical = 4.dp),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(8.dp),
+                ) {
+                    Switch(checked = rememberChoice, onCheckedChange = { rememberChoice = it })
+                    Text(
+                        stringResource(R.string.nip46_signer_batch_remember),
+                        style = MaterialTheme.typography.bodyMedium,
+                    )
+                }
+
+                Spacer(Modifier.height(8.dp))
+                HorizontalDivider()
+                Spacer(Modifier.height(8.dp))
+
+                Button(
+                    onClick = {
+                        val tokens = pending.filter { it.token in selected }
+                        // Per-op remember uses each request's own op; one-time is a single AllowOnce.
+                        if (rememberChoice) {
+                            tokens.forEach { onResolve(listOf(it.token), SignerOpGrant.AllowForOp(it.info.op)) }
+                        } else {
+                            onResolve(tokens.map { it.token }, SignerOpGrant.AllowOnce)
+                        }
+                    },
+                    enabled = selected.isNotEmpty(),
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                ) {
+                    Text(stringResource(R.string.nip46_signer_batch_allow, selected.size))
+                }
+                OutlinedButton(
+                    onClick = { onResolve(pending.filter { it.token in selected }.map { it.token }, SignerOpGrant.DenyOnce) },
+                    enabled = selected.isNotEmpty(),
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp),
+                    colors = ButtonDefaults.outlinedButtonColors(contentColor = MaterialTheme.colorScheme.error),
+                ) {
+                    Text(stringResource(R.string.nip46_signer_batch_deny, selected.size))
+                }
+            }
+        }
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/consent/SignerConsentCoordinator.kt

@@ -0,0 +1,175 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.consent
+
+import android.content.Context
+import android.content.Intent
+import com.vitorpamplona.amethyst.R
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.NostrSignerOp
+import com.vitorpamplona.amethyst.commons.connectedApps.signers.SignerOpGrant
+import com.vitorpamplona.quartz.nip01Core.core.Event
+import com.vitorpamplona.quartz.nip01Core.signers.EventTemplate
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.flow.updateAndGet
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+
+/** Everything the per-operation consent dialog needs to render. */
+data class SignerConsentInfo(
+    val appletTitle: String,
+    val coordinate: String,
+    val op: NostrSignerOp,
+    val operationSummary: String,
+    /** Short excerpt shown in the dialog body (≤ 160 chars). */
+    val contentPreview: String,
+    /**
+     * Full raw content for the "See more" toggle — event JSON for sign/encrypt operations,
+     * decrypted plaintext for decrypt (Amethyst decrypts first, then asks permission to expose).
+     */
+    val rawData: String = "",
+    val iconUrl: String? = null,
+    /**
+     * The account that would sign/encrypt/decrypt, shown as an avatar + name so it's clear which
+     * logged-in identity is acting. Null on paths that don't resolve it; [accountPubKey] seeds the
+     * robohash avatar fallback when there's no picture.
+     */
+    val accountName: String? = null,
+    val accountPicture: String? = null,
+    val accountPubKey: String? = null,
+    /**
+     * The unsigned event a `sign_event`/publish request would sign, so the dialog can render it as a
+     * note preview (what it will look like) in addition to the raw JSON. Null for encrypt/decrypt and
+     * non-event ops.
+     */
+    val previewTemplate: EventTemplate<Event>? = null,
+    /**
+     * The OTHER party of a decrypt request — whose conversation the app is asking to read — shown as
+     * an avatar + name. "X wants to read your messages with Alice" is a categorically different
+     * decision from "X wants to read your private messages", so this must reach the dialog.
+     * Null for every op that has no counterparty (signing, and the napplet/browser paths).
+     */
+    val counterpartyName: String? = null,
+    val counterpartyPicture: String? = null,
+    val counterpartyPubKey: String? = null,
+    /**
+     * A NARROWER op the dialog may offer to remember instead of [op] — today only
+     * [com.vitorpamplona.amethyst.commons.connectedApps.signers.NostrSignerOp.DecryptFrom], i.e.
+     * "always allow, but only for this counterparty". Offered ALONGSIDE the broad "Always allow" so
+     * the user gets granularity without a prompt per conversation. [narrowOpLabel] is its button text.
+     */
+    val narrowOp: NostrSignerOp? = null,
+    val narrowOpLabel: String? = null,
+)
+
+/** One pending per-operation consent request, as the batched sheet renders it. */
+data class PendingConsent(
+    val token: String,
+    val info: SignerConsentInfo,
+)
+
+/**
+ * Bridges the broker to the per-operation signer consent UI. The signer services requests
+ * concurrently (so their prompts can batch), so several requests can await consent at once: they all
+ * land in [pending], one [SignerConsentActivity] observes that list and shows a single-request dialog
+ * or a batched list, and each resolved token completes its own deferred. A dismissed/ignored request
+ * resolves to [SignerOpGrant.DenyOnce] — fails closed.
+ */
+object SignerConsentCoordinator {
+    private val deferreds = ConcurrentHashMap<String, CompletableDeferred<SignerOpGrant>>()
+    private val _pending = MutableStateFlow<List<PendingConsent>>(emptyList())
+
+    /** The live set of requests awaiting the user's decision; the Activity renders this. */
+    val pending: StateFlow<List<PendingConsent>> = _pending
+
+    // A stable notification id (one prompt notification for the whole batch, updated as requests
+    // arrive) so concurrent requests don't each post their own.
+    private val batchNotificationId = "nip46-signer-consent".hashCode()
+
+    // Guards the surface (post/cancel of the one shared notification) against the pending set so a
+    // concurrent arrival's post can't be clobbered by another request's teardown cancel. Without it,
+    // request A could read "pending now empty" and then cancel AFTER request B posted a fresh
+    // notification under the same id, leaving B with no UI while backgrounded (silent deny at timeout).
+    private val surfaceLock = Mutex()
+
+    suspend fun requestConsent(
+        context: Context,
+        info: SignerConsentInfo,
+    ): SignerOpGrant {
+        val token = UUID.randomUUID().toString()
+        val deferred = CompletableDeferred<SignerOpGrant>()
+        deferreds[token] = deferred
+
+        surfaceLock.withLock {
+            _pending.update { it + PendingConsent(token, info) }
+            // Fast path when Amethyst already owns the foreground: open the dialog directly. When the app
+            // is backgrounded this is silently dropped by Android 12+ BAL, so the full-screen-intent
+            // notification is what surfaces the prompt. Both are idempotent — the Activity is singleTop and
+            // observes [pending], and the notification uses a stable id, so concurrent requests just
+            // refresh the one prompt. Wrapped because a BAL-blocked launch can throw rather than no-op.
+            runCatching {
+                context.startActivity(
+                    Intent(context, SignerConsentActivity::class.java)
+                        .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP),
+                )
+            }
+            SignerConsentNotifier.show(
+                context = context,
+                activityClass = SignerConsentActivity::class.java,
+                extraKey = EXTRA_TOKEN,
+                token = "nip46-signer-consent",
+                titleRes = R.string.nip46_signer_notif_sign_title,
+            )
+        }
+
+        return try {
+            deferred.await()
+        } finally {
+            deferreds.remove(token)
+            surfaceLock.withLock {
+                // Remove + emptiness check + cancel are one critical section vs. another request's
+                // add + show, so a fresh notification is never cancelled out from under a live request.
+                val stillPending = _pending.updateAndGet { list -> list.filterNot { it.token == token } }
+                if (stillPending.isEmpty()) SignerConsentNotifier.cancel(context, batchNotificationId)
+            }
+        }
+    }
+
+    fun complete(
+        token: String,
+        grant: SignerOpGrant,
+    ) {
+        deferreds[token]?.complete(grant)
+    }
+
+    fun completeAll(
+        tokens: Collection<String>,
+        grant: SignerOpGrant,
+    ) {
+        tokens.forEach { complete(it, grant) }
+    }
+
+    const val EXTRA_TOKEN = "napplet_signer_consent_token"
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/consent/SignerConsentNotifier.kt

@@ -0,0 +1,141 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.consent
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import androidx.core.app.NotificationCompat
+import com.vitorpamplona.amethyst.Amethyst
+import com.vitorpamplona.amethyst.R
+import com.vitorpamplona.amethyst.ui.stringRes
+
+/**
+ * Surfaces a signer consent/connect [android.app.Activity] from the **background**.
+ *
+ * A bare `context.startActivity(...)` from the application context only opens a window while
+ * Amethyst already owns the foreground. When a signing request arrives over a relay while the app
+ * is backgrounded, Android 12+ background-activity-launch (BAL) restrictions silently drop that
+ * `startActivity`, so the dialog would never appear and the request would sit until it times out.
+ *
+ * A full-screen-intent notification on an `IMPORTANCE_HIGH` channel (with the
+ * `USE_FULL_SCREEN_INTENT` permission the manifest declares) is the documented BAL exception — the
+ * same mechanism [com.vitorpamplona.amethyst.service.call.notification.CallNotifier] uses for
+ * incoming calls. On a locked/idle screen it launches the Activity immediately; while the user is
+ * actively on another app it shows as a heads-up banner they tap to review.
+ *
+ * Each coordinator posts one notification keyed by the request token's hash so concurrent requests
+ * don't clobber each other, and cancels it once the deferred resolves (approved, denied, or timed
+ * out) so no stale prompt lingers.
+ */
+object SignerConsentNotifier {
+    private const val CHANNEL_ID = "com.vitorpamplona.amethyst.SIGNER_CONSENT_CHANNEL"
+
+    private fun ensureChannel(context: Context): NotificationChannel {
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        manager.getNotificationChannel(CHANNEL_ID)?.let { return it }
+
+        val channel =
+            NotificationChannel(
+                CHANNEL_ID,
+                stringRes(context, R.string.nip46_signer_notif_channel_name),
+                NotificationManager.IMPORTANCE_HIGH,
+            ).apply {
+                description = stringRes(context, R.string.nip46_signer_notif_channel_desc)
+            }
+        manager.createNotificationChannel(channel)
+        return channel
+    }
+
+    /**
+     * Posts a full-screen-intent notification whose content/full-screen [PendingIntent] opens
+     * [activityClass] carrying [token]. Returns the notification id to pass to [cancel] once the
+     * request resolves.
+     */
+    fun show(
+        context: Context,
+        activityClass: Class<*>,
+        extraKey: String,
+        token: String,
+        titleRes: Int,
+    ): Int {
+        // When Amethyst already owns the foreground the direct startActivity opens the dialog, so a
+        // heads-up notification would just be redundant noise on top of it. Only fall back to the
+        // full-screen intent when we're backgrounded — the case where startActivity is BAL-blocked.
+        if (appInForeground()) return NO_NOTIFICATION
+
+        val channel = ensureChannel(context)
+        val notificationId = token.hashCode()
+
+        val intent =
+            Intent(context, activityClass)
+                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+                .putExtra(extraKey, token)
+
+        val pendingIntent =
+            PendingIntent.getActivity(
+                context,
+                notificationId,
+                intent,
+                PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+            )
+
+        val notification =
+            NotificationCompat
+                .Builder(context, channel.id)
+                .setSmallIcon(R.drawable.amethyst)
+                .setContentTitle(stringRes(context, titleRes))
+                .setContentText(stringRes(context, R.string.nip46_signer_notif_tap))
+                .setContentIntent(pendingIntent)
+                .setFullScreenIntent(pendingIntent, true)
+                .setPriority(NotificationCompat.PRIORITY_HIGH)
+                .setCategory(NotificationCompat.CATEGORY_RECOMMENDATION)
+                .setAutoCancel(true)
+                .setOngoing(true)
+                .setTimeoutAfter(TIMEOUT_MS)
+                .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+                .build()
+
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        manager.notify(notificationId, notification)
+        return notificationId
+    }
+
+    fun cancel(
+        context: Context,
+        notificationId: Int,
+    ) {
+        if (notificationId == NO_NOTIFICATION) return
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        manager.cancel(notificationId)
+    }
+
+    private fun appInForeground(): Boolean =
+        // Defensive: the signer consent path only runs in the main process (where Amethyst.instance
+        // is set), but touching it from the keyless :napplet process would throw. Treat any failure
+        // as "not foreground" so the notification fallback still fires.
+        runCatching { Amethyst.instance.foregroundTracker.isForeground.value }.getOrDefault(false)
+
+    private const val NO_NOTIFICATION = Int.MIN_VALUE
+    private const val TIMEOUT_MS = 120_000L
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/connectedApps/nip46/DataStoreNip46ClientStore.kt

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.connectedApps.nip46
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.PreferenceDataStoreFactory
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import com.vitorpamplona.amethyst.commons.connectedApps.nip46.Nip46ClientInfo
+import com.vitorpamplona.amethyst.commons.connectedApps.nip46.Nip46ClientStore
+import kotlinx.coroutines.flow.first
+import java.io.File
+import java.security.MessageDigest
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Single-file DataStore-backed [Nip46ClientStore]. Every connected client's
+ * display + relay info lives in one `datastore/nip46_clients.preferences_pb`
+ * file; a SHA-256 prefix of the coordinate is the key so the (already public)
+ * coordinate is kept alongside for [all]'s reverse lookup. Fields are stored
+ * individually so no serialization library is needed; [relays] is newline-joined.
+ */
+class DataStoreNip46ClientStore(
+    private val filesDir: File,
+) : Nip46ClientStore {
+    constructor(context: Context) : this(context.applicationContext.filesDir)
+
+    private val store: DataStore<Preferences> get() = dataStoreFor(File(filesDir, "datastore/nip46_clients.preferences_pb"))
+
+    override suspend fun load(coordinate: String): Nip46ClientInfo? {
+        val prefs = store.data.first()
+        if (prefs[coordKey(coordinate)] == null) return null
+        return Nip46ClientInfo(
+            name = prefs[nameKey(coordinate)],
+            url = prefs[urlKey(coordinate)],
+            image = prefs[imageKey(coordinate)],
+            relays = prefs[relaysKey(coordinate)].toRelaySet(),
+        )
+    }
+
+    override suspend fun store(
+        coordinate: String,
+        info: Nip46ClientInfo,
+    ) {
+        store.edit { prefs ->
+            prefs[coordKey(coordinate)] = coordinate
+            info.name?.let { prefs[nameKey(coordinate)] = it } ?: prefs.remove(nameKey(coordinate))
+            info.url?.let { prefs[urlKey(coordinate)] = it } ?: prefs.remove(urlKey(coordinate))
+            info.image?.let { prefs[imageKey(coordinate)] = it } ?: prefs.remove(imageKey(coordinate))
+            if (info.relays.isNotEmpty()) prefs[relaysKey(coordinate)] = info.relays.joinToString("\n") else prefs.remove(relaysKey(coordinate))
+        }
+    }
+
+    override suspend fun remove(coordinate: String) {
+        store.edit { prefs ->
+            prefs.remove(coordKey(coordinate))
+            prefs.remove(nameKey(coordinate))
+            prefs.remove(urlKey(coordinate))
+            prefs.remove(imageKey(coordinate))
+            prefs.remove(relaysKey(coordinate))
+        }
+    }
+
+    override suspend fun all(): Map<String, Nip46ClientInfo> {
+        val prefs = store.data.first()
+        val result = mutableMapOf<String, Nip46ClientInfo>()
+        for ((key, value) in prefs.asMap()) {
+            if (!key.name.startsWith(COORD_PREFIX)) continue
+            val coordinate = value as? String ?: continue
+            result[coordinate] =
+                Nip46ClientInfo(
+                    name = prefs[nameKey(coordinate)],
+                    url = prefs[urlKey(coordinate)],
+                    image = prefs[imageKey(coordinate)],
+                    relays = prefs[relaysKey(coordinate)].toRelaySet(),
+                )
+        }
+        return result
+    }
+
+    private fun String?.toRelaySet(): Set<String> = this?.split("\n")?.filterTo(mutableSetOf()) { it.isNotEmpty() } ?: emptySet()
+
+    private fun coordKey(coordinate: String) = stringPreferencesKey("$COORD_PREFIX${hash(coordinate)}")
+
+    private fun nameKey(coordinate: String) = stringPreferencesKey("name:${hash(coordinate)}")
+
+    private fun urlKey(coordinate: String) = stringPreferencesKey("url:${hash(coordinate)}")
+
+    private fun imageKey(coordinate: String) = stringPreferencesKey("img:${hash(coordinate)}")
+
+    private fun relaysKey(coordinate: String) = stringPreferencesKey("relays:${hash(coordinate)}")
+
+    companion object {
+        private val stores = ConcurrentHashMap<String, DataStore<Preferences>>()
+
+        private fun dataStoreFor(file: File): DataStore<Preferences> =
+            stores.computeIfAbsent(file.absolutePath) {
+                PreferenceDataStoreFactory.create(produceFile = { file })
+            }
+
+        private const val COORD_PREFIX = "coord:"
+
+        private fun hash(coordinate: String): String {
+            val digest = MessageDigest.getInstance("SHA-256").digest(coordinate.toByteArray())
+            return digest.take(8).joinToString("") { "%02x".format(it) }
+        }
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/favorites/BrowserHistoryRegistry.kt

@@ -0,0 +1,154 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.favorites
+
+import android.content.Context
+import android.util.Log
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import com.vitorpamplona.amethyst.commons.browser.OmniboxInput
+import com.vitorpamplona.quartz.nip01Core.core.JsonMapper
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
+import kotlinx.serialization.Serializable
+
+private val Context.browserHistoryDataStore by preferencesDataStore(name = "browser_history")
+
+/**
+ * One device-local visited site, keyed by full [url]. [visitCount]/[lastVisitedAt] drive frecency ranking
+ * in the omnibox suggestions.
+ */
+@Serializable
+data class BrowserHistoryEntry(
+    val url: String,
+    val title: String,
+    val host: String,
+    val lastVisitedAt: Long,
+    val visitCount: Int,
+)
+
+/**
+ * The browser's visit history — the data behind the omnibox suggestions, alongside the user's favorites.
+ *
+ * **Only pages that actually loaded land here.** [record] is called from the `:napplet` browser host
+ * (relayed over IPC through `NappletBrokerService`) on a *successful* main-frame page-finish — never from
+ * the address bar as the user types — so misspelled/never-resolved hosts never pollute the list. Bounded
+ * to [MAX_ENTRIES] most-recent entries.
+ *
+ * Lives only in the **main process** (the launcher/omnibox consume it; the keyless `:napplet` sandbox
+ * never reads it). Same shape as [FavoriteAppsRegistry]: an authoritative in-memory [StateFlow] for
+ * synchronous Compose reads, with write-through persistence to a DataStore on a background scope.
+ */
+object BrowserHistoryRegistry {
+    private val KEY = stringPreferencesKey("history")
+    private const val MAX_ENTRIES = 500
+
+    private val _history = MutableStateFlow<List<BrowserHistoryEntry>>(emptyList())
+    val history: StateFlow<List<BrowserHistoryEntry>> = _history.asStateFlow()
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    @Volatile private var appContext: Context? = null
+
+    @Volatile private var hydrated = false
+
+    /** Binds the app context and hydrates the on-disk list into [history]. Idempotent. */
+    fun init(context: Context) {
+        if (appContext != null) return
+        val ctx = context.applicationContext
+        appContext = ctx
+        scope.launch {
+            val json = ctx.browserHistoryDataStore.data.first()[KEY]
+            val loaded = if (json != null) decode(json) else emptyList()
+            // Merge disk under anything already recorded this session (session wins, newest-first).
+            update { current -> dedupeNewestFirst(current + loaded) }
+            hydrated = true
+        }
+    }
+
+    /**
+     * Records a successful visit to [url], moving it to the front. An existing entry for the same URL is
+     * bumped (visit count +1, title refreshed if non-blank); otherwise a new entry is prepended.
+     */
+    fun record(
+        url: String,
+        title: String,
+    ) {
+        val host = OmniboxInput.hostOf(url) ?: url
+        val now = System.currentTimeMillis()
+        update { current ->
+            val existing = current.firstOrNull { it.url == url }
+            val entry =
+                if (existing != null) {
+                    existing.copy(
+                        title = title.ifBlank { existing.title },
+                        host = host,
+                        lastVisitedAt = now,
+                        visitCount = existing.visitCount + 1,
+                    )
+                } else {
+                    BrowserHistoryEntry(url = url, title = title, host = host, lastVisitedAt = now, visitCount = 1)
+                }
+            (listOf(entry) + current.filterNot { it.url == url }).take(MAX_ENTRIES)
+        }
+    }
+
+    fun remove(url: String) = update { current -> current.filterNot { it.url == url } }
+
+    fun clear() = update { emptyList() }
+
+    private fun dedupeNewestFirst(list: List<BrowserHistoryEntry>): List<BrowserHistoryEntry> =
+        list
+            .sortedByDescending { it.lastVisitedAt }
+            .distinctBy { it.url }
+            .take(MAX_ENTRIES)
+
+    private inline fun update(transform: (List<BrowserHistoryEntry>) -> List<BrowserHistoryEntry>) {
+        val next = transform(_history.value)
+        if (next == _history.value) return
+        _history.value = next
+        persist(encode(next))
+    }
+
+    private fun persist(json: String) {
+        val ctx = appContext ?: return
+        scope.launch {
+            ctx.browserHistoryDataStore.edit { it[KEY] = json }
+        }
+    }
+
+    private fun encode(list: List<BrowserHistoryEntry>): String = JsonMapper.toJson(list)
+
+    private fun decode(json: String): List<BrowserHistoryEntry> =
+        try {
+            JsonMapper.fromJson<List<BrowserHistoryEntry>>(json)
+        } catch (e: Exception) {
+            Log.w("BrowserHistoryRegistry", "Failed to decode history", e)
+            emptyList()
+        }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/favorites/BrowserIconRegistry.kt

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.favorites
+
+import android.content.Context
+import android.util.Log
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+import java.io.File
+
+/**
+ * Device-local favicon store for browsed sites, keyed by host. Favicons are **captured from the WebView
+ * that already loaded the page** in the keyless `:napplet` browser host (where they ride the page's own —
+ * Tor-routed — network path) and relayed here as PNG bytes over IPC; this is the privacy-preserving
+ * alternative to the main app fetching `host/favicon.ico` itself, which would bypass Tor and leak the
+ * visit. Used to decorate favorite cards and omnibox suggestion rows.
+ *
+ * Lives only in the **main process**. Bytes are persisted as one small PNG per host under
+ * `filesDir/browser_icons`; the deterministic path means the only in-memory state is [keys] — the set of
+ * hosts that currently have an icon — which exists purely to drive Compose recomposition (and to keep
+ * `File.exists()` disk checks out of composition).
+ */
+object BrowserIconRegistry {
+    private const val DIR = "browser_icons"
+
+    private val _keys = MutableStateFlow<Set<String>>(emptySet())
+
+    /** Sanitized host keys that currently have a stored icon. Observe to recompose when an icon arrives. */
+    val keys: StateFlow<Set<String>> = _keys.asStateFlow()
+
+    @Volatile private var iconDir: File? = null
+
+    // Disk work runs here, never on the caller's thread. Both entry points are reached from threads
+    // that must not block: init() from app startup and record() from the broker's IPC handler, which
+    // is the main looper — StrictMode flagged the write, and a slow filesystem would have stalled the
+    // UI while a favicon was saved.
+    private val io = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    /**
+     * Binds the app context and indexes already-stored icons. Idempotent.
+     *
+     * [iconDir] is published synchronously so [iconModelFor] and [record] work immediately; only the
+     * directory scan is deferred. Until it lands [keys] is empty, so an icon simply renders its
+     * placeholder for one frame and then recomposes — [keys] is a StateFlow precisely so that arrival
+     * drives recomposition.
+     */
+    fun init(context: Context) {
+        if (iconDir != null) return
+        val dir = File(context.applicationContext.filesDir, DIR)
+        iconDir = dir
+        io.launch {
+            dir.mkdirs()
+            _keys.value = dir.listFiles()?.mapNotNull { it.name.removeSuffix(PNG).takeIf { n -> n.isNotBlank() } }?.toSet() ?: emptySet()
+        }
+    }
+
+    /** Persists [bytes] as the favicon for [host] and marks it available. Called from the broker on IPC. */
+    fun record(
+        host: String,
+        bytes: ByteArray,
+    ) {
+        val dir = iconDir ?: return
+        if (host.isBlank() || bytes.isEmpty()) return
+        val key = sanitize(host)
+        // Fire-and-forget: a favicon is a decoration, and the IPC handler must not wait on disk.
+        // [keys] updates only after the bytes are actually on disk, so a reader can never be told an
+        // icon exists before the file backing it does.
+        io.launch {
+            try {
+                dir.mkdirs()
+                File(dir, key + PNG).writeBytes(bytes)
+                _keys.update { it + key }
+            } catch (e: Exception) {
+                Log.w("BrowserIconRegistry", "Failed to store favicon for $host", e)
+            }
+        }
+    }
+
+    /**
+     * A Coil model (`file://…`) for [host]'s favicon, or null when none is stored. Reads [keys] so callers
+     * that observe the flow recompose as icons arrive — pass [keys]'s value as a `remember` key.
+     */
+    fun iconModelFor(host: String): String? {
+        val dir = iconDir ?: return null
+        val key = sanitize(host)
+        if (key !in _keys.value) return null
+        return "file://" + File(dir, key + PNG).absolutePath
+    }
+
+    // Hosts map to a flat, filesystem-safe filename. Collisions (two hosts → one key) only mean a shared
+    // icon file, which is harmless for a decoration.
+    private fun sanitize(host: String): String =
+        host
+            .lowercase()
+            .map { if (it.isLetterOrDigit() || it == '.' || it == '-') it else '_' }
+            .joinToString("")
+            .take(120)
+
+    private const val PNG = ".png"
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/favorites/FavoriteAppLauncher.kt

@@ -0,0 +1,231 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.favorites
+
+import android.app.Activity
+import android.content.Context
+import android.content.res.Configuration
+import android.os.Bundle
+import android.util.Log
+import android.widget.Toast
+import com.vitorpamplona.amethyst.Amethyst
+import com.vitorpamplona.amethyst.R
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteApp
+import com.vitorpamplona.amethyst.model.LocalCache
+import com.vitorpamplona.amethyst.model.ThemeType
+import com.vitorpamplona.amethyst.napplet.NappletLauncher
+import com.vitorpamplona.amethyst.napplet.NappletWebViewProfiles
+import com.vitorpamplona.amethyst.napplet.WebAppNetworkRegistry
+import com.vitorpamplona.amethyst.napplethost.HostProfile
+import com.vitorpamplona.amethyst.napplethost.NappletBrowserActivity
+import com.vitorpamplona.quartz.nip01Core.core.Event
+import com.vitorpamplona.quartz.nip5aStaticWebsites.NamedSiteEvent
+import com.vitorpamplona.quartz.nip5aStaticWebsites.RootSiteEvent
+import com.vitorpamplona.quartz.nip5dNapplets.NamedNappletEvent
+import com.vitorpamplona.quartz.nip5dNapplets.RootNappletEvent
+
+/**
+ * Turns a [FavoriteApp] back into a running app. The two cases map to the two launch paths in the
+ * codebase, nothing more:
+ *
+ * - [FavoriteApp.WebApp] → a full-screen direct-WebView
+ *   [NappletBrowserActivity][com.vitorpamplona.amethyst.napplethost.NappletBrowserActivity] (its own
+ *   task/recents entry), so the web client owns the whole screen and scrolls/zooms natively.
+ * - [FavoriteApp.NostrApp] → re-resolve the live event from [LocalCache] by coordinate, read its
+ *   `requires`/website-mode off the event, then hand to [NappletLauncher] (the sandboxed `:napplet`
+ *   host). nsite vs napplet is decided *here*, from the event, never from stored state.
+ *
+ * A [FavoriteApp.NostrApp] whose event hasn't loaded yet can't launch; we surface that instead of
+ * failing silently.
+ */
+object FavoriteAppLauncher {
+    fun launch(
+        context: Context,
+        app: FavoriteApp,
+    ) {
+        when (app) {
+            is FavoriteApp.WebApp -> launchUrl(context, app.url)
+            is FavoriteApp.NostrApp -> launchNostrApp(context, app.coordinate)
+        }
+    }
+
+    /**
+     * Opens [url] full-screen in its own task, so back/recents treat it like a separate app. Uses the
+     * direct-WebView [NappletBrowserActivity] (page scrolls/zooms and the keyboard resizes natively),
+     * resolving the proxy port + this site's remembered Tor choice here in the main process. [preferTor]
+     * forces Tor (when available) regardless of the remembered choice — used for `.onion`, which only
+     * resolves over Tor.
+     */
+    fun launchUrl(
+        context: Context,
+        url: String,
+        preferTor: Boolean = false,
+    ) {
+        val proxyPort = Amethyst.instance.torManager.activePortOrNull.value ?: -1
+        val useTor = proxyPort > 0 && (preferTor || WebAppNetworkRegistry.useTor(url))
+        val themeType = Amethyst.instance.uiPrefs.value.theme.value
+        val theme =
+            when (themeType) {
+                ThemeType.DARK -> "DARK"
+                ThemeType.LIGHT -> "LIGHT"
+                ThemeType.SYSTEM -> {
+                    val nightMask = context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+                    if (nightMask == Configuration.UI_MODE_NIGHT_YES) "DARK" else "LIGHT"
+                }
+            }
+        val isFavorite = FavoriteAppsRegistry.isFavorite("url:$url")
+        val intent =
+            NappletBrowserActivity
+                .intent(
+                    context,
+                    url,
+                    proxyPort,
+                    useTor,
+                    theme = theme,
+                    isFavorite = isFavorite,
+                    // Opaque per-account storage partition, so a web app can't carry one npub's session
+                    // into another. Derived here (the sandbox never sees the pubkey).
+                    webViewProfile = NappletWebViewProfiles.current(),
+                ).apply {
+                    if (context !is Activity) addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK)
+                }
+        context.startActivity(intent)
+    }
+
+    private fun launchNostrApp(
+        context: Context,
+        coordinate: String,
+    ) {
+        val event = LocalCache.getAddressableNoteIfExists(coordinate)?.event
+        when (event) {
+            is RootNappletEvent ->
+                NappletLauncher.launch(context, event, event.pubKey, "")
+            is NamedNappletEvent ->
+                NappletLauncher.launch(context, event, event.pubKey, event.identifier())
+            is RootSiteEvent ->
+                NappletLauncher.launch(
+                    context = context,
+                    paths = event.paths(),
+                    servers = event.servers(),
+                    authorPubKey = event.pubKey,
+                    identifier = "",
+                    aggregateHash = null,
+                    title = event.title() ?: "nsite",
+                    requires = emptyList(),
+                    profile = HostProfile.WEBSITE,
+                )
+            is NamedSiteEvent ->
+                NappletLauncher.launch(
+                    context = context,
+                    paths = event.paths(),
+                    servers = event.servers(),
+                    authorPubKey = event.pubKey,
+                    identifier = event.identifier(),
+                    aggregateHash = null,
+                    title = event.title() ?: event.identifier(),
+                    requires = emptyList(),
+                    profile = HostProfile.WEBSITE,
+                )
+            else -> {
+                Log.w("FavoriteAppLauncher", "Favorited app not resolvable yet: $coordinate")
+                Toast.makeText(context, R.string.favorite_app_still_loading, Toast.LENGTH_SHORT).show()
+            }
+        }
+    }
+
+    /**
+     * Builds the main-process-minted launch parameters for embedding the nsite/napplet at [coordinate]
+     * as an in-app tab (see `NappletHostService`). Returns null when the event isn't resolvable in
+     * [LocalCache] yet — the caller shows a loading state. nsite vs napplet (and website mode) is decided
+     * here from the live event, exactly as in [launchNostrApp].
+     */
+    fun embedParams(
+        context: Context,
+        coordinate: String,
+    ): Bundle? {
+        val event = LocalCache.getAddressableNoteIfExists(coordinate)?.event
+        return when (event) {
+            is RootNappletEvent ->
+                NappletLauncher.buildLaunchParams(
+                    context,
+                    event.paths(),
+                    event.servers(),
+                    event.pubKey,
+                    "",
+                    event.declaredAggregateHash() ?: event.computeAggregateHash(),
+                    event.title() ?: "Napplet",
+                    event.requires(),
+                    HostProfile.NAPPLET,
+                )
+            is NamedNappletEvent ->
+                NappletLauncher.buildLaunchParams(
+                    context,
+                    event.paths(),
+                    event.servers(),
+                    event.pubKey,
+                    event.identifier(),
+                    event.declaredAggregateHash() ?: event.computeAggregateHash(),
+                    event.title() ?: event.identifier(),
+                    event.requires(),
+                    HostProfile.NAPPLET,
+                )
+            is RootSiteEvent ->
+                NappletLauncher.buildLaunchParams(
+                    context,
+                    event.paths(),
+                    event.servers(),
+                    event.pubKey,
+                    "",
+                    null,
+                    event.title() ?: "nsite",
+                    emptyList(),
+                    HostProfile.WEBSITE,
+                )
+            is NamedSiteEvent ->
+                NappletLauncher.buildLaunchParams(
+                    context,
+                    event.paths(),
+                    event.servers(),
+                    event.pubKey,
+                    event.identifier(),
+                    null,
+                    event.title() ?: event.identifier(),
+                    emptyList(),
+                    HostProfile.WEBSITE,
+                )
+            else -> null
+        }
+    }
+
+    /**
+     * The addressable coordinate `kind:pubkey:dtag` used to key an nsite/napplet favorite. Stored
+     * instead of the content hash so the favorite survives routine code/manifest updates.
+     */
+    fun coordinateOf(event: Event): String {
+        val dTag =
+            when (event) {
+                is NamedNappletEvent -> event.identifier()
+                is NamedSiteEvent -> event.identifier()
+                else -> ""
+            }
+        return "${event.kind}:${event.pubKey}:$dTag"
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/favorites/FavoriteAppsRegistry.kt

@@ -0,0 +1,214 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.favorites
+
+import android.content.Context
+import android.util.Log
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteApp
+import com.vitorpamplona.quartz.nip01Core.core.JsonMapper
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
+import kotlinx.serialization.Serializable
+import java.util.concurrent.ConcurrentHashMap
+
+private val Context.favoriteAppsDataStore by preferencesDataStore(name = "favorite_apps")
+
+/**
+ * The user's device-local list of [FavoriteApp]s — the single source of truth shared by the bottom
+ * bar, the Favorite Apps grid, and the browser launcher. Ordered (the user can reorder); de-duplicated
+ * by [FavoriteApp.id].
+ *
+ * Lives only in the **main process** (the launcher/UI consume it); the keyless `:napplet` sandbox never
+ * touches it. An in-memory [StateFlow] is authoritative for the session so Compose can observe it
+ * synchronously, with write-through persistence to a DataStore on a background scope. The list is
+ * stored as a single JSON array under one key (small, bounded, hand-curated data — no need for one key
+ * per entry).
+ */
+object FavoriteAppsRegistry {
+    private val KEY = stringPreferencesKey("favorites")
+
+    // Raw manifest event JSON for each favorited [FavoriteApp.NostrApp], keyed by its addressable
+    // coordinate. Cached so a pinned nsite/napplet resolves instantly on the next cold start — and
+    // offline — instead of waiting on a relay round-trip the way a [FavoriteApp.WebApp]'s URL never
+    // has to. The relay subscription that warms these favorites keeps the cache fresh.
+    private val MANIFESTS_KEY = stringPreferencesKey("manifests")
+
+    private val _favorites = MutableStateFlow<List<FavoriteApp>>(emptyList())
+    val favorites: StateFlow<List<FavoriteApp>> = _favorites.asStateFlow()
+
+    private val manifestCache = MutableStateFlow<Map<String, String>>(emptyMap())
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    @Volatile private var appContext: Context? = null
+
+    // Hydration runs async on a background scope, so the user can add/remove before the disk list
+    // merges in. [removedBeforeHydration] tombstones any id removed in that window, so the merge can't
+    // resurrect a just-deleted favorite from disk.
+    @Volatile private var hydrated = false
+    private val removedBeforeHydration = ConcurrentHashMap.newKeySet<String>()
+
+    /** Binds the app context and hydrates the on-disk list into [favorites]. Idempotent. */
+    fun init(context: Context) {
+        if (appContext != null) return
+        val ctx = context.applicationContext
+        appContext = ctx
+        scope.launch {
+            val prefs = ctx.favoriteAppsDataStore.data.first()
+            val loaded = prefs[KEY]?.let { decode(it) } ?: emptyList()
+            // Don't clobber adds made in this session before hydration finished, and don't resurrect
+            // anything the user removed in that same window.
+            update { current -> (loaded.filterNot { it.id in removedBeforeHydration } + current).distinctBy { it.id } }
+
+            // Same race rules for the manifest cache: a cacheManifest() in this session wins over the
+            // disk copy, and a manifest whose favorite was removed pre-hydration must not come back.
+            val loadedManifests = prefs[MANIFESTS_KEY]?.let { decodeManifests(it) } ?: emptyMap()
+            updateManifests { current -> loadedManifests.filterKeys { "nostr:$it" !in removedBeforeHydration } + current }
+
+            hydrated = true
+            removedBeforeHydration.clear()
+        }
+    }
+
+    fun isFavorite(id: String): Boolean = _favorites.value.any { it.id == id }
+
+    /** Adds [app] to the end if not already present (by [FavoriteApp.id]). */
+    fun add(app: FavoriteApp) = update { current -> if (current.any { it.id == app.id }) current else current + app }
+
+    fun remove(id: String) {
+        if (!hydrated) removedBeforeHydration.add(id)
+        update { current -> current.filterNot { it.id == id } }
+        // Drop the cached manifest too — favorite ids for nsites/napplets are "nostr:<coordinate>".
+        if (id.startsWith("nostr:")) updateManifests { it - id.removePrefix("nostr:") }
+    }
+
+    /** The cached manifest event JSON for a favorited nsite/napplet [coordinate], or null if none. */
+    fun cachedManifest(coordinate: String): String? = manifestCache.value[coordinate]
+
+    /**
+     * Caches the raw manifest event [eventJson] for a favorited nsite/napplet [coordinate] so the next
+     * launch can resolve it instantly / offline. Write-through; no-ops when the JSON is unchanged.
+     */
+    fun cacheManifest(
+        coordinate: String,
+        eventJson: String,
+    ) = updateManifests { if (it[coordinate] == eventJson) it else it + (coordinate to eventJson) }
+
+    /** Replaces the whole list, e.g. after a drag-reorder. */
+    fun setOrder(newOrder: List<FavoriteApp>) = update { newOrder }
+
+    private inline fun update(transform: (List<FavoriteApp>) -> List<FavoriteApp>) {
+        val next = transform(_favorites.value)
+        if (next == _favorites.value) return
+        _favorites.value = next
+        persist(encode(next))
+    }
+
+    private inline fun updateManifests(transform: (Map<String, String>) -> Map<String, String>) {
+        val next = transform(manifestCache.value)
+        if (next == manifestCache.value) return
+        manifestCache.value = next
+        persistManifests(encodeManifests(next))
+    }
+
+    private fun persist(json: String) {
+        val ctx = appContext ?: return
+        scope.launch {
+            ctx.favoriteAppsDataStore.edit { it[KEY] = json }
+        }
+    }
+
+    private fun persistManifests(json: String) {
+        val ctx = appContext ?: return
+        scope.launch {
+            ctx.favoriteAppsDataStore.edit { it[MANIFESTS_KEY] = json }
+        }
+    }
+
+    // --- Persistence DTO ------------------------------------------------------------------------
+    // A flat, type-tagged record so we serialize one concrete shape instead of relying on
+    // polymorphic (sealed) (de)serialization. Mapping to/from the sealed model lives here.
+
+    @Serializable
+    private data class Entry(
+        val type: String,
+        val ref: String,
+        val label: String,
+        val addedAt: Long,
+        val iconUrl: String? = null,
+    )
+
+    private fun encode(list: List<FavoriteApp>): String =
+        JsonMapper.toJson(
+            list.map {
+                when (it) {
+                    is FavoriteApp.NostrApp -> Entry(TYPE_NOSTR, it.coordinate, it.label, it.addedAt, it.iconUrl)
+                    is FavoriteApp.WebApp -> Entry(TYPE_URL, it.url, it.label, it.addedAt, it.iconUrl)
+                }
+            },
+        )
+
+    private fun decode(json: String): List<FavoriteApp> =
+        try {
+            JsonMapper.fromJson<List<Entry>>(json).mapNotNull { entry ->
+                when (entry.type) {
+                    TYPE_NOSTR -> FavoriteApp.NostrApp(entry.ref, entry.label, entry.addedAt, entry.iconUrl)
+                    TYPE_URL -> FavoriteApp.WebApp(entry.ref, entry.label, entry.addedAt, entry.iconUrl)
+                    else -> null
+                }
+            }
+        } catch (e: Exception) {
+            Log.w("FavoriteAppsRegistry", "Failed to decode favorites", e)
+            emptyList()
+        }
+
+    private const val TYPE_NOSTR = "nostr"
+    private const val TYPE_URL = "url"
+
+    // --- Manifest cache persistence -------------------------------------------------------------
+    // Stored as a flat list of (coordinate, json) records under one key — same single-key, hand-curated
+    // shape as the favorites list, so we never serialize a raw polymorphic map.
+
+    @Serializable
+    private data class ManifestEntry(
+        val coordinate: String,
+        val json: String,
+    )
+
+    private fun encodeManifests(manifests: Map<String, String>): String = JsonMapper.toJson(manifests.map { ManifestEntry(it.key, it.value) })
+
+    private fun decodeManifests(json: String): Map<String, String> =
+        try {
+            JsonMapper.fromJson<List<ManifestEntry>>(json).associate { it.coordinate to it.json }
+        } catch (e: Exception) {
+            Log.w("FavoriteAppsRegistry", "Failed to decode favorite manifests", e)
+            emptyMap()
+        }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/favorites/FavoriteNostrAppPreloader.kt

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.favorites
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import com.vitorpamplona.amethyst.commons.favorites.FavoriteApp
+import com.vitorpamplona.amethyst.commons.relayClient.subscriptions.LifecycleAwareKeyDataSourceSubscription
+import com.vitorpamplona.amethyst.model.LocalCache
+import com.vitorpamplona.amethyst.service.relayClient.reqCommand.event.EventFinderQueryState
+import com.vitorpamplona.amethyst.ui.screen.loggedIn.AccountViewModel
+
+/**
+ * Pre-fetches the addressable events behind the user's favorited [FavoriteApp.NostrApp]s (nSites /
+ * nApplets) while a screen that can launch them is on screen.
+ *
+ * A favorite stores only the addressable coordinate `kind:pubkey:dtag`, never the event. The launch
+ * path ([FavoriteAppLauncher.launchNostrApp] / [FavoriteAppLauncher.embedParams]) re-resolves the live
+ * event from [LocalCache] at tap time, so a favorite whose event hasn't streamed in yet can't launch —
+ * the user gets the "isn't loaded yet" toast / unavailable tab. Before this preloader, the only thing
+ * that pulled those events into the cache was visiting the nsite/napplet feed (it subscribes by author),
+ * which is why opening that feed and coming back made a favorite suddenly launchable.
+ *
+ * This subscribes each favorited coordinate to the shared
+ * [EventFinder][com.vitorpamplona.amethyst.service.relayClient.reqCommand.event.EventFinderFilterAssembler]
+ * — the same lifecycle-aware loader [observeNote][com.vitorpamplona.amethyst.service.relayClient.reqCommand.event.observeNote]
+ * uses — so the manifests fetch (via the author's outbox relays) as soon as the launcher opens and are
+ * already in [LocalCache] by the time the user taps. The loader drops each coordinate from its filter
+ * once the event arrives, so this is a one-shot fetch, not a standing feed.
+ */
+@Composable
+fun PreloadFavoriteNostrApps(
+    apps: List<FavoriteApp>,
+    accountViewModel: AccountViewModel,
+) {
+    val account = accountViewModel.account
+    // Reuse the same query-state instances across recompositions (the manager ref-counts by identity),
+    // recomputing only when the favorite list or account changes. Events that already loaded are still
+    // included; the loader simply skips them because their note already has an event.
+    val states =
+        remember(apps, account) {
+            apps
+                .filterIsInstance<FavoriteApp.NostrApp>()
+                .mapNotNull { LocalCache.checkGetOrCreateAddressableNote(it.coordinate) }
+                .map { EventFinderQueryState(it, account) }
+        }
+
+    LifecycleAwareKeyDataSourceSubscription(states, accountViewModel.dataSources().eventFinder)
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/favorites/NappletFavoriteIcon.kt

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.favorites
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.platform.LocalContext
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.vitorpamplona.amethyst.Amethyst
+import com.vitorpamplona.amethyst.commons.browser.OmniboxInput
+import com.vitorpamplona.amethyst.model.LocalCache
+import com.vitorpamplona.amethyst.napplethost.NappletBlobCache
+import com.vitorpamplona.amethyst.napplethost.NappletBlobPrefetcher
+import com.vitorpamplona.quartz.nip01Core.core.Event
+import com.vitorpamplona.quartz.nip5aStaticWebsites.NamedSiteEvent
+import com.vitorpamplona.quartz.nip5aStaticWebsites.RootSiteEvent
+import com.vitorpamplona.quartz.nip5aStaticWebsites.tags.PathTag
+import com.vitorpamplona.quartz.nip5dNapplets.NamedNappletEvent
+import com.vitorpamplona.quartz.nip5dNapplets.RootNappletEvent
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.io.File
+
+/** The chosen icon blob and the servers that hold it — resolved from the live manifest. */
+private class IconBlob(
+    val path: PathTag,
+    val servers: List<String>,
+)
+
+/**
+ * A Coil model (`file://…`) for the app icon an nsite/napplet bundles in its own content — the verified,
+ * content-addressed blob the [NappletIconPath][com.vitorpamplona.quartz.nip5aStaticWebsites.NappletIconPath]
+ * heuristic picks from the manifest's `path` tags — or null when the manifest declares no such icon (or it
+ * hasn't downloaded yet). Used to decorate an nsite/napplet favorite the same way a captured favicon
+ * decorates a web favorite, except this rides the same Tor-routed, sha256-verified blob path as the rest of
+ * the site instead of a clearnet favicon fetch.
+ *
+ * Unlike a webapp's favicon, this can't be captured live: the applet runs in a cross-origin sandboxed
+ * iframe under the trusted shell, so `WebChromeClient.onReceivedIcon` only ever reports the shell's icon,
+ * never the applet's. Deriving it from the bundled blobs is the only path that sees the real icon.
+ *
+ * Observes the addressable note, so the icon resolves whenever the manifest arrives or updates in
+ * LocalCache — not only if it already happened to be cached at first composition (on a cold start the
+ * event streams in from relays a moment later). Returns null until the blob is on disk; the icon then
+ * appears on the next recomposition. All disk + network work runs off the composition thread. The blob is
+ * usually already cached (the browse/feed card prefetches every manifest blob, this one included); the
+ * on-demand fetch here just covers favorites whose card isn't currently on screen.
+ */
+@Composable
+fun rememberNappletIconModel(coordinate: String): String? {
+    val context = LocalContext.current
+
+    // checkGetOrCreate returns null only for a malformed coordinate, so this early return is stable for a
+    // given coordinate (it never flips across recompositions, which would break composition structure).
+    val note = remember(coordinate) { LocalCache.checkGetOrCreateAddressableNote(coordinate) } ?: return null
+    val noteState by note
+        .flow()
+        .metadata.stateFlow
+        .collectAsStateWithLifecycle()
+
+    // Key on the event itself, not the NoteState wrapper: re-resolve only when the manifest actually
+    // changes, not on every unrelated metadata bump (a reaction/zap tracked on the note).
+    val event = noteState.note.event
+    val icon = remember(event) { resolveIconBlob(event) } ?: return null
+
+    var model by remember(icon.path.hash) { mutableStateOf<String?>(null) }
+    LaunchedEffect(icon.path.hash) {
+        withContext(Dispatchers.IO) {
+            val file = File(NappletBlobCache.dirFor(context.cacheDir), icon.path.hash.lowercase())
+            if (!file.isFile) {
+                val torPort = Amethyst.instance.torManager.activePortOrNull.value ?: -1
+                runCatching { NappletBlobPrefetcher.prefetch(listOf(icon.path), icon.servers, context.cacheDir, torPort) }
+            }
+            if (file.isFile) model = "file://" + file.absolutePath
+        }
+    }
+    return model
+}
+
+/** Asks each nsite/napplet event type for its bundled icon blob + the servers that hold it. */
+private fun resolveIconBlob(event: Event?): IconBlob? =
+    when (event) {
+        is RootNappletEvent -> event.iconBlob()?.let { IconBlob(it, event.servers()) }
+        is NamedNappletEvent -> event.iconBlob()?.let { IconBlob(it, event.servers()) }
+        is RootSiteEvent -> event.iconBlob()?.let { IconBlob(it, event.servers()) }
+        is NamedSiteEvent -> event.iconBlob()?.let { IconBlob(it, event.servers()) }
+        else -> null
+    }
+
+/**
+ * A Coil model (`file://…`) for the cached favicon of [url]'s host, or null when no favicon
+ * has been captured yet. The favicon is stored by [BrowserIconRegistry] at browse time (the
+ * WebView captures it in the sandboxed `:napplet` process); this composable just reads the cache.
+ *
+ * Early-returns null when [url] is blank or has no parseable host — this early return is stable
+ * for a given [url] (the host either always parses or never does), so composition structure is
+ * preserved across recompositions.
+ */
+@Composable
+fun rememberWebAppIconModel(url: String): String? {
+    val host = remember(url) { OmniboxInput.hostOf(url) } ?: return null
+    val iconKeys by BrowserIconRegistry.keys.collectAsStateWithLifecycle()
+    return remember(host, iconKeys) { BrowserIconRegistry.iconModelFor(host) }
+}
+
+/**
+ * A Coil model for the bundled icon of an napplet or nsite identified by [author] and
+ * [identifier]. Tries the napplet manifest (kinds 15129 / 35129) first, then falls back to the
+ * nsite manifest (kinds 15128 / 35128). Returns null until the blob lands on disk.
+ */
+@Composable
+fun rememberManifestIconModel(
+    author: String,
+    identifier: String,
+): String? {
+    val nappletCoord =
+        remember(author, identifier) {
+            if (identifier.isEmpty()) "${RootNappletEvent.KIND}:$author:" else "${NamedNappletEvent.KIND}:$author:$identifier"
+        }
+    val nsiteCoord =
+        remember(author, identifier) {
+            if (identifier.isEmpty()) "${RootSiteEvent.KIND}:$author:" else "${NamedSiteEvent.KIND}:$author:$identifier"
+        }
+    return rememberNappletIconModel(nappletCoord) ?: rememberNappletIconModel(nsiteCoord)
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSettings.kt

@@ -22,16 +22,24 @@ package com.vitorpamplona.amethyst.model
 
 import androidx.compose.runtime.Stable
 import com.vitorpamplona.amethyst.commons.audio.VisualizerStyle
+import com.vitorpamplona.amethyst.commons.model.chats.ChatFeedType
 import com.vitorpamplona.amethyst.commons.model.clink.ClinkDebitWalletEntryNorm
+import com.vitorpamplona.amethyst.commons.model.concord.ConcordListRepository
+import com.vitorpamplona.amethyst.commons.model.concord.ConcordViewMode
 import com.vitorpamplona.amethyst.commons.model.emphChat.EphemeralChatRepository
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatListRepository
+import com.vitorpamplona.amethyst.commons.model.nip29RelayGroups.RelayGroupRepository
+import com.vitorpamplona.amethyst.commons.model.nip29RelayGroups.RelayGroupViewMode
 import com.vitorpamplona.amethyst.commons.model.nip47WalletConnect.NwcWalletEntryNorm
 import com.vitorpamplona.amethyst.commons.model.payments.PaymentSource
 import com.vitorpamplona.amethyst.commons.model.payments.PaymentSourceResolver
+import com.vitorpamplona.amethyst.commons.relayauth.RelayAuthPolicy
+import com.vitorpamplona.amethyst.commons.service.pow.PoWCategory
 import com.vitorpamplona.amethyst.model.nip60Cashu.CashuPreferences
 import com.vitorpamplona.amethyst.ui.actions.mediaServers.DEFAULT_MEDIA_SERVERS
 import com.vitorpamplona.amethyst.ui.actions.mediaServers.ServerName
 import com.vitorpamplona.amethyst.ui.screen.FeedDefinition
+import com.vitorpamplona.quartz.concord.cord02Community.ConcordCommunityListEvent
 import com.vitorpamplona.quartz.experimental.ephemChat.list.EphemeralChatListEvent
 import com.vitorpamplona.quartz.experimental.nipA3.PaymentTargetsEvent
 import com.vitorpamplona.quartz.marmot.mip00KeyPackages.KeyPackageRelayListEvent
@@ -57,6 +65,7 @@ import com.vitorpamplona.quartz.nip51Lists.relayLists.BlockedRelayListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.IndexerRelayListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.RelayFeedsListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.TrustedRelayListEvent
+import com.vitorpamplona.quartz.nip51Lists.simpleGroupList.SimpleGroupListEvent
 import com.vitorpamplona.quartz.nip55AndroidSigner.api.CommandType
 import com.vitorpamplona.quartz.nip55AndroidSigner.api.permission.Permission
 import com.vitorpamplona.quartz.nip57Zaps.LnZapEvent
@@ -118,6 +127,14 @@ sealed class TopFilter(
     @Serializable
     object AroundMe : TopFilter(" Around Me ")
 
+    /**
+     * Not a real selection: a sentinel for the "Teleport" chip in the top-nav filter.
+     * The spinner intercepts it to open the map picker and then applies the chosen
+     * [Geohash] instead — it is never persisted or dispatched to a feed flow.
+     */
+    @Serializable
+    object TeleportPicker : TopFilter(" Teleport ")
+
     @Serializable
     object Mine : TopFilter(" Mine ")
 
@@ -177,6 +194,45 @@ class AccountSettings(
     var stripLocationOnUpload: Boolean = true,
     val useLocalBlossomCache: MutableStateFlow<Boolean> = MutableStateFlow(true),
     val localBlossomCacheProfilePicturesOnly: MutableStateFlow<Boolean> = MutableStateFlow(false),
+    /**
+     * BUD-04: after uploading a blob to the primary Blossom server, replicate it to
+     * the user's other configured servers (kind 10063) for redundancy.
+     */
+    val mirrorUploadsToAllServers: MutableStateFlow<Boolean> = MutableStateFlow(true),
+    /**
+     * BUD-05: upload media through the server's `/media` endpoint so the server may
+     * strip metadata and optimize it, instead of the bit-exact `/upload`.
+     */
+    val optimizeMediaOnUpload: MutableStateFlow<Boolean> = MutableStateFlow(false),
+    /**
+     * NIP-46: when true, this account acts as a remote signer (a "bunker") for
+     * other apps, listening on the user's inbox relays for kind:24133 requests.
+     * See [com.vitorpamplona.amethyst.model.nip46Signer.Nip46SignerState].
+     */
+    val nip46SignerEnabled: MutableStateFlow<Boolean> = MutableStateFlow(false),
+    /**
+     * The active pairing secret advertised in this account's `bunker://` URI. An
+     * app that connects with this secret is accepted and registered as a
+     * connected app; regenerating it revokes the ability of not-yet-connected
+     * apps to pair with an old string.
+     */
+    val nip46BunkerSecret: MutableStateFlow<String> = MutableStateFlow(""),
+    /**
+     * A dedicated per-account transport keypair (hex private key) for the NIP-46
+     * bunker. The kind-24133 envelope is wrapped with THIS key, not the account's
+     * identity key, so the bunker address and on-relay traffic don't reveal which
+     * user the bunker belongs to (the identity is disclosed only to a connected
+     * app via `get_public_key`). Generated once and kept stable so the advertised
+     * `bunker://` address doesn't change.
+     */
+    val nip46TransportKey: MutableStateFlow<String> = MutableStateFlow(""),
+    /**
+     * The kind-24133 **event ids** this signer recently serviced. Persisted so that a relay replaying
+     * stored ephemeral requests across an app restart doesn't make it sign the same request twice —
+     * matched by exact event id, so it is immune to client clock skew (unlike a timestamp watermark,
+     * a global timestamp would wrongly drop a second app whose clock lags). Bounded to a recent window.
+     */
+    val nip46SeenRequestIds: MutableStateFlow<Set<String>> = MutableStateFlow(emptySet()),
     /**
      * NIP-9B opt-in: when true, community feeds drop events whose latest cached
      * `kind:34551` rules document fails [com.vitorpamplona.quartz.nip72ModCommunities.rules.CommunityRulesValidator].
@@ -189,7 +245,10 @@ class AccountSettings(
     val defaultDiscoveryFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultPollsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultPicturesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultNappletsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultNsitesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultWorkoutsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultGitRepositoriesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultCalendarsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultProductsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.AroundMe),
     val defaultShortsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
@@ -207,6 +266,8 @@ class AccountSettings(
     val defaultBrowseEmojiSetsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultCommunitiesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.AllFollows),
     val defaultFollowPacksFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultAppRecommendationsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultRelayGroupsDiscoveryFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Mine),
     val nwcWallets: MutableStateFlow<List<NwcWalletEntryNorm>> = MutableStateFlow(emptyList()),
     val clinkDebitWallets: MutableStateFlow<List<ClinkDebitWalletEntryNorm>> = MutableStateFlow(emptyList()),
     // The unified default spend rail (an NWC wallet OR a CLINK debit). Persisted under a
@@ -217,6 +278,7 @@ class AccountSettings(
     var hideNIP17WarningDialog: Boolean = false,
     val alwaysOnNotificationService: MutableStateFlow<Boolean> = MutableStateFlow(false),
     val splitNotificationsEnabled: MutableStateFlow<Boolean> = MutableStateFlow(false),
+    val showMessagesInNotifications: MutableStateFlow<Boolean> = MutableStateFlow(true),
     var backupUserMetadata: MetadataEvent? = null,
     var backupContactList: ContactListEvent? = null,
     var backupDMRelayList: ChatMessageRelayListEvent? = null,
@@ -236,6 +298,8 @@ class AccountSettings(
     var backupFavoriteAlgoFeedsList: FavoriteAlgoFeedsListEvent? = null,
     var backupGeohashList: GeohashListEvent? = null,
     var backupEphemeralChatList: EphemeralChatListEvent? = null,
+    var backupRelayGroupList: SimpleGroupListEvent? = null,
+    var backupConcordList: ConcordCommunityListEvent? = null,
     var backupTrustProviderList: TrustProviderListEvent? = null,
     var backupCashuWallet: CashuWalletEvent? = null,
     var backupNutzapInfo: NutzapInfoEvent? = null,
@@ -262,7 +326,20 @@ class AccountSettings(
     var callVideoResolution: CallVideoResolution = CallVideoResolution.HD_720,
     var callMaxBitrateBps: Int = 1_500_000,
     val callsEnabled: MutableStateFlow<Boolean> = MutableStateFlow(true),
+    val defaultRelayAuthPolicy: MutableStateFlow<RelayAuthPolicy> = MutableStateFlow(RelayAuthPolicy.CUSTOM),
+    val relayGroupViewMode: MutableStateFlow<RelayGroupViewMode> = MutableStateFlow(RelayGroupViewMode.DEFAULT),
+    val concordViewMode: MutableStateFlow<ConcordViewMode> = MutableStateFlow(ConcordViewMode.DEFAULT),
+    // Which conversation protocols the Messages inbox loads and shows. A disabled type is both hidden
+    // from the inbox and dropped from the always-on downloading routes. Defaults to everything on.
+    val enabledChatFeeds: MutableStateFlow<Set<ChatFeedType>> = MutableStateFlow(ChatFeedType.ALL),
+    // The per-situation toggles applied under RelayAuthPolicy.CUSTOM.
+    val relayAuthTrustMyRelaysAndVenues: MutableStateFlow<Boolean> = MutableStateFlow(true),
+    val relayAuthTrustReadFollows: MutableStateFlow<Boolean> = MutableStateFlow(true),
+    val relayAuthTrustMessageFollows: MutableStateFlow<Boolean> = MutableStateFlow(true),
+    val relayAuthTrustMessageStrangers: MutableStateFlow<Boolean> = MutableStateFlow(false),
 ) : EphemeralChatRepository,
+    RelayGroupRepository,
+    ConcordListRepository,
     PublicChatListRepository {
     val saveable = MutableStateFlow(AccountSettingsUpdater(null))
     val syncedSettings: AccountSyncedSettings = AccountSyncedSettings(AccountSyncedSettingsInternal())
@@ -277,6 +354,34 @@ class AccountSettings(
 
     fun isWriteable(): Boolean = keyPair.privKey != null || externalSignerPackageName != null
 
+    fun updateRelayGroupViewMode(mode: RelayGroupViewMode) {
+        if (relayGroupViewMode.value != mode) {
+            relayGroupViewMode.tryEmit(mode)
+            saveAccountSettings()
+        }
+    }
+
+    fun updateConcordViewMode(mode: ConcordViewMode) {
+        if (concordViewMode.value != mode) {
+            concordViewMode.tryEmit(mode)
+            saveAccountSettings()
+        }
+    }
+
+    fun isChatFeedEnabled(type: ChatFeedType): Boolean = type in enabledChatFeeds.value
+
+    fun setChatFeedEnabled(
+        type: ChatFeedType,
+        enabled: Boolean,
+    ) {
+        val current = enabledChatFeeds.value
+        val next = if (enabled) current + type else current - type
+        if (next != current) {
+            enabledChatFeeds.tryEmit(next)
+            saveAccountSettings()
+        }
+    }
+
     // ---
     // Always-on Notification Service
     // ---
@@ -295,6 +400,13 @@ class AccountSettings(
         return newValue
     }
 
+    fun toggleShowMessagesInNotifications(): Boolean {
+        val newValue = !showMessagesInNotifications.value
+        showMessagesInNotifications.tryEmit(newValue)
+        saveAccountSettings()
+        return newValue
+    }
+
     // ---
     // Zaps and Reactions
     // ---
@@ -535,6 +647,35 @@ class AccountSettings(
         }
     }
 
+    fun changeNip46SignerEnabled(enabled: Boolean) {
+        if (nip46SignerEnabled.value != enabled) {
+            nip46SignerEnabled.tryEmit(enabled)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeNip46BunkerSecret(secret: String) {
+        if (nip46BunkerSecret.value != secret) {
+            nip46BunkerSecret.tryEmit(secret)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeNip46TransportKey(hexPrivKey: String) {
+        if (nip46TransportKey.value != hexPrivKey) {
+            nip46TransportKey.tryEmit(hexPrivKey)
+            saveAccountSettings()
+        }
+    }
+
+    /** Replaces the recent serviced-request id set (already bounded by the caller). */
+    fun changeNip46SeenRequestIds(ids: Set<String>) {
+        if (nip46SeenRequestIds.value != ids) {
+            nip46SeenRequestIds.tryEmit(ids)
+            saveAccountSettings()
+        }
+    }
+
     fun changeLocalBlossomCacheProfilePicturesOnly(enabled: Boolean) {
         if (localBlossomCacheProfilePicturesOnly.value != enabled) {
             localBlossomCacheProfilePicturesOnly.tryEmit(enabled)
@@ -542,6 +683,20 @@ class AccountSettings(
         }
     }
 
+    fun changeMirrorUploadsToAllServers(enabled: Boolean) {
+        if (mirrorUploadsToAllServers.value != enabled) {
+            mirrorUploadsToAllServers.tryEmit(enabled)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeOptimizeMediaOnUpload(enabled: Boolean) {
+        if (optimizeMediaOnUpload.value != enabled) {
+            optimizeMediaOnUpload.tryEmit(enabled)
+            saveAccountSettings()
+        }
+    }
+
     fun updateAddClientTag(add: Boolean): Boolean =
         if (syncedSettings.security.updateAddClientTag(add)) {
             saveAccountSettings()
@@ -550,6 +705,25 @@ class AccountSettings(
             false
         }
 
+    fun updatePowDifficulty(difficulty: Int): Boolean =
+        if (syncedSettings.proofOfWork.updateDifficulty(difficulty)) {
+            saveAccountSettings()
+            true
+        } else {
+            false
+        }
+
+    fun updatePowCategory(
+        category: PoWCategory,
+        enabled: Boolean,
+    ): Boolean =
+        if (syncedSettings.proofOfWork.updateCategory(category, enabled)) {
+            saveAccountSettings()
+            true
+        } else {
+            false
+        }
+
     // ---
     // list names
     // ---
@@ -631,6 +805,39 @@ class AccountSettings(
         }
     }
 
+    fun changeDefaultRelayGroupsDiscoveryFollowList(name: FeedDefinition) {
+        changeDefaultRelayGroupsDiscoveryFollowList(name.code)
+    }
+
+    fun changeDefaultRelayGroupsDiscoveryFollowList(name: TopFilter) {
+        if (defaultRelayGroupsDiscoveryFollowList.value != name) {
+            defaultRelayGroupsDiscoveryFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultNappletsFollowList(name: FeedDefinition) {
+        changeDefaultNappletsFollowList(name.code)
+    }
+
+    fun changeDefaultNappletsFollowList(name: TopFilter) {
+        if (defaultNappletsFollowList.value != name) {
+            defaultNappletsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultNsitesFollowList(name: FeedDefinition) {
+        changeDefaultNsitesFollowList(name.code)
+    }
+
+    fun changeDefaultNsitesFollowList(name: TopFilter) {
+        if (defaultNsitesFollowList.value != name) {
+            defaultNsitesFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
     fun changeDefaultWorkoutsFollowList(name: FeedDefinition) {
         changeDefaultWorkoutsFollowList(name.code)
     }
@@ -642,6 +849,17 @@ class AccountSettings(
         }
     }
 
+    fun changeDefaultGitRepositoriesFollowList(name: FeedDefinition) {
+        changeDefaultGitRepositoriesFollowList(name.code)
+    }
+
+    fun changeDefaultGitRepositoriesFollowList(name: TopFilter) {
+        if (defaultGitRepositoriesFollowList.value != name) {
+            defaultGitRepositoriesFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
     fun changeDefaultCalendarsFollowList(name: FeedDefinition) {
         changeDefaultCalendarsFollowList(name.code)
     }
@@ -818,6 +1036,17 @@ class AccountSettings(
         }
     }
 
+    fun changeDefaultAppRecommendationsFollowList(name: FeedDefinition) {
+        changeDefaultAppRecommendationsFollowList(name.code)
+    }
+
+    fun changeDefaultAppRecommendationsFollowList(name: TopFilter) {
+        if (defaultAppRecommendationsFollowList.value != name) {
+            defaultAppRecommendationsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
     // ---
     // language services
     // ---
@@ -1155,6 +1384,33 @@ class AccountSettings(
         }
     }
 
+    override fun relayGroupList() = backupRelayGroupList
+
+    override fun updateRelayGroupListTo(newRelayGroupList: SimpleGroupListEvent?) {
+        // Joined groups can live in the NIP-44 private items (encrypted content),
+        // so an empty `tags` is NOT an empty list — guard only on null.
+        if (newRelayGroupList == null) return
+
+        // Events might be different objects, we have to compare their ids.
+        if (backupRelayGroupList?.id != newRelayGroupList.id) {
+            backupRelayGroupList = newRelayGroupList
+            saveAccountSettings()
+        }
+    }
+
+    override fun concordList() = backupConcordList
+
+    override fun updateConcordListTo(newConcordList: ConcordCommunityListEvent?) {
+        // The joined list lives entirely in NIP-44-encrypted content (secrets),
+        // so an empty `tags` is NOT an empty list — guard only on null.
+        if (newConcordList == null) return
+
+        if (backupConcordList?.id != newConcordList.id) {
+            backupConcordList = newConcordList
+            saveAccountSettings()
+        }
+    }
+
     fun updateTrustProviderListTo(trustProviderList: TrustProviderListEvent?) {
         if (trustProviderList == null || trustProviderList.tags.isEmpty()) return
 
@@ -1420,6 +1676,31 @@ class AccountSettings(
             saveAccountSettings()
         }
     }
+
+    fun changeDefaultRelayAuthPolicy(policy: RelayAuthPolicy) {
+        if (defaultRelayAuthPolicy.value != policy) {
+            defaultRelayAuthPolicy.tryEmit(policy)
+            saveAccountSettings()
+        }
+    }
+
+    private fun changeToggle(
+        flow: MutableStateFlow<Boolean>,
+        enabled: Boolean,
+    ) {
+        if (flow.value != enabled) {
+            flow.tryEmit(enabled)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeRelayAuthTrustMyRelaysAndVenues(enabled: Boolean) = changeToggle(relayAuthTrustMyRelaysAndVenues, enabled)
+
+    fun changeRelayAuthTrustReadFollows(enabled: Boolean) = changeToggle(relayAuthTrustReadFollows, enabled)
+
+    fun changeRelayAuthTrustMessageFollows(enabled: Boolean) = changeToggle(relayAuthTrustMessageFollows, enabled)
+
+    fun changeRelayAuthTrustMessageStrangers(enabled: Boolean) = changeToggle(relayAuthTrustMessageStrangers, enabled)
 }
 
 @Serializable

amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSyncedSettings.kt

@@ -22,6 +22,8 @@ package com.vitorpamplona.amethyst.model
 
 import androidx.compose.runtime.Stable
 import com.vitorpamplona.amethyst.commons.audio.VisualizerStyle
+import com.vitorpamplona.amethyst.commons.service.pow.PoWCategory
+import com.vitorpamplona.amethyst.commons.service.pow.PoWPolicy
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.notifications.equalImmutableLists
 import com.vitorpamplona.quartz.nip17Dm.base.ChatroomKey
 import com.vitorpamplona.quartz.nip57Zaps.LnZapEvent
@@ -72,6 +74,11 @@ class AccountSyncedSettings(
         AccountChatPreferences(
             MutableStateFlow(internalSettings.chats.toChatroomKeys()),
         )
+    val proofOfWork =
+        AccountPoWPreferences(
+            MutableStateFlow(internalSettings.proofOfWork.difficulty),
+            MutableStateFlow(PoWCategory.fromIds(internalSettings.proofOfWork.enabledCategories)),
+        )
 
     fun toInternal(): AccountSyncedSettingsInternal =
         AccountSyncedSettingsInternal(
@@ -104,6 +111,14 @@ class AccountSyncedSettings(
             videoPlayer = AccountVideoPlayerPreferencesInternal(videoPlayer.buttonItems.value),
             media = AccountMediaPreferencesInternal(media.audioVisualizer.value.name),
             chats = AccountChatPreferencesInternal(chats.pinnedChatrooms.value.map { it.users.sorted() }),
+            proofOfWork =
+                AccountPoWPreferencesInternal(
+                    proofOfWork.difficulty.value,
+                    // sorted so the serialized form is deterministic
+                    proofOfWork.enabledCategories.value
+                        .map { it.id }
+                        .sorted(),
+                ),
         )
 
     fun updateFrom(syncedSettingsInternal: AccountSyncedSettingsInternal) {
@@ -182,6 +197,19 @@ class AccountSyncedSettings(
         if (chats.pinnedChatrooms.value != newPinnedChatrooms) {
             chats.pinnedChatrooms.tryEmit(newPinnedChatrooms)
         }
+
+        // clamp like the local setter: a synced NIP-78 event from another
+        // client could carry an out-of-range value that would crash the miner
+        // (>256) or mine forever (41+).
+        val newDifficulty = syncedSettingsInternal.proofOfWork.difficulty.coerceIn(0, PoWPolicy.MAX_DIFFICULTY)
+        if (proofOfWork.difficulty.value != newDifficulty) {
+            proofOfWork.difficulty.tryEmit(newDifficulty)
+        }
+
+        val newPoWCategories = PoWCategory.fromIds(syncedSettingsInternal.proofOfWork.enabledCategories)
+        if (proofOfWork.enabledCategories.value != newPoWCategories) {
+            proofOfWork.enabledCategories.tryEmit(newPoWCategories)
+        }
     }
 
     fun dontTranslateFromFilteredBySpokenLanguages(): Set<String> = languages.dontTranslateFrom.value - getLanguagesSpokenByUser()
@@ -285,6 +313,43 @@ class AccountChatPreferences(
     val pinnedChatrooms: MutableStateFlow<Set<ChatroomKey>>,
 )
 
+@Stable
+class AccountPoWPreferences(
+    val difficulty: MutableStateFlow<Int> = MutableStateFlow(0),
+    val enabledCategories: MutableStateFlow<Set<PoWCategory>> = MutableStateFlow(PoWCategory.DEFAULT_ENABLED),
+) {
+    fun updateDifficulty(newDifficulty: Int): Boolean {
+        // compare the coerced value: reporting a change for an out-of-range
+        // input that clamps to the current value would republish identical
+        // settings to relays.
+        val coerced = newDifficulty.coerceIn(0, MAX_POW_DIFFICULTY)
+        return if (difficulty.value != coerced) {
+            difficulty.tryEmit(coerced)
+            true
+        } else {
+            false
+        }
+    }
+
+    fun updateCategory(
+        category: PoWCategory,
+        enabled: Boolean,
+    ): Boolean {
+        val current = enabledCategories.value
+        val updated = if (enabled) current + category else current - category
+        return if (updated != current) {
+            enabledCategories.tryEmit(updated)
+            true
+        } else {
+            false
+        }
+    }
+
+    companion object {
+        const val MAX_POW_DIFFICULTY = PoWPolicy.MAX_DIFFICULTY
+    }
+}
+
 internal fun AccountChatPreferencesInternal.toChatroomKeys(): Set<ChatroomKey> = pinnedRooms.mapTo(mutableSetOf()) { ChatroomKey(it.toSet()) }
 
 @Stable

amethyst/src/main/java/com/vitorpamplona/amethyst/model/AccountSyncedSettingsInternal.kt

@@ -22,6 +22,7 @@ package com.vitorpamplona.amethyst.model
 
 import android.content.res.Resources
 import androidx.core.os.ConfigurationCompat
+import com.vitorpamplona.amethyst.commons.service.pow.PoWCategory
 import com.vitorpamplona.quartz.nip57Zaps.LnZapEvent
 import kotlinx.serialization.Serializable
 import java.util.Locale
@@ -157,6 +158,7 @@ class AccountSyncedSettingsInternal(
     val videoPlayer: AccountVideoPlayerPreferencesInternal = AccountVideoPlayerPreferencesInternal(),
     val media: AccountMediaPreferencesInternal = AccountMediaPreferencesInternal(),
     val chats: AccountChatPreferencesInternal = AccountChatPreferencesInternal(),
+    val proofOfWork: AccountPoWPreferencesInternal = AccountPoWPreferencesInternal(),
 )
 
 @Serializable
@@ -206,6 +208,14 @@ class AccountMediaPreferencesInternal(
     var audioVisualizer: String = "CLASSIC",
 )
 
+@Serializable
+class AccountPoWPreferencesInternal(
+    // NIP-13 target difficulty in leading zero bits; 0 = don't mine anything.
+    val difficulty: Int = 0,
+    // PoWCategory ids the user wants mined when difficulty > 0.
+    val enabledCategories: List<String> = PoWCategory.DEFAULT_ENABLED.map { it.id },
+)
+
 @Serializable
 class AccountChatPreferencesInternal(
     // Rooms pinned to the top of the chat list. Each room is its member

amethyst/src/main/java/com/vitorpamplona/amethyst/model/AntiSpamFilter.kt

@@ -82,10 +82,12 @@ class AntiSpamFilter {
                 (recentAddressables[hash] != null && recentAddressables[hash] != address) ||
                 (spamMessages[hash] != null && !spamMessages[hash].duplicatedEventAddresses.contains(address))
             ) {
+                // may be null if the first duplicate was evicted from the LRU cache
+                // while the spammer record still matches this hash.
                 val existingAddress = recentAddressables[hash]
 
-                val link1 = njumpLink(NAddress.create(existingAddress.kind, existingAddress.pubKeyHex, existingAddress.dTag, relay))
                 val link2 = njumpLink(NAddress.create(event.kind, event.pubKey, event.dTag(), relay))
+                val link1 = existingAddress?.let { njumpLink(NAddress.create(it.kind, it.pubKeyHex, it.dTag, relay)) } ?: link2
 
                 Log.w("Duplicated/SPAM") { "${relay?.url} $link1 $link2" }
 
@@ -111,8 +113,10 @@ class AntiSpamFilter {
                 (existingEvent != null && existingEvent != event.id) ||
                 (spamMessages[hash] != null && !spamMessages[hash].duplicatedEventIds.contains(event.id))
             ) {
-                val link1 = njumpLink(NEvent.create(existingEvent, null, null, relay))
                 val link2 = njumpLink(NEvent.create(event.id, null, null, relay))
+                // existingEvent may be null if the first duplicate was evicted from the
+                // LRU cache while the spammer record still matches this hash.
+                val link1 = existingEvent?.let { njumpLink(NEvent.create(it, null, null, relay)) } ?: link2
 
                 Log.w("Duplicated/SPAM") { "${relay?.url} $link1 $link2" }
 
@@ -149,12 +153,12 @@ class AntiSpamFilter {
                     Spammer(
                         pubkeyHex = event.pubKey,
                         duplicatedEventIds = setOf(),
-                        duplicatedEventAddresses = setOf(recentAddressables[hashCode], event.address()),
+                        duplicatedEventAddresses = setOfNotNull(recentAddressables[hashCode], event.address()),
                     )
                 } else {
                     Spammer(
                         pubkeyHex = event.pubKey,
-                        duplicatedEventIds = setOf(recentEventIds[hashCode], event.id),
+                        duplicatedEventIds = setOfNotNull(recentEventIds[hashCode], event.id),
                         duplicatedEventAddresses = setOf(),
                     )
                 }

amethyst/src/main/java/com/vitorpamplona/amethyst/model/ConcordInviteResult.kt

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.model
+
+/**
+ * The outcome of redeeming a Concord invite link (CORD-05). Separating the failure
+ * modes lets the UI tell the user *why* it failed and — crucially — whether
+ * retrying could ever help, so a link we can never open doesn't strand the user on
+ * an endless "redeeming…" spinner with a retry button that loops forever.
+ */
+sealed interface ConcordInviteResult {
+    /** Redeemed and joined; navigate to [communityId]. */
+    data class Joined(
+        val communityId: String,
+    ) : ConcordInviteResult
+
+    /** The link itself is malformed, or this account can't join (read-only key). Retrying can't help. */
+    data object InvalidLink : ConcordInviteResult
+
+    /**
+     * No invite bundle was reachable on any relay — a transient miss (relays down,
+     * link too new to have propagated, or expired). Retrying may help.
+     */
+    data object NotReachable : ConcordInviteResult
+
+    /**
+     * The link was revoked: the newest event at its coordinate is a `vsk=9` revocation
+     * tombstone (CORD-05 §2). Retrying can't help — the owner retired this link.
+     */
+    data object Revoked : ConcordInviteResult
+
+    /**
+     * The bundle opened fine, but its `expires_at` has passed. Retrying can't help —
+     * unlike [Revoked] the owner didn't retire the link, it simply timed out, so the
+     * user's next step is to ask for a fresh one.
+     */
+    data object Expired : ConcordInviteResult
+
+    /**
+     * The bundle event was found but could not be opened with the link's token —
+     * typically because it was minted by a newer/incompatible Concord client whose
+     * bundle format this app can't read yet. Retrying can't help.
+     */
+    data object Incompatible : ConcordInviteResult
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/GeohashChatIdentityState.kt

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.model
+
+import androidx.core.content.edit
+import com.vitorpamplona.amethyst.Amethyst
+import com.vitorpamplona.quartz.experimental.bitchat.identity.GeohashKeyDerivation
+import com.vitorpamplona.quartz.nip01Core.core.hexToByteArray
+import com.vitorpamplona.quartz.nip01Core.core.toHexKey
+import com.vitorpamplona.quartz.nip01Core.crypto.KeyPair
+import com.vitorpamplona.quartz.nip01Core.signers.NostrSigner
+import com.vitorpamplona.quartz.nip01Core.signers.NostrSignerInternal
+import com.vitorpamplona.quartz.utils.RandomInstance
+
+/**
+ * The account's anonymous, per-geohash chat identities.
+ *
+ * Geohash channels are location-tagged, so posting under the account's real npub
+ * would publish the user's movements tied to their public identity. Instead each
+ * cell gets a throwaway key that is unlinkable to the npub (and to the user's key
+ * in every other cell). This state object caches the derived keys and owns the
+ * seed they come from, keyed to a single account — so switching accounts (or
+ * logging out) switches identities with it.
+ *
+ * The seed is chosen per signer:
+ * - **Local key account** → derived from the account private key
+ *   ([GeohashKeyDerivation.accountSeed]). Stable across all of the user's devices
+ *   and recoverable from the account, while staying publicly unlinkable.
+ * - **Remote (NIP-46) / external (NIP-55) signer** → the raw key is unreachable,
+ *   so a random 32-byte seed is kept in this account's encrypted storage. Because
+ *   the store is scoped to the account's pubkey, two accounts on one device get
+ *   different seeds (a global seed would have made their throwaway identities
+ *   collide, linking the accounts in every cell).
+ */
+class GeohashChatIdentityState(
+    private val signer: NostrSigner,
+) {
+    private val lock = Any()
+    private val cache = HashMap<String, KeyPair>()
+
+    @Volatile private var cachedDeviceSeed: ByteArray? = null
+
+    @Volatile private var cachedNickname: String? = null
+
+    /**
+     * The user's display handle for location chats: a single global nickname, persisted per account.
+     * Bitchat carries this as the per-message `["n", …]` tag rather than a kind-0 profile, and kind-20000
+     * messages are ephemeral (relays needn't store them), so the only durable home for it is the device.
+     * Kept in this account's encrypted storage, so it survives restarts and switches with the account.
+     * Empty string means "no nickname set". Reads touch disk on first call — invoke off the main thread.
+     */
+    fun nickname(): String {
+        cachedNickname?.let { return it }
+        synchronized(lock) {
+            cachedNickname?.let { return it }
+            val value = Amethyst.instance.encryptedStorage(signer.pubKey).getString(PREF_NICKNAME, "") ?: ""
+            cachedNickname = value
+            return value
+        }
+    }
+
+    /** Persists the global location-chat nickname (trimmed) for this account. */
+    fun setNickname(value: String) {
+        val trimmed = value.trim()
+        synchronized(lock) {
+            cachedNickname = trimmed
+            Amethyst.instance.encryptedStorage(signer.pubKey).edit { putString(PREF_NICKNAME, trimmed) }
+        }
+    }
+
+    /** The Nostr key pair to use inside [geohash]. Derivation is cheap but cached; call off the main thread. */
+    fun keyPair(geohash: String): KeyPair =
+        synchronized(lock) {
+            cache.getOrPut(geohash) { GeohashKeyDerivation.deriveKeyPair(seed(), geohash) }
+        }
+
+    private fun seed(): ByteArray = accountPrivKey()?.let { GeohashKeyDerivation.accountSeed(it) } ?: deviceSeed()
+
+    private fun accountPrivKey(): ByteArray? = (signer as? NostrSignerInternal)?.keyPair?.privKey
+
+    /** Random per-account seed, used only when the account key is unreachable (bunker / external signer). */
+    private fun deviceSeed(): ByteArray {
+        cachedDeviceSeed?.let { return it }
+        synchronized(lock) {
+            cachedDeviceSeed?.let { return it }
+            val prefs = Amethyst.instance.encryptedStorage(signer.pubKey)
+            val existing = prefs.getString(PREF_KEY, null)
+            val seed =
+                if (existing != null && existing.length == GeohashKeyDerivation.SEED_SIZE * 2) {
+                    existing.hexToByteArray()
+                } else {
+                    val fresh = RandomInstance.bytes(GeohashKeyDerivation.SEED_SIZE)
+                    prefs.edit { putString(PREF_KEY, fresh.toHexKey()) }
+                    fresh
+                }
+            cachedDeviceSeed = seed
+            return seed
+        }
+    }
+
+    companion object {
+        private const val PREF_KEY = "geohash_chat_device_seed"
+        private const val PREF_NICKNAME = "geohash_chat_nickname"
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/GitPullRequestUpdateIndex.kt

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.model
+
+import com.vitorpamplona.amethyst.model.LocalCache.observeEvents
+import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.relay.filters.Filter
+import com.vitorpamplona.quartz.nip34Git.pr.GitPullRequestUpdateEvent
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.flowOn
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
+
+/**
+ * Cross-screen index of the most recent NIP-34 pull-request update event
+ * (kind 1619) per parent pull-request id, kept up to date from
+ * [LocalCache.observeEvents]. A PR update *revises* its parent PR with a
+ * newer commit / merge base, so the UI folds the latest one into the PR rather
+ * than listing updates separately. Like [GitStatusIndex], updates aren't tracked
+ * in `Note.replies`, so a per-row cache scan would otherwise be required.
+ *
+ * The kind-indexed [observeEvents] re-emits the whole matching list on every new
+ * 1619 (and seeds it from the cache index via `init()`), so [latestByPullRequest]
+ * is just that list reduced to the latest-per-parent map. Shared [SharingStarted.Eagerly]
+ * — never `WhileSubscribed` — because callers read `.value` synchronously and must
+ * not see a stale map when no one is actively collecting. `null` means "not loaded yet".
+ */
+object GitPullRequestUpdateIndex {
+    private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
+
+    val latestByPullRequest: StateFlow<Map<HexKey, GitPullRequestUpdateEvent>?> =
+        LocalCache
+            .observeEvents<GitPullRequestUpdateEvent>(Filter(kinds = listOf(GitPullRequestUpdateEvent.KIND)))
+            .map { latestByParent(it) }
+            .flowOn(Dispatchers.IO)
+            .stateIn(scope, SharingStarted.Eagerly, null)
+
+    private fun latestByParent(events: List<GitPullRequestUpdateEvent>): Map<HexKey, GitPullRequestUpdateEvent> {
+        val latest = HashMap<HexKey, GitPullRequestUpdateEvent>()
+        for (event in events) {
+            val target = event.parentPullRequestId() ?: continue
+            val current = latest[target]
+            if (current == null || event.createdAt > current.createdAt) {
+                latest[target] = event
+            }
+        }
+        return latest
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/GitStatusIndex.kt

@@ -20,66 +20,78 @@
  */
 package com.vitorpamplona.amethyst.model
 
+import com.vitorpamplona.amethyst.model.LocalCache.observeEvents
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.relay.filters.Filter
+import com.vitorpamplona.quartz.nip34Git.status.GitStatusAppliedEvent
+import com.vitorpamplona.quartz.nip34Git.status.GitStatusClosedEvent
 import com.vitorpamplona.quartz.nip34Git.status.GitStatusEvent
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
-import kotlinx.coroutines.flow.asStateFlow
-import kotlinx.coroutines.flow.onStart
-import kotlinx.coroutines.launch
-import java.util.concurrent.atomic.AtomicBoolean
+import kotlinx.coroutines.flow.flowOn
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
 
 /**
  * Cross-screen index of the most recent NIP-34 status event (kinds
  * 1630-1633) per target id, kept up to date from
- * [LocalCache.live.newEventBundles]. Status events are not tracked in
+ * [LocalCache.observeEvents]. Status events are not tracked in
  * `Note.replies` (see `LocalCache.computeReplyTo`), so the only way to
  * find them otherwise would be a full cache scan per row.
+ *
+ * The kind-indexed [observeEvents] re-emits the whole matching list on every new
+ * status event (and seeds it from the cache index via `init()`), so [latestByTarget]
+ * is just that list reduced to the latest-per-target map. Shared [SharingStarted.Eagerly]
+ * — never `WhileSubscribed` — because callers (e.g. [isClosedOrResolved] and the feed
+ * filters) read `.value` synchronously and must not see a stale map when no one is
+ * actively collecting. `null` means "not loaded yet".
  */
 object GitStatusIndex {
     private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
-    private val started = AtomicBoolean(false)
 
-    private val mutableLatestByTarget = MutableStateFlow<Map<HexKey, GitStatusEvent>?>(null)
-    val latestByTarget: StateFlow<Map<HexKey, GitStatusEvent>?> = mutableLatestByTarget.asStateFlow()
+    private val statusKinds =
+        listOf(
+            GitStatusEvent.KIND_OPEN,
+            GitStatusEvent.KIND_APPLIED,
+            GitStatusEvent.KIND_CLOSED,
+            GitStatusEvent.KIND_DRAFT,
+        )
 
-    fun startIfNeeded() {
-        if (!started.compareAndSet(false, true)) return
-        scope.launch {
-            // Subscribe to bundle updates BEFORE the initial scan via onStart, so any
-            // events that arrive between scan start and collector attach are picked up.
-            LocalCache.live.newEventBundles
-                .onStart {
-                    val initial = HashMap<HexKey, GitStatusEvent>()
-                    LocalCache.notes.forEach { _, note ->
-                        val event = note.event as? GitStatusEvent ?: return@forEach
-                        val target = event.rootEventId() ?: return@forEach
-                        val current = initial[target]
-                        if (current == null || event.createdAt > current.createdAt) {
-                            initial[target] = event
-                        }
-                    }
-                    mutableLatestByTarget.value = initial
-                }.collect { bundle -> processBundle(bundle) }
-        }
-    }
+    val latestByTarget: StateFlow<Map<HexKey, GitStatusEvent>?> =
+        LocalCache
+            .observeEvents<GitStatusEvent>(Filter(kinds = statusKinds))
+            .map { reduceLatestByTarget(it) }
+            .flowOn(Dispatchers.IO)
+            .stateIn(scope, SharingStarted.Eagerly, null)
 
-    private fun processBundle(bundle: Set<Note>) {
-        val snapshot = mutableLatestByTarget.value ?: emptyMap()
-        var modified: HashMap<HexKey, GitStatusEvent>? = null
-        for (note in bundle) {
-            val event = note.event as? GitStatusEvent ?: continue
+    private fun reduceLatestByTarget(events: List<GitStatusEvent>): Map<HexKey, GitStatusEvent> {
+        val latest = HashMap<HexKey, GitStatusEvent>()
+        for (event in events) {
             val target = event.rootEventId() ?: continue
-            val map = modified ?: snapshot
-            val current = map[target]
+            val current = latest[target]
             if (current == null || event.createdAt > current.createdAt) {
-                if (modified == null) modified = HashMap(snapshot)
-                modified[target] = event
+                latest[target] = event
             }
         }
-        modified?.let { mutableLatestByTarget.value = it }
+        return latest
+    }
+
+    /**
+     * Whether the latest status for [targetId] marks it as closed (kind 1632)
+     * or applied/resolved/merged (kind 1631). Items with no status event, or
+     * whose latest status is open (1630) or draft (1633), are considered open.
+     *
+     * Reads from the synchronous snapshot in [latestByTarget]; pass an explicit
+     * [map] to avoid re-reading the value across a batch.
+     */
+    fun isClosedOrResolved(
+        targetId: HexKey,
+        map: Map<HexKey, GitStatusEvent>? = latestByTarget.value,
+    ): Boolean {
+        val event = map?.get(targetId) ?: return false
+        return event is GitStatusClosedEvent || event is GitStatusAppliedEvent
     }
 }

amethyst/src/main/java/com/vitorpamplona/amethyst/model/HashtagIcon.kt

@@ -20,99 +20,12 @@
  */
 package com.vitorpamplona.amethyst.model
 
-import androidx.compose.foundation.layout.padding
-import androidx.compose.material3.Text
-import androidx.compose.runtime.Composable
-import androidx.compose.runtime.Immutable
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.graphics.vector.ImageVector
-import androidx.compose.ui.tooling.preview.Preview
-import androidx.compose.ui.unit.dp
-import com.vitorpamplona.amethyst.commons.hashtags.Amethyst
-import com.vitorpamplona.amethyst.commons.hashtags.Btc
-import com.vitorpamplona.amethyst.commons.hashtags.Cashu
-import com.vitorpamplona.amethyst.commons.hashtags.Coffee
-import com.vitorpamplona.amethyst.commons.hashtags.CustomHashTagIcons
-import com.vitorpamplona.amethyst.commons.hashtags.Flowerstr
-import com.vitorpamplona.amethyst.commons.hashtags.Footstr
-import com.vitorpamplona.amethyst.commons.hashtags.Gamestr
-import com.vitorpamplona.amethyst.commons.hashtags.Grownostr
-import com.vitorpamplona.amethyst.commons.hashtags.Lightning
-import com.vitorpamplona.amethyst.commons.hashtags.Mate
-import com.vitorpamplona.amethyst.commons.hashtags.Nostr
-import com.vitorpamplona.amethyst.commons.hashtags.Plebs
-import com.vitorpamplona.amethyst.commons.hashtags.Skull
-import com.vitorpamplona.amethyst.commons.hashtags.Tunestr
-import com.vitorpamplona.amethyst.commons.hashtags.Weed
-import com.vitorpamplona.amethyst.commons.hashtags.Zap
-import com.vitorpamplona.amethyst.commons.model.EmptyTagList
-import com.vitorpamplona.amethyst.commons.richtext.HashTagSegment
-import com.vitorpamplona.amethyst.commons.richtext.RegularTextSegment
-import com.vitorpamplona.amethyst.ui.components.HashTag
-import com.vitorpamplona.amethyst.ui.components.RenderRegular
-import com.vitorpamplona.amethyst.ui.components.RenderTextParagraph
-import com.vitorpamplona.amethyst.ui.navigation.navs.EmptyNav
-import com.vitorpamplona.amethyst.ui.theme.ThemeComparisonColumn
+import com.vitorpamplona.amethyst.commons.ui.richtext.HashtagIcon as CommonsHashtagIcon
+import com.vitorpamplona.amethyst.commons.ui.richtext.checkForHashtagWithIcon as commonsCheckForHashtagWithIcon
 
-@Preview
-@Composable
-fun RenderHashTagIconsPreview() {
-    ThemeComparisonColumn {
-        RenderRegular(
-            "Testing rendering of hashtags: #flowerstr #Bitcoin, #nostr, #lightning, #zap, #amethyst, #cashu, #plebs, #coffee, #skullofsatoshi, #grownostr, #footstr, #tunestr, #weed, #mate, #gamestr, #gamechain",
-            EmptyTagList,
-        ) { paragraph, _, spaceWidth, modifier ->
-            RenderTextParagraph(paragraph, spaceWidth, modifier) { word ->
-                when (word) {
-                    is HashTagSegment -> HashTag(word, EmptyNav())
-                    is RegularTextSegment -> Text(word.segmentText)
-                }
-            }
-        }
-    }
-}
+// The hashtag-icon table now lives in commons/ui/richtext so the shared
+// RichTextViewer and both front ends resolve the same icons. These re-exports keep
+// the historical `com.vitorpamplona.amethyst.model` call sites working.
+typealias HashtagIcon = CommonsHashtagIcon
 
-fun checkForHashtagWithIcon(tag: String): HashtagIcon? =
-    when (tag.lowercase()) {
-        "₿itcoin", "bitcoin", "btc", "timechain", "bitcoiner", "bitcoiners" -> bitcoin
-        "nostr", "nostrich", "nostriches", "thenostr" -> nostr
-        "lightning", "lightningnetwork" -> lightning
-        "zap", "zaps", "zapper", "zappers", "zapping", "zapped", "zapathon", "zapraiser", "zaplife", "zapchain" -> zap
-        "amethyst" -> amethyst
-        "cashu", "ecash", "nut", "nuts", "deeznuts" -> cashu
-        "plebs", "pleb", "plebchain" -> plebs
-        "coffee", "coffeechain", "cafe" -> coffee
-        "skullofsatoshi" -> skull
-        "grownostr", "gardening", "garden" -> growstr
-        "footstr" -> footstr
-        "flowerstr" -> flowerstr
-        "tunestr", "music", "nowplaying" -> tunestr
-        "mate", "matechain", "matestr" -> matestr
-        "weed", "weedstr", "420", "cannabis", "marijuana" -> weed
-        "gamestr", "gaming", "gamechain" -> gamestr
-        else -> null
-    }
-
-val bitcoin = HashtagIcon(CustomHashTagIcons.Btc, "Bitcoin", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val nostr = HashtagIcon(CustomHashTagIcons.Nostr, "Nostr", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val lightning = HashtagIcon(CustomHashTagIcons.Lightning, "Lightning", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val zap = HashtagIcon(CustomHashTagIcons.Zap, "Zap", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val amethyst = HashtagIcon(CustomHashTagIcons.Amethyst, "Amethyst", Modifier.padding(start = 2.dp, bottom = 1.dp, top = 1.dp))
-val cashu = HashtagIcon(CustomHashTagIcons.Cashu, "Cashu", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val plebs = HashtagIcon(CustomHashTagIcons.Plebs, "Pleb", Modifier.padding(start = 2.dp, bottom = 1.dp, top = 1.dp))
-val coffee = HashtagIcon(CustomHashTagIcons.Coffee, "Coffee", Modifier.padding(start = 3.dp, bottom = 1.dp, top = 1.dp))
-val skull = HashtagIcon(CustomHashTagIcons.Skull, "SkullofSatoshi", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val growstr = HashtagIcon(CustomHashTagIcons.Grownostr, "GrowNostr", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val footstr = HashtagIcon(CustomHashTagIcons.Footstr, "Footstr", Modifier.padding(start = 2.dp, bottom = 1.dp, top = 1.dp))
-val flowerstr = HashtagIcon(CustomHashTagIcons.Flowerstr, "Flowerstr", Modifier.padding(start = 2.dp, bottom = 1.dp, top = 1.dp))
-val tunestr = HashtagIcon(CustomHashTagIcons.Tunestr, "Tunestr", Modifier.padding(start = 1.dp, bottom = 1.dp, top = 1.dp))
-val weed = HashtagIcon(CustomHashTagIcons.Weed, "Weed", Modifier.padding(start = 1.dp, bottom = 0.dp, top = 0.dp))
-val matestr = HashtagIcon(CustomHashTagIcons.Mate, "Mate", Modifier.padding(start = 1.dp, bottom = 0.dp, top = 0.dp))
-val gamestr = HashtagIcon(CustomHashTagIcons.Gamestr, "GameStr", Modifier.padding(start = 1.dp, bottom = 0.dp, top = 0.dp))
-
-@Immutable
-class HashtagIcon(
-    val icon: ImageVector,
-    val description: String,
-    val modifier: Modifier = Modifier,
-)
+fun checkForHashtagWithIcon(tag: String): HashtagIcon? = commonsCheckForHashtagWithIcon(tag)

amethyst/src/main/java/com/vitorpamplona/amethyst/model/LocalCache.kt

@@ -30,8 +30,11 @@ import com.vitorpamplona.amethyst.commons.model.Channel
 import com.vitorpamplona.amethyst.commons.model.OnchainZapStatus
 import com.vitorpamplona.amethyst.commons.model.cache.ICacheProvider
 import com.vitorpamplona.amethyst.commons.model.cache.LargeSoftCache
+import com.vitorpamplona.amethyst.commons.model.concord.ConcordChannel
 import com.vitorpamplona.amethyst.commons.model.emphChat.EphemeralChatChannel
+import com.vitorpamplona.amethyst.commons.model.geohashChat.GeohashChatChannel
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatChannel
+import com.vitorpamplona.amethyst.commons.model.nip29RelayGroups.RelayGroupChannel
 import com.vitorpamplona.amethyst.commons.model.nip53LiveActivities.LiveActivitiesChannel
 import com.vitorpamplona.amethyst.commons.model.observables.CreatedAtIdHexComparator
 import com.vitorpamplona.amethyst.commons.model.observables.EventListMatchingFilter
@@ -47,6 +50,8 @@ import com.vitorpamplona.amethyst.model.nipBCOnchainZaps.OnchainZapResolver
 import com.vitorpamplona.amethyst.service.BundledInsert
 import com.vitorpamplona.amethyst.service.checkNotInMainThread
 import com.vitorpamplona.amethyst.ui.note.dateFormatter
+import com.vitorpamplona.quartz.concord.cord02Community.ConcordCommunityListEvent
+import com.vitorpamplona.quartz.concord.cord03Channels.ConcordChannelId
 import com.vitorpamplona.quartz.experimental.agora.FundraiserEvent
 import com.vitorpamplona.quartz.experimental.attestations.attestation.AttestationEvent
 import com.vitorpamplona.quartz.experimental.attestations.proficiency.AttestorProficiencyEvent
@@ -54,11 +59,14 @@ import com.vitorpamplona.quartz.experimental.attestations.recommendation.Attesto
 import com.vitorpamplona.quartz.experimental.attestations.request.AttestationRequestEvent
 import com.vitorpamplona.quartz.experimental.audio.header.AudioHeaderEvent
 import com.vitorpamplona.quartz.experimental.audio.track.AudioTrackEvent
+import com.vitorpamplona.quartz.experimental.birdstar.BirdDetectionEvent
 import com.vitorpamplona.quartz.experimental.birdstar.BirdexEvent
+import com.vitorpamplona.quartz.experimental.bitchat.geohash.GeohashChatEvent
 import com.vitorpamplona.quartz.experimental.edits.TextNoteModificationEvent
 import com.vitorpamplona.quartz.experimental.ephemChat.chat.EphemeralChatEvent
 import com.vitorpamplona.quartz.experimental.ephemChat.chat.RoomId
 import com.vitorpamplona.quartz.experimental.ephemChat.list.EphemeralChatListEvent
+import com.vitorpamplona.quartz.experimental.fitness.workout.ExerciseTemplateEvent
 import com.vitorpamplona.quartz.experimental.fitness.workout.WorkoutRecordEvent
 import com.vitorpamplona.quartz.experimental.interactiveStories.InteractiveStoryPrologueEvent
 import com.vitorpamplona.quartz.experimental.interactiveStories.InteractiveStoryReadingStateEvent
@@ -75,6 +83,7 @@ import com.vitorpamplona.quartz.experimental.nipsOnNostr.NipTextEvent
 import com.vitorpamplona.quartz.experimental.nns.NNSEvent
 import com.vitorpamplona.quartz.experimental.notifications.wake.WakeUpEvent
 import com.vitorpamplona.quartz.experimental.profileGallery.ProfileGalleryEntryEvent
+import com.vitorpamplona.quartz.experimental.ps1saves.Ps1SaveEvent
 import com.vitorpamplona.quartz.experimental.roadstr.confirmation.RoadEventConfirmationEvent
 import com.vitorpamplona.quartz.experimental.roadstr.report.RoadEventReportEvent
 import com.vitorpamplona.quartz.experimental.zapPolls.ZapPollEvent
@@ -149,6 +158,24 @@ import com.vitorpamplona.quartz.nip28PublicChat.admin.ChannelMetadataEvent
 import com.vitorpamplona.quartz.nip28PublicChat.admin.ChannelMuteUserEvent
 import com.vitorpamplona.quartz.nip28PublicChat.list.ChannelListEvent
 import com.vitorpamplona.quartz.nip28PublicChat.message.ChannelMessageEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.GroupId
+import com.vitorpamplona.quartz.nip29RelayGroups.groupId
+import com.vitorpamplona.quartz.nip29RelayGroups.metadata.GroupAdminsEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.metadata.GroupMembersEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.metadata.GroupMetadataEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.metadata.GroupParticipantsEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.metadata.GroupPinnedEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.metadata.SupportedRolesEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.CreateGroupEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.CreateInviteEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.DeleteEventEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.DeleteGroupEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.EditMetadataEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.PutUserEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.RemoveUserEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.moderation.UpdatePinListEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.request.JoinRequestEvent
+import com.vitorpamplona.quartz.nip29RelayGroups.request.LeaveRequestEvent
 import com.vitorpamplona.quartz.nip30CustomEmoji.pack.EmojiPackEvent
 import com.vitorpamplona.quartz.nip30CustomEmoji.selection.EmojiPackSelectionEvent
 import com.vitorpamplona.quartz.nip31Alts.AltTag
@@ -192,6 +219,7 @@ import com.vitorpamplona.quartz.nip51Lists.relayLists.RelayFeedsListEvent
 import com.vitorpamplona.quartz.nip51Lists.relayLists.TrustedRelayListEvent
 import com.vitorpamplona.quartz.nip51Lists.relaySets.RelaySetEvent
 import com.vitorpamplona.quartz.nip51Lists.releaseArtifactSet.ReleaseArtifactSetEvent
+import com.vitorpamplona.quartz.nip51Lists.simpleGroupList.SimpleGroupListEvent
 import com.vitorpamplona.quartz.nip52Calendar.appt.day.CalendarDateSlotEvent
 import com.vitorpamplona.quartz.nip52Calendar.appt.time.CalendarTimeSlotEvent
 import com.vitorpamplona.quartz.nip52Calendar.calendar.CalendarEvent
@@ -216,10 +244,13 @@ import com.vitorpamplona.quartz.nip58Badges.accepted.AcceptedBadgeSetEvent
 import com.vitorpamplona.quartz.nip58Badges.award.BadgeAwardEvent
 import com.vitorpamplona.quartz.nip58Badges.definition.BadgeDefinitionEvent
 import com.vitorpamplona.quartz.nip58Badges.profile.ProfileBadgesEvent
+import com.vitorpamplona.quartz.nip59Giftwrap.HasInnerEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.seals.SealedRumorEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.wraps.GiftWrapEvent
 import com.vitorpamplona.quartz.nip5aStaticWebsites.NamedSiteEvent
 import com.vitorpamplona.quartz.nip5aStaticWebsites.RootSiteEvent
+import com.vitorpamplona.quartz.nip5dNapplets.NamedNappletEvent
+import com.vitorpamplona.quartz.nip5dNapplets.RootNappletEvent
 import com.vitorpamplona.quartz.nip60Cashu.history.CashuSpendingHistoryEvent
 import com.vitorpamplona.quartz.nip60Cashu.quote.CashuMintQuoteEvent
 import com.vitorpamplona.quartz.nip60Cashu.token.CashuTokenEvent
@@ -248,6 +279,7 @@ import com.vitorpamplona.quartz.nip72ModCommunities.definition.CommunityDefiniti
 import com.vitorpamplona.quartz.nip72ModCommunities.follow.CommunityListEvent
 import com.vitorpamplona.quartz.nip75ZapGoals.GoalEvent
 import com.vitorpamplona.quartz.nip78AppData.AppSpecificDataEvent
+import com.vitorpamplona.quartz.nip7DThreads.ThreadEvent
 import com.vitorpamplona.quartz.nip84Highlights.HighlightEvent
 import com.vitorpamplona.quartz.nip85TrustedAssertions.list.TrustProviderListEvent
 import com.vitorpamplona.quartz.nip85TrustedAssertions.users.ContactCardEvent
@@ -286,6 +318,8 @@ import com.vitorpamplona.quartz.nipF4Podcasts.authored.AuthoredPodcastsEvent
 import com.vitorpamplona.quartz.nipF4Podcasts.episode.PodcastEpisodeEvent
 import com.vitorpamplona.quartz.nipF4Podcasts.favorites.FavoritePodcastsListEvent
 import com.vitorpamplona.quartz.nipF4Podcasts.metadata.PodcastMetadataEvent
+import com.vitorpamplona.quartz.nipXXPodcasting20.episode.Podcasting20EpisodeEvent
+import com.vitorpamplona.quartz.nipXXPodcasting20.trailer.Podcasting20TrailerEvent
 import com.vitorpamplona.quartz.utils.DualCase
 import com.vitorpamplona.quartz.utils.Hex
 import com.vitorpamplona.quartz.utils.Log
@@ -327,6 +361,9 @@ object LocalCache : ILocalCache, ICacheProvider {
     val publicChatChannels = LargeCache<HexKey, PublicChatChannel>()
     val liveChatChannels = LargeCache<Address, LiveActivitiesChannel>()
     val ephemeralChannels = LargeCache<RoomId, EphemeralChatChannel>()
+    val geohashChannels = LargeCache<String, GeohashChatChannel>()
+    val relayGroupChannels = LargeCache<GroupId, RelayGroupChannel>()
+    val concordChannels = LargeCache<ConcordChannelId, ConcordChannel>()
 
     val paymentTracker = NwcPaymentTracker()
 
@@ -600,6 +637,13 @@ object LocalCache : ILocalCache, ICacheProvider {
 
     fun getEphemeralChatChannelIfExists(key: RoomId): EphemeralChatChannel? = ephemeralChannels.get(key)
 
+    fun getGeohashChannelIfExists(geohash: String): GeohashChatChannel? = geohashChannels.get(geohash)
+
+    fun getRelayGroupChannelIfExists(key: GroupId): RelayGroupChannel? = relayGroupChannels.get(key)
+
+    /** Every relay group we know of that is hosted on [relay] (its channel directory). */
+    fun getRelayGroupChannelsOnRelay(relay: NormalizedRelayUrl): List<RelayGroupChannel> = relayGroupChannels.filter { key, _ -> key.relayUrl == relay }
+
     fun getLiveActivityChannelIfExists(key: Address): LiveActivitiesChannel? = liveChatChannels.get(key)
 
     fun getNoteIfExists(event: Event): Note? =
@@ -688,6 +732,85 @@ object LocalCache : ILocalCache, ICacheProvider {
 
     fun getOrCreateEphemeralChannel(key: RoomId): EphemeralChatChannel = ephemeralChannels.getOrCreate(key) { EphemeralChatChannel(key) }
 
+    fun getOrCreateGeohashChannel(geohash: String): GeohashChatChannel = geohashChannels.getOrCreate(geohash) { GeohashChatChannel(geohash) }
+
+    fun getOrCreateRelayGroupChannel(key: GroupId): RelayGroupChannel = relayGroupChannels.getOrCreate(key) { RelayGroupChannel(key) }
+
+    fun getConcordChannelIfExists(key: ConcordChannelId): ConcordChannel? = concordChannels.get(key)
+
+    fun getOrCreateConcordChannel(key: ConcordChannelId): ConcordChannel = concordChannels.getOrCreate(key) { ConcordChannel(key) }
+
+    /**
+     * Lands a decrypted Concord chat rumor in the cache as a real Note and, for
+     * message-like kinds, attaches it to its channel so the shared chat feed and
+     * the Messages inbox render it (with previews, threading, OTS, reactions/zaps
+     * reusing the same id-keyed machinery as every other chat). Reactions (kind 7),
+     * deletes (kind 5), etc. are consumed too — they wire to their target Note by
+     * `e`-tag through [justConsume] — but are not themselves added as channel rows.
+     *
+     * Fed by [com.vitorpamplona.amethyst.commons.model.concord.ConcordSessionManager]
+     * once a wrap decrypts + validates against the folded Control Plane.
+     */
+    fun consumeConcordRumor(
+        communityId: String,
+        channelIdHex: String,
+        rumor: Event,
+        seenOnRelays: Set<NormalizedRelayUrl> = emptySet(),
+    ) {
+        // Attach to the channel BEFORE justConsume sets the event and notifies feeds,
+        // so the note already carries its ConcordChannel gatherer when it flows through
+        // the Messages-list incremental filter (which routes rows by that gatherer).
+        val messageRow =
+            if (rumor is ChatEvent || rumor is CommentEvent) {
+                val ch = getOrCreateConcordChannel(ConcordChannelId(communityId, channelIdHex))
+                val note = getOrCreateNote(rumor.id)
+                // Skip attaching a row for a message we already know is deleted (its kind-5 delete
+                // was processed first). Otherwise every reproject — which re-emits the whole wrap
+                // buffer — would re-add then re-remove it, churning the feed. justConsume still
+                // records the (already-known) deletion below; a delete arriving LATER is handled by
+                // the normal deletion cascade unlinking the note from its gatherers.
+                if (!deletionIndex.hasBeenDeleted(rumor)) ch.addNote(note)
+                ch to note
+            } else {
+                null
+            }
+        // wasVerified = true: a Concord rumor is unsigned (its `sig` is empty), so a signature
+        // check would fail and the event would never load onto its Note — leaving the chat row
+        // stuck on the "loading / not found" placeholder. Its authenticity is already established
+        // by the envelope open path (ConcordStreamEnvelope.open verifies the seal signature,
+        // binds rumor.pubKey == seal.pubKey, and checks rumor.verifyId()), exactly like a NIP-59
+        // gift-wrapped DM rumor, so we consume it as pre-verified.
+        justConsume(rumor, null, true)
+
+        // A Concord rumor is decrypted locally with the plane key, so it arrives with no
+        // per-relay attribution (relay = null above). Stamp the relays its carrying wrap was
+        // seen on — mirroring NIP-17's addRelayToNoteAndInners — so the chat UI can show where
+        // the message actually came from, not just the channel's configured relays.
+        if (seenOnRelays.isNotEmpty()) {
+            getNoteIfExists(rumor.id)?.takeIf { it.event != null }?.let { note ->
+                seenOnRelays.forEach { note.addRelay(it) }
+            }
+        }
+
+        // justConsume bails without loading the event when the rumor has already been deleted
+        // (a kind-5 delete referencing it was processed first — easy to hit in Concord because a
+        // reproject re-emits the whole wrap buffer and ordering isn't guaranteed) or fails to
+        // verify. We attached the row up front, so an unpopulated note would otherwise linger as a
+        // permanent "Event is loading…" ghost. Drop it; the reverse order (delete after the message)
+        // is already handled by the normal deletion cascade unlinking the note from its gatherers.
+        messageRow?.let { (ch, note) ->
+            if (note.event == null) {
+                ch.removeNote(note)
+            } else {
+                // The row was attached (addNote) BEFORE justConsume set the event, so addNote saw a
+                // null createdAt and could not pick lastNote or order the feed. The event is loaded
+                // now — refresh so the channel's last-message preview, unread count, and ordering are
+                // correct (otherwise lastNote stays null forever and every row reads "No messages yet").
+                ch.refreshAfterEventLoad(note)
+            }
+        }
+    }
+
     fun checkGetOrCreatePublicChatChannel(key: String): PublicChatChannel? {
         if (isValidHex(key)) {
             return getOrCreatePublicChatChannel(key)
@@ -773,7 +896,11 @@ object LocalCache : ILocalCache, ICacheProvider {
 
         if (relay != null) {
             author.addRelayBeingUsed(relay, event.createdAt)
-            note.addRelay(relay)
+            // A gift wrap re-delivered by another relay is a duplicate (returns
+            // false below and is never re-processed), so drill into the already
+            // unwrapped chain here — otherwise the relay never reaches the
+            // rumor note that the chat UI actually renders.
+            addRelayToNoteAndInners(note, relay)
         }
 
         // Already processed this event.
@@ -1368,6 +1495,7 @@ object LocalCache : ILocalCache, ICacheProvider {
             is LiveActivitiesChatMessageEvent -> noteEvent.activityAddress()?.let { getLiveActivityChannelIfExists(it) }
             is LiveActivitiesEvent -> getLiveActivityChannelIfExists(noteEvent.address())
             is EphemeralChatEvent -> noteEvent.roomId()?.let { getEphemeralChatChannelIfExists(it) }
+            is GeohashChatEvent -> noteEvent.geohash()?.let { getGeohashChannelIfExists(it) }
             else -> null
         }
 
@@ -1427,6 +1555,11 @@ object LocalCache : ILocalCache, ICacheProvider {
     ): Boolean {
         val note = getOrCreateNote(event.id)
 
+        if (relay != null) {
+            getOrCreateUser(event.pubKey).addRelayBeingUsed(relay, event.createdAt)
+            note.addRelay(relay)
+        }
+
         // Already processed this event.
         if (note.event != null) return false
 
@@ -1457,6 +1590,11 @@ object LocalCache : ILocalCache, ICacheProvider {
     ): Boolean {
         val note = getOrCreateNote(event.id)
 
+        if (relay != null) {
+            getOrCreateUser(event.pubKey).addRelayBeingUsed(relay, event.createdAt)
+            note.addRelay(relay)
+        }
+
         // Already processed this event.
         if (note.event != null) return false
 
@@ -1488,6 +1626,14 @@ object LocalCache : ILocalCache, ICacheProvider {
     ): Boolean {
         val note = getOrCreateNote(event.id)
 
+        // Approval notes render their own relay list directly in community feeds
+        // (there is no repost-style indirection to a replyTo for them), so without
+        // this attribution the "accepted by relays" gallery line stays empty forever.
+        if (relay != null) {
+            getOrCreateUser(event.pubKey).addRelayBeingUsed(relay, event.createdAt)
+            note.addRelay(relay)
+        }
+
         // Already processed this event.
         if (note.event != null) return false
 
@@ -1715,6 +1861,216 @@ object LocalCache : ILocalCache, ICacheProvider {
         return new
     }
 
+    /**
+     * Public geohash chat message (kind 20000). Routes into the cell's
+     * [GeohashChatChannel]. Presence (kind 20001) is deliberately NOT consumed
+     * here — it is an empty-content heartbeat handled by the live chat screen, so
+     * it never becomes a room's "last message".
+     */
+    fun consume(
+        event: GeohashChatEvent,
+        relay: NormalizedRelayUrl?,
+        wasVerified: Boolean,
+    ): Boolean {
+        val geohash = event.geohash() ?: return false
+
+        val new = consumeRegularEvent(event, relay, wasVerified)
+
+        if (new) {
+            val note = getOrCreateNote(event.id)
+            val channel = getOrCreateGeohashChannel(geohash)
+            channel.addNote(note, relay)
+        }
+
+        return new
+    }
+
+    /**
+     * NIP-29 addressables (kinds 39000-39005) are authoritative for a group's metadata,
+     * roster, roles and pins ONLY when signed by the relay's own key — the NIP-11 `self`
+     * pubkey. This returns false only when we can positively tell an event is NOT relay-signed
+     * (the relay advertises a `self` and the event's author differs), so a stray or malicious
+     * user-published 39000/39001/… served by a lax relay can't overwrite a group's state (e.g.
+     * inject itself into the admin list). When `self` isn't known yet — the NIP-11 doc hasn't
+     * loaded, or the relay doesn't advertise one — we don't block, so legitimate groups still
+     * populate and this never regresses a relay whose key we simply haven't fetched.
+     */
+    private fun isRelaySignedGroupEvent(
+        event: Event,
+        relay: NormalizedRelayUrl,
+    ): Boolean {
+        val self =
+            Amethyst.instance.nip11Cache
+                .getFromCache(relay)
+                .self ?: return true
+        return event.pubKey == self
+    }
+
+    /**
+     * NIP-29 relay-signed group metadata (kind 39000). Stored as an addressable
+     * note and used to populate the [RelayGroupChannel]'s name/picture/about/
+     * flags. The group is keyed by (host relay + group id): unlike NIP-C7, a
+     * NIP-29 event does not carry its host relay in a tag — the host is the relay
+     * that served it — so the channel can only be associated when we know the
+     * serving relay (provenance). With no relay we still store the metadata.
+     */
+    fun consume(
+        event: GroupMetadataEvent,
+        relay: NormalizedRelayUrl?,
+        wasVerified: Boolean,
+    ): Boolean {
+        val new = consumeBaseReplaceable(event, relay, wasVerified)
+
+        if (relay != null && isRelaySignedGroupEvent(event, relay)) {
+            val note = getOrCreateAddressableNote(event.address())
+            val channel = getOrCreateRelayGroupChannel(GroupId(event.groupId(), relay))
+            (note.event as? GroupMetadataEvent)?.let { channel.updateGroupInfo(it, note) }
+        }
+
+        return new
+    }
+
+    /** NIP-29 relay-signed member list (kind 39002) → the group's roster. */
+    fun consume(
+        event: GroupMembersEvent,
+        relay: NormalizedRelayUrl?,
+        wasVerified: Boolean,
+    ): Boolean {
+        val new = consumeBaseReplaceable(event, relay, wasVerified)
+        if (relay != null && isRelaySignedGroupEvent(event, relay)) {
+            val latest = getOrCreateAddressableNote(event.address()).event as? GroupMembersEvent
+            latest?.let { getOrCreateRelayGroupChannel(GroupId(it.groupId(), relay)).updateMembers(it) }
+        }
+        return new
+    }
+
+    /** NIP-29 relay-signed admin list (kind 39001) → the group's roster. */
+    fun consume(
+        event: GroupAdminsEvent,
+        relay: NormalizedRelayUrl?,
+        wasVerified: Boolean,
+    ): Boolean {
+        val new = consumeBaseReplaceable(event, relay, wasVerified)
+        if (relay != null && isRelaySignedGroupEvent(event, relay)) {
+            val latest = getOrCreateAddressableNote(event.address()).event as? GroupAdminsEvent
+            latest?.let { getOrCreateRelayGroupChannel(GroupId(it.groupId(), relay)).updateAdmins(it) }
+        }
+        return new
+    }
+
+    /** NIP-29 relay-signed pinned-message list (kind 39005) → the group's pins. */
+    fun consume(
+        event: GroupPinnedEvent,
+        relay: NormalizedRelayUrl?,
+        wasVerified: Boolean,
+    ): Boolean {
+        val new = consumeBaseReplaceable(event, relay, wasVerified)
+        if (relay != null && isRelaySignedGroupEvent(event, relay)) {
+            val latest = getOrCreateAddressableNote(event.address()).event as? GroupPinnedEvent
+            latest?.let { getOrCreateRelayGroupChannel(GroupId(it.groupId(), relay)).updatePinned(it) }
+        }
+        return new
+    }
+
+    /** NIP-29 relay-declared supported roles (kind 39003) → the group's role set. */
+    fun consume(
+        event: SupportedRolesEvent,
+        relay: NormalizedRelayUrl?,
+        wasVerified: Boolean,
+    ): Boolean {
+        val new = consumeBaseReplaceable(event, relay, wasVerified)
+        if (relay != null && isRelaySignedGroupEvent(event, relay)) {
+            val latest = getOrCreateAddressableNote(event.address()).event as? SupportedRolesEvent
+            latest?.let { getOrCreateRelayGroupChannel(GroupId(it.groupId(), relay)).updateSupportedRoles(it) }
+        }
+        return new
+    }
+
+    /**
+     * Attach a group-scoped content event (a kind-9 chat, kind-1068 poll, …
+     * carrying an `h` tag) to its [RelayGroupChannel]. NIP-29 reuses the generic
+     * content kinds and scopes them with `h`, so the note is consumed normally
+     * and then, when it belongs to a group and we know the serving relay, added
+     * to that group's channel timeline.
+     */
+    private fun attachToRelayGroupIfScoped(
+        event: Event,
+        relay: NormalizedRelayUrl?,
+    ) {
+        val groupId = event.groupId() ?: return
+        val note = getOrCreateNote(event.id)
+        // Only attach a note we've actually loaded — never a placeholder for an
+        // unverified/not-yet-seen event. This is checked here (not via the "was
+        // newly consumed" flag) so the host relay's echo of an event we already
+        // stored from our own send still lands in the channel.
+        if (note.event == null) return
+
+        if (relay != null) {
+            val exact = GroupId(groupId, relay)
+            val existing = getRelayGroupChannelIfExists(exact)
+            if (existing != null) {
+                // Normal arrival: the group's host-pinned filters served it, so the serving relay IS the
+                // group's key and its channel already exists. Fast O(1) path — no scan.
+                existing.addNote(note, relay)
+            } else {
+                // No channel keyed to the serving relay: this may be a stray from a NON-host relay (e.g. a
+                // quoted kind-9 resolved by id). Redirect it to the group's single confirmed host rather
+                // than mint a phantom channel the group's screens never read (the serving-relay hazard);
+                // fall back to the serving-relay key when there is no single host (new/ambiguous group).
+                val target = redirectStrayRelayGroupContent(relayGroupCandidatesFor(groupId)) ?: exact
+                getOrCreateRelayGroupChannel(target).addNote(note, relay)
+            }
+        } else {
+            // Our own optimistic send has no provenance relay, so we can't build the (groupId,
+            // relay) key. Attach only when a SINGLE open channel has this group id (the room being
+            // composed in). When the id is ambiguous across relays — e.g. the relay-wide "_" group
+            // joined on several relays — skip: attaching to all of them bleeds the message into
+            // rooms it wasn't sent to. The host relay's echo (relay != null) lands it on the right key.
+            relayGroupChannels
+                .filter { key, _ -> key.id == groupId }
+                .singleOrNull()
+                ?.addNote(note, null)
+        }
+    }
+
+    /** Candidate group channels for the [redirectStrayRelayGroupContent] slow path — one scan by group id. */
+    private fun relayGroupCandidatesFor(groupId: String): List<RelayGroupTargetCandidate> =
+        relayGroupChannels
+            .filter { key, _ -> key.id == groupId }
+            .map { RelayGroupTargetCandidate(it.groupId, it.hasRelaySignedState()) }
+
+    /**
+     * Same routing as [attachToRelayGroupIfScoped] but for kind-11 threads, which
+     * are kept in a separate collection from the chat timeline so the two content
+     * types don't mix in one feed.
+     */
+    private fun attachThreadToRelayGroupIfScoped(
+        event: Event,
+        relay: NormalizedRelayUrl?,
+    ) {
+        val groupId = event.groupId() ?: return
+        val note = getOrCreateNote(event.id)
+        if (note.event == null) return
+
+        if (relay != null) {
+            val exact = GroupId(groupId, relay)
+            val existing = getRelayGroupChannelIfExists(exact)
+            if (existing != null) {
+                existing.addThread(note)
+            } else {
+                // Same serving-relay hazard as the chat path: prefer the single confirmed host over a phantom.
+                val target = redirectStrayRelayGroupContent(relayGroupCandidatesFor(groupId)) ?: exact
+                getOrCreateRelayGroupChannel(target).addThread(note)
+            }
+        } else {
+            // See attachToRelayGroupIfScoped: only attach when the group id is unambiguous.
+            relayGroupChannels
+                .filter { key, _ -> key.id == groupId }
+                .singleOrNull()
+                ?.addThread(note)
+        }
+    }
+
     fun consume(
         event: LiveActivitiesChatMessageEvent,
         relay: NormalizedRelayUrl?,
@@ -2518,7 +2874,6 @@ object LocalCache : ILocalCache, ICacheProvider {
             }
         } catch (e: Exception) {
             if (e is CancellationException) throw e
-            null
         }
 
         return liveChatChannels.filter { _, channel ->
@@ -2642,6 +2997,10 @@ object LocalCache : ILocalCache, ICacheProvider {
             pruneHiddenMessagesChannel(channel, account)
         }
 
+        geohashChannels.forEach { _, channel ->
+            pruneHiddenMessagesChannel(channel, account)
+        }
+
         liveChatChannels.forEach { _, channel ->
             pruneHiddenMessagesChannel(channel, account)
         }
@@ -2649,6 +3008,10 @@ object LocalCache : ILocalCache, ICacheProvider {
         publicChatChannels.forEach { _, channel ->
             pruneHiddenMessagesChannel(channel, account)
         }
+
+        relayGroupChannels.forEach { _, channel ->
+            pruneHiddenMessagesChannel(channel, account)
+        }
     }
 
     // 2× the 10-min `PRESENCE_FRESHNESS_WINDOW_SECONDS` used by
@@ -2691,6 +3054,10 @@ object LocalCache : ILocalCache, ICacheProvider {
             pruneOldMessagesChannel(channel)
         }
 
+        geohashChannels.forEach { _, channel ->
+            pruneOldMessagesChannel(channel)
+        }
+
         liveChatChannels.forEach { _, channel ->
             pruneOldMessagesChannel(channel)
         }
@@ -2699,6 +3066,10 @@ object LocalCache : ILocalCache, ICacheProvider {
             pruneOldMessagesChannel(channel)
         }
 
+        relayGroupChannels.forEach { _, channel ->
+            pruneOldMessagesChannel(channel)
+        }
+
         chatroomList.forEach { userHex, room ->
             // History floors are pinned per scope on first advance; null means that window never paged
             // history, so its cursors hold no position to misalign and nothing needs rewinding. Only the
@@ -2992,7 +3363,28 @@ object LocalCache : ILocalCache, ICacheProvider {
             }
         }
 
-        note?.addRelay(relay)
+        note?.let { addRelayToNoteAndInners(it, relay) }
+    }
+
+    /**
+     * Adds [relay] to [note] and to every already-unwrapped inner note of its
+     * gift-wrap chain (wrap → seal → rumor). The chat UI renders the inner
+     * rumor, so a relay recorded only on the outer envelope never surfaces as
+     * an icon. Inner notes that don't exist yet are not lost: the unwrap path
+     * copies the envelope's relays down via [copyRelaysFromTo] when it runs.
+     */
+    fun addRelayToNoteAndInners(
+        note: Note,
+        relay: NormalizedRelayUrl,
+    ) {
+        note.addRelay(relay)
+
+        val noteEvent = note.event
+        if (noteEvent is HasInnerEvent) {
+            noteEvent.innerEventId?.let { innerId ->
+                getNoteIfExists(innerId)?.let { addRelayToNoteAndInners(it, relay) }
+            }
+        }
     }
 
     // Observers line up here.
@@ -3019,10 +3411,28 @@ object LocalCache : ILocalCache, ICacheProvider {
         live.removedNote(newNote)
     }
 
+    /**
+     * Resource-usage ledger hook: called with (elapsedNanos, valid) for every
+     * signature verification so the app can account crypto CPU per day.
+     * Wired by AppModules like [onchainBackend]; null costs nothing.
+     */
+    @Volatile
+    var verifyMeter: ((elapsedNanos: Long, valid: Boolean) -> Unit)? = null
+
     fun justVerify(event: Event): Boolean {
         checkNotInMainThread()
 
-        return if (!event.verify()) {
+        val meter = verifyMeter
+        if (meter == null) return justVerifyInner(event)
+
+        val start = System.nanoTime()
+        val valid = justVerifyInner(event)
+        meter(System.nanoTime() - start, valid)
+        return valid
+    }
+
+    private fun justVerifyInner(event: Event): Boolean =
+        if (!event.verify()) {
             try {
                 event.checkSignature()
             } catch (e: Exception) {
@@ -3033,7 +3443,6 @@ object LocalCache : ILocalCache, ICacheProvider {
         } else {
             true
         }
-    }
 
     fun consume(
         event: DraftWrapEvent,
@@ -3484,6 +3893,14 @@ object LocalCache : ILocalCache, ICacheProvider {
                     consumeBaseReplaceable(event, relay, wasVerified)
                 }
 
+                is BirdDetectionEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is Ps1SaveEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
                 is CommentEvent -> {
                     consumeRegularEvent(event, relay, wasVerified)
                 }
@@ -3524,10 +3941,101 @@ object LocalCache : ILocalCache, ICacheProvider {
                     consume(event, relay, wasVerified)
                 }
 
+                is GeohashChatEvent -> {
+                    consume(event, relay, wasVerified)
+                }
+
                 is EphemeralChatListEvent -> {
                     consumeBaseReplaceable(event, relay, wasVerified)
                 }
 
+                // NIP-51 "simple groups" list (kind 10009): the user's joined NIP-29 groups +
+                // servers. Replaceable like its sibling lists; RelayGroupListState reads it from the
+                // addressable cache, so it must be stored (it was silently dropped before).
+                is SimpleGroupListEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
+                // Concord private joined-communities list (kind 13302). Replaceable, self-encrypted;
+                // ConcordChannelListState observes it via the addressable cache (Address(13302, me, "")),
+                // so — exactly like the 10009 list above — it must be stored replaceably or the Concord
+                // hub stays empty even after the event arrives.
+                is ConcordCommunityListEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
+                is GroupMetadataEvent -> {
+                    consume(event, relay, wasVerified)
+                }
+
+                is GroupMembersEvent -> {
+                    consume(event, relay, wasVerified)
+                }
+
+                is GroupAdminsEvent -> {
+                    consume(event, relay, wasVerified)
+                }
+
+                is GroupPinnedEvent -> {
+                    consume(event, relay, wasVerified)
+                }
+
+                // 39003 (relay-declared roles) is durable group state like 39000/39001/39002:
+                // route it onto the channel so a moderation UI can offer the relay's role set.
+                is SupportedRolesEvent -> {
+                    consume(event, relay, wasVerified)
+                }
+
+                // Remaining NIP-29 relay-group kinds. The relay-signed 39004 AV-participants
+                // addressable is durable group state, so it's stored replaceably. The 9xxx
+                // moderation actions and join/leave requests are regular one-shot events the
+                // relay is authoritative for (it applies them and republishes the
+                // 39000/39001/39002); we store them so they're queryable and don't fall through
+                // to the "Not Supported" warning, but we don't act on them client-side.
+                is GroupParticipantsEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
+                is PutUserEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is RemoveUserEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is EditMetadataEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is DeleteEventEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is UpdatePinListEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is DeleteGroupEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is CreateGroupEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is CreateInviteEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is JoinRequestEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
+                is LeaveRequestEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified)
+                }
+
                 is ExternalIdentitiesEvent -> {
                     consumeBaseReplaceable(event, relay, wasVerified)
                 }
@@ -3573,7 +4081,15 @@ object LocalCache : ILocalCache, ICacheProvider {
                 }
 
                 is GiftWrapEvent -> {
-                    consumeRegularEvent(event, relay, wasVerified)
+                    // A wrap with an empty content carries no NIP-44 ciphertext and can
+                    // never be unwrapped — reject it before paying for a signature check
+                    // and a cache slot. Locally stripped copies (copyNoContent) are
+                    // assigned straight to note.event and never pass through here.
+                    if (event.content.isEmpty()) {
+                        false
+                    } else {
+                        consumeRegularEvent(event, relay, wasVerified)
+                    }
                 }
 
                 is GroupEvent -> {
@@ -3624,6 +4140,14 @@ object LocalCache : ILocalCache, ICacheProvider {
                     consumeBaseReplaceable(event, relay, wasVerified)
                 }
 
+                is RootNappletEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
+                is NamedNappletEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
                 is ChessGameEvent -> {
                     consumeRegularEvent(event, relay, wasVerified)
                 }
@@ -3741,7 +4265,12 @@ object LocalCache : ILocalCache, ICacheProvider {
                 }
 
                 is PodcastMetadataEvent -> {
-                    consumeBaseReplaceable(event, relay, wasVerified)
+                    // Drop the known "Mock Podcast" spam flood instead of caching thousands of them.
+                    if (event.isMockSpam()) {
+                        false
+                    } else {
+                        consumeBaseReplaceable(event, relay, wasVerified)
+                    }
                 }
 
                 is AuthoredPodcastsEvent -> {
@@ -3752,6 +4281,14 @@ object LocalCache : ILocalCache, ICacheProvider {
                     consumeBaseReplaceable(event, relay, wasVerified)
                 }
 
+                is Podcasting20EpisodeEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
+                is Podcasting20TrailerEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
                 is LnZapEvent -> {
                     consume(event, relay, wasVerified)
                 }
@@ -3861,11 +4398,25 @@ object LocalCache : ILocalCache, ICacheProvider {
                 }
 
                 is ChatEvent -> {
-                    consumeRegularEvent(event, relay, wasVerified)
+                    consumeRegularEvent(event, relay, wasVerified).also {
+                        // Attach on every arrival, not just the newly-consumed one:
+                        // our own send is consumed first with a null relay, so the
+                        // host relay's later echo (new == false) is what carries the
+                        // provenance needed to key the channel. attach is idempotent.
+                        attachToRelayGroupIfScoped(event, relay)
+                    }
                 }
 
                 is PollEvent -> {
-                    consumeRegularEvent(event, relay, wasVerified)
+                    consumeRegularEvent(event, relay, wasVerified).also {
+                        attachToRelayGroupIfScoped(event, relay)
+                    }
+                }
+
+                is ThreadEvent -> {
+                    consumeRegularEvent(event, relay, wasVerified).also {
+                        attachThreadToRelayGroupIfScoped(event, relay)
+                    }
                 }
 
                 is PollResponseEvent -> {
@@ -4004,6 +4555,10 @@ object LocalCache : ILocalCache, ICacheProvider {
                     consumeRegularEvent(event, relay, wasVerified)
                 }
 
+                is ExerciseTemplateEvent -> {
+                    consumeBaseReplaceable(event, relay, wasVerified)
+                }
+
                 is PaymentTargetsEvent -> {
                     consume(event, relay, wasVerified)
                 }