v.1.12.5

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/CLAUDE.md

@@ -12,14 +12,27 @@ architecture while sharing the back end components with the android counterpart.
 a non-interactive JVM command-line client that drives the same `quartz` + `commons` code — used by
 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. `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
+exists. `geode` is a standalone JVM Nostr relay (Ktor) built on quartz's
+relay-server code; smaller modules are `benchmark` (Android macrobenchmarks) 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
 production listener AND speaker paths both run on moq-lite to interop with the
 nostrnests reference relay. The IETF code is kept as a reference + unit-test
 implementation for any future IETF target; see
 `nestsClient/plans/2026-04-26-moq-lite-gap.md`.
 
+Canonical NIP specs live at <https://github.com/nostr-protocol/nips> — use
+`/nip <number>` to pull a specific one (it fetches the spec file directly).
+
+## Verify, Don't Guess
+
+Don't assert a diagnosis you haven't reproduced. This repo gives you cheap
+verification tools: `./gradlew test`, per-module test suites, and the `amy`
+CLI (built partly to drive `quartz`/`commons` for interop checks). If a
+claim is checkable in under a minute, check it before stating it — write
+the failing case first, watch it fail, then explain.
+
 ## Architecture
 
 ```
@@ -40,10 +53,11 @@ amethyst/
 │       ├── commonMain/    # Protocol, frame/packet codecs, TLS state machine
 │       ├── jvmAndroid/    # JCA-backed AEAD + UDP socket actuals
 │       └── commonTest/    # RFC vector + adversarial tests
-├── nestsClient/    # Audio-room client (IETF MoQ-transport today; moq-lite phase pending)
+├── nestsClient/    # Audio-room client (production runs on moq-lite; IETF MoQ kept as reference)
 │   └── src/
 │       ├── commonMain/    # MoQ session, NestsListener, audio glue
 │       └── jvmAndroid/    # Opus encode/decode, AudioRecord/AudioTrack
+├── geode/          # Standalone JVM Nostr relay (Ktor) on quartz's relay-server code
 ├── desktopApp/     # Desktop JVM application (layouts, navigation)
 ├── amethyst/       # Android app (layouts, navigation)
 └── cli/            # Amy — non-interactive CLI (JVM only, no Compose)
@@ -51,7 +65,12 @@ amethyst/
 
 **Sharing Philosophy:**
 - `quartz/` = Nostr business logic, protocol, data (no UI)
-- `commons/` = Shared UI components, icons, composables, flows and ViewModels
+- `commons/` = Shared code for every front end (Android, Desktop, iOS, and the
+  headless `cli`): domain models, state holders, ViewModels, the relay client,
+  shared services, **and** the Compose UI that ≥1 GUI front end renders. The
+  package taxonomy, the CLI-safe / UI boundary, and a "where does my code go?"
+  guide are documented in **`commons/ARCHITECTURE.md`** — read it before adding
+  a new package or dropping code into `commons`.
 - `quic/` = Transport library (QUIC + HTTP/3 + WebTransport); reusable for any
   KMP project that needs MoQ. Has no Android-framework dependencies.
 - `nestsClient/` = MoQ + audio-rooms client; takes `:quic` as transport,
@@ -65,191 +84,62 @@ The global `docs/plans/` folder is frozen — don't add new plans there.
 
 ## Tech Stack
 
+Exact versions live in `gradle/libs.versions.toml` (the source of truth — check
+there rather than trusting a number copied here).
+
 | Layer | Technology |
 |-------|------------|
 | **Core** | Quartz (Nostr KMP) |
-| **UI** | Compose Multiplatform 1.10.3 |
+| **UI** | Compose Multiplatform |
 | **Async** | kotlinx.coroutines + Flow |
 | **Network** | OkHttp (JVM) |
 | **Serialization** | Jackson |
 | **DI** | Manual / Koin |
-| **Build** | Gradle 8.x, Kotlin 2.3.20 |
+| **Build** | Gradle + Kotlin Multiplatform |
 
 ## Skills
 
-Specialized skills provide domain expertise with bundled resources and patterns:
+The full list of available skills (with descriptions and triggers) is injected
+into every session, so it isn't duplicated here. Two kinds exist and are meant
+to be used together:
 
-| Skill | Expertise | When to Use |
-|-------|-----------|-------------|
-| `nostr-expert` | Nostr protocol (Quartz library) | Event types, NIPs, tags, signing, Bech32, NIP-44, LargeCache |
-| `kotlin-expert` | Advanced Kotlin patterns | StateFlow, sealed classes, @Immutable, DSLs, common utilities |
-| `kotlin-coroutines` | Advanced async patterns | supervisorScope, callbackFlow, relay pools, testing |
-| `kotlin-multiplatform` | Platform abstraction | expect/actual, source sets, sharing decisions |
-| `compose-expert` | Shared UI components | Material3, state hoisting, recomposition, rich-text parsing |
-| `android-expert` | Android platform | Navigation, permissions, lifecycle, Material3, Coil image loading |
-| `desktop-expert` | Desktop platform | Window, MenuBar, keyboard shortcuts, DeckLayout |
-| `gradle-expert` | Build system | Dependencies, versioning, packaging, optimization |
-| `account-state` | `Account` + `LocalCache` | Per-user StateFlows, event store, adding account-scoped settings |
-| `relay-client` | Subscriptions & filter assembly | `ComposeSubscriptionManager`, assemblers, preloaders, EOSE |
-| `feed-patterns` | Feeds & DAL | `FeedFilter`, `AdditiveComplexFeedFilter`, `FeedViewModel` family |
-| `auth-signers` | `NostrSigner` implementations | Local, NIP-46 bunker, NIP-55 Android external signer |
-| `quartz-integration` | Quartz as an external library | Gradle setup, `NostrClient`, `KeyPair`, for external projects |
-| `amy-expert` | Amy CLI (`cli/` module) | Adding `amy <verb>` commands, JSON output contract, extracting logic from `amethyst/` into `commons/` so CLI can call it |
-| `find-missing-translations` | Utility | Extract untranslated Android strings |
-| `find-non-lambda-logs` | Utility | Audit Log calls for lambda overloads |
-
-### Technique-layer skills (Compose / Kotlin best practices)
-
-These are general Compose/Kotlin decision-framework skills (vendored from
-`chrisbanes/skills`). The skills above are **codebase-oriented** ("where is X in
-Amethyst, what pattern do we use"); these are **technique-oriented** ("what is
-the correct Compose/Kotlin design here"). They complement — not replace — the
-codebase skills: e.g. `compose-expert` tells you where shared composables live,
-`compose-slot-api-pattern` tells you how to shape their public API.
-
-| Skill | Expertise | Complements |
-|-------|-----------|-------------|
-| `compose-recomposition-performance` | Router: which recomposition axis is the problem | `compose-expert` |
-| `compose-stability-diagnostics` | Compiler reports, strong skipping, `ImmutableList` at UI boundaries | `compose-expert`, `kotlin-expert` |
-| `compose-state-deferred-reads` | Phase-aware state reads, block-form modifiers, provider lambdas | `compose-expert` |
-| `compose-slot-api-pattern` | `@Composable` slot design for reusable components | `compose-expert` |
-| `compose-modifier-and-layout-style` | `modifier` parameter conventions, chain construction, conditional hoisting | `compose-expert` |
-| `compose-side-effects` | `LaunchedEffect`/`DisposableEffect`/`SideEffect`, keys, `rememberUpdatedState` | `compose-expert` |
-| `compose-state-holder-ui-split` | State-holder vs plain-UI composable split | `compose-expert`, `feed-patterns` |
-| `kotlin-flow-state-event-modeling` | StateFlow/SharedFlow/Channel choice, sentinels, `stateIn`, `update {}` | `kotlin-expert` |
-| `kotlin-coroutines-structured-concurrency` | Stored-scope anti-pattern, `suspend` boundaries, `runBlocking`, cancellation | `kotlin-coroutines` |
-| `kotlin-types-value-class` | `@JvmInline value class` vs `data class`, Compose stability | `kotlin-expert` |
-
-## Workflow
-
-**When you ask for a feature:**
-
-1. **Quick skill assessment** - I identify which skills are relevant
-2. **Propose which skills** - I present which skills I'll use for the task
-3. **Get approval** - You review and approve (or adjust) the skill selection
-4. **Review plan using approved skills** - I invoke the approved skills to create detailed implementation plan
-5. **Execute with skills** - Skills collaborate to implement the feature
-
-**Example:**
-```
-You: "Add video support to notes"
-Me: "I'll use:
-     - /nostr-expert (NIP-71 video events)
-     - /compose-expert (video player UI)
-     - /android-expert (platform video APIs)
-     Proceed?"
-You: "yes"
-Me: [invokes skills to create plan]
-     "Plan from skills:
-      1. nostr-expert: Use NIP-71 kind 34235 for video events...
-      2. compose-expert: Create VideoPlayer composable in commons...
-      3. android-expert: Use ExoPlayer for Android...
-      Proceed with implementation?"
-You: "yes"
-Me: [implements using skill guidance]
-```
-
-## Commands
-
-- `/desktop-run` - Build and run desktop app
-- `/nip <number>` - Get NIP implementation guidance
+- **Codebase-oriented** skills (`nostr-expert`, `compose-expert`, `feed-patterns`,
+  `account-state`, `amy-expert`, …) answer "where is X in Amethyst, what pattern
+  do we use here."
+- **Technique-oriented** skills (vendored from `chrisbanes/skills`, e.g.
+  `compose-slot-api-pattern`, `kotlin-flow-state-event-modeling`) answer "what is
+  the correct Compose/Kotlin design." They complement, not replace, the codebase
+  skills: `compose-expert` tells you where shared composables live;
+  `compose-slot-api-pattern` tells you how to shape their public API.
 
 ## Feature Workflow
 
-**CRITICAL: Always check existing implementations first before creating new code!**
+**CRITICAL: Check existing implementations first — most logic already exists.**
+Before writing code, survey all modules (use Grep/Explore) for managers, caches,
+state systems, filters, ViewModels, and composables that already do the job. Your
+job is usually to **reuse** (`quartz` protocol/business logic), **extract**
+(Android UI/ViewModels → `commons`), and add **platform-specific** layouts/nav —
+not to duplicate existing managers, caches, or state.
 
-When picking up a new task or feature, follow this process:
+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.
 
-### Step 0: Survey Existing Implementation (MANDATORY)
+**Share vs keep platform-native:**
 
-**Before writing ANY code, thoroughly audit ALL modules:**
+- **Share** → `quartz/commonMain/` (business logic, data models, protocol) and
+  `commons/commonMain/` (major UI components, **ViewModels** under
+  `viewmodels/`, icons). ViewModels are platform-agnostic state + logic
+  (StateFlow/SharedFlow), so they belong in `commons`.
+- **Keep native** → screen composables/scaffolding (Desktop `Window` vs Android
+  `Activity`), navigation (sidebar vs bottom nav), platform interactions
+  (gestures, keyboard shortcuts), system integrations (notifications, file
+  pickers).
 
-1. **Search for existing implementations across all modules:**
-   ```bash
-   # Search in quartz for protocol/business logic
-   grep -r "class.*Manager\|object.*Cache\|class.*Filter" quartz/src/commonMain/
-
-   # Search in commons for UI components
-   grep -r "@Composable.*Card\|@Composable.*View\|@Composable.*Dialog" commons/src/
-
-   # Search in amethyst for Android patterns
-   grep -r "class.*ViewModel\|class.*Account\|class.*State" amethyst/src/main/java/
-
-   # Search for specific functionality
-   grep -r "fun isFollowing\|fun subscribe\|fun getMetadata" {quartz,commons,amethyst}/src/
-   ```
-
-2. **Understand existing architecture patterns:**
-   - Event stores and caching systems
-   - State management patterns (StateFlow, mutable states)
-   - ViewModel patterns and lifecycle handling
-   - Filter builders and relay subscription patterns
-   - UI component hierarchies
-
-3. **Key principle:** Most logic already exists! Your job is to:
-   - **Reuse** existing protocol/business logic from quartz
-   - **Extract** shareable UI components AND ViewModels from amethyst to commons
-   - Create **platform-specific** layouts/navigation for Desktop
-   - **NOT** duplicate existing managers, caches, or state systems
-
-4. **Document findings in implementation plan as a matrix:**
-
-   | File/Component | Status | Location | Action |
-   |----------------|--------|----------|--------|
-   | FilterBuilders | ✅ Exists | quartz/relay/filters/ | Reuse as-is |
-   | NoteCard | 📦 Extract | amethyst/ui/note/ → commons/ | Extract to commons |
-   | HomeFeedViewModel | 📦 Extract | amethyst/ → commons/commonMain/viewmodels/ | Extract to commons |
-   | ProfileCache | ⚠️ Avoid | N/A | Already in User/Account pattern |
-
-   **Legend:**
-   - ✅ **Reuse** - Exists and can be used directly
-   - 📦 **Extract** - Exists in Android, needs extraction to commons
-   - 🆕 **New** - Doesn't exist, needs creation (platform-specific only)
-   - ⚠️ **Avoid** - Duplicate functionality, use existing pattern instead
-
-### Step 1: Analyze Android Implementation
-
-After surveying (Step 0), deeply examine the Android implementation:
-1. Find the relevant feature/component in `amethyst/` module
-2. Understand the current implementation patterns
-3. Identify dependencies and integrations
-4. Map out what code can be shared vs platform-specific
-
-### Step 2: Create Implementation Plan
-
-Before coding, create a plan that categorizes work into three buckets:
-
-| Category | Description | Location |
-|----------|-------------|----------|
-| **Android-Specific** | Platform-native layouts, navigation patterns | `amethyst/`, `androidMain/` |
-| **Reusable (Shared)** | Business logic, UI components, **ViewModels**, state management | `quartz/commonMain/`, `commons/commonMain/` |
-| **Desktop-Specific** | Desktop-native layouts, navigation patterns, platform APIs | `desktopApp/`, `jvmMain/` |
-
-### Step 3: Code Sharing Strategy
-
-**Share:**
-- Business logic and data models → `quartz/commonMain/`
-- Major UI components (cards, lists, dialogs) → `commons/commonMain/`
-- **ViewModels** (state, business logic) → `commons/commonMain/viewmodels/`
-- Icons and visual assets → `commons/commonMain/`
-
-**Keep Platform-Native:**
-- **Screen composables** (layout, scaffolding) - Desktop uses `Window`, Android uses `Activity`
-- Navigation patterns (sidebar vs bottom nav)
-- Platform-specific interactions (gestures, keyboard shortcuts)
-- System integrations (notifications, file pickers)
-
-**Rationale:** ViewModels contain platform-agnostic state management (StateFlow/SharedFlow) and business logic. Screens consume ViewModels but render differently (Desktop sidebar + content area vs Android bottom nav).
-
-### Step 4: Extract Shared Components
-
-When extracting UI components:
-1. Identify reusable composables in Android code
-2. Move to `commons/commonMain/` (consult `/compose-expert` for patterns)
-3. Create expect/actual declarations for platform-specific behavior (consult `/kotlin-multiplatform`)
-4. Update both Android and Desktop to use shared component
-
-**Note:** `quartz/` is protocol-only (no composables). Shared UI goes in `commons/` after converting it to KMP.
+When extracting a composable: move it to `commons/commonMain/` (see
+`/compose-expert`), add expect/actual for any platform behavior (see
+`/kotlin-multiplatform`), then point both Android and Desktop at the shared
+version. `quartz/` is protocol-only — no composables.
 
 ## Build Commands
 
@@ -270,41 +160,65 @@ When extracting UI components:
 ./gradlew spotlessApply
 ```
 
+## Dependency Licensing
+
+**MANDATORY whenever you introduce a new third-party dependency** — in *any*
+module (`quartz`, `commons`, `amethyst`, `desktopApp`, `cli`, `quic`,
+`nestsClient`, …), whether you add it to `gradle/libs.versions.toml` or to a
+module's `build.gradle.kts`: determine its license **before** wiring it in.
+Amethyst ships under the **MIT** license, so a copyleft dependency linked into a
+distributed artifact (APK, desktop binary) can force that artifact's
+combined-work terms onto the whole project.
+
+Verify against the dependency's actual `LICENSE`/`COPYING` file or its published
+POM — **not from memory**. Then classify and act:
+
+- **Permissive** (MIT, Apache-2.0, BSD, ISC, MPL-2.0, zlib, …) → **OK**,
+  proceed.
+- **LGPL, or GPL/EPL with a linking / Classpath exception** → **WARN.**
+  Acceptable to link (the exception keeps our own code MIT), but call it out in
+  your summary so the human knows. Confirm the exception actually exists in the
+  LICENSE text — don't assume it does.
+- **Stricter than LGPL** — GPL/AGPL **without** a linking exception, SSPL,
+  proprietary/commercial-only, or anything where the linking-exception check is
+  "no" → **STRONGLY WARN and STOP.** Do not add it silently. Surface it
+  prominently and **require an explicit call-out in the PR description** so a
+  maintainer makes the decision. Prefer a permissive alternative, a clean-room
+  implementation, or dropping the feature.
+
+For any GPL-family hit the decisive question is always **"is there a linking
+(LGPL/Classpath) exception?"** — that is what separates a WARN from a STOP.
+(Example: TarsosDSP, GPLv3 with no exception, was removed from `amethyst` and
+replaced with an in-house pitch shifter for exactly this reason.)
+
 ## Quartz KMP Structure
 
-The Quartz library uses expect/actual for platform-specific implementations:
+Quartz uses expect/actual for platform-specific implementations (e.g. crypto
+backed by `secp256k1-kmp-jni-android` on Android and `secp256k1-kmp-jni-jvm` on
+JVM). See `/kotlin-multiplatform` for the expect/actual and source-set patterns.
 
-```kotlin
-// commonMain - shared protocol logic
-expect class CryptoProvider {
-    fun sign(message: ByteArray, privateKey: ByteArray): ByteArray
-    fun verify(message: ByteArray, signature: ByteArray, publicKey: ByteArray): Boolean
-}
+## Icons
 
-// androidMain - uses secp256k1-kmp-jni-android
-actual class CryptoProvider { /* Android implementation */ }
+The Material Symbols font bundled at
+`commons/src/commonMain/composeResources/font/material_symbols_outlined.ttf`
+is a **subset** that only contains the glyphs referenced from
+`commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/icons/symbols/MaterialSymbols.kt`.
 
-// jvmMain - uses secp256k1-kmp-jni-jvm
-actual class CryptoProvider { /* JVM implementation */ }
+**MANDATORY:** Whenever you add a new icon — i.e. introduce a
+`MaterialSymbol("\uXXXX")` codepoint that wasn't already referenced anywhere in
+`MaterialSymbols.kt` — you MUST regenerate the subset font by running:
+
+```bash
+./tools/material-symbols-subset/subset.sh
 ```
 
-## Key Patterns
+Commit the regenerated `material_symbols_outlined.ttf` alongside your
+`MaterialSymbols.kt` change. Without this step the new icon renders as tofu (□)
+at runtime because the glyph is not in the bundled font.
 
-### Platform Abstraction
-```kotlin
-// commonMain
-expect fun openExternalUrl(url: String)
-
-// androidMain
-actual fun openExternalUrl(url: String) {
-    context.startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
-}
-
-// jvmMain (Desktop)
-actual fun openExternalUrl(url: String) {
-    Desktop.getDesktop().browse(URI(url))
-}
-```
+Reusing a codepoint already present in `MaterialSymbols.kt` does NOT require
+regenerating. See `tools/material-symbols-subset/README.md` for details and
+prerequisites (`pip install fonttools brotli`).
 
 ## Code Formatting
 After completing any task that modifies Kotlin files, always run:
@@ -329,12 +243,5 @@ Do this before considering the task complete.
 
 ## Git Workflow
 
-- Branch: `feat/desktop-<feature>` or `fix/desktop-<issue>`
 - Commits: Conventional commits (`feat:`, `fix:`, etc.)
 - Never use `--no-verify`
-
-## Resources
-
-- [Nostr NIPs](https://github.com/nostr-protocol/nips)
-- [Compose Multiplatform](https://www.jetbrains.com/compose-multiplatform/)
-- [KMP Documentation](https://kotlinlang.org/docs/multiplatform.html)

.claude/commands/desktop-run.md

@@ -12,7 +12,7 @@ Build and run the Amethyst Desktop application:
 
 If the build fails, check:
 
-1. **JDK Version**: Requires JDK 17+
+1. **JDK Version**: Requires JDK 21+ (`jvmToolchain(21)` in `desktopApp/build.gradle.kts`)
    ```bash
    java -version
    ```
@@ -39,7 +39,7 @@ If the build fails, check:
 ./gradlew :desktopApp:packageMsi
 
 # Linux
-./gradlew :desktopApp:packageDeb
+./gradlew :desktopApp:packageDeb   # or :desktopApp:packageRpm
 ```
 
-Outputs will be in `desktopApp/build/compose/binaries/`
+Outputs will be in `desktopApp/build/compose/binaries/main/`

.claude/commands/extract.md

@@ -8,7 +8,7 @@ Extract the component `$ARGUMENTS` from the Android app to shared KMP code:
 
 1. **Locate the component** in the amethyst module:
    ```bash
-   find amethyst/src -name "*$ARGUMENTS*" -o -name "*$ARGUMENTS*"
+   find amethyst/src -name "*$ARGUMENTS*"
    grep -r "fun $ARGUMENTS\|class $ARGUMENTS" amethyst/src/
    ```
 
@@ -18,7 +18,7 @@ Extract the component `$ARGUMENTS` from the Android app to shared KMP code:
    - Android Compose specifics vs standard Compose
 
 3. **Identify what can be shared**:
-   - Pure Composable functions → `shared-ui/commonMain/`
+   - Pure Composable functions → `commons/commonMain/`
    - Business logic → `quartz/commonMain/`
    - Platform-specific → create expect/actual
 

.claude/core-skills-plan.md

@@ -1,339 +1,37 @@
-# AmethystMultiplatform Skills Creation Plan
-
-## Overview
-Create 8 hybrid domain skills combining general expertise with AmethystMultiplatform-specific patterns.
-
-**Approach:** Each skill provides domain knowledge + project-specific implementation patterns from codebase.
-
-## Skills to Implement
-
-### 1. kotlin-multiplatform ✅ COMPLETED
-**Focus:** KMP architecture, jvmAndroid source set pattern, expect/actual
-
-**SKILL.md sections:**
-- Mental model: KMP hierarchy as dependency graph
-- Source set architecture: commonMain → jvmAndroid → {androidMain, jvmMain}
-- The jvmAndroid pattern (unique to this project, verified in quartz/build.gradle.kts:132-149)
-- expect/actual mechanics with 24+ examples from codebase
-- iOS framework setup for Quartz distribution
-
-**Bundled resources:**
-- `references/source-set-hierarchy.md` - Visual diagram + examples
-- `references/expect-actual-catalog.md` - All 24 expect/actual pairs with patterns
-- `scripts/validate-kmp-structure.sh` - Verify source set dependencies
-- `assets/kmp-hierarchy-diagram.png` - Visual graph
-
-**Differentiation:** Existing kotlin-multiplatform agent = general KMP. This skill = Amethyst's unique jvmAndroid pattern, concrete examples.
-
-**Status:** ✅ Skill created and packaged at `.claude/skills/kotlin-multiplatform/`
-
----
-
-### 2. gradle-expert ✅ COMPLETED
-**Focus:** Build optimization, dependency resolution, multi-module KMP troubleshooting
-
-**SKILL.md sections:**
-- Build architecture: 4 modules, dependency flow
-- Version catalog mastery (libs.versions.toml)
-- Module dependency patterns (api vs implementation)
-- Android-specific: compileSdk, proguard
-- Desktop packaging: TargetFormat, distributions
-- Build performance: daemon, parallel, caching
-- Common errors: compose version conflicts, secp256k1 JNI variants
-
-**Bundled resources:**
-- `references/build-commands.md` - Common gradle tasks
-- `references/dependency-graph.md` - Module visualization
-- `references/version-catalog-guide.md` - Version catalog patterns
-- `references/common-errors.md` - Troubleshooting guide
-- `scripts/analyze-build-time.sh` - Performance report
-- `scripts/fix-dependency-conflicts.sh` - Conflict patterns
-
-**Differentiation:** Focus on 4-module structure, KMP + Android + Desktop combo, specific issues (compose conflicts).
-
-**Status:** ✅ SKILL.md (549 lines) + 4 references + 2 scripts created at `.claude/skills/gradle-expert/`
-
----
-
-### 3. kotlin-expert ✅ DRAFT COMPLETE
-**Focus:** Flow state management, sealed hierarchies, immutability, DSL builders, inline/reified
-
-**SKILL.md sections:**
-- Flow state management: StateFlow/SharedFlow patterns (AccountManager, RelayConnectionManager)
-- Sealed hierarchies: sealed class vs sealed interface decision trees (AccountState, SignerResult)
-- Immutability: @Immutable for Compose performance (173+ event classes)
-- DSL builders: Type-safe fluent APIs (TagArrayBuilder, TlvBuilder)
-- Inline functions: reified generics, performance optimization (OptimizedJsonMapper)
-- Value classes: Zero-cost wrappers (optimization opportunity)
-
-**Bundled resources:**
-- `references/flow-patterns.md` - StateFlow/SharedFlow with AccountManager, RelayManager patterns
-- `references/sealed-class-catalog.md` - All 8 sealed types in quartz with usage patterns
-- `references/dsl-builder-examples.md` - TagArrayBuilder, PrivateTagArrayBuilder, TlvBuilder, custom DSL patterns
-- `references/immutability-patterns.md` - @Immutable annotation, data classes, ImmutableList/Map/Set
-
-**Differentiation:** Complements kotlin-coroutines agent (deep async). This skill = Amethyst Kotlin idioms (StateFlow state management, sealed for type safety, @Immutable for Compose, DSL builders).
-
-**Status:** ✅ SKILL.md (455 lines) + 4 references created at `.claude/skills/kotlin-expert/`
-
-**10-Step Progress:**
-1. ✅ UNDERSTAND - Defined scope (Flow/sealed/DSL/immutability/inline)
-2. ✅ EXPLORE - Found 173 @Immutable events, StateFlow in AccountManager/RelayManager, SignerResult generics, TagArrayBuilder
-3. ✅ RESEARCH - StateFlow vs SharedFlow, sealed class vs interface best practices 2025
-4. ✅ SYNTHESIZE - Extracted Amethyst patterns (hot flows for state, sealed for results, @Immutable for perf)
-5. ✅ DRAFT - Created SKILL.md + 4 reference files (flow, sealed, dsl, immutability)
-6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
-7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
-8. ⏸️ TEST - Deferred to later (requires real usage scenarios)
-9. ⏸️ FINALIZE - Deferred to later
-10. ✅ DOCUMENT - Updated plan
-
----
-
-### 4. compose-expert ✅ COMPLETED
-**Focus:** Shared composables, state management, animations, Material3
-
-**SKILL.md sections:**
-- Shared composables philosophy (100+ already shared in commons/commonMain)
-- State management: remember, derivedStateOf, produceState (visual patterns)
-- Recomposition optimization: @Stable/@Immutable (visual usage)
-- Material3 conventions: theming
-- Custom icons: ImageVector builders (robohash pattern)
-- Platform differences: Desktop vs Android UI
-- Performance: lazy lists, image loading
-- Decision framework: share by default in commonMain
-
-**Bundled resources:**
-- `references/shared-composables-catalog.md` - Complete catalog with patterns
-- `references/state-patterns.md` - State hoisting, derivedStateOf examples
-- `references/icon-assets.md` - ImageVector patterns, roboBuilder DSL
-- `scripts/find-composables.sh` - Grep @Composable utility
-
-**Differentiation:** Multiplatform Compose patterns, shared vs platform UI philosophy, Amethyst conventions (robohash, custom icons). Delegates navigation to platform experts, defers Kotlin language details to kotlin-expert.
-
-**Status:** ✅ SKILL.md (578 lines) + 3 references + 1 script created at `.claude/skills/compose-expert/`
-
----
-
-### 5. ios-expert
-**Focus:** iosMain patterns, Swift/KMP interop, XCFramework generation
-
-**SKILL.md sections:**
-- iOS source sets: iosMain, iosArm64Main
-- Swift interop: type mapping, nullability
-- expect/actual iOS: 10+ examples from quartz/iosMain
-- XCFramework setup: baseName = "quartz-kmpKit"
-- Platform APIs: platform.posix, CFNetwork, Security
-- CocoaPods integration
-- XCode project setup
-
-**Bundled resources:**
-- `references/ios-actual-implementations.md` - 10 iosMain actuals
-- `references/swift-interop-guide.md` - Type mapping
-- `references/xcode-integration.md` - XCode setup
-- `scripts/generate-xcframework.sh` - Build all iOS targets
-
-**Differentiation:** iOS platform specialization with Amethyst iosMain patterns, Quartz framework setup.
-
----
-
-### 6. desktop-expert ✅ DRAFT COMPLETE
-**Focus:** Desktop UX, window management, Compose Desktop APIs, OS-specific conventions
-
-**SKILL.md sections:**
-- Desktop entry point: application {} DSL
-- Window management: WindowState, positioning, multi-window
-- Menu system: MenuBar, keyboard shortcuts (OS-aware)
-- System tray: minimize to tray
-- Desktop navigation: NavigationRail pattern (vs Android bottom nav)
-- File system: Desktop.getDesktop(), file pickers, drag-drop
-- Desktop UX principles: keyboard-first, native feel, tooltips
-- OS-specific behavior: macOS vs Windows vs Linux
-- Platform detection: PlatformDetector utility
-- Packaging: DMG, MSI, DEB distribution
-
-**Bundled resources:**
-- `references/desktop-compose-apis.md` - Complete Desktop API catalog (Window, Tray, MenuBar, Dialog, etc.)
-- `references/desktop-navigation.md` - NavigationRail vs BottomNav patterns
-- `references/keyboard-shortcuts.md` - Standard shortcuts by OS with DesktopShortcuts helper
-- `references/os-detection.md` - Platform detection, file paths, system integration
-
-**Differentiation:** Desktop-only APIs, OS conventions (Cmd vs Ctrl), NavigationRail, delegates build to gradle-expert and shared code to kotlin-multiplatform/compose-expert.
-
-**Status:** ✅ SKILL.md + 4 references created at `.claude/skills/desktop-expert/`
-
-**10-Step Progress:**
-1. ✅ UNDERSTAND - Defined desktop usage scenarios
-2. ✅ EXPLORE - Analyzed desktopApp/ module patterns (Main.kt, FeedScreen.kt, LoginScreen.kt)
-3. ✅ RESEARCH - Compose Desktop APIs, OS-specific UX conventions (JetBrains docs, HIG)
-4. ✅ SYNTHESIZE - Extracted desktop principles from codebase
-5. ✅ DRAFT - Created SKILL.md + 4 reference files
-6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
-7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
-8. ⏸️ TEST - Deferred to later (requires real desktop scenarios)
-9. ⏸️ FINALIZE - Deferred to later
-10. ✅ DOCUMENT - Updated plan
-
----
-
-### 7. android-expert ✅ DRAFT COMPLETE
-**Focus:** Android platform APIs, navigation, permissions, Material Design
-
-**SKILL.md sections:**
-- Android module structure: amethyst/ layout
-- Navigation: Navigation Compose, bottom nav
-- Permissions: runtime (camera, biometric)
-- Platform APIs: Intent, Context, ContentResolver
-- Lifecycle: Lifecycle-aware, ViewModel
-- Material Design: Android Material 3
-- Build config: Proguard, R8
-- Android UX: mobile-first patterns
-
-**Bundled resources:**
-- `references/android-navigation.md` - Navigation Compose
-- `references/android-permissions.md` - Permission handling
-- `references/proguard-rules.md` - Proguard explanation
-- `scripts/analyze-apk-size.sh` - APK optimization
-
-**Differentiation:** amethyst module structure, Android vs desktop patterns, Amethyst conventions.
-
-**Status:** ✅ SKILL.md + 3 references + 1 script created at `.claude/skills/android-expert/`
-
-**10-Step Progress:**
-1. ✅ UNDERSTAND - Defined Android usage scenarios
-2. ✅ EXPLORE - Analyzed amethyst/ module patterns
-3. ✅ RESEARCH - Android best practices + KMP Android patterns
-4. ✅ SYNTHESIZE - Extracted Android principles from codebase
-5. ✅ DRAFT - Initialized skill, created resources
-6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
-7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
-8. ⏸️ TEST - Deferred to later
-9. ⏸️ FINALIZE - Deferred to later
-10. ✅ DOCUMENT - Updated plan
-
----
-
-### 8. nostr-expert ✅ COMPLETED
-**Focus:** Nostr protocol, NIPs, Quartz architecture, event patterns
-
-**SKILL.md sections:**
-- Quartz architecture: package structure by NIP (57 NIPs implemented)
-- Event anatomy: IEvent, Event, kinds, tags
-- EventTemplate & TagArrayBuilder DSL patterns
-- Common event types: TextNoteEvent, MetadataEvent, ReactionEvent, Addressable events
-- Tag patterns: e-tag, p-tag, a-tag, d-tag with builders
-- Threading (NIP-10): reply/root markers
-- Cryptography: secp256k1 signing, NIP-44 encryption
-- Bech32 encoding: npub, nsec, note, nevent
-- Event validation & verification
-- Common workflows: publishing, querying, zaps, gift-wrapped DMs
-
-**Bundled resources:**
-- `references/nip-catalog.md` - All 57 NIPs with package locations (179 lines)
-- `references/event-hierarchy.md` - Event class hierarchy, kind classifications (293 lines)
-- `references/tag-patterns.md` - Tag structure, TagArrayBuilder DSL, parsing (251 lines)
-- `scripts/nip-lookup.sh` - Find NIP implementations by number or search term
-
-**Differentiation:** nostr-protocol agent = NIP specs. This skill = Quartz implementation patterns (57 NIPs), concrete code examples from codebase.
-
-**Status:** ✅ SKILL.md (552 lines) + 3 references + 1 script created at `.claude/skills/nostr-expert/`
-
----
-
-## Implementation Workflow
-
-Using skill-creator 10-step methodology per skill:
-
-**Overall Plan:**
-1. **UNDERSTAND** ✅ - 8 skills defined, user clarifications obtained
-2. **EXPLORE** ✅ - Codebase analyzed via Explore agent
-3. **RESEARCH** ✅ - Domain patterns identified via Plan agent
-4. **SYNTHESIZE** ✅ - Skills designed above
-
-**Per-Skill Implementation:**
-- kotlin-multiplatform: ✅ COMPLETED
-- gradle-expert: ✅ COMPLETED
-- kotlin-expert: ✅ COMPLETED
-- compose-expert: ✅ COMPLETED
-- desktop-expert: ✅ COMPLETED
-- android-expert: ✅ COMPLETED
-- nostr-expert: ✅ COMPLETED
-- ios-expert: ⏸️ DEFERRED (iOS not yet implemented in AmethystMultiplatform)
-
-## Critical Files Referenced
-
-**Build patterns:**
-- `/quartz/build.gradle.kts:132-149` - jvmAndroid source set
-- `/commons/build.gradle.kts` - Shared UI setup
-
-**Code patterns:**
-- `/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip10Notes/TextNoteEvent.kt` - Event structure
-- `/commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/account/AccountManager.kt` - StateFlow pattern
-- `/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Platform.kt` - expect/actual
-
-**Documentation:**
-- `/docs/shared-ui-analysis.md` - UI migration strategy
-
-## Output Location
-`.claude/skills/<skill-name>/` for each skill
-
-## Next Steps
-
-1. ✅ Save this plan as `.claude/core-skills-plan.md` for reference
-2. ✅ Completed kotlin-multiplatform skill
-3. ✅ Completed gradle-expert skill
-4. ✅ Completed kotlin-expert skill
-5. ✅ Completed compose-expert skill
-6. ✅ Completed desktop-expert skill
-7. ✅ Completed android-expert skill
-8. ✅ Completed nostr-expert skill
-9. ⏸️ Deferred ios-expert (iOS not yet implemented in codebase)
-
-## Current Status: 7/8 Skills Completed
-
-**Completed Skills (Auto-loaded from `.claude/skills/`):**
-1. ✅ kotlin-multiplatform (KMP architecture, jvmAndroid pattern, expect/actual)
-2. ✅ gradle-expert (Build system, dependencies, version catalog, troubleshooting)
-3. ✅ kotlin-expert (Flow state, sealed classes, @Immutable, DSL builders)
-4. ✅ compose-expert (Shared composables, state management, Material3, ImageVector)
-5. ✅ desktop-expert (Desktop UX, window management, Compose Desktop APIs)
-6. ✅ android-expert (Android platform APIs, navigation, permissions)
-7. ✅ nostr-expert (Nostr protocol, Quartz implementation, NIPs, events, tags)
-
-**Deferred:**
-- ⏸️ ios-expert (iOS not implemented yet in AmethystMultiplatform)
-
-## Skill Loading
-
-**All completed skills are automatically loaded** when this project opens. Skills are auto-discovered from `.claude/skills/` directory.
-
-To manually verify skills are loaded:
-```bash
-ls -1 .claude/skills/
-```
-
-Should show:
-- android-expert/
-- compose-expert/
-- desktop-expert/
-- gradle-expert/
-- kotlin-expert/
-- kotlin-multiplatform/
-- nostr-expert/
-
----
+# Amethyst Skill Library — History & Changelog
+
+> Historical record of how the `.claude/skills/` library was built and audited.
+> The 8 original skills were created in 2025 using the skill-creator 10-step
+> methodology (detailed per-skill progress logs pruned in 2026-06 — see git
+> history of this file if you need them). For the current skill list and how
+> the two skill layers (codebase-oriented vs technique-oriented) fit together,
+> see the Skills section of `.claude/CLAUDE.md`.
+
+## Phase 1 (2025): Core skills created
+
+Eight hybrid domain skills (general expertise + Amethyst-specific patterns),
+each with a SKILL.md plus bundled `references/` and `scripts/`:
+
+1. **kotlin-multiplatform** — KMP architecture, the jvmAndroid source-set pattern, expect/actual catalog
+2. **gradle-expert** — build system, version catalog, dependency troubleshooting
+3. **kotlin-expert** — Flow state, sealed hierarchies, @Immutable, DSL builders
+4. **compose-expert** — shared composables, state management, Material3, ImageVector
+5. **desktop-expert** — Desktop UX, window management, Compose Desktop APIs
+6. **android-expert** — Android navigation, permissions, platform APIs
+7. **nostr-expert** — Nostr protocol, Quartz implementation, NIPs, events, tags
+8. **ios-expert** — ⏸️ deferred (iOS targets are mature, but no iOS-specific UI work has surfaced in this repo yet)
 
 ## Phase 2 (2026-04): Audit & Expansion
 
 After a full audit of the skill library, the following changes were made:
 
 ### Stale references fixed
-- `CLAUDE.md` tech-stack versions updated to Compose 1.10.3 / Kotlin 2.3.20.
-- `kotlin-multiplatform` reframed iOS as a mature target (not future) and added secp256k1-kmp 0.23.0 version notes.
-- `desktop-expert` Main.kt line references rewritten to match current layout (Main.kt grew from ~270 to ~1341 lines; NavigationRail moved to `ui/deck/SinglePaneLayout.kt:97`); the obsolete "hardcoded ctrl = true anti-pattern" section replaced with a note that `isMacOS` branching is now applied throughout.
+- `CLAUDE.md` tech-stack versions replaced with a pointer to `gradle/libs.versions.toml` as the source of truth.
+- `kotlin-multiplatform` reframed iOS as a mature target (not future) and added secp256k1-kmp version notes.
+- `desktop-expert` Main.kt line references rewritten to match current layout (NavigationRail moved to `ui/deck/SinglePaneLayout.kt`); the obsolete "hardcoded ctrl = true anti-pattern" section replaced with a note that `isMacOS` branching is now applied throughout.
 
 ### Redundant files removed
-- `.claude/skills/compose-desktop.md` deleted (superseded by `desktop-expert/`). `quartz-kmp.md` kept as a small breadcrumb pointer.
+- `.claude/skills/compose-desktop.md` deleted (superseded by `desktop-expert/`).
 
 ### New references added to existing skills
 - `nostr-expert/references/nip19-bech32.md` — `Nip19Parser`, `Bech32Util`, `TlvBuilder`, entities.
@@ -346,33 +44,44 @@ After a full audit of the skill library, the following changes were made:
 
 ### New skills created
 - **`account-state/`** — `Account.kt` (50+ StateFlow properties) and `LocalCache.kt` event store.
-  - `references/account-state-flow.md`, `references/local-cache.md`
-- **`relay-client/`** — `ComposeSubscriptionManager`, filter assemblers, preloaders (`MetadataPreloader`, `MetadataRateLimiter`).
-  - `references/filter-assemblers.md`, `references/preloaders.md`
+- **`relay-client/`** — `ComposeSubscriptionManager`, filter assemblers, preloaders.
 - **`feed-patterns/`** — `FeedFilter`, `AdditiveComplexFeedFilter`, `FeedViewModel` hierarchy in `commons/`.
-  - `references/feed-filter-composition.md`, `references/viewmodel-base-classes.md`
-- **`auth-signers/`** — `NostrSigner` abstraction across `NostrSignerInternal`, `NostrSignerRemote` (NIP-46), `NostrSignerExternal` (NIP-55).
-  - `references/nip46-remote-signer.md`, `references/nip55-android-signer.md`
+- **`auth-signers/`** — `NostrSigner` abstraction across internal, NIP-46 remote, and NIP-55 external signers.
 
-### Updated skills directory (Phase 2)
-```
-- android-expert/
-- auth-signers/                (new)
-- account-state/               (new)
-- compose-expert/
-- desktop-expert/
-- feed-patterns/               (new)
-- find-missing-translations/
-- find-non-lambda-logs/
-- gradle-expert/
-- kotlin-coroutines/
-- kotlin-expert/
-- kotlin-multiplatform/
-- nostr-expert/
-- quartz-integration/
-- relay-client/                (new)
-- quartz-kmp.md                (breadcrumb pointer)
-```
+## Phase 3 (2026-06): Fable 5 config review
 
-### Still deferred
-- ⏸️ `ios-expert` — iOS targets are mature but iOS-specific UI work hasn't surfaced yet in this repo.
+Instructions written to coach older models were removed now that the model
+handles them natively; stale references fixed:
+
+- `CLAUDE.md`: deleted the 5-step skill-approval "Workflow" section
+  (skills auto-trigger; the approval loop blocked autonomous sessions);
+  condensed "Verify, Don't Guess" to the repo-specific tooling pointers and
+  dropped references to `/bugfix` / `/investigate` (never committed to this
+  repo); replaced the mandated emoji survey matrix with one-line guidance.
+- `android-expert` and `desktop-expert` SKILL.md gained YAML frontmatter —
+  without it they were listed without trigger descriptions and never
+  auto-invoked.
+- `commands/extract.md`: fixed stale `shared-ui/` module name → `commons/`.
+- `skills/quartz-kmp.md` breadcrumb deleted (KMP migration long complete;
+  `quartz-integration` and `nostr-expert` cover its pointers).
+- Stop hook moved to `.claude/hooks/stop-spotless.sh` and gated on modified
+  Kotlin files, so Q&A-only turns no longer pay a Gradle invocation.
+
+Second audit pass (every concrete claim checked against the code; `amy-expert`,
+`find-missing-translations`, `find-non-lambda-logs`, and the vendored technique
+skills verified clean):
+
+- `auth-signers`: bunker login entry point corrected — `NostrSignerRemote.fromBunkerUri(...)`
+  + `connect()`, not the nonexistent `RemoteSignerManager.connect(url)`.
+- `nostr-expert`: NIP count 57 → 80+ packages; `Nip44v2.encrypt/decrypt`
+  static-object snippet replaced with the real `Nip44` facade
+  (returns `EncryptedInfo`, `encodePayload()` for event content); invented
+  `Nip19.npubEncode`/`Nip19Result` API replaced with the real `ByteArray`
+  extensions (`toNpub()`, …), entity `create()` helpers, and
+  `Nip19Parser.uriToRoute()?.entity`.
+- `nostr-expert/references/nip-catalog.md`: heading count (60+8) replaced with
+  actual package counts (87 + 23 experimental) and a ground-truth pointer.
+- `quartz-integration`: NIP-19 decode example rewritten for
+  `ParseReturn.entity` (the `Nip19Parser.Return.*` sealed class never existed);
+  Event Store section corrected from "Android only" to commonMain/all platforms
+  with the real `store.sqlite.EventStore` import and suspend generic `query<T>`.

.claude/hooks/session-start.sh

@@ -160,7 +160,7 @@ echo -e "\n504667f4c0de7af1a06de9f4b1727b84351f2910" >> "$ANDROID_SDK_DIR/licens
 echo -e "\nd975f751698a77b662f1254ddbeed3901e976f5a" > "$ANDROID_SDK_DIR/licenses/intel-android-extra-license"
 
 # Create local.properties if missing
-REPO_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-/home/user/Amber}")"
+REPO_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$PWD}")"
 LOCAL_PROPS="$REPO_ROOT/local.properties"
 if [ ! -f "$LOCAL_PROPS" ]; then
   echo "sdk.dir=$ANDROID_SDK_DIR" > "$LOCAL_PROPS"

.claude/hooks/stop-spotless.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Stop hook: format Kotlin sources, but only when the working tree actually
+# has modified Kotlin files — skips the Gradle invocation on Q&A-only turns.
+set -uo pipefail
+
+cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
+
+if git status --porcelain 2>/dev/null | grep -qE '[.]kts?$'; then
+  ./gradlew spotlessApply 2>/dev/null
+fi
+
+exit 0

.claude/settings.json

@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./gradlew spotlessApply 2>/dev/null",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-spotless.sh",
             "timeout": 120
           }
         ]

.claude/skills/account-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: account-state
-description: Account state and in-memory event store patterns in Amethyst. Use when working with `Account.kt` (per-user StateFlow properties — follow list, relays, settings, mutes, bookmarks), `LocalCache` (the object-level event store backed by `LargeCache`), `User`/`Note` model classes, or any ViewModel that reads user-specific state. Covers how account events cascade from relay arrival to UI state, how to add a new account-scoped setting, and when to read from `LocalCache` vs subscribe to a StateFlow.
+description: Account state and in-memory event store patterns in Amethyst. Use when working with `Account.kt` (per-user state objects — `kind3FollowList`, `nip65RelayList`, `muteList`, `bookmarkState`, each exposing a `.flow` StateFlow), `LocalCache` (the object-level event store backed by `LargeCache`), `User`/`Note` model classes, or any ViewModel that reads user-specific state. Covers how account events cascade from relay arrival to UI state, how to add a new account-scoped setting, and when to read from `LocalCache` vs subscribe to a StateFlow.
 ---
 
 # Account & Local Cache State
@@ -21,10 +21,10 @@ The backbone of Amethyst's client state: one `Account` per signed-in user, plus
 Relay frame ──► LocalCache.insertOrUpdateNote() ──► LocalCacheFlow emits change
                                                             │
                                                             ▼
-                                Account observes relevant kinds (3, 10002, 10000, …)
+                                Account state objects pin the relevant addressable notes
                                                             │
                                                             ▼
-                                     Account StateFlow updates (followList, relays, mutes, …)
+                            State-object `.flow` updates (kind3FollowList, nip65RelayList, muteList, …)
                                                             │
                                                             ▼
                                                     ViewModels collect
@@ -33,22 +33,22 @@ Relay frame ──► LocalCache.insertOrUpdateNote() ──► LocalCacheFlow e
                                                  Composables render
 ```
 
-`LocalCache` is the event store. `Account` is the *derived* per-user view (follow list, relays, mutes, emojis, bookmarks, etc.). UI listens to `Account`'s StateFlows, not directly to `LocalCache`, except for note-level rendering.
+`LocalCache` is the event store. `Account` is the *derived* per-user view (follow list, relays, mutes, emojis, bookmarks, etc.). UI listens to the `.flow` of `Account`'s state objects, not directly to `LocalCache`, except for note-level rendering.
 
 ## Key Files
 
 ### `Account.kt` (singleton-per-session)
 
-- `class Account(...)` — holds 50+ StateFlow properties, each wired to a specific Nostr kind:
-  - `followListFlow` ← NIP-02 ContactList (kind 3)
-  - `relayListFlow` ← NIP-65 RelayList (kind 10002)
-  - `muteListFlow` ← NIP-51 Lists (kind 10000)
-  - `bookmarkListFlow` ← NIP-51 Lists (kind 10003)
-  - `topNavFeedsFlow`, `marmotGroupsFlow`, `customEmojisFlow`, `privateBookmarksFlow`, etc.
-  - Settings: `defaultZapAmountsFlow`, `theme`, `language`, `proxyFlow`, `showSensitiveContentFlow`, …
-- Each flow has a private `MutableStateFlow` and a public read-only `StateFlow` view. Mutation goes through specific methods (`sendPost`, `follow(pubKey)`, `addBookmark(...)`) that both update the flow and publish the signed replaceable event.
-- Uses `CoroutinesExt.launchIO` for network / crypto; UI reads via `collectAsStateWithLifecycle` on Android and `collectAsState` on Desktop.
-- Sibling files per feature live alongside: `AccountSettings.kt`, `AccountSyncedSettings.kt`, plus per-NIP state objects under `model/nip02FollowLists/`, `model/nip51Lists/`, `model/nip65RelayList/`, etc.
+- `class Account(...)` — holds 50+ **state objects**, one per feature, each wired to a specific Nostr kind:
+  - `kind3FollowList = Kind3FollowListState(...)` ← NIP-02 ContactList (kind 3)
+  - `nip65RelayList = Nip65RelayListState(...)` ← NIP-65 RelayList (kind 10002), plus siblings `dmRelayList`, `searchRelayList`, `blockedRelayList`, `trustedRelayList`, `proxyRelayList`, `broadcastRelayList`, `indexerRelayList`, …
+  - `muteList = MuteListState(...)` ← NIP-51 MuteList (kind 10000)
+  - `bookmarkState = BookmarkListState(...)` ← NIP-51 Bookmarks (kind 10003), plus `labeledBookmarkLists`, `pinState`, `interestSets`, `peopleLists`, `followLists`, `hashtagList`, `geohashList`, `communityList`, `emoji`, `blossomServers`, …
+  - Derived/merged views: `hiddenUsers`, `allFollows`, `homeRelays`, `outboxRelays`, `dmRelays`, `notificationRelays`, `trustedRelays`, and the `live*FollowListsPerRelay` outbox loaders.
+- **The pattern:** each `XState` class pins its addressable note via `cache.getOrCreateAddressableNote(address)` (a long-term reference so GC/eviction can't drop it), exposes `val flow: StateFlow<…>` derived from the note's metadata flow (decrypted through a per-feature `DecryptionCache`, with backup fallback from `AccountSettings`, `stateIn(scope, Eagerly, …)`), and offers suspend mutation helpers (e.g. `MuteListState.hideUser(pubkey)`) that build the updated signed event. Consumers read `account.muteList.flow`, never a raw `MutableStateFlow` on `Account`.
+- Encrypted lists pair the state object with a `DecryptionCache` sibling (`muteListDecryptionCache`, `peopleListDecryptionCache`, …) so NIP-44 decryption results are cached per event.
+- UI reads via `collectAsStateWithLifecycle` on Android and `collectAsState` on Desktop.
+- Sibling files per feature live alongside: `AccountSettings.kt`, `AccountSyncedSettings.kt`, plus per-NIP state classes under `model/nip02FollowLists/`, `model/nip51Lists/`, `model/nip65RelayList/`, etc.
 
 ### `LocalCache.kt`
 
@@ -72,31 +72,29 @@ Relay frame ──► LocalCache.insertOrUpdateNote() ──► LocalCacheFlow e
 Typical recipe:
 
 1. If the setting is persisted as a Nostr event, pick the right kind (e.g. NIP-51 list, NIP-78 app-specific data, NIP-65 relay list).
-2. Add a model folder under `amethyst/.../model/nipXX…/` with an `ExtState`/builder class if needed.
-3. In `Account.kt`:
-   - Add a private `MutableStateFlow<T>`.
-   - Expose a `StateFlow<T>` read view.
-   - Subscribe to the relay (via the relayClient subscription pattern — see `relay-client` skill).
-   - On event arrival, parse with the quartz event class and update the flow.
-   - Write a mutation method (`updateX(...)`) that builds a new event via the corresponding `TagArrayBuilder`, signs through `NostrSigner`, and publishes.
-4. Add UI that `collect`s the flow. Settings screens live in `amethyst/.../ui/screen/loggedIn/settings/`.
+2. Add a model folder under `amethyst/.../model/nipXX…/` with an `XState` class modeled on an existing one (`MuteListState` for an encrypted list, `BookmarkListState` for a plain one):
+   - Pin the addressable note: `val xNote = cache.getOrCreateAddressableNote(XEvent.createAddress(signer.pubKey))`.
+   - Expose `val flow: StateFlow<…>` mapped from `xNote.flow().metadata.stateFlow`, decrypting through a per-feature `DecryptionCache` if the list is private, with backup fallback from `AccountSettings`, then `stateIn(scope, Eagerly, default)`.
+   - Add suspend mutation helpers that build the updated event via the quartz event class (`XEvent.add/remove/create`) and return it signed.
+3. In `Account.kt`, instantiate the state object (and its `DecryptionCache` sibling if encrypted) as a `val`. Publishing the returned event goes through `Account`'s send path; the relay subscription side is the relayClient pattern (see `relay-client` skill).
+4. Add UI that `collect`s `account.x.flow`. Settings screens live in `amethyst/.../ui/screen/loggedIn/settings/`.
 
 ## `LocalCache` vs `Account` Flow — Which to Read?
 
 - **Are you rendering a specific note / user you hold an id for?** → `LocalCache.getOrCreateNote(id)` + collect `note.flowSet.metadata`.
-- **Are you rendering "my follows", "my mutes", "my relays"?** → `Account.<featureFlow>`.
+- **Are you rendering "my follows", "my mutes", "my relays"?** → `account.<feature>.flow` (e.g. `account.kind3FollowList.flow`, `account.muteList.flow`, `account.nip65RelayList.flow`).
 - **Are you rendering a feed?** → Use a `FeedFilter` + `FeedViewModel` (see `feed-patterns` skill). Don't scan `LocalCache` in a composable.
 
 ## Gotchas
 
 - **`LocalCache` is a singleton across accounts.** Switching accounts doesn't wipe it — `Account` re-derives its flows from the same cache.
 - **Don't store Flows inside `Note` / `User`** expecting them to survive eviction. Eviction drops the whole object.
-- **Mutations to `Account` flows must also publish the signing event.** A flow update without a publish means other clients won't see it.
+- **State-object mutation helpers return a signed event — publishing it is the caller's job.** A locally updated list without a publish means other clients won't see it.
 - **`Note` is mutable** — treat instances as identity-based (same id → same Note). Use `.flowSet` when you need reactive state.
 - **`MemoryTrimmingService` can evict aggressively** on Android under pressure. Don't assume a previously-seen note is still resident.
 
 ## References
 
-- `references/account-state-flow.md` — catalog of major `Account` StateFlow properties and their source kinds.
+- `references/account-state-flow.md` — catalog of major `Account` state objects and their source kinds.
 - `references/local-cache.md` — `LocalCache` internals, insertion path, indexes.
 - Complements: `nostr-expert` (event parsing), `relay-client` (subscription wiring), `feed-patterns` (how feeds consume this state), `auth-signers` (how mutation signs events).

.claude/skills/account-state/references/account-state-flow.md

@@ -1,93 +1,94 @@
-# Account StateFlow Catalog
+# Account State-Object Catalog
 
-`Account.kt` exposes dozens of `StateFlow` properties that mirror different facets of the current user. This is a map from flow → Nostr kind → model package.
+`Account.kt` composes ~50 **feature state objects** (not raw StateFlow
+properties). Each object pins its backing addressable note in `LocalCache`,
+exposes `val flow: StateFlow<…>` (decrypted + backup-merged + `stateIn`), and
+offers suspend mutation helpers that return signed events. Consumers read
+`account.<property>.flow`.
 
-(Flow names are exact as of the current `Account.kt`; if a flow has been renamed, grep `Account.kt` for the old name.)
+(Property and class names are exact as of the current `Account.kt`; if one has
+been renamed, grep `Account.kt` for the class name.)
 
 ## Identity & Contacts
 
-| Flow | Kind(s) | Source | Model package |
-|------|---------|--------|---------------|
-| `userProfile().liveMetadata` | 0 MetadataEvent | relay | `model/nip01UserMetadata/` |
-| `followListFlow` | 3 ContactListEvent | relay | `model/nip02FollowLists/` |
-| `followersFlow` | derived | LocalCache scan | — |
-| `muteListFlow` | 10000 NIP-51 | relay | `model/nip51Lists/` |
-| `blockListFlow` | 10000 list variant | relay | `model/nip51Lists/` |
+| Account property | State class | Kind | Package |
+|------------------|-------------|------|---------|
+| `userMetadata` | `UserMetadataState` | 0 | `amethyst/.../model/nip01UserMetadata/` |
+| `kind3FollowList` | `Kind3FollowListState` | 3 | `model/nip02FollowLists/` |
+| `muteList` (+ `muteListDecryptionCache`) | `MuteListState` | 10000 | `model/nip51Lists/muteList/` |
+| `blockPeopleList`, `peopleLists` | `BlockPeopleListState`, `PeopleListsState` | NIP-51 people sets | `model/nip51Lists/peopleList/` |
+| `followLists` | `FollowListsState` | NIP-51 follow sets | `model/nip51Lists/peopleList/` |
+| `hiddenUsers` | `HiddenUsersState` — derived from `muteList.flow` + `blockPeopleList.flow` | — | `model/nip51Lists/` |
+| `allFollows` | `MergedFollowListsState` — merges kind3 + people/follow/hashtag/geohash/community lists | — | `model/serverList/` |
 
-## Relays & Connectivity
+## Relay Lists
 
-| Flow | Kind | Package |
-|------|------|---------|
-| `relayListFlow` | 10002 RelayList (NIP-65) | `model/nip65RelayList/` |
-| `dmRelayListFlow` | 10050 | `model/nip65RelayList/` |
-| `searchRelayListFlow` | 10007 | `model/nip65RelayList/` |
-| `nip86RelayListFlow` | NIP-86 relay management | `model/nip86RelayManagement/` |
-| `proxyFlow`, `torStateFlow` | local preferences | `model/torState/`, `AccountSyncedSettings` |
+| Account property | State class | Kind | Package |
+|------------------|-------------|------|---------|
+| `nip65RelayList` | `Nip65RelayListState` | 10002 | `model/nip65RelayList/` |
+| `dmRelayList` | `DmRelayListState` | 10050 | `model/nip17Dms/` |
+| `searchRelayList` | `SearchRelayListState` | 10007 | `model/nip51Lists/searchRelays/` |
+| `blockedRelayList` | `BlockedRelayListState` | 10006 | `model/nip51Lists/blockedRelays/` |
+| `localRelayList` | `LocalRelayListState` | local | `model/localRelays/` |
+| `privateStorageRelayList` | `PrivateStorageRelayListState` | private storage | `model/edits/` |
+| `keyPackageRelayList`, `trustedRelayList`, `proxyRelayList`, `broadcastRelayList`, `indexerRelayList`, `relayFeedsList` | per-feature `…RelayListState` classes, each with a `DecryptionCache` sibling | custom relay sets | `model/nip51Lists/…` |
+
+Derived relay views (merge several of the above): `homeRelays`
+(`AccountHomeRelayState`), `outboxRelays`, `dmRelays`, `notificationRelays`,
+`trustedRelays`, `followPlusAllMineWithIndex`, `followPlusAllMineWithSearch`,
+`defaultGlobalRelays`.
 
 ## Content Lists
 
-| Flow | Kind | Package |
-|------|------|---------|
-| `bookmarkListFlow` | 10003 | `model/nip51Lists/` |
-| `privateBookmarksFlow` | encrypted list | `model/nip51Lists/` |
-| `topNavFeedsFlow` | custom | `model/topNavFeeds/` |
-| `customEmojisFlow` | 10030 NIP-30 | `model/nip30CustomEmojis/` |
-| `marmotGroupsFlow` | NIP-29 (marmot variant) | `model/marmot/` |
-| `nip72CommunitiesFlow` | 34550 (NIP-72) | `model/nip72Communities/` |
-| `nip64ChessFlow` | NIP-64 chess games | `model/nip64Chess/` |
+| Account property | State class | Kind | Package |
+|------------------|-------------|------|---------|
+| `bookmarkState` (and legacy `oldBookmarkState`) | `BookmarkListState` | 10003 | `model/nip51Lists/` |
+| `labeledBookmarkLists` | `LabeledBookmarkListsState` | NIP-51 bookmark sets | `model/nip51Lists/labeledBookmarkLists/` |
+| `pinState` | `PinListState` | NIP-51 | `model/nip51Lists/` |
+| `interestSets` | `InterestSetsState` | NIP-51 interest sets | `model/nip51Lists/interestSets/` |
+| `hashtagList` / `geohashList` | `HashtagListState` / `GeohashListState` | NIP-51 | `model/nip51Lists/hashtagLists/`, `…/geohashLists/` |
+| `communityList` | `CommunityListState` | NIP-72 communities | `model/nip72Communities/` |
+| `favoriteAlgoFeedsList` | `FavoriteAlgoFeedsListState` | NIP-51 | `model/nip51Lists/` |
+| `emoji`, `ownedEmojiPacks` | `EmojiPackState`, `OwnedEmojiPacksState` | 10030 | `commons/.../commons/model/nip30CustomEmojis/` |
+| `publicChatList` | `PublicChatListState` | NIP-28 | `commons/.../commons/model/nip28PublicChats/` |
+| `ephemeralChatList` | `EphemeralChatListState` | ephemeral chats | `commons/.../commons/model/emphChat/` |
+| `blossomServers` | `BlossomServerListState` | Blossom (BUD) | `model/nipB7Blossom/` |
 
-## Messaging
+## Other Feature State
 
-| Flow | Kind | Package |
-|------|------|---------|
-| `dmInboxFlow` | 14 / 1059 (NIP-17 / gift-wrap) | `model/nip17Dms/` |
-| `nwcSettingsFlow` | NIP-47 wallet connect | `model/nip47WalletConnect/` |
-| `paymentTargetsFlow` | NIP-A3 | `model/nipA3PaymentTargets/` |
-| `blossomServersFlow` | NIP-B7 blossom | `model/nipB7Blossom/` |
+| Account property | State class | Purpose | Package |
+|------------------|-------------|---------|---------|
+| `vanish` | `VanishRequestsState` | NIP-62 vanish requests | `model/nip62Vanish/` |
+| `appSpecific` | `AppSpecificState` | NIP-78 app data | `model/nip78AppSpecific/` |
+| `otsState` | `OtsState` | NIP-03 OpenTimestamps | `model/nip03Timestamp/` |
+| `live*FollowListsPerRelay` | `OutboxLoaderState(...).flow` — already a flow | per-feed outbox routing | `model/topNavFeeds/` |
+| `privateDMDecryptionCache`, `draftsDecryptionCache` | `PrivateDMCache`, `DraftEventCache` | NIP-44 decryption caches | — |
 
-## Settings & UI
-
-| Flow | Source | Package |
-|------|--------|---------|
-| `uiSettingsFlow` | local | `model/UiSettings.kt`, `UiSettingsFlow.kt` |
-| `antiSpamFilter` | local | `model/AntiSpamFilter.kt` |
-| `privacyOptionsFlow` | local | `model/privacyOptions/` |
-| `trustedAssertionsFlow` | derived | `model/trustedAssertions/` |
-| `defaultZapAmountsFlow`, `theme`, `language` | local preferences | `AccountSettings.kt`, `AccountSyncedSettings.kt` |
-
-## Advanced / Derived
-
-| Flow | Purpose | Package |
-|------|---------|---------|
-| `accountsCacheFlow` | multi-account switcher | `model/accountsCache/` |
-| `algoFeedsFlow` | custom algorithmic feeds | `model/algoFeeds/` |
-| `vanishFlow` | NIP-62 account vanish requests | `model/nip62Vanish/` |
-| `nip78AppSpecificFlow` | NIP-78 app-specific data | `model/nip78AppSpecific/` |
-| `serverListFlow` | media/upload servers | `model/serverList/` |
+Note the migration direction: newer/extracted state classes live in
+`commons/src/commonMain/.../commons/model/`, the rest still in
+`amethyst/src/main/java/.../model/`. Check both when looking for one.
 
 ## Publishing Mutations
 
-Every flow has a corresponding mutation method on `Account` that:
+State objects' mutation helpers (e.g. `MuteListState.hideUser(pubkey)`,
+`BookmarkListState` add/remove) **build and sign** the updated replaceable
+event via the quartz event class (`XEvent.add / remove / create`) and return
+it. The caller (usually a method on `Account`) is responsible for sending it
+through the client. Decryption results are cached in the paired
+`…DecryptionCache` so re-renders don't re-decrypt.
 
-1. Constructs the updated event using a `TagArrayBuilder`.
-2. Signs through the injected `NostrSigner` (see `auth-signers` skill).
-3. Publishes to the appropriate relay set.
-4. Updates the local StateFlow *before* relay round-trip (optimistic).
-5. Rolls back / reconciles on failure.
+## When a State Object Doesn't Exist Yet
 
-Examples of mutation methods (names may vary slightly in current code):
-- `follow(pubKey)` / `unfollow(pubKey)`
-- `addBookmark(noteId)` / `removeBookmark(noteId)`
-- `mute(pubKey)` / `unmute(pubKey)`
-- `updateRelayList(...)`, `updateDmRelayList(...)`
-- `sendPost(...)`, `sendReaction(...)`, `sendZap(...)`
+If you're adding a new NIP that's user-scoped, follow the pattern (full recipe
+in `SKILL.md`):
 
-## When a Flow Doesn't Exist Yet
-
-If you're adding a new NIP that's user-scoped, follow the pattern:
-
-1. Create `model/nipXX…/` with an optional `ExtState`/builder class.
-2. Add `private val _xFlow = MutableStateFlow(initial)` + `val xFlow: StateFlow<T> = _xFlow.asStateFlow()` to `Account`.
-3. Wire the relay subscription (see `relay-client` skill).
-4. Add the mutation method that builds, signs, and publishes.
-5. Update persistence if the setting is local-only (`AccountSettings.kt`).
+1. Create `model/nipXX…/XState.kt` modeled on `MuteListState` (encrypted) or
+   `BookmarkListState` (plain).
+2. Pin the note with `cache.getOrCreateAddressableNote(...)`, expose
+   `val flow: StateFlow<…>` via `stateIn(scope, Eagerly, default)`.
+3. Instantiate it in `Account.kt` (plus a `DecryptionCache` sibling if
+   private), and wire the relay subscription (see `relay-client` skill).
+4. Add mutation helpers that build, sign, and return the event; publish from
+   the calling site.
+5. Use `AccountSettings` for the local backup copy if the list must survive
+   relay loss.

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

@@ -1,3 +1,8 @@
+---
+name: android-expert
+description: Android platform patterns for the `amethyst/` module. Use when working with (1) Android navigation (Navigation Compose, type-safe routes, bottom nav), (2) runtime permissions (camera, notifications, biometrics), (3) platform APIs (Intent, Context, Activity, ContentResolver), (4) Material3 theming and edge-to-edge UI, (5) AndroidManifest.xml and intent filters, (6) Proguard/R8 and APK optimization, (7) Android lifecycle (ViewModel, collectAsStateWithLifecycle), (8) Coil image loading. Delegates shared composables to compose-expert, build files to gradle-expert, and KMP structure to kotlin-multiplatform.
+---
+
 # android-expert
 
 Android platform expertise for Amethyst Multiplatform project. Covers Compose Navigation, Material3, permissions, lifecycle, and Android-specific patterns in KMP architecture.
@@ -733,125 +738,29 @@ fun SignerIntegration(accountViewModel: AccountViewModel) {
 
 ## 6. Build Configuration
 
-### Android Block
+Build files — the `android {}` block, the version catalog, dependencies,
+Proguard/R8, and Desktop packaging — are **gradle-expert's** domain. Use
+`/gradle-expert` instead of duplicating that guidance here. In particular, the
+app version and the Android `versionCode` both live in
+`gradle/libs.versions.toml` (`app` / `appCode`); `amethyst/build.gradle.kts`
+reads both from the catalog, so a release bump is a single-file edit.
+
+The one build detail that is genuinely Android-specific — not generic Gradle —
+is the **product-flavor split** that ships two channels from one codebase:
 
-**build.gradle (Amethyst pattern):**
 ```gradle
-android {
-    namespace = 'com.vitorpamplona.amethyst'
-    compileSdk = 36
-
-    defaultConfig {
-        applicationId = "com.vitorpamplona.amethyst"
-        minSdk = 26          // Android 8.0 (Oreo)
-        targetSdk = 36       // Android 15
-        versionCode = 444
-        versionName = "1.09.2"
-
-        vectorDrawables {
-            useSupportLibrary = true
-        }
-    }
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_21
-        targetCompatibility = JavaVersion.VERSION_21
-    }
-
-    buildFeatures {
-        compose = true
-        buildConfig = true   // Enable BuildConfig access
-    }
-
-    composeOptions {
-        kotlinCompilerExtensionVersion = libs.versions.compose.compiler.get()
-    }
-
-    packaging {
-        resources {
-            excludes += '/META-INF/{AL2.0,LGPL2.1}'
-        }
-    }
-
-    // Product flavors for Play Store vs F-Droid
-    flavorDimensions = ["channel"]
-    productFlavors {
-        create("play") {
-            dimension = "channel"
-            // Firebase, Google services
-        }
-        create("fdroid") {
-            dimension = "channel"
-            // UnifiedPush, open-source alternatives
-        }
-    }
-}
-
-kotlin {
-    compilerOptions {
-        jvmTarget = JvmTarget.JVM_21
-    }
+flavorDimensions = ["channel"]
+productFlavors {
+    create("play")   { dimension = "channel" } // Firebase, Google services
+    create("fdroid") { dimension = "channel" } // UnifiedPush, open-source only
 }
 ```
 
-### Dependencies
+`play` carries Firebase/Google services; `fdroid` swaps them for UnifiedPush and
+open-source alternatives so the F-Droid build stays proprietary-free.
 
-**Key Android Dependencies:**
-```gradle
-dependencies {
-    // Compose BOM
-    implementation(platform(libs.androidx.compose.bom))
-    implementation(libs.androidx.compose.ui)
-    implementation(libs.androidx.compose.material3)
-    implementation(libs.androidx.compose.ui.tooling.preview)
-
-    // Navigation
-    implementation(libs.androidx.navigation.compose)
-
-    // Lifecycle
-    implementation(libs.androidx.lifecycle.runtime.compose)
-    implementation(libs.androidx.lifecycle.viewmodel.compose)
-
-    // Activity
-    implementation(libs.androidx.activity.compose)
-
-    // Accompanist
-    implementation(libs.accompanist.permissions)
-
-    // Shared module
-    implementation(project(":commons"))
-    implementation(project(":quartz"))
-}
-```
-
-### Proguard Rules
-
-**Common Rules for Amethyst:**
-```proguard
-# Keep Kotlin metadata
--keep class kotlin.Metadata { *; }
-
-# Keep Nostr event classes
--keep class com.vitorpamplona.quartz.events.** { *; }
-
-# Keep serialization
--keepattributes *Annotation*, InnerClasses
--dontnote kotlinx.serialization.AnnotationsKt
-
-# OkHttp
--dontwarn okhttp3.**
--keep class okhttp3.** { *; }
-
-# Compose
--keep class androidx.compose.** { *; }
--dontwarn androidx.compose.**
-```
-
-**Reference:** See `references/proguard-rules.md` for complete Proguard configuration.
-
-### APK Optimization
-
-**Reference:** See `scripts/analyze-apk-size.sh` for APK size analysis.
+Proguard/R8 rules: see `references/proguard-rules.md`. APK size analysis:
+`scripts/analyze-apk-size.sh`.
 
 ## 7. KMP Android Source Sets
 

.claude/skills/auth-signers/SKILL.md

@@ -75,7 +75,7 @@ Most feature code should go through `Account`'s mutation methods (`account.sendR
 Entry points:
 
 - **Existing private key** (`nsec`, 32-byte hex, file) → `NostrSignerInternal`.
-- **Bunker URL** (`bunker://...`) → `RemoteSignerManager.connect(url)` in `nip46RemoteSigner/signer/RemoteSignerManager.kt` returns a `NostrSignerRemote`.
+- **Bunker URL** (`bunker://...`) → `NostrSignerRemote.fromBunkerUri(bunkerUri, localSigner, client)` in `nip46RemoteSigner/signer/NostrSignerRemote.kt` parses the URI and returns a `NostrSignerRemote`; then call its `suspend fun connect()` to perform the NIP-46 handshake.
 - **Installed external signer app** (Amber, nos2x, etc. on Android) → `ExternalSignerLogin.launch(...)` opens the signer app; approval yields a `NostrSignerExternal`.
 
 The UI hosts both flows via `amethyst/.../ui/screen/loggedOff/login/` — look there for `ExternalSignerButton.kt` and the bunker-URL paste screen.

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

@@ -1,3 +1,8 @@
+---
+name: desktop-expert
+description: Compose Multiplatform Desktop patterns for the `desktopApp/` module. Use when working with (1) Desktop-only APIs (Window, WindowState, Tray, MenuBar, Dialog), (2) keyboard shortcuts and menu systems with OS-aware conventions (Cmd vs Ctrl, isMacOS branching), (3) desktop navigation (NavigationRail/sidebar vs Android bottom nav, multi-window), (4) file system integration (file pickers, drag-and-drop, Desktop.getDesktop()), (5) OS-specific behavior on macOS/Windows/Linux, (6) desktop UX principles (keyboard-first, tooltips). Delegates shared composables to compose-expert, build/packaging to gradle-expert, and source-set structure to kotlin-multiplatform.
+---
+
 # Desktop Expert
 
 Expert in Compose Multiplatform Desktop development for AmethystMultiplatform. Covers Desktop-specific APIs, OS conventions, navigation patterns, and UX principles.
@@ -69,7 +74,7 @@ fun main() = application {
 - `rememberWindowState()` manages size/position
 - `onCloseRequest` handles window close
 
-**See:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt` — `fun main()` at L172, `application {` at L186, top-level `Window` at L229, `MenuBar` at L234.
+**See:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt` — grep for `fun main()`, `application {`, the top-level `Window`, and `MenuBar {` (the file is large and line numbers drift; navigate by symbol).
 
 ---
 
@@ -275,9 +280,9 @@ Row(Modifier.fillMaxSize()) {
 }
 ```
 
-**See:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/deck/SinglePaneLayout.kt` (NavigationRail at L97, items at L103+). `DeckLayout` alongside it handles multi-pane workspaces.
+**In Amethyst Desktop:** the sidebar is the custom `MainSidebar` composable in `desktopApp/.../ui/deck/DeckSidebar.kt`, instantiated from `Main.kt` and shared by both layout modes (`SinglePaneLayout` and the multi-pane `DeckLayout` alongside it). It is hand-rolled, not Material's `NavigationRail` — use `NavigationRail` only for new, simpler cases.
 
-**Why NavigationRail?**
+**Why a left sidebar?**
 - Desktop has horizontal space (1200+ dp width)
 - Vertical sidebar is standard desktop pattern
 - Always visible (no tabs hidden)
@@ -285,7 +290,7 @@ Row(Modifier.fillMaxSize()) {
 
 **Android comparison:**
 - Android: `BottomNavigationBar` (horizontal, bottom)
-- Desktop: `NavigationRail` (vertical, left)
+- Desktop: left vertical sidebar (`MainSidebar`)
 
 ### Multi-Pane Layouts
 

.claude/skills/desktop-expert/references/desktop-navigation.md

@@ -11,11 +11,11 @@ Comparison of mobile vs desktop navigation patterns in AmethystMultiplatform.
 
 ---
 
-## Desktop: NavigationRail
+## Desktop: Left Sidebar
 
 ### Current Implementation
 
-**File:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/deck/SinglePaneLayout.kt` (NavigationRail begins at L97; `NavigationRailItem`s at L103 and L127+).
+**File:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/deck/DeckSidebar.kt` — the custom `MainSidebar` composable, instantiated from `Main.kt` and shared by both `SinglePaneLayout` and the multi-pane `DeckLayout`. Amethyst Desktop does **not** use Material's `NavigationRail`; the snippet below shows the generic Compose pattern for reference, useful for simpler new surfaces.
 
 ```kotlin
 @Composable

.claude/skills/feed-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feed-patterns
-description: Feed composition and data-access layer patterns in Amethyst. Use when adding or modifying a feed (home, profile, hashtag, bookmarks, notifications, DMs, communities), working with `FeedFilter` / `AdditiveComplexFeedFilter` / `ChangesFlowFilter` / `FilterByListParams` in `amethyst/.../ui/dal/`, or extending the `FeedViewModel` family in `commons/.../viewmodels/`. Covers how feeds scan `LocalCache`, react to changes, apply ordering, and render through Compose.
+description: Feed composition and data-access layer patterns in Amethyst. Use when adding or modifying a feed (home, profile, hashtag, bookmarks, notifications, DMs, communities), working with the shared `FeedFilter` / `AdditiveFeedFilter` / `ChangesFlowFilter` / `FeedContentState` in `commons/.../ui/feeds/`, the Android-only `AdditiveComplexFeedFilter` / `FilterByListParams` in `amethyst/.../ui/dal/`, or extending the `FeedViewModel` family in `commons/.../viewmodels/`. Covers how feeds scan `LocalCache`, react to changes, apply ordering, and render through Compose.
 ---
 
 # Feed Patterns
@@ -24,27 +24,33 @@ Amethyst's "feed" abstraction is: a `FeedFilter` that decides which notes belong
 │                 ◄── ChatroomFeedViewModel                   │
 │                 ◄── MarmotGroupFeedViewModel                │
 │                                                             │
-│   FeedContentState — the flow the UI collects               │
+│                                                             │
+│ commons/.../ui/feeds/  (shared, KMP)                        │
+│   IFeedFilter / FeedFilter<T>  (abstract base)              │
+│   IAdditiveFeedFilter / AdditiveFeedFilter<T>               │
+│   ChangesFlowFilter                                         │
+│   FeedContentState, FeedState — the flow the UI collects    │
 └─────────────────────────────────────────────────────────────┘
               ▲
               │ uses
               │
 ┌─────────────────────────────────────────────────────────────┐
-│ amethyst/.../ui/dal/  (Android; feeds defined per screen)   │
-│   FeedFilter<T>   (abstract)                                │
+│ amethyst/.../ui/dal/  (Android-only additions)              │
 │   AdditiveComplexFeedFilter<T, U>                           │
-│   ChangesFlowFilter                                         │
 │   FilterByListParams                                        │
-│   DefaultFeedOrder                                          │
+│   DefaultFeedOrder (Note/Event/Card comparators)            │
+│   (FeedFilters.kt & ChangesFlowFilter.kt here are just      │
+│    back-compat typealiases re-exporting commons)            │
 │                                                             │
-│   Plus concrete feeds: HomeFeedFilter, HashtagFeedFilter,   │
-│   BookmarkListFeedFilter, NotificationFeedFilter, …         │
+│   Concrete feeds: HomeNewThreadFeedFilter,                  │
+│   HashtagFeedFilter, NotificationFeedFilter, … live in      │
+│   feature folders under ui/screen/loggedIn/*/dal/           │
 └─────────────────────────────────────────────────────────────┘
               ▲
               │ reads
               │
 ┌─────────────────────────────────────────────────────────────┐
-│ model/LocalCache.kt + Account.<featureFlow>                 │
+│ model/LocalCache.kt + account.<feature>.flow                │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -60,25 +66,33 @@ Amethyst's "feed" abstraction is: a `FeedFilter` that decides which notes belong
 - **`MarmotGroupFeedViewModel.kt`** — NIP-29 / marmot group feed.
 - **`LiveStreamTopZappersViewModel.kt`, `SearchBarState.kt`, `ChatNewMessageState.kt`** — narrower, non-feed states that share the plumbing.
 
-### Android DAL (the filters)
+### Shared filter bases (commons)
+
+`commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/feeds/`:
+
+- **`FeedFilter.kt`** — `abstract class FeedFilter<T> : IFeedFilter<T>`. Has `feed(): List<T>` (the sync query against the cache), `feedKey(): String` (identity used to cache), `limit()`, and `loadTop()`.
+- **`AdditiveFeedFilter.kt`** — `abstract class AdditiveFeedFilter<T> : FeedFilter<T>(), IAdditiveFeedFilter<T>`. Adds incremental updates (the "additive" part): `updateListWith(oldList, newItems)` runs `applyFilter(newItems)` and grafts accepted items onto the existing list (re-`sort` + `take(limit())`) without recomputing everything.
+- **`ChangesFlowFilter.kt`** — wraps a filter with a coarse "state changed" signal so the ViewModel knows to re-query.
+- **`FeedContentState.kt` / `FeedState.kt`** — the reactive state the UI collects.
+
+### Android DAL (additions on top)
 
 `amethyst/src/main/java/com/vitorpamplona/amethyst/ui/dal/`:
 
-- **`FeedFilters.kt`** — `abstract class FeedFilter<T>`. Has `feed(): List<T>` (the sync query against `LocalCache`) and `feedKey(): String` (identity used to cache).
-- **`AdditiveComplexFeedFilter.kt`** — `abstract class AdditiveComplexFeedFilter<T, U> : FeedFilter<T>()`. Adds incremental updates (the "additive" part): when a single new event arrives, the filter can decide whether to graft it onto the existing list without recomputing everything.
-- **`ChangesFlowFilter.kt`** — wraps a filter with a coarse "Account state changed" signal so the ViewModel knows to re-query.
-- **`FilterByListParams.kt`** — common parameters (author set, exclude muted, limit, since/until) shared across many filters.
-- **`DefaultFeedOrder.kt`** — standard sort (by `createdAt` desc, plus tiebreakers for stable paging).
+- **`AdditiveComplexFeedFilter.kt`** — `abstract class AdditiveComplexFeedFilter<T, U> : FeedFilter<T>()`: like `AdditiveFeedFilter` but the incoming items (`Set<U>`) are a different type than the list rows (`T`).
+- **`FilterByListParams.kt`** — common parameters (top-nav filter, exclude muted, since/until) shared across many filters.
+- **`DefaultFeedOrder.kt`** — standard comparators (`createdAt` desc + id tiebreaker for stable paging) for `Note`, `Event`, and `Card`.
+- **`FeedFilters.kt` / `ChangesFlowFilter.kt`** — back-compat typealiases re-exporting the commons classes; don't add logic here.
 
-Concrete filters (Home, Hashtag, Profile, Bookmark, Notifications, Communities, etc.) live in feature subfolders under `amethyst/.../ui/screen/loggedIn/*/` — each extends `FeedFilter` or `AdditiveComplexFeedFilter`.
+Concrete filters (Home, Hashtag, Profile, Bookmark, Notifications, Communities, etc.) live in feature `dal/` subfolders under `amethyst/.../ui/screen/loggedIn/*/` — each extends `FeedFilter`, `AdditiveFeedFilter`, or `AdditiveComplexFeedFilter`. Desktop has its own in `desktopApp/.../feeds/DesktopFeedFilters.kt`.
 
 ## Adding a New Feed
 
-1. **Define the filter.** Extend `AdditiveComplexFeedFilter<Note, Set<HexKey>>` (or plain `FeedFilter<Note>` if additivity doesn't matter). Implement:
+1. **Define the filter.** Extend `AdditiveFeedFilter<Note>` (or plain `FeedFilter<Note>` if additivity doesn't matter; `AdditiveComplexFeedFilter<T, U>` if incoming items differ in type from list rows). Implement:
    - `feedKey()` — stable identity (e.g. hashtag name, account pubkey).
    - `feed()` — synchronous scan over `LocalCache` / `Account` state producing an ordered list.
    - `limit()` — pagination hint.
-   - If using `AdditiveComplexFeedFilter`: `applyFilter(collection: Set<Note>): Set<Note>` and `sort(collection: Set<Note>): List<Note>`.
+   - If additive: `applyFilter(collection: Set<Note>): Set<Note>` and `sort(collection: Set<Note>): List<Note>`.
 2. **Pick or write a ViewModel.** If the feed's membership shifts often (bookmarks, notifications), extend `ListChangeFeedViewModel`. Otherwise `FeedViewModel`.
 3. **Wire invalidation.** The ViewModel must observe the right `Account` flows + `LocalCacheFlow` so it re-queries when state changes.
 4. **Render.** In the composable, collect `viewModel.feedState.feedContent` and render with a `LazyColumn { items(..., key = { it.id }) { NoteCompose(it) } }`.
@@ -86,9 +100,9 @@ Concrete filters (Home, Hashtag, Profile, Bookmark, Notifications, Communities,
 
 ## Filter Sharing (Android vs Desktop)
 
-- `FeedFilter` and the concrete filters currently live in `amethyst/.../ui/dal/` — **Android-only**. Desktop has parallel filters in `desktopApp/.../feeds/`.
-- ViewModels are in `commons/commonMain/` — **shared**. That's the boundary: filter is Android (could be extracted), ViewModel is shared.
-- When porting a new feed, extract the filter to a KMP-friendly location only if both platforms need it.
+- The filter **base classes** (`FeedFilter`, `AdditiveFeedFilter`, `ChangesFlowFilter`) and feed state (`FeedContentState`) are in `commons/.../ui/feeds/` — **shared**. ViewModels are in `commons/.../viewmodels/` — **shared**.
+- The **concrete** filters are platform-local: Android's in `amethyst/.../ui/screen/loggedIn/*/dal/`, Desktop's in `desktopApp/.../feeds/`. `amethyst/.../ui/dal/` keeps Android-only helpers (`AdditiveComplexFeedFilter`, `FilterByListParams`, `DefaultFeedOrder`) plus back-compat typealiases.
+- When porting a feed, share the concrete filter only if both platforms need identical inclusion rules.
 
 ## Gotchas
 
@@ -96,7 +110,7 @@ Concrete filters (Home, Hashtag, Profile, Bookmark, Notifications, Communities,
 - **`feedKey()` is used as a cache key.** Two different semantic feeds must produce different keys, otherwise their state cross-contaminates.
 - **Additive updates must stay consistent with the full recompute.** If `applyFilter` accepts a note that `feed()` wouldn't include, UX drifts.
 - **Paging isn't free** — use `limit()` and `since/until` in `FilterByListParams` rather than trimming a giant scan.
-- **Notifications feed is special** — it inspects `Account.followListFlow` and `LocalCache` deletions to hide muted/deleted content; always run through `FilterByListParams.exclude*` paths rather than filtering post-hoc.
+- **Notifications feed is special** — it inspects the follow/mute state (`account.kind3FollowList.flow`, `account.hiddenUsers`) and `LocalCache` deletions to hide muted/deleted content; always run through the `FilterByListParams` exclusion paths rather than filtering post-hoc.
 
 ## References
 

.claude/skills/feed-patterns/references/feed-filter-composition.md

@@ -7,11 +7,12 @@ Step-by-step recipe for composing a new feed. Assume the feed shows `Note`s filt
 | If… | Use |
 |-----|-----|
 | Membership is stable (e.g. "my follows") and you re-compute on change | `FeedFilter<Note>` |
-| New notes arrive one at a time and should slot into the list incrementally | `AdditiveComplexFeedFilter<Note, Set<Note>>` |
+| New notes arrive one at a time and should slot into the list incrementally | `AdditiveFeedFilter<Note>` |
+| Incoming items are a different type than the list rows | `AdditiveComplexFeedFilter<T, U>` (Android-only) |
 | The feed is a simple list that changes frequently (e.g. bookmarks, lists) | `FeedFilter<Note>` + `ListChangeFeedViewModel` |
 | The feed is a DM thread | `ChatroomFeedViewModel` (already provides filter machinery) |
 
-All live in `amethyst/src/main/java/com/vitorpamplona/amethyst/ui/dal/`.
+The bases live in `commons/src/commonMain/.../commons/ui/feeds/`; `AdditiveComplexFeedFilter` and the `FilterByListParams` / `DefaultFeedOrder` helpers in `amethyst/src/main/java/.../ui/dal/`.
 
 ## 2. Write the Filter
 
@@ -19,7 +20,7 @@ All live in `amethyst/src/main/java/com/vitorpamplona/amethyst/ui/dal/`.
 class HashtagFeedFilter(
     private val accountViewModel: AccountViewModel,
     private val hashtag: String,
-) : AdditiveComplexFeedFilter<Note, Set<Note>>() {
+) : AdditiveFeedFilter<Note>() {
 
     override fun feedKey(): String = "Hashtag-$hashtag"
 
@@ -28,7 +29,7 @@ class HashtagFeedFilter(
     override fun feed(): List<Note> {
         val params = FilterByListParams.create(
             excludeMuted = true,
-            hiddenUsers  = accountViewModel.hiddenUsersFlow.value,
+            hiddenUsers  = account.hiddenUsers.flow.value,
         )
         return LocalCache.hashtagIndex[hashtag]
             .orEmpty()
@@ -69,7 +70,7 @@ class HashtagFeedViewModel(
 )
 ```
 
-If membership changes aggressively (e.g. the user toggles a mute), use `ListChangeFeedViewModel` instead and hook into `Account.muteListFlow`.
+If membership changes aggressively (e.g. the user toggles a mute), use `ListChangeFeedViewModel` instead and hook into `account.muteList.flow`.
 
 ## 4. Wire Invalidation
 
@@ -78,7 +79,7 @@ If membership changes aggressively (e.g. the user toggles a mute), use `ListChan
 ```kotlin
 init {
     viewModelScope.launch {
-        accountViewModel.muteListFlow.collect { invalidateAll() }
+        account.muteList.flow.collect { invalidateAll() }
     }
 }
 ```

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

@@ -15,6 +15,23 @@ 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
 
+## 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.
+
+What this means for this skill:
+
+1. **The raw on-disk diff is the candidate set.** A key missing from a locale file is either genuinely untranslated *or* a source-identical entry Crowdin stripped. Both are reported; the human decides which to skip. The Crowdin web UI ("N untranslated") is the ground truth for what genuinely needs work.
+2. **Source-identical entries are a small, recognizable minority.** Brand terms (`Nowhere X`), single-word loanwords (`Apps` / `Feed` / `Issues`), and bare version/format strings (`v%1$s`) are the usual cases. Skip these by inspection rather than translating them to something identical.
+3. **Don't add source-identical fallbacks.** Android falls back to `values/strings.xml` at runtime, so a key intentionally kept as English already renders correctly, and Crowdin's next sync would strip a local duplicate anyway.
+
+> **Historical note:** an earlier version of this skill tried to auto-filter the
+> candidate list with a git "sync-timestamp" heuristic (skip any key added before
+> the last `New Crowdin translations` commit). It was **dropped** because it
+> produced false negatives: a key added shortly before an export that translators
+> simply hadn't reached yet is genuinely missing, but the heuristic classified it
+> as "Crowdin already decided." Trust the raw diff + the Crowdin UI instead.
+
 ## Target Locales
 
 The default set of locales (unless the user specifies otherwise):
@@ -39,24 +56,55 @@ Target:   amethyst/src/main/res/values-<locale>/strings.xml
 
 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.
 
+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.).
+
 ```bash
-# Extract translatable keys from default (exclude translatable="false")
+# Strings: extract translatable keys from default (exclude translatable="false")
+echo "=== missing <string> ==="
 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 \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort)
+
+# Plurals: a separate resource type — MUST be diffed independently
+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 \
+    | sed 's/.*name="\([^"]*\)".*/\1/' | sort)
 ```
 
-This gives the list of missing key names. Do NOT diff each locale separately — assume the same keys are missing in all target locales.
+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":
+
+```bash
+for locale in cs-rCZ 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) \
+    <(grep '<string name=' amethyst/src/main/res/values-$locale/strings.xml \
+      | sed 's/.*name="\([^"]*\)".*/\1/' | sort) | wc -l)
+  np=$(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-$locale/strings.xml \
+      | sed 's/.*name="\([^"]*\)".*/\1/' | sort) | wc -l)
+  echo "$locale: strings=$ns plurals=$np total=$((ns+np))"
+done
+```
+
+The combined `strings + plurals` total should line up with the Crowdin web UI's untranslated count for that locale. If it does, the raw diff is your actionable set (minus any source-identical entries you skip by inspection — see Background).
 
 ### 3. Get English values for missing keys
 
-For each missing key, extract its English value:
+For each missing key, extract its English value. `<string>` is a single line; `<plurals>` is a multi-line block — handle each appropriately.
 
 ```bash
-# For each missing key, extract the full line from default strings.xml
+# Missing <string>: full line from default strings.xml
 while IFS= read -r key; do
   grep "name=\"$key\"" amethyst/src/main/res/values/strings.xml
 done < <(comm -23 \
@@ -65,6 +113,19 @@ done < <(comm -23 \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
   <(grep '<string name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
+
+# Missing <plurals>: extract the multi-line block (opening tag through </plurals>)
+while IFS= read -r key; do
+  awk -v key="$key" '
+    $0 ~ "<plurals name=\"" key "\"" { in_p = 1 }
+    in_p { print }
+    in_p && /<\/plurals>/ { in_p = 0 }
+  ' amethyst/src/main/res/values/strings.xml
+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 \
+    | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
 ```
 
 ### 4. Audit missing strings for plural-shaped patterns
@@ -74,7 +135,14 @@ Before presenting results, **scan the missing English strings** for two red-flag
 1. **Hardcoded `"1"` next to a noun.** A new English string like `"1 reply"`, `"1 follower"`, or `"1 minute ago"` almost always belongs in a `<plurals>` resource — not a `<string>`. Hardcoding `1` in English forces every translator to either also hardcode `1` (breaking languages where the `one` category covers other numbers, e.g. some Slavic languages) or to silently change the meaning.
 2. **A `%d` / `%1$d` placeholder in a clearly singular/plural sentence** (e.g. `"%1$d reply"`, `"%d follower"`). Even though the placeholder is parameterised, English-only `one`/`other` agreement won't survive translation into languages that need `few`/`many`.
 
-Also **audit existing `<plurals>` resources** for the same anti-pattern — any locale's `quantity="one"` item that hardcodes the literal `1` (instead of using a `%d` / `%1$d` placeholder) is broken for languages where the `one` CLDR category covers more than just `n=1` (Russian, Ukrainian, Croatian, etc.). Flag and offer to fix:
+Also **audit existing `<plurals>` resources** for two anti-patterns:
+
+1. **`quantity="one"` items that hardcode the literal `1`** (instead of using a `%d` / `%1$d` placeholder) — broken for languages where the `one` CLDR category covers more than just `n=1` (Russian, Ukrainian, Croatian, etc.).
+2. **`quantity="zero"` items in any locale that doesn't natively use the `zero` CLDR category** — i.e. **everything except Arabic (`ar`) and Welsh (`cy`)**. ICU/CLDR maps `count=0` to `other` for English and all the locales we ship to (cs, de, pt-BR, sv, etc.), so `<item quantity="zero">` is **dead code** there: `getQuantityString(id, 0)` will pick `other`, never the zero entry, and the visible runtime string ends up `"…0 items"` instead of the intended `"…no items"`.
+
+If a UX genuinely wants special "no items" wording at count=0, that has to be a call-site `if (count == 0)` branch to a separate `<string>`, **not** a `quantity="zero"` plural item.
+
+Flag and offer to fix:
 
 ```bash
 # Scan every locale's strings.xml for <item quantity="one"> entries that
@@ -96,6 +164,27 @@ for f in amethyst/src/main/res/values/strings.xml amethyst/src/main/res/values-*
 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
+  # Skip Arabic and Welsh — they natively use the zero category.
+  case "$f" in
+    *values-ar*|*values-cy*) continue ;;
+  esac
+  awk -v file="$f" '
+    /<plurals/ { in_plurals = 1; name = $0; sub(/.*name="/, "", name); sub(/".*/, "", name) }
+    in_plurals && /quantity="zero"/ {
+      text = $0; sub(/^[^>]*>/, "", text); sub(/<.*$/, "", text)
+      print file ":  <plurals name=\"" name "\">  zero=\"" text "\""
+    }
+    /<\/plurals>/ { in_plurals = 0 }
+  ' "$f"
+done
+```
+
+For each hit, warn the user that the entry is unreachable in that locale. The fix is to **remove the `<item quantity="zero">`** and, if the UX wanted distinct wording for count=0, add a separate `<string>` plus an `if (count == 0)` branch at the call site (see "Plurals: handle with care" below).
+
 Quick scan over the missing keys:
 
 ```bash
@@ -147,6 +236,14 @@ When adding or proposing **`<plurals>`** entries, follow these rules:
   - Arabic (`ar`): `zero`, `one`, `two`, `few`, `many`, `other`
   - German / Swedish / Brazilian Portuguese: `one`, `other`
 - When a missing string contains a count placeholder and is conceptually a singular/plural pair, **flag it before translating** — it may belong as a `<plurals>` resource rather than a single `<string>`. Surface this to the user before proposing translations.
+- **Do not use `quantity="zero"` outside Arabic (`ar`) and Welsh (`cy`).** CLDR's `zero` category is integer-bearing only in those two languages. Android calls `PluralRules.select(0)` for the device locale; in English/German/Czech/Polish/Russian/Swedish/Portuguese/etc. it returns `other`, so the explicit `<item quantity="zero">` is never picked at runtime and the user sees `"…0 items"` instead of the intended wording. If the design calls for "no items" at count=0, model it as a separate `<string>` and an `if (count == 0)` branch at the call site:
+  ```kotlin
+  val label = if (count == 0) {
+      stringRes(R.string.foo_no_items, dateLabel)
+  } else {
+      pluralStringResource(R.plurals.foo_items, count, dateLabel, count)
+  }
+  ```
 - Reference: [Android `<plurals>` docs](https://developer.android.com/guide/topics/resources/string-resource#Plurals) and [CLDR plural rules](https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html).
 
 **Then ask the user:** "Would you like me to translate these missing strings into [list of target locales]?"
@@ -161,8 +258,11 @@ When adding translated strings to locale files:
 ## Common Mistakes
 
 - **Forgetting `translatable="false"`** — these should never appear in locale files
-- **Not checking string-arrays/plurals** — only checking `<string>` misses other resource types
-- **Diffing each locale separately** — only diff against `cs-rCZ`; assume the same keys are missing everywhere
+- **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.
 - **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`)
+- **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`)
+- **Using `<item quantity="zero">` to special-case count=0** — outside Arabic and Welsh, this entry is unreachable: ICU/CLDR maps 0 → `other`, so the runtime never picks the zero item and the user sees `"…0 items"`. Special-case at the call site with a separate `<string>` instead.

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

@@ -5,11 +5,11 @@ description: Build optimization, dependency resolution, and multi-module KMP tro
 
 # Gradle Expert
 
-Build system expertise for AmethystMultiplatform's 4-module KMP architecture. Focus: practical troubleshooting, dependency resolution, and project-specific optimizations.
+Build system expertise for AmethystMultiplatform's 10-module KMP architecture (`amethyst`, `benchmark`, `quartz`, `geode`, `commons`, `quic`, `nestsClient`, `desktopApp`, `cli`, `quic-interop` — see `settings.gradle.kts`). Focus: practical troubleshooting, dependency resolution, and project-specific optimizations.
 
 ## Build Architecture Mental Model
 
-Think of this project as **4 layers**:
+The core app stack is **4 layers** (the other modules hang off it: `cli` and `geode` are JVM apps over `commons`/`quartz`, `nestsClient` sits on `quic`, `benchmark` and `quic-interop` are test harnesses):
 
 ```
 ┌─────────────┬─────────────┐
@@ -165,11 +165,11 @@ implementation(libs.jna)
 
 **The problem:** Two Compose ecosystems (Multiplatform + AndroidX) must align, or duplicate classes.
 
-**Current project config:**
+**Current project config** (always re-check `gradle/libs.versions.toml` — these drift):
 ```toml
-composeMultiplatform = "1.9.3"  # Plugin + runtime
-composeBom = "2025.12.01"       # AndroidX Compose BOM
-kotlin = "2.3.0"
+composeMultiplatform = "1.11.1"  # Plugin + runtime
+composeBom = "2026.05.01"        # AndroidX Compose BOM
+kotlin = "2.3.21"
 ```
 
 **Rule:** Compose Multiplatform version must be compatible with Kotlin version. Check: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compatibility-and-versioning.html

.claude/skills/gradle-expert/references/dependency-graph.md

@@ -3,46 +3,50 @@
 ## Visual Hierarchy
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                    Root Project                          │
-│                     (Amethyst)                           │
-└─────────────────────────────────────────────────────────┘
-                          │
-         ┌────────────────┼────────────────┐
-         │                │                │
-         ▼                ▼                ▼
-┌─────────────┐  ┌─────────────┐  ┌─────────────┐
-│  :amethyst  │  │ :desktopApp │  │ :benchmark  │
-│  (Android)  │  │   (JVM)     │  │  (Android)  │
-└─────────────┘  └─────────────┘  └─────────────┘
-       │                │                │
-       │                │                │
-       └────────────────┼────────────────┘
-                        │
-                        ▼
-                ┌─────────────┐
-                │  :commons   │
-                │  (KMP UI)   │
-                │             │
-                │ jvmAndroid  │
-                │  /      \   │
-                │ jvm   android│
-                └─────────────┘
-                        │
-                        │
-                        ▼
-                ┌─────────────┐
-                │  :quartz    │
-                │(KMP Library)│
-                │             │
-                │ commonMain  │
-                │     │       │
-                │ jvmAndroid  │
-                │  /  |  \    │
-                │jvm and ios  │
-                └─────────────┘
+   Apps / harnesses                                  Libraries
+┌─────────────┐ ┌─────────────┐ ┌────────────┐
+│  :amethyst  │ │ :desktopApp │ │ :benchmark │
+│  (Android)  │ │    (JVM)    │ │ (Android)  │
+└──┬───┬───┬──┘ └──┬───────┬──┘ └─┬───────┬──┘
+   │   │   └───────┼────┐  │      │       │
+   │   │           │    │  │      │       │
+   │   ▼           ▼    │  │      ▼       │
+   │ ┌────────────────┐ │  │ (androidTest │
+   │ │   :commons     │◄┼──┼──only)       │
+   │ │   (KMP UI)     │ │  │              │
+   │ └───────┬────────┘ │  │              │
+   │         │     ▲    │  │              │
+   ▼         │     │    │  │              │
+┌──────────────┐   │  ┌─┴──┴─┐  ┌───────┐ │
+│ :nestsClient │   │  │ :cli │  │:geode │ │
+│ (KMP, MoQ)   │   │  │(JVM) │  │(JVM   │ │
+└──┬────────┬──┘   │  └──┬───┘  │relay) │ │
+   │        │      │     │      └───┬───┘ │
+   ▼        │      │     │          │     │
+┌────────┐  │      │     │          │     │
+│ :quic  │  │      │     │          │     │
+│ (KMP)  │  │      │     │          │     │
+└───┬────┘  │      │     │          │     │
+    │ ▲     │      │     │          │     │
+    │ └── :quic-interop  │          │     │
+    ▼       ▼      ▼     ▼          ▼     ▼
+        ┌──────────────────────────────┐
+        │           :quartz            │
+        │         (KMP Library)        │
+        └──────────────────────────────┘
 ```
 
+Verified edges (from each module's `build.gradle.kts`):
+
+- `:amethyst` → `:quartz`, `:commons`, `:nestsClient`
+- `:desktopApp` → `:quartz`, `:commons`
+- `:benchmark` → `:quartz`, `:commons` (androidTest only)
+- `:cli` → `:quartz`, `:commons`
+- `:geode` → `:quartz` (api + testFixtures)
+- `:nestsClient` → `:quartz` (api), `:quic`
+- `:quic` → `:quartz` (api)
+- `:quic-interop` → `:quic` (project dir: `quic/interop`)
+
 ## Module Details
 
 ### :quartz (KMP Nostr Library)
@@ -86,11 +90,41 @@
 **Type:** Android Library
 **Targets:** Android
 **Dependencies:**
-- Modules: `:commons`, `:quartz`
+- Modules: `:commons`, `:quartz` (androidTest only)
 - External: AndroidX Benchmark
 
 **Role:** Performance benchmarking for Android builds
 
+### :cli (Amy CLI)
+**Type:** JVM Application (no Compose)
+**Dependencies:** `:quartz`, `:commons`
+
+**Role:** `amy`, the non-interactive command-line client; thin assembly layer, no new logic (see `amy-expert` skill)
+
+### :geode (Relay Server)
+**Type:** JVM Application (Ktor)
+**Dependencies:** `:quartz` (api + testFixtures)
+
+**Role:** Standalone Nostr relay built on quartz's relay-server code
+
+### :quic (QUIC Transport)
+**Type:** Kotlin Multiplatform Library
+**Dependencies:** `:quartz` (api)
+
+**Role:** Pure-Kotlin QUIC v1 + HTTP/3 + WebTransport client (no JNI); transport for MoQ
+
+### :nestsClient (Audio Rooms)
+**Type:** Kotlin Multiplatform Library
+**Dependencies:** `:quartz` (api), `:quic`
+
+**Role:** MoQ / moq-lite audio-room client for the NIP-53 nests feature
+
+### :quic-interop (Interop Harness)
+**Type:** JVM Application (project dir `quic/interop`)
+**Dependencies:** `:quic`
+
+**Role:** QUIC interop-runner test client
+
 ## Dependency Flow Patterns
 
 ### Desktop Build Chain
@@ -177,9 +211,9 @@ implementation(libs.jna)  // JAR variant
 implementation(compose.ui)              // Compose Multiplatform BOM
 implementation(compose.material3)
 
-// Version catalog alignment
-composeMultiplatform = "1.9.3"
-composeBom = "2025.12.01"  // AndroidX Compose
+// Version catalog alignment (re-check libs.versions.toml — these drift)
+composeMultiplatform = "1.11.1"
+composeBom = "2026.05.01"  // AndroidX Compose
 ```
 **Why:** Two Compose ecosystems (Multiplatform + AndroidX) must align
 

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

@@ -807,6 +807,5 @@ Passing lambda to function?
 
 ---
 
-**Version:** 1.0.0
-**Last Updated:** 2025-12-30
-**Codebase Reference:** AmethystMultiplatform commit 258c4e011
+**Version:** 1.0.1
+**Last Updated:** 2026-06-10

.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 (57 NIPs 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). Complements nostr-protocol agent (NIP specs) - this skill provides Quartz codebase patterns and implementation details.
 ---
 
 # Nostr Protocol Expert (Quartz Implementation)
@@ -313,26 +313,24 @@ class LocalSigner(private val privateKey: ByteArray) : ISigner {
 ### Encryption (NIP-44)
 
 ```kotlin
-// Modern encryption (ChaCha20-Poly1305)
-object Nip44v2 {
-    fun encrypt(plaintext: String, privateKey: ByteArray, pubKey: HexKey): String
-    fun decrypt(ciphertext: String, privateKey: ByteArray, pubKey: HexKey): String
+// Modern encryption (ChaCha20-Poly1305) via the Nip44 facade
+// (nip44Encryption/Nip44.kt — picks the current version, decrypts any)
+object Nip44 {
+    fun encrypt(msg: String, privateKey: ByteArray, pubKey: ByteArray): Nip44v2.EncryptedInfo
+    fun decrypt(payload: String, privateKey: ByteArray, pubKey: ByteArray): String
 }
 
 // Usage
-val encrypted = Nip44v2.encrypt(
-    plaintext = "Secret message",
-    privateKey = myPrivateKey,
-    pubKey = recipientPubKey
-)
+val encrypted = Nip44.encrypt("Secret message", myPrivateKey, recipientPubKey)
+val payload = encrypted.encodePayload()  // base64 string for event content
 
-val decrypted = Nip44v2.decrypt(
-    ciphertext = encrypted,
-    privateKey = myPrivateKey,
-    pubKey = senderPubKey
-)
+val decrypted = Nip44.decrypt(payload, myPrivateKey, senderPubKey)
 ```
 
+Most code should not call `Nip44` directly — go through
+`signer.nip44Encrypt(plaintext, toPublicKey)` / `signer.nip44Decrypt(ciphertext, fromPublicKey)`
+so remote/external signers keep working.
+
 **Pattern**: Elliptic curve Diffie-Hellman + ChaCha20-Poly1305 AEAD.
 
 ### NIP-04 (Deprecated)
@@ -345,44 +343,34 @@ object Nip04 {
 }
 ```
 
-**Note**: Use NIP-44 (Nip44v2) for new implementations. NIP-04 has security issues.
+**Note**: Use NIP-44 (`Nip44`) for new implementations. NIP-04 has security issues.
 
 ## Bech32 Encoding (NIP-19)
 
+Encoding uses extension functions on `ByteArray` (`nip19Bech32/ByteArrayExt.kt`);
+TLV entities carry relay hints via `create()` helpers on the entity classes in
+`nip19Bech32/entities/`. Decoding goes through `Nip19Parser`, whose
+`uriToRoute()` returns a `ParseReturn?` wrapping the parsed `Entity`.
+
 ```kotlin
-object Nip19 {
-    // Encode
-    fun npubEncode(pubkey: HexKey): String  // npub1...
-    fun nsecEncode(privateKey: ByteArray): String  // nsec1...
-    fun noteEncode(eventId: HexKey): String  // note1...
-    fun neventEncode(eventId: HexKey, relays: List<String> = emptyList()): String
-    fun nprofileEncode(pubkey: HexKey, relays: List<String> = emptyList()): String
-    fun naddrEncode(kind: Int, pubkey: HexKey, dTag: String, relays: List<String> = emptyList()): String
+// Encode simple entities: ByteArray extensions
+val npub = pubkeyBytes.toNpub()   // "npub1..."
+val nsec = privKeyBytes.toNsec()  // "nsec1..."
+val note = eventIdBytes.toNote()  // "note1..."
 
-    // Decode
-    fun decode(bech32: String): Nip19Result
-}
-
-sealed class Nip19Result {
-    data class NPub(val hex: HexKey) : Nip19Result()
-    data class NSec(val hex: HexKey) : Nip19Result()
-    data class Note(val hex: HexKey) : Nip19Result()
-    data class NEvent(val hex: HexKey, val relays: List<String>) : Nip19Result()
-    data class NProfile(val hex: HexKey, val relays: List<String>) : Nip19Result()
-    data class NAddr(val kind: Int, val pubkey: HexKey, val dTag: String, val relays: List<String>) : Nip19Result()
-}
+// Encode TLV entities with relay hints (relays: List<NormalizedRelayUrl>)
+val nevent = NEvent.create(eventIdHex, authorHex, kind, relays)
+val nprofile = NProfile.create(pubkeyHex, relays)
 ```
 
 **Usage**:
 ```kotlin
-// Encode
-val npub = Nip19.npubEncode(pubkeyHex)
-// Output: "npub1..."
-
-// Decode
-when (val result = Nip19.decode(npub)) {
-    is Nip19Result.NPub -> println("Pubkey: ${result.hex}")
-    is Nip19Result.NEvent -> println("Event: ${result.hex}, relays: ${result.relays}")
+// Decode (also accepts nostr: URIs); entity types live in nip19Bech32.entities
+when (val entity = Nip19Parser.uriToRoute(input)?.entity) {
+    is NPub -> println("Pubkey: ${entity.hex}")
+    is NEvent -> println("Event: ${entity.hex}, relays: ${entity.relay}")
+    is NAddress -> println("Address: ${entity.aTag()}")
+    null -> println("not a valid bech32 entity")
     else -> println("Other type")
 }
 ```

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

@@ -1,4 +1,8 @@
-# NIP Catalog: 60 Standard + 8 Experimental NIPs in Quartz
+# NIP Catalog: Quartz NIP Packages
+
+As of 2026-06 Quartz has **87 standard `nip*` packages** plus **23 packages
+under `experimental/`**. The categorized list below may lag behind —
+`ls quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/` is ground truth.
 
 ## Standard NIPs by Category
 

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

@@ -7,7 +7,7 @@ description: Integration guide for using the Quartz Nostr KMP library in externa
 
 Reference for integrating `com.vitorpamplona.quartz:quartz` into external Nostr KMP projects.
 
-**Published artifact**: `com.vitorpamplona.quartz:quartz:1.09.2` (Maven Central)
+**Published artifact**: `com.vitorpamplona.quartz:quartz:1.12.5` (Maven Central)
 **Targets**: JVM 21+, Android (minSdk 21+), iOS (XCFramework `quartz-kmpKit`)
 **License**: MIT
 
@@ -19,7 +19,7 @@ Reference for integrating `com.vitorpamplona.quartz:quartz` into external Nostr
 
 ```toml
 [versions]
-quartz = "1.09.2"
+quartz = "1.12.5"
 
 [libraries]
 quartz = { module = "com.vitorpamplona.quartz:quartz", version.ref = "quartz" }
@@ -41,7 +41,7 @@ kotlin {
 
 ```kotlin
 dependencies {
-    implementation("com.vitorpamplona.quartz:quartz:1.09.2")
+    implementation("com.vitorpamplona.quartz:quartz:1.12.5")
 }
 ```
 
@@ -447,23 +447,28 @@ val textNote = Event.fromJson(json) as? TextNoteEvent
 
 ```kotlin
 import com.vitorpamplona.quartz.nip19Bech32.Nip19Parser
+import com.vitorpamplona.quartz.nip19Bech32.entities.NAddress
+import com.vitorpamplona.quartz.nip19Bech32.entities.NEvent
+import com.vitorpamplona.quartz.nip19Bech32.entities.NNote
+import com.vitorpamplona.quartz.nip19Bech32.entities.NProfile
+import com.vitorpamplona.quartz.nip19Bech32.entities.NPub
 
-// Decode any bech32 entity
-val result = Nip19Parser.uriToRoute("npub1abc...")
-// Returns: NPub | NSec | Note | NEvent | NProfile | NAddr | null
-
-when (val r = Nip19Parser.uriToRoute(input)) {
-    is Nip19Parser.Return.NPub    -> println("pubkey: ${r.hex}")
-    is Nip19Parser.Return.Note    -> println("event id: ${r.hex}")
-    is Nip19Parser.Return.NEvent  -> println("event: ${r.hex}, relays: ${r.relays}")
-    is Nip19Parser.Return.NProfile -> println("profile: ${r.hex}")
-    is Nip19Parser.Return.NAddr   -> println("address: ${r.kind}:${r.pubKey}:${r.dTag}")
-    null -> println("not a valid bech32 entity")
-    else -> {}
+// Decode any bech32 entity (plain or nostr:-prefixed).
+// uriToRoute() returns Nip19Parser.ParseReturn? — the parsed Entity is in .entity
+when (val entity = Nip19Parser.uriToRoute(input)?.entity) {
+    is NPub     -> println("pubkey: ${entity.hex}")
+    is NNote    -> println("event id: ${entity.hex}")
+    is NEvent   -> println("event: ${entity.hex}, relays: ${entity.relay}")
+    is NProfile -> println("profile: ${entity.hex}")
+    is NAddress -> println("address: ${entity.aTag()}")
+    null        -> println("not a valid bech32 entity")
+    else        -> {}
 }
 
-// The parser also handles nostr: URI scheme
-val result = Nip19Parser.uriToRoute("nostr:npub1abc...")
+// Encode: ByteArray extensions from nip19Bech32/ByteArrayExt.kt
+val npub = pubkeyBytes.toNpub()   // also toNsec(), toNote(), ...
+// TLV entities with relay hints (relays: List<NormalizedRelayUrl>)
+val nevent = NEvent.create(eventIdHex, authorHex, kind, relays)
 ```
 
 ---
@@ -601,21 +606,22 @@ In Xcode: drag & drop the `.xcframework` into your project, then use from Swift
 
 ---
 
-## 14. Event Store (Android only)
+## 14. Event Store (SQLite, all platforms)
 
-SQLite-based storage with full NIP support (NIP-09, NIP-40, NIP-45, NIP-50, NIP-62):
+SQLite-backed storage in `commonMain` (JVM, Android, iOS — uses the bundled
+androidx.sqlite driver) with full NIP support (NIP-09, NIP-40, NIP-45, NIP-50,
+NIP-62). All operations are `suspend`:
 
 ```kotlin
-import com.vitorpamplona.quartz.nip01Core.store.EventStore
-import android.content.Context
+import com.vitorpamplona.quartz.nip01Core.store.sqlite.EventStore
 
-val store = EventStore()
+val store = EventStore()  // default DB file "events.db"
 
 // Insert
 store.insert(event)
 
 // Query
-val events = store.query(
+val events = store.query<Event>(
     Filter(authors = listOf(pubKey), kinds = listOf(1), limit = 50)
 )
 
@@ -623,7 +629,7 @@ val events = store.query(
 val count = store.count(Filter(kinds = listOf(1)))
 
 // Full-text search (NIP-50)
-val results = store.query(Filter(search = "bitcoin"))
+val results = store.query<Event>(Filter(search = "bitcoin"))
 ```
 
 ---

.claude/skills/quartz-integration/references/gradle-setup.md

@@ -3,7 +3,7 @@
 ## Current version
 
 ```
-com.vitorpamplona.quartz:quartz:1.09.2
+com.vitorpamplona.quartz:quartz:1.12.5
 ```
 
 Check latest: https://central.sonatype.com/artifact/com.vitorpamplona.quartz/quartz
@@ -16,7 +16,7 @@ Check latest: https://central.sonatype.com/artifact/com.vitorpamplona.quartz/qua
 
 ```toml
 [versions]
-quartz = "1.09.2"
+quartz = "1.12.5"
 
 [libraries]
 quartz = { module = "com.vitorpamplona.quartz:quartz", version.ref = "quartz" }
@@ -55,7 +55,7 @@ kotlin {
 ```kotlin
 // build.gradle.kts (app module)
 dependencies {
-    implementation("com.vitorpamplona.quartz:quartz:1.09.2")
+    implementation("com.vitorpamplona.quartz:quartz:1.12.5")
 }
 ```
 
@@ -70,7 +70,7 @@ plugins {
 }
 
 dependencies {
-    implementation("com.vitorpamplona.quartz:quartz:1.09.2")
+    implementation("com.vitorpamplona.quartz:quartz:1.12.5")
     // JNA needed for libsodium (NIP-44) on JVM
     implementation("net.java.dev.jna:jna:5.18.1")
 }

.claude/skills/quartz-kmp.md

@@ -1,23 +0,0 @@
-# Quartz KMP (Legacy Skill — Migration Complete)
-
-> The KMP migration of Quartz is **complete**. This file is kept for historical reference.
->
-> For integrating Quartz into external projects, use the **`quartz-integration`** skill instead.
-> For working with Quartz internals within Amethyst, use the **`nostr-expert`** skill.
-
-## What was migrated
-
-The Quartz library was successfully converted from Android-only to full KMP supporting:
-- **commonMain** — All Nostr protocol logic, events, filters, tags
-- **jvmAndroid** — OkHttp WebSocket, Jackson JSON, relay serializers
-- **androidMain** — SQLite event store, NIP-55 Android signer
-- **jvmMain** — Desktop JVM crypto (lazysodium-java, secp256k1-jni-jvm)
-- **iosMain** — iOS targets (XCFramework `quartz-kmpKit`)
-
-## Current artifact
-
-```
-com.vitorpamplona.quartz:quartz:1.09.2
-```
-
-See `.claude/skills/quartz-integration/SKILL.md` for full integration guide.

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

@@ -24,17 +24,23 @@ relayClient/
 ├── assemblers/              # "Given these inputs, build this relay Filter"
 │   ├── MetadataFilterAssembler.kt      # kind 0 for N pubkeys
 │   ├── ReactionsFilterAssembler.kt     # kind 7 for N note ids
-│   └── FeedMetadataCoordinator.kt      # coordinates metadata loads for a feed
+│   ├── FeedMetadataCoordinator.kt      # coordinates metadata loads for a feed
+│   └── CashuMintDirectoryFilterAssembler.kt / CashuWalletFilterAssembler.kt
 ├── composeSubscriptionManagers/
 │   ├── ComposeSubscriptionManager.kt              # interface Subscribable<T>
 │   ├── MutableComposeSubscriptionManager.kt       # reference impl
 │   └── ComposeSubscriptionManagerControls.kt      # DisposableEffect-style controls
 ├── eoseManagers/            # EOSE tracking per subscription
+│   └── IEoseManager / BaseEoseManager / PerKeyEoseManager / SingleSubEoseManager
+├── nip17Dm/                 # gift-wrap DM plumbing
+│   └── FilterGiftWrapsToPubkey.kt / GiftWrapDecryptor.kt
 ├── preload/
 │   ├── MetadataPreloader.kt            # bulk-fetch metadata with rate limiting
 │   └── MetadataRateLimiter.kt          # token-bucket-ish limiter
 └── subscriptions/
-    └── KeyDataSourceSubscription.kt    # "this set of keys drives this filter"
+    ├── KeyDataSourceSubscription.kt    # "this set of keys drives this filter"
+    ├── LifecycleAwareKeyDataSourceSubscription.kt
+    └── PrioritizedSubscriptionQueue.kt / SubscriptionPriority.kt
 ```
 
 ## Core Concept: `Subscribable<T>`

.github/actions/assert-stable-release/action.yml

@@ -6,7 +6,7 @@ description: >-
 
 inputs:
   tag:
-    description: "Tag to validate (e.g. v1.08.0)"
+    description: "Tag to validate (e.g. vX.YY.Z)"
     required: true
   is_prerelease:
     description: "Whether the release is marked as prerelease (empty string treated as false)"

.github/actions/import-macos-cert/action.yml

@@ -0,0 +1,90 @@
+name: Import macOS Developer ID certificate
+description: >
+  Import a Developer ID Application certificate (base64-encoded .p12) into a
+  throwaway keychain so codesign/jpackage can find it during the job. Soft:
+  when no certificate is supplied it is a no-op and reports signing=false, so
+  callers build UNSIGNED artifacts exactly as before.
+
+inputs:
+  certificate-p12-base64:
+    description: Base64 of the Developer ID Application .p12 (cert + private key)
+    required: true
+  certificate-password:
+    description: Password used when the .p12 was exported
+    required: true
+
+outputs:
+  signing:
+    description: "'true' if a certificate was imported, else 'false'"
+    value: ${{ steps.import.outputs.signing }}
+  keychain:
+    description: >
+      Absolute path of the throwaway keychain holding the imported cert (empty
+      when signing=false). Pass to tools that need an explicit keychain — e.g.
+      Compose's macOS signing, whose certificate lookup doesn't resolve the
+      search list reliably on CI runners the way bare `codesign` does.
+    value: ${{ steps.import.outputs.keychain }}
+  identity:
+    description: >
+      The imported certificate's full "Developer ID Application: NAME (TEAMID)"
+      common name, resolved from the keychain (empty when signing=false or if it
+      could not be parsed). `codesign` accepts a SHA-1 hash or a CN substring,
+      but Compose's MacSigner runs `security find-certificate -c <identity>`
+      after prepending "Developer ID Application: " — so it only works with the
+      exact common name. Feed this to Compose's `signing.identity`.
+    value: ${{ steps.import.outputs.identity }}
+
+runs:
+  using: composite
+  steps:
+    - id: import
+      shell: bash
+      env:
+        CERT_P12: ${{ inputs.certificate-p12-base64 }}
+        CERT_PASSWORD: ${{ inputs.certificate-password }}
+      run: |
+        set -euo pipefail
+        if [[ -z "${CERT_P12:-}" ]]; then
+          echo "::notice::No macOS signing certificate configured — artifacts will be UNSIGNED."
+          echo "signing=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        KEYCHAIN="$RUNNER_TEMP/amethyst-signing.keychain-db"
+        KEYCHAIN_PWD="$(openssl rand -base64 24)"
+        CERT_PATH="$RUNNER_TEMP/developer_id.p12"
+        security create-keychain -p "$KEYCHAIN_PWD" "$KEYCHAIN"
+        security set-keychain-settings -lut 21600 "$KEYCHAIN"
+        security unlock-keychain -p "$KEYCHAIN_PWD" "$KEYCHAIN"
+        echo "$CERT_P12" | base64 --decode > "$CERT_PATH"
+        security import "$CERT_PATH" -P "$CERT_PASSWORD" \
+          -k "$KEYCHAIN" -T /usr/bin/codesign -T /usr/bin/productsign
+        # Let codesign use the private key without an interactive UI prompt.
+        security set-key-partition-list -S apple-tool:,apple:,codesign: \
+          -s -k "$KEYCHAIN_PWD" "$KEYCHAIN" >/dev/null
+        # Prepend our keychain to the user search list so codesign sees it.
+        security list-keychains -d user -s "$KEYCHAIN" \
+          $(security list-keychains -d user | sed -e 's/[\"[:space:]]//g')
+        # Also make it the default keychain. Bare `codesign` resolves identities
+        # via the search list, but some tools (Compose's MacSigner runs
+        # `security find-certificate` to map the identity to a cert) don't find
+        # it on the search list alone on these runners. Callers that need an
+        # explicit keychain can read the `keychain` output below.
+        security default-keychain -d user -s "$KEYCHAIN"
+        rm -f "$CERT_PATH"
+        # Resolve the certificate's exact common name. Compose's MacSigner maps
+        # its identity to a cert via `security find-certificate -c <name>` (after
+        # prepending "Developer ID Application: " when absent), so it needs the
+        # full CN — a SHA-1 hash or partial name in the secret signs fine with
+        # bare `codesign` but yields "Could not find certificate ...". Pull the
+        # canonical name straight from the keychain so the caller is independent
+        # of whatever form the MAC_SIGN_IDENTITY secret takes.
+        IDENTITY_NAME="$(security find-identity -v -p codesigning "$KEYCHAIN" \
+          | grep -o '"Developer ID Application:[^"]*"' | head -1 | tr -d '"' || true)"
+        echo "signing=true" >> "$GITHUB_OUTPUT"
+        echo "keychain=$KEYCHAIN" >> "$GITHUB_OUTPUT"
+        echo "identity=$IDENTITY_NAME" >> "$GITHUB_OUTPUT"
+        if [[ -n "$IDENTITY_NAME" ]]; then
+          echo "::notice::Resolved signing identity: $IDENTITY_NAME"
+        else
+          echo "::warning::Could not resolve a 'Developer ID Application' identity from the keychain; callers will fall back to the MAC_SIGN_IDENTITY secret."
+        fi

.github/workflows/build.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
-          distribution: 'zulu'
+          distribution: 'temurin'
           java-version: 21
 
       # Remote Gradle build cache: writes on push to main, reads on PRs and
@@ -34,12 +34,12 @@ jobs:
       # :amethyst alone). Replaces the narrower `cache: gradle` previously on
       # actions/setup-java, which only cached `modules-2`.
       - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v6
         with:
           cache-read-only: ${{ github.ref != 'refs/heads/main' }}
 
       - name: Linter (gradle)
-        run: ./gradlew spotlessCheck
+        run: ./gradlew spotlessCheck :quartz:verifyKmpPurity :commons:verifyKmpPurity
 
   build-desktop:
     needs: lint
@@ -71,92 +71,28 @@ jobs:
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
-          distribution: 'zulu'
+          distribution: 'temurin'
           java-version: 21
 
       - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v6
         with:
           cache-read-only: ${{ github.ref != 'refs/heads/main' }}
 
-      # Cache vlc-setup plugin downloads (VLC + UPX archives) keyed on the
-      # versions pinned in desktopApp/build.gradle.kts. Each OS gets its own
-      # cache namespace because the plugin downloads platform-specific archives.
-      # On a hit the vlcDownload / upxDownload tasks are up-to-date and we
-      # never touch get.videolan.org; on a miss (version bump or new runner)
-      # we fall back to fetching, which is what the in-build retry budget
-      # exists for.
-      - name: Cache vlc-setup downloads
-        uses: actions/cache@v4
-        with:
-          path: ~/.gradle/vlcSetup
-          key: vlcsetup-${{ runner.os }}-${{ hashFiles('desktopApp/build.gradle.kts') }}
-          restore-keys: |
-            vlcsetup-${{ runner.os }}-
-
-      # Pre-fetch VLC + UPX archives into ~/.gradle/vlcSetup before invoking
-      # Gradle. The vlc-setup plugin (ir.mahozad.vlc-setup 0.1.0) writes its
-      # downloads to ${gradleUserHomeDir}/vlcSetup/ and sets overwrite(false),
-      # so an existing file there makes vlcDownload / upxDownload up-to-date
-      # and Gradle never opens a socket to videolan.org.
-      #
-      # Why curl instead of relying on de.undercouch.gradle.tasks.download:
-      # curl --retry-all-errors with a long --retry-max-time tolerates a
-      # sustained get.videolan.org outage far better than the plugin's inner
-      # retry budget (retries(4) + 5min readTimeout in build.gradle.kts),
-      # which has been hitting SocketTimeoutException on Windows runners.
-      #
-      # Cache hit: the file is already on disk, fetch() short-circuits, this
-      # step takes <1s. Cache miss: curl downloads with aggressive retries,
-      # populating the cache for the next run.
-      #
-      # Versions are pinned to match desktopApp/build.gradle.kts (vlcVersion
-      # = 3.0.20) and the vlc-setup extension default (upxVersion = 4.2.4).
-      # NOTE: vlcVersion lags behind upstream VLC because the Linux plugins on
-      # Maven Central (ir.mahozad:vlc-plugins-linux) are only published for
-      # 3.0.20 / 3.0.20-2. Bump only after the Maven artifact is republished.
-      # macOS does not download UPX — UPX cannot compress .dylib files.
-      - name: Pre-fetch VLC + UPX archives
-        env:
-          VLC_VERSION: "3.0.20"
-          UPX_VERSION: "4.2.4"
-        run: |
-          set -euo pipefail
-          DEST="$HOME/.gradle/vlcSetup"
-          mkdir -p "$DEST"
-          fetch() {
-            local url="$1" out="$2"
-            if [[ -s "$out" ]]; then
-              echo "cached: $out"
-              return 0
-            fi
-            echo "fetching: $url"
-            curl -fL --retry 10 --retry-delay 5 --retry-all-errors \
-                 --retry-max-time 900 --connect-timeout 30 \
-                 -o "$out.part" "$url"
-            mv "$out.part" "$out"
-          }
-          case "${{ runner.os }}" in
-            Windows)
-              fetch "https://get.videolan.org/vlc/${VLC_VERSION}/win64/vlc-${VLC_VERSION}-win64.zip" \
-                    "$DEST/vlc-${VLC_VERSION}.zip"
-              fetch "https://github.com/upx/upx/releases/download/v${UPX_VERSION}/upx-${UPX_VERSION}-win64.zip" \
-                    "$DEST/upx-${UPX_VERSION}.zip"
-              ;;
-            Linux)
-              fetch "https://repo1.maven.org/maven2/ir/mahozad/vlc-plugins-linux/${VLC_VERSION}/vlc-plugins-linux-${VLC_VERSION}.jar" \
-                    "$DEST/vlc-${VLC_VERSION}.jar"
-              fetch "https://github.com/upx/upx/releases/download/v${UPX_VERSION}/upx-${UPX_VERSION}-amd64_linux.tar.xz" \
-                    "$DEST/upx-${UPX_VERSION}.tar.xz"
-              ;;
-            macOS)
-              fetch "https://get.videolan.org/vlc/${VLC_VERSION}/macosx/vlc-${VLC_VERSION}-universal.dmg" \
-                    "$DEST/vlc-${VLC_VERSION}.dmg"
-              ;;
-          esac
+      # Compose UI smoke test (DesktopLaunchSmokeTest) uses Skiko which needs
+      # a display server on Linux. xvfb provides a virtual framebuffer.
+      - name: Install xvfb (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y xvfb
 
       - name: Test + Build Desktop (gradle)
-        run: ./gradlew :quartz:jvmTest :commons:jvmTest :nestsClient:jvmTest :cli:test :desktopApp:test :desktopApp:${{ matrix.desktop-task }}
+        run: |
+          CMD="./gradlew :quartz:jvmTest :commons:jvmTest :nestsClient:jvmTest :cli:test :desktopApp:test :desktopApp:${{ matrix.desktop-task }}"
+          if [ "${{ runner.os }}" = "Linux" ]; then
+            xvfb-run --auto-servernum $CMD
+          else
+            $CMD
+          fi
 
       # jpackage pins libicu to the build host's version (libicu74 on
       # ubuntu-24.04). Rewrite the .deb so testers on other Debian/Ubuntu
@@ -174,6 +110,71 @@ jobs:
           name: ${{ matrix.desktop-artifact-name }}
           path: ${{ matrix.desktop-artifact-path }}
 
+  test-quartz-ios:
+    # Phase 1 of the iOS support plan
+    # (amethyst/plans/2026-05-24-ios-support.md): keep :quartz green on iOS
+    # so JVM-only imports can't sneak into commonMain unnoticed. The
+    # `verifyKmpPurity` task in the lint job is the fast pre-check (Linux,
+    # ~1s); this job is the real one — compiles for the device variant
+    # and actually runs the simulator test suite.
+    needs: lint
+    runs-on: macos-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: 21
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          cache-read-only: ${{ github.ref != 'refs/heads/main' }}
+
+      # Two tasks, two purposes:
+      # - iosSimulatorArm64Test runs the existing iosTest suite on the
+      #   simulator (NIP-04 / NIP-17 / NIP-19 / NIP-49 / AES-GCM /
+      #   Chatroom keys), exercising secp256k1 and CryptoKit-backed
+      #   primitives on a real Apple toolchain.
+      # - compileTestKotlinIosArm64 catches any device-only compile drift
+      #   (iosArm64 = aarch64-apple-ios) without needing a physical
+      #   device to run on. Compile-only is enough — running on-device
+      #   would require xcodebuild + a provisioning profile.
+      - name: Test Quartz on iOS
+        run: |
+          ./gradlew \
+            :quartz:iosSimulatorArm64Test \
+            :quartz:compileTestKotlinIosArm64
+
+      # :commons gained iosArm64 + iosSimulatorArm64 targets in Phase 2 of the
+      # iOS plan. Actual UI / lifecycle wiring will land with the iosApp module
+      # in Phase 3, but the shared commonMain + commonTest sources are already
+      # built here against an Apple Native frontend. Same two-task shape as
+      # quartz above:
+      # - iosSimulatorArm64Test compiles AND runs the shared commonTest suite
+      #   on the simulator. commonTest is built for every target, so a test
+      #   reaching for a JVM-only API (JUnit, javaClass, @JvmStatic, or a
+      #   jvmAndroid-only symbol) breaks the Apple build even though
+      #   :commons:jvmTest stays green — this is the job that catches it.
+      # - compileTestKotlinIosArm64 catches device-only compile drift
+      #   (iosArm64 = aarch64-apple-ios) without needing a physical device.
+      - name: Test Commons on iOS
+        run: |
+          ./gradlew \
+            :commons:iosSimulatorArm64Test \
+            :commons:compileTestKotlinIosArm64
+
+      - name: Upload iOS Test Reports
+        uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: Quartz iOS Test Reports
+          path: quartz/build/reports
+
   test-and-build-android:
     needs: lint
     runs-on: ubuntu-latest
@@ -185,11 +186,11 @@ jobs:
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
-          distribution: 'zulu'
+          distribution: 'temurin'
           java-version: 21
 
       - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v6
         with:
           cache-read-only: ${{ github.ref != 'refs/heads/main' }}
 

.github/workflows/create-release.yml

@@ -11,7 +11,7 @@ on:
         type: boolean
         default: false
       test_tag:
-        description: 'Synthetic tag name for dry-run (e.g. v1.08.0-dryrun); ignored on tag push'
+        description: 'Synthetic tag name for dry-run (e.g. vX.YY.Z-dryrun); ignored on tag push'
         type: string
         default: 'v0.0.0-dryrun'
 
@@ -21,9 +21,13 @@ permissions:
 env:
   # Asset naming contract: amethyst-desktop-<version>-<family>-<arch>.<ext>
   # Single source of truth in scripts/asset-name.sh.
-  # linuxdeploy pinned release — bump via Dependabot, verify SHA256 via env var below.
-  LINUXDEPLOY_URL: https://github.com/linuxdeploy/linuxdeploy/releases/download/1-alpha-20240109-1/linuxdeploy-x86_64.AppImage
-  LINUXDEPLOY_SHA256: c86d6540f1df31061f02f539a2d3445f8d7f85cc3994eee1e74cd1ac97b76df0
+  # appimagetool pinned release — bump via Dependabot, verify SHA256 via env var below.
+  # We used to use linuxdeploy here, but it auto-walks the AppDir with ldd to
+  # bundle deps — that fights jpackage's self-contained JRE (libjvm.so has
+  # $ORIGIN RPATH so ldd can't resolve it standalone). appimagetool only
+  # embeds the AppDir as-is, which is what we actually want.
+  APPIMAGETOOL_URL: https://github.com/AppImage/appimagetool/releases/download/1.9.0/appimagetool-x86_64.AppImage
+  APPIMAGETOOL_SHA256: 46fdd785094c7f6e545b61afcfb0f3d98d8eab243f644b4b17698c01d06083d1
 
 jobs:
   # ---------------------------------------------------------------------------
@@ -35,7 +39,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - { os: macos-13,       arch: x64,   family: macos,          tasks: "packageReleaseDmg" }
           - { os: macos-14,       arch: arm64, family: macos,          tasks: "packageReleaseDmg" }
           - { os: windows-latest, arch: x64,   family: windows,        tasks: "packageReleaseMsi createReleaseDistributable" }
           - { os: ubuntu-latest,  arch: x64,   family: linux,          tasks: "packageReleaseDeb packageReleaseRpm" }
@@ -52,7 +55,7 @@ jobs:
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
-          distribution: 'zulu'
+          distribution: 'temurin'
           java-version: 21
 
       - name: Resolve tag + version
@@ -84,20 +87,53 @@ jobs:
         if: matrix.family == 'linux'
         run: sudo apt-get update && sudo apt-get install -y rpm fakeroot
 
-      - name: Fetch linuxdeploy (linux-portable only, SHA-verified)
+      - name: Fetch appimagetool (linux-portable only, SHA-verified)
         if: matrix.family == 'linux-portable'
         run: |
           set -euo pipefail
-          curl -fsSL --retry 3 "$LINUXDEPLOY_URL" -o desktopApp/packaging/appimage/linuxdeploy-x86_64.AppImage
-          actual=$(sha256sum desktopApp/packaging/appimage/linuxdeploy-x86_64.AppImage | awk '{print $1}')
-          if [[ "$actual" != "$LINUXDEPLOY_SHA256" ]]; then
-            echo "::error::linuxdeploy SHA256 mismatch. Expected $LINUXDEPLOY_SHA256, got $actual"
+          # appimagetool 1.9.0 validates the .desktop file via desktop-file-validate.
+          sudo apt-get update && sudo apt-get install -y desktop-file-utils
+          curl -fsSL --retry 3 "$APPIMAGETOOL_URL" -o desktopApp/packaging/appimage/appimagetool-x86_64.AppImage
+          actual=$(sha256sum desktopApp/packaging/appimage/appimagetool-x86_64.AppImage | awk '{print $1}')
+          if [[ "$actual" != "$APPIMAGETOOL_SHA256" ]]; then
+            echo "::error::appimagetool SHA256 mismatch. Expected $APPIMAGETOOL_SHA256, got $actual"
             exit 1
           fi
-          chmod +x desktopApp/packaging/appimage/linuxdeploy-x86_64.AppImage
+          chmod +x desktopApp/packaging/appimage/appimagetool-x86_64.AppImage
+
+      # 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
+      # provisioned) the DMG is built UNSIGNED, exactly as before. notarytool
+      # runs as part of the gradle task when the identity env is exported below.
+      - name: Import Apple Developer ID certificate (macOS leg, if configured)
+        if: matrix.family == 'macos'
+        id: mac_keychain
+        uses: ./.github/actions/import-macos-cert
+        with:
+          certificate-p12-base64: ${{ secrets.MAC_CERTIFICATE_P12 }}
+          certificate-password: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
 
       - name: Build desktop artifacts
         uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60  # v4.0.0
+        env:
+          # Empty on non-macOS legs and on the macOS leg when no cert is
+          # configured — the gradle macOS{} block skips signing when the
+          # identity is blank. Prefer the full common name resolved from the
+          # keychain over the raw secret: Compose's signer maps the identity via
+          # `security find-certificate` and only matches the exact "Developer ID
+          # Application: …" CN, whereas the secret may be a hash or partial name
+          # (which bare codesign accepts but Compose does not). Fall back to the
+          # secret if resolution failed.
+          AMETHYST_MAC_SIGN_IDENTITY: ${{ steps.mac_keychain.outputs.signing == 'true' && (steps.mac_keychain.outputs.identity || secrets.MAC_SIGN_IDENTITY) || '' }}
+          # Explicit keychain for Compose's MacSigner. Its `security
+          # find-certificate` lookup doesn't resolve the imported cert via the
+          # search list on these runners ("Could not find certificate ... in
+          # keychain []"), so point it at the throwaway keychain directly.
+          AMETHYST_MAC_SIGN_KEYCHAIN: ${{ steps.mac_keychain.outputs.signing == 'true' && steps.mac_keychain.outputs.keychain || '' }}
+          AMETHYST_NOTARY_APPLE_ID: ${{ secrets.MAC_NOTARY_APPLE_ID }}
+          AMETHYST_NOTARY_PASSWORD: ${{ secrets.MAC_NOTARY_PASSWORD }}
+          AMETHYST_NOTARY_TEAM_ID: ${{ secrets.MAC_NOTARY_TEAM_ID }}
         with:
           max_attempts: 2
           timeout_minutes: 15
@@ -204,11 +240,10 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - { os: macos-13,      arch: x64,   family: macos, tasks: "amyImage" }
           - { os: macos-14,      arch: arm64, family: macos, tasks: "amyImage" }
           - { os: ubuntu-latest, arch: x64,   family: linux, tasks: "amyImage jpackageDeb jpackageRpm" }
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
+    timeout-minutes: 45  # macOS leg also codesigns + notarizes the jlink image
     defaults:
       run:
         shell: bash
@@ -219,7 +254,7 @@ jobs:
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
-          distribution: 'zulu'
+          distribution: 'temurin'
           java-version: 21
 
       - name: Resolve tag + version
@@ -257,6 +292,96 @@ jobs:
           timeout_minutes: 15
           command: ./gradlew --no-daemon :cli:${{ matrix.tasks }}
 
+      # amy is headless: the Compose UI render stack (skiko + its native dylibs,
+      # foundation/material/material3/ui/animation) must never reach the CLI
+      # image. cli/build.gradle.kts excludes it from runtimeClasspath; this
+      # guards against a transitive dep silently dragging it back (size + macOS
+      # notarization-surface regression). compose.runtime is CLI-safe and stays.
+      - name: Assert no Compose UI in the amy image
+        run: |
+          set -euo pipefail
+          LIB="cli/build/install/amy/lib"
+          leak="$(ls "$LIB" | grep -iE 'skiko|foundation(-layout)?-desktop|material3?-desktop|material-ripple|ui-desktop|animation(-core)?-desktop' || true)"
+          if [ -n "$leak" ]; then
+            echo "::error::Compose UI render stack leaked into the amy CLI image:"
+            echo "$leak" | sed 's/^/  /'
+            echo "Exclude it in cli/build.gradle.kts (configurations.runtimeClasspath)."
+            exit 1
+          fi
+          echo "OK: no skiko / Compose UI render jars in the amy image ($(du -sh "$LIB" | cut -f1))."
+
+      # macOS only: import the Developer ID cert (no-op without the secret) so
+      # the next step can codesign the jlink image. The jvm bundle for
+      # Homebrew-core is NOT signed here — Homebrew strips quarantine itself.
+      - name: Import Apple Developer ID certificate (macOS leg, if configured)
+        if: matrix.family == 'macos'
+        id: mac_keychain
+        uses: ./.github/actions/import-macos-cert
+        with:
+          certificate-p12-base64: ${{ secrets.MAC_CERTIFICATE_P12 }}
+          certificate-password: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
+
+      # Codesign + notarize the macOS jlink image (amy-<ver>-macos-arm64.tar.gz)
+      # for users who download it directly. A loose tarball can't be stapled
+      # (stapler only does .app/.dmg/.pkg), so Gatekeeper verifies notarization
+      # online on first run. Runs before "Collect" so the tarred image is signed.
+      - name: Sign + notarize amy image (macOS leg, if configured)
+        if: matrix.family == 'macos' && steps.mac_keychain.outputs.signing == 'true'
+        env:
+          SIGN_IDENTITY: ${{ secrets.MAC_SIGN_IDENTITY }}
+          NOTARY_APPLE_ID: ${{ secrets.MAC_NOTARY_APPLE_ID }}
+          NOTARY_PASSWORD: ${{ secrets.MAC_NOTARY_PASSWORD }}
+          NOTARY_TEAM_ID: ${{ secrets.MAC_NOTARY_TEAM_ID }}
+        run: |
+          set -euo pipefail
+          IMG="cli/build/amy-image/amy"
+          ENTITLEMENTS="cli/packaging/macos/amy.entitlements"
+          # First sign the macOS Mach-O natives buried INSIDE the bundled jars
+          # (secp256k1/jna/sqlite/skiko/jkeychain/mediaplayer). The loose-file
+          # loop below can't see them, but Apple's notary recurses into jars and
+          # rejects any unsigned Mach-O — so this must run before notarize.
+          SIGN_IDENTITY="$SIGN_IDENTITY" scripts/sign-macos-jar-natives.sh "$IMG"
+          # Sign every loose Mach-O binary in the bundled JRE. Each is signed
+          # independently (no enclosing .app seals them), so order is irrelevant.
+          # Executables get the hardened-runtime entitlements; dylibs don't.
+          while IFS= read -r f; do
+            case "$(file -b "$f")" in
+              *Mach-O*executable*)
+                codesign --force --options runtime --timestamp \
+                  --entitlements "$ENTITLEMENTS" --sign "$SIGN_IDENTITY" "$f" ;;
+              *Mach-O*)
+                codesign --force --options runtime --timestamp \
+                  --sign "$SIGN_IDENTITY" "$f" ;;
+            esac
+          done < <(find "$IMG" -type f)
+          codesign --verify --strict --verbose=2 "$IMG/runtime/bin/java"
+          # Notarize: zip the signed image, submit, wait for Apple's verdict.
+          # The notary service recursively inspects the lib/*.jar files; their
+          # embedded Mach-O natives are signed by sign-macos-jar-natives.sh
+          # above. Surface the per-file log on any non-Accepted verdict so a
+          # regression is diagnostic rather than a bare failure.
+          ZIP="$RUNNER_TEMP/amy-notarize.zip"
+          OUT="$RUNNER_TEMP/notary-submit.json"
+          ditto -c -k --keepParent "$IMG" "$ZIP"
+          if ! xcrun notarytool submit "$ZIP" \
+                --apple-id "$NOTARY_APPLE_ID" --password "$NOTARY_PASSWORD" \
+                --team-id "$NOTARY_TEAM_ID" --wait --output-format json > "$OUT"; then
+            echo "::warning::notarytool submit exited non-zero"
+          fi
+          cat "$OUT"
+          STATUS="$(jq -r '.status // "Unknown"' "$OUT" 2>/dev/null || echo Unknown)"
+          SUBMISSION_ID="$(jq -r '.id // empty' "$OUT" 2>/dev/null || true)"
+          if [ "$STATUS" != "Accepted" ]; then
+            echo "::error::Notarization status: $STATUS"
+            if [ -n "$SUBMISSION_ID" ]; then
+              echo "----- notary log -----"
+              xcrun notarytool log "$SUBMISSION_ID" \
+                --apple-id "$NOTARY_APPLE_ID" --password "$NOTARY_PASSWORD" \
+                --team-id "$NOTARY_TEAM_ID" || true
+            fi
+            exit 1
+          fi
+
       # jpackage pins libicu to the build host's version (libicu74 on
       # ubuntu-24.04). Rewrite the .deb so it installs across Debian/Ubuntu.
       - name: Relax libicu dependency in .deb
@@ -273,6 +398,23 @@ jobs:
           source scripts/asset-name.sh
           collect_cli_assets "${{ matrix.family }}" "${{ matrix.arch }}" "${{ steps.ver.outputs.version }}" dist
 
+      # Homebrew-core ships a no-JRE jar bundle and depends_on "openjdk" — it
+      # cannot use the jlink tarball above (bundled runtime) nor build from
+      # source (its sandbox blocks Gradle's Maven downloads). installDist
+      # (bin/amy + lib/*.jar, no runtime/) is exactly that bundle. It is pure
+      # JVM bytecode, so one platform-independent asset serves every OS; we cut
+      # it on the linux leg only. amyImage depends on installDist, so the
+      # cli/build/install/amy tree already exists here.
+      - name: Package no-JRE jvm bundle for Homebrew (linux leg only)
+        if: matrix.family == 'linux'
+        run: |
+          set -euo pipefail
+          VER="${{ steps.ver.outputs.version }}"
+          SRC="cli/build/install/amy"
+          test -x "$SRC/bin/amy"
+          ( cd "$SRC" && tar czf "$OLDPWD/dist/amy-${VER}-jvm.tar.gz" bin lib )
+          echo "Collected: dist/amy-${VER}-jvm.tar.gz"
+
       - name: Enforce CLI size budget (200 MB per asset)
         run: |
           set -euo pipefail
@@ -342,7 +484,7 @@ jobs:
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
-          distribution: 'zulu'
+          distribution: 'temurin'
           java-version: 21
 
       - name: Cache gradle

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

@@ -0,0 +1,143 @@
+name: Desktop Smoke Test
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'desktopApp/**'
+      - '.github/workflows/smoke-test-desktop.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: smoke-desktop-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # -------------------------------------------------------------------------
+  # 1) Compose UI test — verifies the composable tree renders (login screen)
+  #    under the dev classpath. Catches missing string resources, broken
+  #    composables, and basic dependency-graph issues.
+  # -------------------------------------------------------------------------
+  compose-ui-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: 21
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          cache-read-only: true
+
+      - name: Install xvfb
+        run: sudo apt-get update && sudo apt-get install -y xvfb
+
+      - name: Run desktop tests (including UI smoke test)
+        run: xvfb-run --auto-servernum ./gradlew :desktopApp:test
+
+  # -------------------------------------------------------------------------
+  # 2) Release .deb build + launch — builds the ProGuard'd, jlink'd .deb
+  #    package, installs it, and verifies the process stays alive for 10s.
+  #    Catches ProGuard stripping (JNI, reflection), missing jlink modules
+  #    (java.management, java.prefs), and native lib bundling issues.
+  # -------------------------------------------------------------------------
+  release-deb-launch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: 21
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          cache-read-only: true
+
+      - name: Install xvfb + packaging deps
+        run: sudo apt-get update && sudo apt-get install -y xvfb fakeroot
+
+      - name: Build release .deb
+        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60  # v4.0.0
+        with:
+          max_attempts: 2
+          timeout_minutes: 20
+          command: ./gradlew --no-daemon :desktopApp:packageReleaseDeb
+
+      - name: Relax libicu dependency
+        run: |
+          set -euo pipefail
+          chmod +x scripts/relax-deb-libicu.sh
+          scripts/relax-deb-libicu.sh desktopApp/build/compose/binaries/main-release/deb/*.deb
+
+      - name: Install .deb
+        run: |
+          # jpackage's post-install script runs xdg-desktop-menu which fails
+          # on CI runners ("No writable system menu directory"). The files are
+          # extracted successfully; only the menu registration fails. Allow the
+          # dpkg error, then verify the binary was actually installed.
+          sudo dpkg -i desktopApp/build/compose/binaries/main-release/deb/*.deb || true
+          echo "Installed files:"
+          dpkg -L amethyst | head -30
+          # Fail if the binary wasn't actually extracted
+          test -d /opt/amethyst || test -d /opt/Amethyst || {
+            echo "FAIL: /opt/amethyst not found after dpkg -i"
+            exit 1
+          }
+
+      - name: Smoke test — app launches and stays alive
+        run: |
+          set -euo pipefail
+
+          # Find the launcher binary
+          LAUNCHER=$(find /opt -name "Amethyst" -type f -executable 2>/dev/null | head -1)
+          if [[ -z "$LAUNCHER" ]]; then
+            # Fallback: search dpkg file list
+            LAUNCHER=$(dpkg -L amethyst | grep -E '/bin/[Aa]methyst$' | head -1)
+          fi
+          if [[ -z "$LAUNCHER" ]]; then
+            echo "FAIL: could not find Amethyst launcher binary"
+            dpkg -L amethyst
+            exit 1
+          fi
+          echo "Launcher: $LAUNCHER"
+
+          # Launch under xvfb with a timeout safety net
+          xvfb-run --auto-servernum timeout 30 "$LAUNCHER" &
+          APP_PID=$!
+          echo "PID: $APP_PID"
+
+          # Wait 10s — if the process is still alive, the app launched successfully
+          sleep 10
+
+          if kill -0 "$APP_PID" 2>/dev/null; then
+            echo "PASS: Application launched and stayed alive for 10s"
+            kill "$APP_PID" || true
+            wait "$APP_PID" 2>/dev/null || true
+          else
+            wait "$APP_PID" 2>/dev/null
+            EXIT_CODE=$?
+            echo "FAIL: Application exited with code $EXIT_CODE within 10s"
+            exit 1
+          fi
+
+      - name: Upload .deb artifact (for manual testing)
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: Release DEB (smoke-tested)
+          path: desktopApp/build/compose/binaries/main-release/deb/*.deb

.gitignore

@@ -161,14 +161,23 @@ TASKS.md
 .claude/settings.local.json
 .claude/scheduled_tasks.lock
 
-# Downloaded VLC binaries (vlc-setup plugin)
-desktopApp/src/jvmMain/appResources/linux/
-desktopApp/src/jvmMain/appResources/macos/
-desktopApp/src/jvmMain/appResources/windows/
+# Per-OS appResources slots — historically the ir.mahozad.vlc-setup plugin
+# populated these with VLC binaries (no longer used; superseded by
+# kdroidFilter ComposeMediaPlayer). We still ignore the directory contents
+# by default to keep stale workspaces from accidentally bundling old VLC
+# trees into local packages, but explicitly track the ffmpeg/README.md
+# drop-in slot for the LGPL FFmpeg binaries used by VideoThumbnailCache.
+desktopApp/src/jvmMain/appResources/linux/*
+desktopApp/src/jvmMain/appResources/macos/*
+desktopApp/src/jvmMain/appResources/windows/*
+!desktopApp/src/jvmMain/appResources/linux/ffmpeg/
+!desktopApp/src/jvmMain/appResources/macos/ffmpeg/
+!desktopApp/src/jvmMain/appResources/windows/ffmpeg/
+desktopApp/src/jvmMain/appResources/*/ffmpeg/*
+!desktopApp/src/jvmMain/appResources/*/ffmpeg/README.md
 
 # CI-fetched AppImage tooling (downloaded by create-release workflow; not committed)
-desktopApp/packaging/appimage/linuxdeploy-x86_64.AppImage
-desktopApp/packaging/appimage/linuxdeploy-extracted/
+desktopApp/packaging/appimage/appimagetool-x86_64.AppImage
 desktopApp/packaging/appimage/squashfs-root/
 
 # Git worktrees

.idea/kotlinc.xml

@@ -8,6 +8,6 @@
   </component>
   <component name="KotlinJpsPluginSettings">
     <option name="externalSystemId" value="Gradle" />
-    <option name="version" value="2.3.21" />
+    <option name="version" value="2.4.0" />
   </component>
 </project>

BUILDING.md

@@ -1,13 +1,22 @@
 # Building Amethyst Desktop
 
-This guide covers building Amethyst Desktop from source, the release pipeline,
-and one-time bootstrap steps for distribution channels.
+This guide has everything **any fork** needs to build Amethyst from source and
+cut its own release: prerequisites, build commands, the CI release pipeline, the
+secrets it needs, the distribution channels, and one-time bootstrap steps.
+
+> **Amethyst maintainers:** the account-specific checklist for shipping the
+> official build (Play Console upload, Zapstore `zsp publish` with our nsec,
+> secret ownership) lives in [`RELEASE_OPS.md`](RELEASE_OPS.md). This
+> file stays fork-generic.
 
 - [Prerequisites](#prerequisites)
 - [Clone + first build](#clone--first-build)
+- [Generated & vendored artifacts](#generated--vendored-artifacts)
 - [Per-format build commands](#per-format-build-commands)
 - [Asset naming contract](#asset-naming-contract)
 - [Release runbook](#release-runbook)
+- [Secrets the CI needs](#secrets-the-ci-needs)
+- [Distribution channels](#distribution-channels)
 - [Bootstrap runbook (one-time)](#bootstrap-runbook-one-time)
 - [Troubleshooting installs](#troubleshooting-installs)
 - [Uninstall + state paths](#uninstall--state-paths)
@@ -27,7 +36,8 @@ 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`; `linuxdeploy` for AppImage
+- **Linux (all)**: nothing extra for `.deb`; `rpm` + `fakeroot` for `.rpm`;
+  `appimagetool` + `desktop-file-utils` for AppImage
 
 Install Linux RPM tooling:
 
@@ -39,12 +49,15 @@ sudo apt-get install -y rpm fakeroot
 sudo dnf install -y rpm-build
 ```
 
-Install linuxdeploy locally (CI fetches its own — SHA-verified):
+Install appimagetool locally (CI fetches its own — SHA-verified):
 
 ```bash
-curl -fsSL -o desktopApp/packaging/appimage/linuxdeploy-x86_64.AppImage \
-  https://github.com/linuxdeploy/linuxdeploy/releases/download/1-alpha-20240109-1/linuxdeploy-x86_64.AppImage
-chmod +x desktopApp/packaging/appimage/linuxdeploy-x86_64.AppImage
+# Debian/Ubuntu — appimagetool calls desktop-file-validate on the .desktop entry
+sudo apt-get install -y desktop-file-utils
+
+curl -fsSL -o desktopApp/packaging/appimage/appimagetool-x86_64.AppImage \
+  https://github.com/AppImage/appimagetool/releases/download/1.9.0/appimagetool-x86_64.AppImage
+chmod +x desktopApp/packaging/appimage/appimagetool-x86_64.AppImage
 ```
 
 ---
@@ -64,6 +77,29 @@ cd amethyst
 
 ---
 
+## Generated & vendored artifacts
+
+Two build inputs are **generated by tools but committed to the repo**, so a
+normal build or release does **not** run either — Gradle just consumes the
+checked-in output. You only regenerate them under the specific conditions below,
+and each has its own guide:
+
+| Artifact | Committed at | Regenerate when | Guide |
+|---|---|---|---|
+| **Material Symbols subset font** | `commons/src/commonMain/composeResources/font/material_symbols_outlined.ttf` | You add/remove a `MaterialSymbol("\uXXXX")` codepoint in `MaterialSymbols.kt`, or bump the upstream font | [`tools/material-symbols-subset/README.md`](tools/material-symbols-subset/README.md) — run `./tools/material-symbols-subset/subset.sh` |
+| **Arti (Tor) native libs** | `amethyst/src/main/jniLibs/*.so` | You update the pinned Arti version, change the JNI wrapper, or want to reproduce the binaries | [`tools/arti-build/README.md`](tools/arti-build/README.md) |
+
+> **Material Symbols is mandatory after icon changes.** The bundled font is a
+> ~210-glyph subset; a new codepoint that isn't in it renders as tofu (□) at
+> runtime. Regenerate and commit the `.ttf` alongside the `MaterialSymbols.kt`
+> change. Reusing an existing codepoint needs no regeneration.
+
+Both tools have their own prerequisites (`fonttools`/`brotli` for the font; a
+Rust toolchain + Android NDK 25+ for Arti) documented in their READMEs — they
+are **not** required to build Amethyst from the committed sources.
+
+---
+
 ## Per-format build commands
 
 | Artifact | Command | Output |
@@ -107,11 +143,11 @@ amethyst-desktop-<version>-<family>-<arch>.<ext>
 
 Where:
 
-| Field | Values                                                  |
-|---|---------------------------------------------------------|
-| `<version>` | Tag stripped of leading `v` (e.g. `1.09.2`)             |
-| `<family>` | `macos`, `windows`, `linux`                             |
-| `<arch>` | `x64`, `arm64`                                          |
+| Field | Values                                                |
+|---|-------------------------------------------------------|
+| `<version>` | Tag stripped of leading `vX.YY.ZZ`                    |
+| `<family>` | `macos`, `windows`, `linux`                           |
+| `<arch>` | `x64`, `arm64`                                        |
 | `<ext>` | `dmg`, `msi`, `zip`, `deb`, `rpm`, `AppImage`, `tar.gz` |
 
 Single source of truth: [`scripts/asset-name.sh`](scripts/asset-name.sh).
@@ -120,10 +156,10 @@ any change is a breaking contract.
 
 Examples:
 
-- `amethyst-desktop-1.09.2-macos-x64.dmg`
-- `amethyst-desktop-1.09.2-macos-arm64.dmg`
-- `amethyst-desktop-1.09.2-windows-x64.msi`
-- `amethyst-desktop-1.09.2-linux-x64.AppImage`
+- `amethyst-desktop-1.12.1-macos-x64.dmg`
+- `amethyst-desktop-1.12.1-macos-arm64.dmg`
+- `amethyst-desktop-1.12.1-windows-x64.msi`
+- `amethyst-desktop-1.12.1-linux-x64.AppImage`
 
 ---
 
@@ -132,38 +168,37 @@ Examples:
 The release flow is driven by a tag push. Every cut ships Android + Desktop +
 Quartz library in one pipeline.
 
-1. **Bump the app version** in `gradle/libs.versions.toml`:
+1. **Bump the app version and Android `versionCode`** in
+   `gradle/libs.versions.toml` (`appCode` is a monotonic integer — it must
+   increment even when `app` is unchanged):
 
    ```toml
    [versions]
    app = "1.08.1"  # new semver
+   appCode = "449" # Android versionCode
    ```
 
-2. **Bump Android `versionCode`** in `amethyst/build.gradle` (monotonic integer,
-   must increment even for same `versionName`):
+   `amethyst/build.gradle.kts` reads both from the catalog
+   (`versionCode = libs.versions.appCode.get().toInt()`), so there is nothing
+   else to edit.
 
-   ```groovy
-   versionCode = 443
-   versionName = generateVersionName(libs.versions.app.get())
-   ```
-
-3. **Commit + tag + push**:
+2. **Commit + tag + push**:
 
    ```bash
-   git commit -am "chore(release): 1.08.1"
-   git tag -s v1.08.1 -m "Release 1.08.1"
+   git commit -am "chore(release): 1.12.1"
+   git tag -s v1.12.1 -m "Release 1.12.1"
    git push && git push --tags
    ```
 
-4. **Wait** for the `Create Release Assets` workflow to finish (~25–30 min).
+3. **Wait** for the `Create Release Assets` workflow to finish (~25–30 min).
 
-5. **Verify**:
+4. **Verify**:
    - GH Release contains 8 desktop assets + 12 Android assets
    - Asset sizes look sane (see §Enforce asset size budget — CI auto-fails at 1 GB/asset)
    - Intel + ARM DMGs both present
    - Android flow unchanged
 
-6. **Stable vs prerelease** — a tag containing `-rc`, `-beta`, `-alpha`, `-dev`,
+5. **Stable vs prerelease** — a tag containing `-rc`, `-beta`, `-alpha`, `-dev`,
    or `-snapshot` is auto-classified as prerelease. Stable tags trigger the
    Homebrew + Winget bump workflows.
 
@@ -199,19 +234,149 @@ uninstall before a new release. Leave it alone forever.
 
 ---
 
+## Secrets the CI needs
+
+The `Create Release Assets` workflow reads these from GitHub repo secrets. A
+fork must provide its **own** values — none are inherited. (`GITHUB_TOKEN` is
+provided automatically; everything else you set yourself.)
+
+| Secret | What it is | Used for |
+|---|---|---|
+| `SIGNING_KEY` | Base64 of your **Android keystore** (`.jks`/`.keystore`) | Signs the Play + F-Droid **AAB and APK** |
+| `KEY_ALIAS` | Keystore key alias | Same Android signing step |
+| `KEY_STORE_PASSWORD` | Keystore password | Same |
+| `KEY_PASSWORD` | Key password | Same |
+| `SONATYPE_USERNAME` | Maven Central (Sonatype) user token name | Publishing the `quartz` library |
+| `SONATYPE_PASSWORD` | Maven Central user token password | Same |
+| `SIGNING_PRIVATE_KEY` | **GPG/PGP** private key, ASCII-armored | Signs the Maven artifacts (Central requires it) |
+| `SIGNING_PASSWORD` | Passphrase for that GPG key | Same |
+| `MAC_CERTIFICATE_P12` | Base64 of your **Apple Developer ID Application** cert (`.p12`, includes the private key) | Signs the macOS desktop **DMG** and the macOS **amy** jlink tarball |
+| `MAC_CERTIFICATE_PASSWORD` | Password set when exporting the `.p12` | Imports the cert into the CI keychain |
+| `MAC_SIGN_IDENTITY` | Full identity string, e.g. `Developer ID Application: Your Name (TEAMID)` | The `codesign` identity to sign with |
+| `MAC_NOTARY_APPLE_ID` | Apple ID email of the notarization account | Apple notarization (`notarytool`) |
+| `MAC_NOTARY_PASSWORD` | **App-specific** password for that Apple ID (not the login password) | Same |
+| `MAC_NOTARY_TEAM_ID` | 10-char Apple Developer **Team ID** | Same |
+| `HOMEBREW_TOKEN` | PAT for `Homebrew/homebrew-cask` | Desktop cask bump (stable tags) |
+| `WINGET_TOKEN` | PAT for `microsoft/winget-pkgs` | Desktop winget bump (stable tags) |
+| `CROWDIN_PERSONAL_TOKEN`, `CROWDIN_PROJECT_ID` | Crowdin API creds | Translation sync (separate workflow, not the release) |
+
+Note the **three distinct signing identities** people often conflate:
+`SIGNING_KEY` + `KEY_*` is the **Android keystore**; `SIGNING_PRIVATE_KEY` +
+`SIGNING_PASSWORD` is the **GPG key** for Maven Central; `MAC_CERTIFICATE_*` +
+`MAC_SIGN_IDENTITY` + `MAC_NOTARY_*` is the **Apple Developer ID** for the macOS
+desktop DMG. They are unrelated — each comes from a different authority.
+
+The macOS signing secrets are **optional**: if `MAC_CERTIFICATE_P12` is unset
+the release workflow still builds the DMG **and** the macOS `amy` tarball, just
+**unsigned** (the previous behavior). Provision all six to switch signing +
+notarization on for both. Obtaining them requires Apple Developer Program
+membership ($99/yr). The same one certificate signs both artifacts.
+
+The macOS `amy` tarball is the jlink image (bundled JRE), so signing it means
+codesigning every Mach-O binary in that runtime with hardened-runtime
+entitlements (`cli/packaging/macos/amy.entitlements` — needed so the JVM can
+load the secp256k1 native library it extracts at runtime). A loose `.tar.gz`
+cannot be **stapled** (Apple's `stapler` only handles `.app`/`.dmg`/`.pkg`), so
+Gatekeeper verifies notarization **online** on first run — fine for a CLI.
+Note the Homebrew-core jvm bundle (`amy-<version>-jvm.tar.gz`) is **not** signed:
+Homebrew removes the quarantine attribute on its own downloads.
+
+> **Validated (Developer ID `D77MCV9NZ7`):** signing every Mach-O in the bundled
+> JRE with hardened runtime + `amy.entitlements` lets `amy init` derive a key via
+> secp256k1 with no library-validation crash. Dropping `disable-library-validation`
+> reproduces `UnsatisfiedLinkError: … different Team IDs` on the runtime-extracted
+> `libsecp256k1-jni.dylib` — so that entitlement is load-bearing, not decorative.
+>
+> **Open risk — embedded jar natives.** The notary service unpacks `lib/*.jar`
+> recursively and checks every Mach-O for a signature + hardened runtime. Our
+> sign loop only touches loose files, so 9 unsigned natives ride along inside
+> jars on a macOS build: `secp256k1` (1, required at runtime), `jna` (2),
+> `sqlite` (2), and `skiko` (4, dead weight — Compose UI the CLI never renders).
+> Whether `notarytool` returns `Accepted` or `Invalid` on these is **unverified**
+> (the local validation had no notary creds). **Decide it with one run:** set the
+> six `MAC_*` secrets and trigger `create-release.yml` via `workflow_dispatch`
+> with `dry_run=true` — the sign+notarize step runs regardless of `dry_run` and
+> now prints the per-file notary log on a non-`Accepted` verdict. If it comes
+> back `Invalid`, the fix is to codesign the dylibs *inside* those jars before
+> zipping (and/or strip the unused `skiko`/Compose jars from the CLI image — the
+> `:commons` core/ui split the size budget already flags). The **desktop** app
+> bundles the same jars through Compose/jpackage notarization, so run a desktop
+> dry-run too; its in-jar handling differs and is likewise unverified.
+
+Generating the values:
+
+```bash
+# Android keystore → base64 for SIGNING_KEY (one line, no wrapping)
+keytool -genkey -v -keystore upload.jks -keyalg RSA -keysize 2048 \
+  -validity 10000 -alias upload          # creates the keystore (once)
+base64 -i upload.jks | tr -d '\n'        # paste output into SIGNING_KEY
+
+# GPG key → armored private key for SIGNING_PRIVATE_KEY
+gpg --full-generate-key                  # create the key (once)
+gpg --armor --export-secret-keys <KEY_ID>   # paste output into SIGNING_PRIVATE_KEY
+
+# Apple Developer ID Application cert → base64 for MAC_CERTIFICATE_P12.
+# In Keychain Access, export the "Developer ID Application: ..." cert (with its
+# private key) as a .p12, setting an export password (-> MAC_CERTIFICATE_PASSWORD).
+base64 -i developer_id.p12 | tr -d '\n'  # paste output into MAC_CERTIFICATE_P12
+security find-identity -v -p codesigning  # shows the exact MAC_SIGN_IDENTITY string
+# MAC_NOTARY_PASSWORD is an app-specific password from https://appleid.apple.com
+# (Sign-In and Security -> App-Specific Passwords), NOT your Apple ID login.
+```
+
+`SONATYPE_USERNAME`/`SONATYPE_PASSWORD` are a **user token** from
+<https://central.sonatype.com> (Account → Generate User Token), not your login.
+A fork that doesn't publish a library can drop the `Publish Quartz Lib` step and
+the four Sonatype/GPG secrets.
+
+---
+
+## Distribution channels
+
+One `v*` tag fans out to several channels. Which apply depends on where a fork
+distributes; the official Amethyst rollout for each is in
+[`RELEASE_OPS.md`](RELEASE_OPS.md).
+
+| Channel | How it ships | Push or pull |
+|---|---|---|
+| **GitHub Releases** | The release workflow builds + signs all assets and attaches them to the tag's Release | Automatic (CI) |
+| **Maven Central** | Same workflow runs `publishAllPublicationsToMavenCentral` for `quartz` | Automatic (CI) |
+| **Google Play** | Download the signed `amethyst-googleplay-<version>.aab` from the GH Release and upload it in Play Console | **Manual push** |
+| **F-Droid** | F-Droid's build server detects the new tag and **builds the `fdroid` flavor from source** per its recipe in the external [`fdroiddata`](https://gitlab.com/fdroid/fdroiddata) repo, then signs + publishes itself | **Pull (build-from-source)** |
+| **Zapstore** | The [`zsp`](https://zapstore.dev/) CLI reads [`zapstore.yaml`](zapstore.yaml) and publishes a Nostr software-release event signed with the app's nsec | **Manual push (Nostr)** |
+| **Homebrew + Winget** | `bump-homebrew.yml` / `bump-winget.yml` open version-bump PRs on stable tags | Automatic (CI) |
+
+Two channels need the build to stay split into product flavors (see
+`amethyst/build.gradle.kts` → `productFlavors`):
+
+- **`play`** carries Firebase / Google Play Services (push notifications, ML
+  Kit, etc.) → the Google Play AAB.
+- **`fdroid`** swaps those for UnifiedPush and no-op/open-source
+  implementations (`amethyst/src/fdroid/…`) so the build is free of proprietary
+  dependencies → what F-Droid builds and what Zapstore distributes.
+
+**F-Droid is pull, not push.** We never upload to F-Droid; its server builds our
+tagged source. Keeping the `fdroid` flavor proprietary-free and the
+`fastlane/metadata/android/` descriptions current is all that's required. F-Droid
+reads an optional per-release changelog from
+`fastlane/metadata/android/en-US/changelogs/<versionCode>.txt`.
+
+---
+
 ## Bootstrap runbook (one-time)
 
 ### Secrets to provision in GitHub repo settings
 
+The full secret inventory is in [§ Secrets the CI needs](#secrets-the-ci-needs).
+The two that need the most setup care are the package-manager PATs, because of
+their token type and scope:
+
 | Secret | Purpose | Scope |
 |---|---|---|
 | `HOMEBREW_TOKEN` | Bump Homebrew cask | Fine-grained PAT — `Homebrew/homebrew-cask` only — `Contents: write` + `Pull requests: write` — 90d expiry |
 | `WINGET_TOKEN` | Submit Winget manifests | Classic PAT — `public_repo` — 90d expiry (dedicated bot account preferred; `vedantmgoyal9/winget-releaser` does not support fine-grained) |
 
-All existing secrets (`SIGNING_KEY`, `SONATYPE_USERNAME`, etc.) remain
-unchanged.
-
-Rotate both on a 90-day cadence. Owner: assigned via `docs/RELEASE_OPS.md`
+Rotate both on a 90-day cadence. Owner: assigned via `RELEASE_OPS.md`
 or equivalent issue tracker. On rotation, paste new token and run
 `gh workflow run bump-homebrew.yml` on the most recent stable tag to verify.
 
@@ -219,19 +384,64 @@ or equivalent issue tracker. On rotation, paste new token and run
 
 ```bash
 brew bump-cask-pr amethyst-nostr \
-  --version 1.09.2 \
-  --url "https://github.com/vitorpamplona/amethyst/releases/download/v1.09.2/amethyst-desktop-1.09.2-macos-arm64.dmg"
+  --version 1.12.1 \
+  --url "https://github.com/vitorpamplona/amethyst/releases/download/v1.12.1/amethyst-desktop-1.12.1-macos-arm64.dmg"
 ```
 
 The cask filename is `amethyst-nostr` (not `amethyst` — that's taken by a
 tiling window manager). After the first PR is merged, `bump-homebrew.yml`
 auto-submits new version bumps on each stable release.
 
+> **The desktop app is already on mainline Homebrew.** `homebrew/cask` *is* the
+> mainline cask repo — GUI apps live in homebrew-**cask**, CLIs in
+> homebrew-**core**; both are "mainline." A private tap is only the *fallback*
+> if Homebrew ever rejects the (now signed + notarized) cask.
+
+### Homebrew-core formula for the `amy` CLI (one-time initial PR)
+
+The CLI goes to **homebrew-core** (mainline formulae), not homebrew-cask —
+casks are for GUI apps. homebrew-core builds in a **network-sandboxed**
+environment, so a from-source Gradle build can't resolve its Maven
+dependencies there. Instead the formula downloads the pre-built **no-JRE jar
+bundle** `amy-<version>-jvm.tar.gz` (published by `create-release.yml`) and
+`depends_on "openjdk"`. The reference formula lives at
+[`cli/packaging/homebrew/amy.rb`](cli/packaging/homebrew/amy.rb).
+
+To submit:
+
+```bash
+# 1. Grab the published asset's sha256
+curl -fsSL -o amy-jvm.tar.gz \
+  https://github.com/vitorpamplona/amethyst/releases/download/v1.12.1/amy-1.12.1-jvm.tar.gz
+shasum -a 256 amy-jvm.tar.gz
+
+# 2. Fill the url + sha256 into cli/packaging/homebrew/amy.rb, then open the PR
+brew create --set-name amy --tap homebrew/core \
+  https://github.com/vitorpamplona/amethyst/releases/download/v1.12.1/amy-1.12.1-jvm.tar.gz
+#    (paste the reference formula body, run `brew audit --new amy`,
+#     `brew install --build-from-source amy`, `brew test amy`, then PR it.)
+```
+
+Caveats that the maintainer must weigh before submitting:
+
+- **Name collision.** `amy` may already exist in homebrew-core — check with
+  `brew search amy` first. If taken, fall back to `amethyst-cli`.
+- **Pre-built-jar scrutiny.** homebrew-core prefers source builds; downloading
+  a jar bundle is an accepted-but-reviewed pattern for JVM tools. Be ready to
+  justify it (sandboxed Gradle can't fetch Maven deps).
+- **Bundle size.** The bundle is ~70 MB today because `:commons` leaks
+  Compose/Skiko jars onto the CLI classpath. Trimming that (a `:commons`
+  core/ui split) would shrink it and smooth review — tracked as a follow-up.
+
+After the formula merges, the `livecheck` block lets homebrew-core's BrewTestBot
+auto-open version-bump PRs on each stable release — no token or workflow on our
+side (unlike the cask/winget bumps).
+
 ### Winget (one-time initial submission)
 
 ```bash
 wingetcreate new \
-  https://github.com/vitorpamplona/amethyst/releases/download/v1.09.2/amethyst-desktop-1.09.2-windows-x64.msi
+  https://github.com/vitorpamplona/amethyst/releases/download/v1.12.1/amethyst-desktop-1.12.1-windows-x64.msi
 ```
 
 Set `PackageIdentifier = VitorPamplona.Amethyst`. After the first manifest is
@@ -368,9 +578,17 @@ for the deprecation date. When it hits:
 Homebrew has committed to disabling unsigned casks in `Homebrew/homebrew-cask`
 on 2026-09-01. Before that date:
 
-**Option A**: Commit budget to Apple Developer Program ($99/yr), add
-`signing { sign.set(true) }` + `notarization {}` blocks to
-`desktopApp/build.gradle.kts`, wire Developer ID + notary creds into CI.
+**Option A (wiring done — needs Apple creds)**: The `signing { sign.set(true) }`
++ `notarization {}` blocks are already in `desktopApp/build.gradle.kts` (gated on
+the `AMETHYST_MAC_SIGN_IDENTITY` env var), and the macOS leg of
+`create-release.yml` imports a Developer ID cert into a throwaway keychain and
+exports the signing/notary env. It all stays a **no-op until the six
+`MAC_*`/notary secrets are provisioned** (see [§ Secrets the CI
+needs](#secrets-the-ci-needs)) — until then the DMG builds unsigned. To turn it
+on: join the Apple Developer Program ($99/yr), create a *Developer ID
+Application* certificate, generate an app-specific password, and set the six
+secrets. The first signed+notarized DMG is best validated with a
+`workflow_dispatch` dry-run before a real tag.
 
 **Option B**: Pivot to a private Homebrew tap:
 

PRIVACY.md

@@ -1,54 +1,114 @@
 # Amethyst Privacy Policy and Terms of Use
 
-## Privacy Policy
+**App:** Amethyst (Android Nostr client)<br>
+**Publisher:** Vitor Pamplona<br>
+**Contact:** amethyst@vitorpamplona.com<br>
+**Last updated:** 2026-05-24
 
-Effective as of Jun 12, 2023
+Amethyst is free, open-source software (MIT License — see `LICENSE`). It is not a service. There is no Amethyst server, no Amethyst account, and the developer has no access to data stored on your device.
 
-The Amethyst app for Android does not collect or process any personal information from its users. 
+Amethyst lets you browse content from third-party Nostr **relays** that you choose. Those relays host the content. They are independent of Amethyst, with their own operators and their own policies.
 
-The app is used to browse third-party Nostr servers (called Relays) that may or may not collect personal information and are not covered by this privacy policy. Each third-party relay server comes equipped with its own privacy policy and terms of use that can be viewed through the app or through that server's website. The developers of this open-source project or maintainers of the distribution channels (app stores) do not have access to the data located in the user's phone. Accounts are fully maintained by the user. We do not have control over them. 
+This document explains what data leaves your phone, who can see it, and the standards that apply to use of the app.
 
-The app may collect a per-device token, your public key, and a preferred Relay to connect to and provide push notification services through Google's Firebase Cloud Messaging. Other than that, the data from connected accounts is only stored locally on the device when it's required for the functionality and performance of Amethyst. This data is strictly confidential and cannot be accessed by other apps (on non-rooted devices). Phone data can be deleted by clearing Amethyst's local storage or uninstalling the app.
+## Privacy
 
-Amethyst offers several options for uploading pictures and videos to post online. You can choose the server at your discretion. Similar to relays, such services are independent of the app and have their own privacy policy and terms of use. 
+### Data sent off-device
 
-### Privacy with Relay services
+Using the app causes the following data to leave your phone:
 
-Your Internet Protocol (IP) address is exposed to the relays you connect to. If you want to improve your privacy, consider utilizing a service that masks your IP address (e.g., a VPN) from trackers online.
+- **Nostr events** you publish, sent to the relays you have configured.
+- **Subscriptions** (filters describing what you want to read), sent to those relays.
+- **Media uploads** (images, audio, video), sent to the media server you select.
+- *(Google Play build, push notifications enabled)* a per-device push token, your public key, and a preferred relay, registered with Google Firebase Cloud Messaging so a notification proxy can wake the app.
+- *(F-Droid build, push notifications enabled)* a per-device token registered with whichever UnifiedPush distributor you install (e.g. ntfy).
 
-The relay can also see which public keys you are using and what information you are requesting from the network. Your public key is tied to your IP address and your relay filters.
+The developer does not run any server that aggregates or stores this data.
 
-Relays have all your data in raw text. They know your IP, your name, your location (guessed from IP), your pub key, all your contacts, and other relays, and can read every action you do (post, like, boost, quote, report, etc) with the exception of the content inside Private Zaps and Private DMs.
+### Data stored on your device
 
-While the content of direct messages (DMs) is only visible to you and your DM Nostr counterparty, everyone can see when you and your counterparty are DM-ing each other. Image uploads in the DM screen use one of the chosen image servers and simply paste the image link into the DM text. Your uploaded pictures are available to anyone with that direct link. 
+Configuration, cached events, keys, drafts, and other operational data live in the app's local storage. Other apps cannot read it on a standard, non-rooted Android device. You can wipe it by clearing the app's storage or uninstalling.
 
-### Visibility & Permanence of Your Content on Nostr Relays
+### What relays can see
 
-#### Information Visibility
+A relay you connect to sees:
 
-Content that you share can be shared with other relays by any user of the network. 
-The information you share is publicly visible to anyone reading from relays that have access to your information. Your information may also be visible to Nostr users who do not share relays with you.
+- Your IP address (or the Tor exit node when using it).
+- Your public key.
+- The events you publish (posts, reactions, reposts, reports, etc.).
+- The filters you subscribe to.
 
-#### Information Permanence
+A relay does **not** see the plaintext of:
 
-Information shared on Nostr should be assumed permanent for privacy purposes. There is no way to guarantee deleting or editing any content once posted.
+- Private Direct Messages (encrypted to the recipient under NIP-17 / NIP-44).
+- Private Zaps.
 
-## Child safety standards
+A relay can still see *that* you and another user are exchanging DMs even though it cannot read them. To reduce what a relay can correlate to you, route the app over a VPN or Tor.
 
-Amethyst does not knowingly collect information from children. The app has no age verification because it collects no personal information from anyone. The application is 17+. We rely on Google Play's age verification to make sure the user downloading the app is an adult. Since we do not control which relays the user connects to, there is no content moderation beyond the standard block post, block account, and report post and/or account that will hide the content from the user.
+### Media uploads
+
+Uploads go to the media server you select. That server is independent of Amethyst and has its own policy. Anyone holding the resulting link — including media attached to a DM — can fetch the file.
+
+### Public content is effectively permanent
+
+Anything you publish to a relay can be copied to other relays or clients. Once published, you should assume it cannot be reliably deleted from the network.
+
+## Child Safety Standards
+
+These are the published Child Safety Standards for **Amethyst**, the Android Nostr client published on Google Play by **Vitor Pamplona**. They are published under Google Play's Child Safety Standards policy.
+
+They are a community standard, not a license restriction. Amethyst's source code remains licensed under the MIT License in `LICENSE`.
+
+### Prohibition
+
+Using Amethyst to create, upload, share, solicit, or distribute child sexual abuse and exploitation (CSAE) material — including child sexual abuse material (CSAM) — or to groom, exploit, or harm a minor is prohibited and is illegal in essentially every jurisdiction.
+
+### In-app tools
+
+Amethyst provides:
+
+- **Report Post** and **Report Account** — publish a signed Nostr report (including the "Illegal Content" reason) so relays and other clients can act on it.
+- **Block Post** / **Block Account** — hide content locally on your device.
+- **Block Relay** — add a relay to your NIP-51 Blocked Relay List so the app stops fetching from or publishing to it. This is the strongest tool the app offers against a relay that refuses to moderate.
+- **Mute Words / Hashtags** — filter unwanted content from your feeds.
+
+### Addressing CSAM
+
+Amethyst does not host content, so the app cannot remove CSAM. Only the relay hosting the content can remove it. In the United States, 18 U.S.C. §2258A makes hosting providers — not viewer applications — the entities required to report to the National Center for Missing & Exploited Children (NCMEC).
+
+If you encounter CSAM through Amethyst:
+
+1. Report the content in-app and select "Illegal Content."
+2. Add the hosting relay to your Blocked Relay List.
+3. Report directly to **NCMEC** at https://report.cybertip.org/ (United States) or to an **INHOPE** hotline at https://www.inhope.org/ (other jurisdictions). These bodies can compel the hosting provider to act.
+4. You may also email **amethyst@vitorpamplona.com** with the relay URL and event ID. The developer cannot remove content from third-party relays, but may forward the report to relay operators it is in contact with and may stop recommending the offending relay in any list shipped with the app.
+
+### Compliance
+
+Amethyst is distributed under Google Play's Child Safety Standards policy and applicable law. Obligations attached to the **hosting** of content rest with relay operators.
+
+### Age rating
+
+Amethyst's Google Play listing is rated 17+. The app does not request or store age information.
 
 ## Terms of Use
 
-### For versions downloaded from Google's Play Store
+### Google Play build
 
-You cannot use the Amethyst app for Android to submit Objectionable Content to relays. Objectionable Content includes but is not limited to: (i) sexually explicit materials; (ii) obscene, defamatory, libelous, slanderous, violent and/or unlawful content or profanity; (iii) content that infringes upon the rights of any third party, including copyright, trademark, privacy, publicity or other personal or proprietary rights, or that is deceptive or fraudulent; (iv) content that promotes the use or sale of illegal or regulated substances, tobacco products, ammunition and/or firearms; and (v) illegal content related to gambling.
+You agree not to use the Google Play build of Amethyst to submit Objectionable Content to relays. Objectionable Content includes:
 
-### For versions downloaded from F-Droid
+- Sexually explicit material.
+- Obscene, defamatory, libelous, slanderous, violent, or unlawful content.
+- Content that infringes third-party rights (copyright, trademark, privacy, publicity).
+- Content that is deceptive or fraudulent.
+- Content promoting illegal drugs, tobacco, firearms, ammunition, or illegal gambling.
 
-We do not control the distribution of the application in F-Droid. Legal matters should be resolved between the user and F-Droid. 
+These Terms apply only to the Google Play distribution of Amethyst.
 
-## Other Notes
+### F-Droid and other source-built distributions
 
-We reserve the right to modify this Privacy Policy and Terms of Use at any time. Any modifications to this document will be effective upon our posting of the new terms and/or upon implementation of the new changes on the Service (or as otherwise indicated at the time of posting). In all cases, your continued use of the app after the posting of any modified Privacy Policy and Terms of Use indicates your acceptance of the terms of the modified Privacy Policy and/or Terms of Use.
+The MIT License in `LICENSE` is the only instrument governing your right to use, study, modify, and redistribute the software. No additional terms are imposed on these builds. Any dispute over distribution through F-Droid is between you and F-Droid.
 
-If you have any questions about Amethyst or this privacy policy, you can send a message to amethyst@vitorpamplona.com
+## Updates
+
+This document may change. The current version is published at https://github.com/vitorpamplona/amethyst/blob/main/PRIVACY.md.

README.md

@@ -14,7 +14,8 @@ Join the social network you control.
 [![PlayStore downloads](https://img.shields.io/endpoint?color=green&logo=google-play&logoColor=green&url=https%3A%2F%2Fplay.cuzi.workers.dev%2Fplay%3Fi%3Dcom.vitorpamplona.amethyst%26gl%3DUS%26hl%3Den%26l%3DPlayStore%26m%3D%24shortinstalls)](https://play.google.com/store/apps/details?id=com.vitorpamplona.amethyst)
 
 [![Last Version](https://img.shields.io/github/release/vitorpamplona/amethyst.svg?maxAge=3600&label=Stable&labelColor=06599d&color=043b69)](https://github.com/vitorpamplona/amethyst)
-[![JitPack version](https://jitpack.io/v/vitorpamplona/amethyst.svg)](https://jitpack.io/#vitorpamplona/amethyst)
+[![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)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/vitorpamplona/amethyst)
@@ -269,18 +270,16 @@ For the Play build:
 
 ## Deploying
 
-Full release + bootstrap runbooks (Android AAB upload, desktop packaging,
-Homebrew cask, Winget manifest, Apple Developer signing budget time-box) live
-in [BUILDING.md § Release runbook](BUILDING.md#release-runbook) and
-[BUILDING.md § Bootstrap runbook (one-time)](BUILDING.md#bootstrap-runbook-one-time).
+A release is one tag push. Bump `app` and `appCode` in
+`gradle/libs.versions.toml`, then `git tag -s vX.Y.Z && git push --tags` — the
+`Create Release Assets` workflow builds and signs every Android, desktop, CLI,
+and Maven artifact, and Homebrew + Winget auto-bump on stable tags.
 
-TL;DR for cutting a release:
-
-1. Bump `app` in `gradle/libs.versions.toml` (e.g. `"1.08.1"`)
-2. Bump `versionCode` in `amethyst/build.gradle`
-3. `git commit -am "chore(release): 1.08.1" && git tag -s v1.08.1 && git push --tags`
-4. Wait for `Create Release Assets` workflow — 20 Android assets + 8 desktop assets go live on GH Release; Homebrew + Winget auto-bump on stable tags
-5. Upload AAB to Play Store manually (existing step)
+- **[BUILDING.md](BUILDING.md)** — everything any fork needs: build commands,
+  the CI pipeline, the secrets it requires, and the distribution channels.
+- **[RELEASE_OPS.md](RELEASE_OPS.md)** — the Amethyst maintainers'
+  ship checklist: the manual Play Store upload, Zapstore `zsp publish`, F-Droid
+  pull, and release-notes publishing.
 
 ## Using the Quartz library
 
@@ -298,20 +297,43 @@ repositories {
 Add the following line to your `commonMain` dependencies:
 
 ```gradle
-implementation('com.vitorpamplona.quartz:quartz:1:05.0')
+implementation('com.vitorpamplona.quartz:quartz:1.12.5')
 ```
 
 Variations to each platform are also available:
 
 ```gradle
-implementation('com.vitorpamplona.quartz:quartz-android:1:05.0')
-implementation('com.vitorpamplona.quartz:quartz-jvm:1:05.0')
-implementation('com.vitorpamplona.quartz:quartz-iosarm64:1:05.0')
-implementation('com.vitorpamplona.quartz:quartz-iossimulatorarm64:1:05.0')
+implementation('com.vitorpamplona.quartz:quartz-android:1.12.5')
+implementation('com.vitorpamplona.quartz:quartz-jvm:1.12.5')
+implementation('com.vitorpamplona.quartz:quartz-iosarm64:1.12.5')
+implementation('com.vitorpamplona.quartz:quartz-iossimulatorarm64:1.12.5')
 ```
 
 Check versions on [MavenCentral](https://central.sonatype.com/search?q=com.vitorpamplona.quartz)
 
+#### Snapshots (JitPack)
+
+Tagged releases go to Maven Central. For **pre-release / snapshot** builds —
+e.g. to test an unreleased fix straight from `main` or a feature branch — use
+[JitPack](https://jitpack.io/#vitorpamplona/amethyst), which builds the module
+on demand from any git ref:
+
+```gradle
+repositories {
+    maven { url = uri("https://jitpack.io") }
+}
+
+dependencies {
+    // version can be a tag, a commit hash, or "<branch>-SNAPSHOT"
+    implementation("com.github.vitorpamplona.amethyst:quartz:main-SNAPSHOT")
+}
+```
+
+The resolvable refs and the exact module coordinates are listed on the
+[JitPack page](https://jitpack.io/#vitorpamplona/amethyst). Prefer a Maven
+Central release for anything shipping to production — JitPack snapshots are not
+guaranteed stable.
+
 ### How to use
 
 Manage logged in users with the `KeyPair` class

RELEASE_OPS.md

@@ -0,0 +1,218 @@
+# Release Ops (Amethyst maintainers)
+
+This is the **operational checklist the Amethyst team follows to ship a
+release** — the account-specific, push-the-buttons side of cutting a version.
+The *generic* build/release mechanics (how the CI pipeline works, the asset
+naming contract, the secret names a fork must set, desktop packaging) live in
+[`BUILDING.md`](BUILDING.md). Read that first; this doc only covers what is
+specific to shipping the official Amethyst artifacts.
+
+> Forks: you do **not** need this file. `BUILDING.md` has everything you need to
+> build and release your own fork. This describes our accounts and channels.
+
+---
+
+## At a glance
+
+A release is one tag push that fans out to five distribution channels:
+
+| Channel | Mechanism | Who pushes |
+|---|---|---|
+| **GitHub Releases** | Automatic — the `Create Release Assets` workflow builds + signs everything on the `v*` tag | CI |
+| **Google Play** | **Manual** — download the signed AAB from the GH Release, upload in Play Console | Maintainer |
+| **F-Droid** | **Pull** — F-Droid's build server builds the `fdroid` flavor from source when it sees the new tag | F-Droid (we just maintain the recipe + metadata) |
+| **Zapstore** | `zsp publish` reads `zapstore.yaml`, signs a Nostr release event with Amethyst's nsec | Maintainer |
+| **Homebrew + Winget** | Automatic — `bump-homebrew.yml` / `bump-winget.yml` fire on stable tags | CI |
+
+Maven Central (the `quartz` library) also publishes automatically from the same
+workflow.
+
+---
+
+## 1. Pre-tag checklist
+
+1. **Bump the version** in `gradle/libs.versions.toml` — both keys:
+   ```toml
+   app     = "1.12.1"   # semver, drives every module + the tag
+   appCode = "449"      # Android versionCode, monotonic — must increment
+   ```
+   That single edit propagates to Android (`versionName`/`versionCode`),
+   Desktop & CLI (`packageVersion`), `quartz` (Maven version) and `geode`
+   (`RelayInfo.VERSION`). Nothing else hardcodes the version.
+
+2. **Write the changelog** as `docs/changelog/vMAJOR.MINOR.PP.md` (zero-padded,
+   e.g. `v1.12.01.md`) and add it to `docs/changelog/README.md`. Follow the
+   house style: plain text, short verb-first sentences.
+
+3. **Publish the release-notes note on Nostr** with Amethyst's account and paste
+   its event id into `amethyst/build.gradle.kts`:
+   ```kotlin
+   buildConfigField("String", "RELEASE_NOTES_ID", "\"<new-event-id-hex>\"")
+   ```
+   This id is what the in-app drawer's "Release Notes" link and the donation
+   card open (`DrawerContent.kt`, `ShowDonationCard.kt`). It must point at the
+   note for *this* version, so publish the note **before** tagging and commit
+   the new id together with the version bump.
+
+   <!-- TODO(maintainer): document the exact command/account used to publish the
+        release-notes note (which signer, which relays). -->
+
+4. **Sanity-build locally** (optional but cheap): `./gradlew assembleRelease`
+   and a desktop `packageDistributionForCurrentOS`, or run the workflow's
+   dry-run (see BUILDING.md § Dry-run).
+
+---
+
+## 2. Cut the release
+
+Commit, tag, push — see [`BUILDING.md` § Release runbook](BUILDING.md#release-runbook)
+for the exact commands. The tag must equal `app` from the catalog (the workflow
+asserts this and fails fast otherwise). A clean `vMAJOR.MINOR.PATCH` tag is
+classified **stable** and triggers the Homebrew/Winget bumps; anything with a
+`-rc`/`-beta`/`-alpha`/`-dev` suffix is a prerelease and skips them.
+
+When the `Create Release Assets` workflow finishes (~25–30 min) the GH Release
+holds, per the asset-name contract:
+
+- **Android:** 5 Google Play APKs + 5 F-Droid APKs + 2 AABs
+  (`amethyst-googleplay-*-v…apk` / `.aab`, `amethyst-fdroid-*-v…apk` / `.aab`)
+- **Desktop:** 8 assets (DMG/MSI/DEB/RPM/AppImage/zip/tar.gz)
+- **CLI:** the `amy` artifacts
+- **Maven Central:** `com.vitorpamplona.quartz:quartz:<version>` published
+
+---
+
+## 3. Per-channel shipping
+
+### GitHub Releases — automatic
+Nothing to do beyond pushing the tag. Verify the asset count and that Intel +
+ARM DMGs are both present (BUILDING.md § Verify).
+
+### Google Play — manual upload
+1. Download `amethyst-googleplay-<version>.aab` from the GH Release.
+2. Play Console → app `com.vitorpamplona.amethyst` → **Production** (or the
+   staged-rollout track we're using) → create release → upload the AAB.
+3. The release notes field can reuse the `docs/changelog` text.
+4. Roll out.
+
+### F-Droid — pull / build-from-source
+F-Droid does **not** accept an upload from us. Its build server polls the repo,
+and when it sees the new `v*` tag it builds the **`fdroid` product flavor** from
+source (reproducibly) per the recipe in the separate
+[`fdroiddata`](https://gitlab.com/fdroid/fdroiddata) repo
+(`metadata/com.vitorpamplona.amethyst.yml`), then signs and publishes to the
+F-Droid repo on its own cadence.
+
+What we own to keep that working:
+- The **`fdroid` flavor** (`amethyst/src/fdroid/…`) must stay free of
+  proprietary deps — it swaps Firebase/Google services for UnifiedPush and
+  no-op/open implementations (ML Kit, writing assistant, push). Google-only
+  libraries live behind the `play` flavor.
+- The fastlane metadata under `fastlane/metadata/android/` (descriptions,
+  images). F-Droid reads per-version changelogs from
+  `fastlane/metadata/android/en-US/changelogs/<versionCode>.txt` if present —
+  add one (e.g. `449.txt`) when we want a changelog shown on F-Droid; otherwise
+  none is displayed.
+- The `AutoUpdateMode`/`UpdateCheckMode` in the fdroiddata recipe tracks tags,
+  so a correct `vX.Y.Z` tag + bumped `versionCode` is usually all F-Droid needs.
+
+After a release, just confirm F-Droid picked up the new version (it can lag a
+few days): <https://f-droid.org/packages/com.vitorpamplona.amethyst/>.
+
+### Zapstore — `zsp publish` with Amethyst's nsec
+[Zapstore](https://zapstore.dev/) is a Nostr-native app store. The `zsp` CLI
+reads [`zapstore.yaml`](zapstore.yaml) at the repo root (name, summary,
+description, tags, license, `icon`, screenshots, `supported_nips`, and the
+`variants` regexes that match our `*-fdroid-*.apk` / `*-googleplay-*.apk`
+GH-release assets), then publishes a signed software-release event to Nostr
+relays.
+
+```bash
+# from the repo root, after the GH Release assets exist
+zsp publish
+```
+
+It signs with **Amethyst's nsec** — provide the key the way `zsp` expects
+(`SIGN_WITH` env var / prompt / its own config), never commit it.
+
+**Relays.** `zsp` does *not* take relays from `zapstore.yaml`; it reads the
+`RELAY_URLS` env var (comma-separated) and defaults to `wss://relay.zapstore.dev`
+when unset. To fan the release event out to more relays for discoverability,
+set `RELAY_URLS` for the run:
+
+```bash
+RELAY_URLS="wss://relay.zapstore.dev,wss://relay.damus.io,wss://nos.lol,wss://vitor.nostr1.com" \
+  SIGN_WITH=<amethyst-nsec> zsp publish
+```
+
+Keep `wss://relay.zapstore.dev` in the list — that is the relay the Zapstore app
+itself reads from.
+
+### Homebrew + Winget — automatic
+`bump-homebrew.yml` and `bump-winget.yml` fire on stable tags and open PRs
+against `Homebrew/homebrew-cask` (cask `amethyst-nostr`) and
+`microsoft/winget-pkgs` (`VitorPamplona.Amethyst`). No action unless one fails —
+then see BUILDING.md § Bootstrap and § Incident response.
+
+---
+
+## 4. Operated infrastructure
+
+### Push notification server
+
+The Google Play (FCM) flavor delivers push through a server we operate at
+`push.amethyst.social`, built from
+[`vitorpamplona/amethyst-push-notif-server`](https://github.com/vitorpamplona/amethyst-push-notif-server).
+It registers devices, watches their NIP-65 inbox / NIP-17 DM relays, and sends
+wake-up pushes.
+
+- **`play` flavor** → push via this server (Firebase/FCM).
+- **`fdroid` flavor** → UnifiedPush through a distributor app the user installs
+  (e.g. ntfy); it does **not** use our server.
+- Both are complemented by the on-device always-on `NotificationRelayService`
+  (see [`PULL_NOTIFICATION.md`](PULL_NOTIFICATION.md)), which keeps the user's
+  relay connections alive without any push server at all.
+
+The push server has its **own repo, deploy, and release cadence** — a normal app
+release does **not** redeploy it. Coordinate a server deploy only when the app
+changes the registration/push contract (token format, payload, or endpoint), so
+the running server stays compatible with the shipped app.
+
+<!-- TODO(maintainer): document the push-server deploy steps + hosting, and
+     which app-side changes require a coordinated push-server deploy. -->
+
+---
+
+## 5. Secrets ownership & rotation
+
+The workflow's required secrets and what they sign are inventoried generically
+in [`BUILDING.md` § Secrets](BUILDING.md#secrets-the-ci-needs). Amethyst-specific
+ownership:
+
+| Secret(s) | Protects | Rotation |
+|---|---|---|
+| `SIGNING_KEY`, `KEY_ALIAS`, `KEY_STORE_PASSWORD`, `KEY_PASSWORD` | The **Android upload keystore** — losing/leaking it is the worst case; Play app signing identity | Keep the keystore backed up offline; never rotate casually (Play upload key reset is a support process) |
+| `SONATYPE_USERNAME`, `SONATYPE_PASSWORD` | Maven Central namespace `com.vitorpamplona` | On compromise |
+| `SIGNING_PRIVATE_KEY`, `SIGNING_PASSWORD` | The **GPG key** signing Maven artifacts | Per GPG key expiry |
+| `HOMEBREW_TOKEN`, `WINGET_TOKEN` | Cask + winget bump PRs | **90-day cadence** (see BUILDING.md § Bootstrap) |
+| `CROWDIN_PERSONAL_TOKEN`, `CROWDIN_PROJECT_ID` | Translation sync | On compromise |
+
+Owner assignments and rotation reminders live with the team (issue tracker).
+
+<!-- TODO(maintainer): name the owner per secret and where backups live. -->
+
+---
+
+## 6. Post-release verification
+
+- [ ] GH Release: expected asset count, Intel + ARM DMGs, sizes sane.
+- [ ] Maven Central: `quartz:<version>` resolves (allow propagation time).
+- [ ] Play Console: rollout started, no policy rejection.
+- [ ] Zapstore: release event visible.
+- [ ] F-Droid: new version detected (may lag days).
+- [ ] Homebrew + Winget bump PRs opened (stable only).
+- [ ] In-app "Release Notes" link opens the note matching `RELEASE_NOTES_ID`.
+- [ ] Push still works on a `play` build (only if the push contract changed —
+      see § 4); UnifiedPush still works on an `fdroid` build.
+
+If anything ships broken, see [`BUILDING.md` § Incident response](BUILDING.md#incident-response).

amethyst/build.gradle

@@ -1,435 +0,0 @@
-import org.jetbrains.kotlin.gradle.dsl.JvmTarget
-
-plugins {
-    alias(libs.plugins.androidApplication)
-    alias(libs.plugins.googleServices)
-    alias(libs.plugins.jetbrainsComposeCompiler)
-    alias(libs.plugins.serialization)
-}
-
-def getCurrentBranch() {
-    try {
-        def branch = 'git rev-parse --abbrev-ref HEAD'.execute().text.trim()
-        return branch
-    } catch (Exception e) {
-        println "Could not determine git branch: ${e.message}"
-        return "unknown"
-    }
-}
-
-def generateVersionName(String baseVersion) {
-    def currentBranch = getCurrentBranch()
-
-    if (currentBranch == "main" || currentBranch == "master" || currentBranch == "unknown" || currentBranch == "HEAD") {
-        return baseVersion
-    } else {
-        // Clean branch name for version (replace special characters)
-        def cleanBranch = currentBranch.replaceAll(/[^a-zA-Z0-9\-_]/, "-")
-
-        // Limit branch name to maximum 20 characters
-        if (cleanBranch.length() > 20) {
-            cleanBranch = cleanBranch.substring(0, 20)
-        }
-
-        return "${baseVersion}-${cleanBranch}"
-    }
-}
-
-// Workaround: stability.analyzer plugin doesn't declare task dependencies properly for Gradle 9.x
-afterEvaluate {
-    def stabilityNames = tasks.names.findAll { it.contains("StabilityCheck") }
-    def compileNames = tasks.names.findAll { it.matches("compile.*UnitTestKotlin") }
-    stabilityNames.each { scName ->
-        compileNames.each { ctName ->
-            tasks.named(scName).configure { mustRunAfter(tasks.named(ctName)) }
-        }
-    }
-}
-
-android {
-    namespace = 'com.vitorpamplona.amethyst'
-    compileSdk = libs.versions.android.compileSdk.get().toInteger()
-
-    defaultConfig {
-        applicationId = "com.vitorpamplona.amethyst"
-        minSdk = libs.versions.android.minSdk.get().toInteger()
-        targetSdk = libs.versions.android.targetSdk.get().toInteger()
-        versionCode = 445
-        versionName = generateVersionName(libs.versions.app.get())
-        buildConfigField "String", "RELEASE_NOTES_ID", "\"b1b91d7ee0c5da9d081d1a53470248ee4585b058b11aa34fe28c0e3e07ac1e0a\""
-
-        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
-        vectorDrawables {
-            useSupportLibrary = true
-        }
-        resourceConfigurations += [
-            'ar',
-            'ar-rSA',
-            'bn-rBD',
-            'cs',
-            'cs-rCZ',
-            'cy-rGB',
-            'da-rDK',
-            'de',
-            'de-rDE',
-            'el-rGR',
-            'en-rGB',
-            'eo',
-            'eo-rUY',
-            'es',
-            'es-rES',
-            'es-rMX',
-            'es-rUS',
-            'et-rEE',
-            'fa',
-            'fa-rIR',
-            'fi-rFI',
-            'fo-rFO',
-            'fr',
-            'fr-rCA',
-            'fr-rFR',
-            'gu-rIN',
-            'hi-rIN',
-            'hr-rHR',
-            'hu',
-            'hu-rHU',
-            'in',
-            'in-rID',
-            'it-rIT',
-            'iw-rIL',
-            'ja',
-            'ja-rJP',
-            'kk-rKZ',
-            'ko-rKR',
-            'ks-rIN',
-            'ku-rTR',
-            'lt-rLT',
-            'ne-rNP',
-            'nl',
-            'nl-rBE',
-            'nl-rNL',
-            'pcm-rNG',
-            'pl-rPL',
-            'pt-rBR',
-            'pt-rPT',
-            'ru',
-            'ru-rRU',
-            'ru-rUA',
-            'sa-rIN',
-            'sl-rSI',
-            'so-rSO',
-            'sr-rSP',
-            'ss-rZA',
-            'sv-rSE',
-            'sw-rKE',
-            'sw-rTZ',
-            'ta',
-            'ta-rIN',
-            'th',
-            'th-rTH',
-            'tr',
-            'tr-rTR',
-            'uk',
-            'uk-rUA',
-            'ur-rIN',
-            'uz-rUZ',
-            'vi-rVN',
-            'zh',
-            'zh-rCN',
-            'zh-rHK',
-            'zh-rSG',
-            'zh-rTW'
-        ]
-    }
-
-    // Opt-in fast-build flags. Default behavior is unchanged.
-    //
-    //   -PdisableAbiSplits=true       skip per-ABI APK splits; produces a single
-    //                                 APK per (flavor, buildType) instead of 5.
-    //                                 Cuts ~600 MB of intermediates and several
-    //                                 minutes off CI.
-    //   -PdisableUniversalApk=true    when ABI splits are enabled, skip the
-    //                                 extra universal APK output. (No effect
-    //                                 when disableAbiSplits is also set, since
-    //                                 there are no splits to add to.)
-    //   -Pamethyst.skipMapping=true   disable R8 minification on release and
-    //                                 benchmark. APK is larger, but builds are
-    //                                 much faster and outputs/mapping/ (~260MB)
-    //                                 is not produced. Local-dev and PR-CI use
-    //                                 only — release pipelines must not set it.
-    def disableAbiSplits = providers.gradleProperty("disableAbiSplits")
-            .map { it.toBoolean() }.getOrElse(false)
-    def disableUniversalApk = providers.gradleProperty("disableUniversalApk")
-            .map { it.toBoolean() }.getOrElse(false)
-    def skipMapping = providers.gradleProperty("amethyst.skipMapping")
-            .map { it.toBoolean() }.getOrElse(false)
-
-    buildTypes {
-        release {
-            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), 'proguard-rules.pro'
-            minifyEnabled = !skipMapping
-        }
-        debug {
-            applicationIdSuffix '.debug'
-            versionNameSuffix '-DEBUG'
-            resValue "string", "app_name", "@string/app_name_debug"
-        }
-        create("benchmark") {
-            initWith(getByName("release"))
-            applicationIdSuffix '.benchmark'
-            versionNameSuffix '-BENCHMARK'
-            resValue "string", "app_name", "@string/app_name_benchmark"
-            profileable = true
-            signingConfig = signingConfigs.debug
-        }
-    }
-
-    // TODO: remove this when lightcompressor uses one MP4 parser only
-    packaging {
-        resources {
-            resources.pickFirsts.add('builddef.lst')
-            resources.pickFirsts.add('META-INF/LICENSE.md')
-            resources.pickFirsts.add('META-INF/LICENSE-notice.md')
-        }
-    }
-
-    flavorDimensions = ["channel"]
-
-    productFlavors {
-        play {
-            getIsDefault().set(true)
-            dimension "channel"
-            buildConfigField "boolean", "IS_CASTING_AVAILABLE", "true"
-        }
-
-        fdroid {
-            dimension "channel"
-            buildConfigField "boolean", "IS_CASTING_AVAILABLE", "false"
-        }
-    }
-
-    splits {
-        abi {
-            enable = !disableAbiSplits
-            reset()
-            include "x86", "x86_64", "arm64-v8a", "armeabi-v7a"
-            universalApk = !disableUniversalApk
-        }
-    }
-
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_21
-        targetCompatibility JavaVersion.VERSION_21
-    }
-
-    buildFeatures {
-        compose = true
-        buildConfig = true
-        resValues = true
-    }
-
-    packagingOptions {
-        resources {
-            excludes += ['/META-INF/{AL2.0,LGPL2.1}', '**/libscrypt.dylib']
-        }
-    }
-
-    lint {
-        disable 'MissingTranslation'
-    }
-
-    testOptions {
-        unitTests.returnDefaultValues = true
-    }
-}
-
-// TODO: until google merges and unifiedpush updates https://github.com/tink-crypto/tink-java-apps/pull/5
-configurations.all {
-    def tink = "com.google.crypto.tink:tink-android:1.17.0"
-    resolutionStrategy {
-        force(tink)
-        dependencySubstitution {
-            substitute module('com.google.crypto.tink:tink') using module(tink)
-        }
-    }
-}
-
-kotlin {
-    compilerOptions {
-        jvmTarget = JvmTarget.JVM_21
-    }
-}
-
-composeCompiler {
-    reportsDestination = layout.buildDirectory.dir("compose_compiler")
-    metricsDestination = layout.buildDirectory.dir("compose_compiler")
-}
-
-dependencies {
-    implementation platform(libs.androidx.compose.bom)
-
-    implementation project(path: ':quartz')
-    implementation project(path: ':commons')
-    implementation project(path: ':nestsClient')
-    implementation libs.androidx.core.ktx
-    implementation libs.androidx.activity.compose
-
-    implementation libs.androidx.ui
-    implementation libs.androidx.ui.graphics
-    implementation libs.androidx.ui.tooling.preview
-
-    // Needs this to open gallery / image upload
-    implementation libs.androidx.fragment.ktx
-
-    // Navigation
-    implementation libs.androidx.navigation.compose
-
-    // Material 3 Design
-    implementation libs.androidx.material3
-
-    // Adaptive Layout / Two Pane
-    implementation libs.androidx.material3.windowSize
-    implementation libs.accompanist.adaptive
-
-    // Lifecycle
-    implementation libs.androidx.lifecycle.runtime.ktx
-    implementation libs.androidx.lifecycle.runtime.compose
-    implementation libs.androidx.lifecycle.viewmodel.compose
-
-    // Zoomable images
-    implementation libs.zoomable
-
-    // Biometrics
-    implementation libs.androidx.biometric.ktx
-
-    // Background Work
-    implementation libs.androidx.work.runtime.ktx
-
-    // Websockets API
-    implementation libs.okhttp
-    implementation libs.okhttpCoroutines
-
-    // Encrypted Key Storage
-    implementation libs.androidx.security.crypto.ktx
-    implementation libs.androidx.datastore.preferences
-
-    // view videos
-    implementation libs.androidx.media3.exoplayer
-    implementation libs.androidx.media3.exoplayer.hls
-    implementation libs.androidx.media3.ui.compose.material3
-    implementation libs.androidx.media3.session
-
-    // important for proxy / tor
-    implementation libs.androidx.media3.datasource.okhttp
-
-    // Load images from the web.
-    implementation libs.coil.compose
-    // view gifs
-    implementation libs.coil.gif
-    // view svgs
-    implementation libs.coil.svg
-    // enables network for coil
-    implementation libs.coil.okhttp
-    // loads thumbnails for media3
-    // TODO: Replace this to the FrameExtractor in media 3
-    // when FrameExtractor accepts custom data sources.
-    implementation(libs.coil.video)
-
-    // Permission to upload pictures:
-    implementation libs.accompanist.permissions
-
-    // For QR generation
-    implementation libs.zxing
-    implementation libs.zxing.embedded
-
-    // Markdown
-    //implementation "com.halilibo.compose-richtext:richtext-ui:0.16.0"
-    //implementation "com.halilibo.compose-richtext:richtext-ui-material:0.16.0"
-    //implementation "com.halilibo.compose-richtext:richtext-commonmark:0.16.0"
-
-    // Markdown (With fix for full-image bleeds)
-    implementation libs.markdown.ui
-    implementation libs.markdown.ui.material3
-    implementation libs.markdown.commonmark
-
-    // Language picker and Theme chooser
-    implementation libs.androidx.appcompat
-
-    // Dynamically adjust between phone and tablet UI
-    implementation libs.androidx.window.core.android
-
-    // Local model for language identification
-    playImplementation libs.google.mlkit.language.id
-
-    // Google services model the translate text
-    playImplementation libs.google.mlkit.translate
-
-    // On-device AI writing assistance (Gemini Nano via AICore)
-    playImplementation libs.google.mlkit.genai.proofreading
-    playImplementation libs.google.mlkit.genai.prompt
-    playImplementation libs.google.mlkit.genai.rewriting
-
-    // On-device alt-text suggestions: genai image description (preferred, descriptive sentences)
-    // with image-labeling as a keyword-join fallback for devices without AICore.
-    playImplementation libs.google.mlkit.genai.image.description
-
-    // PushNotifications
-    playImplementation platform(libs.firebase.bom)
-    playImplementation libs.firebase.messaging
-
-    //PushNotifications(FDroid)
-    fdroidImplementation libs.unifiedpush
-
-    // Google Cast SDK — Chromecast support. Play flavor only because the
-    // framework hard-depends on Google Play services, which is unavailable
-    // on de-Googled / GrapheneOS devices that ship the F-Droid build.
-    playImplementation libs.play.services.cast.framework
-
-    // Charts
-    implementation libs.vico.charts.compose
-    implementation libs.vico.charts.m3
-
-    // Waveform visualizer
-    implementation libs.audiowaveform
-
-    // Video compression lib
-    implementation libs.abedElazizShe.video.compressor.fork
-    // Image compression lib
-    implementation libs.zelory.image.compressor
-
-    // EXIF metadata stripping
-    implementation libs.androidx.exifinterface
-
-    // Voice anonymization DSP
-    implementation libs.tarsosdsp
-
-    // WebRTC for voice/video calls
-    implementation libs.stream.webrtc.android
-
-    // Cbor for cashuB format
-    implementation libs.kotlinx.serialization.cbor
-
-    // Kotlin serialization for the times where we need the Json tree and performance is not that important.
-    implementation(libs.kotlinx.serialization.json)
-
-    testImplementation libs.junit
-    testImplementation libs.mockk
-    testImplementation libs.kotlinx.coroutines.test
-
-    androidTestImplementation platform(libs.androidx.compose.bom)
-    androidTestImplementation libs.androidx.junit
-    androidTestImplementation libs.androidx.junit.ktx
-    androidTestImplementation libs.androidx.espresso.core
-    androidTestImplementation libs.androidx.ui.test.junit4
-    androidTestImplementation libs.mockk.android
-
-    debugImplementation platform(libs.androidx.compose.bom)
-    debugImplementation libs.androidx.ui.tooling
-    debugImplementation libs.androidx.ui.test.manifest
-
-    implementation libs.androidx.camera.core
-    implementation libs.androidx.camera.camera2
-    implementation libs.androidx.camera.lifecycle
-    implementation libs.androidx.camera.view
-    implementation libs.androidx.camera.extensions
-}

amethyst/build.gradle.kts

@@ -0,0 +1,515 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    alias(libs.plugins.androidApplication)
+    alias(libs.plugins.googleServices)
+    alias(libs.plugins.jetbrainsComposeCompiler)
+    alias(libs.plugins.serialization)
+    alias(libs.plugins.googleKsp)
+}
+
+fun getCurrentBranch(workingDir: java.io.File): String =
+    try {
+        val process =
+            ProcessBuilder("git", "rev-parse", "--abbrev-ref", "HEAD")
+                .directory(workingDir)
+                .redirectErrorStream(true)
+                .start()
+        val branch =
+            process.inputStream
+                .bufferedReader()
+                .use { it.readText() }
+                .trim()
+        val exitCode = process.waitFor()
+        if (exitCode != 0) "unknown" else branch
+    } catch (e: Exception) {
+        println("Could not determine git branch: ${e.message}")
+        "unknown"
+    }
+
+fun generateVersionName(
+    baseVersion: String,
+    workingDir: java.io.File,
+): String {
+    val currentBranch = getCurrentBranch(workingDir)
+
+    if (currentBranch == "main" || currentBranch == "master" || currentBranch == "unknown" || currentBranch == "HEAD") {
+        return baseVersion
+    }
+
+    // Clean branch name for version (replace special characters)
+    var cleanBranch = currentBranch.replace(Regex("[^a-zA-Z0-9\\-_]"), "-")
+
+    // Limit branch name to maximum 20 characters
+    if (cleanBranch.length > 20) {
+        cleanBranch = cleanBranch.substring(0, 20)
+    }
+
+    return "$baseVersion-$cleanBranch"
+}
+
+// Workaround: stability.analyzer plugin doesn't declare task dependencies properly for Gradle 9.x
+afterEvaluate {
+    val stabilityNames = tasks.names.filter { it.contains("StabilityCheck") }
+    val compileNames = tasks.names.filter { it.matches(Regex("compile.*UnitTestKotlin")) }
+    stabilityNames.forEach { scName ->
+        compileNames.forEach { ctName ->
+            tasks.named(scName).configure { mustRunAfter(tasks.named(ctName)) }
+        }
+    }
+}
+
+android {
+    namespace = "com.vitorpamplona.amethyst"
+    compileSdk =
+        libs.versions.android.compileSdk
+            .get()
+            .toInt()
+
+    defaultConfig {
+        applicationId = "com.vitorpamplona.amethyst"
+        minSdk =
+            libs.versions.android.minSdk
+                .get()
+                .toInt()
+        targetSdk =
+            libs.versions.android.targetSdk
+                .get()
+                .toInt()
+        versionCode =
+            libs.versions.appCode
+                .get()
+                .toInt()
+        versionName = generateVersionName(libs.versions.app.get(), rootDir)
+        buildConfigField("String", "RELEASE_NOTES_ID", "\"40e817712e397c07ba31784a92fa474aa095896a828c0e2dea0d09c60d49ee1e\"")
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables {
+            useSupportLibrary = true
+        }
+        @Suppress("UnstableApiUsage")
+        resourceConfigurations +=
+            listOf(
+                "ar",
+                "ar-rSA",
+                "bn-rBD",
+                "cs",
+                "cs-rCZ",
+                "cy-rGB",
+                "da-rDK",
+                "de",
+                "de-rDE",
+                "el-rGR",
+                "en-rGB",
+                "eo",
+                "eo-rUY",
+                "es",
+                "es-rES",
+                "es-rMX",
+                "es-rUS",
+                "et-rEE",
+                "fa",
+                "fa-rIR",
+                "fi-rFI",
+                "fo-rFO",
+                "fr",
+                "fr-rCA",
+                "fr-rFR",
+                "gu-rIN",
+                "hi-rIN",
+                "hr-rHR",
+                "hu",
+                "hu-rHU",
+                "in",
+                "in-rID",
+                "it-rIT",
+                "iw-rIL",
+                "ja",
+                "ja-rJP",
+                "kk-rKZ",
+                "ko-rKR",
+                "ks-rIN",
+                "ku-rTR",
+                "lt-rLT",
+                "ne-rNP",
+                "nl",
+                "nl-rBE",
+                "nl-rNL",
+                "pcm-rNG",
+                "pl-rPL",
+                "pt-rBR",
+                "pt-rPT",
+                "ru",
+                "ru-rRU",
+                "ru-rUA",
+                "sa-rIN",
+                "sl-rSI",
+                "so-rSO",
+                "sr-rSP",
+                "ss-rZA",
+                "sv-rSE",
+                "sw-rKE",
+                "sw-rTZ",
+                "ta",
+                "ta-rIN",
+                "th",
+                "th-rTH",
+                "tr",
+                "tr-rTR",
+                "uk",
+                "uk-rUA",
+                "ur-rIN",
+                "uz-rUZ",
+                "vi-rVN",
+                "zh",
+                "zh-rCN",
+                "zh-rHK",
+                "zh-rSG",
+                "zh-rTW",
+            )
+    }
+
+    // Opt-in fast-build flags. Default behavior is unchanged.
+    //
+    //   -PdisableAbiSplits=true       skip per-ABI APK splits; produces a single
+    //                                 APK per (flavor, buildType) instead of 5.
+    //                                 Cuts ~600 MB of intermediates and several
+    //                                 minutes off CI.
+    //   -PdisableUniversalApk=true    when ABI splits are enabled, skip the
+    //                                 extra universal APK output. (No effect
+    //                                 when disableAbiSplits is also set, since
+    //                                 there are no splits to add to.)
+    //   -Pamethyst.skipMapping=true   disable R8 minification on release and
+    //                                 benchmark. APK is larger, but builds are
+    //                                 much faster and outputs/mapping/ (~260MB)
+    //                                 is not produced. Local-dev and PR-CI use
+    //                                 only — release pipelines must not set it.
+    val disableAbiSplits =
+        providers
+            .gradleProperty("disableAbiSplits")
+            .map { it.toBoolean() }
+            .getOrElse(false)
+    val disableUniversalApk =
+        providers
+            .gradleProperty("disableUniversalApk")
+            .map { it.toBoolean() }
+            .getOrElse(false)
+    val skipMapping =
+        providers
+            .gradleProperty("amethyst.skipMapping")
+            .map { it.toBoolean() }
+            .getOrElse(false)
+
+    buildTypes {
+        getByName("release") {
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+            isMinifyEnabled = !skipMapping
+        }
+        getByName("debug") {
+            applicationIdSuffix = ".debug"
+            versionNameSuffix = "-DEBUG"
+            resValue("string", "app_name", "@string/app_name_debug")
+        }
+        create("benchmark") {
+            initWith(getByName("release"))
+            applicationIdSuffix = ".benchmark"
+            versionNameSuffix = "-BENCHMARK"
+            resValue("string", "app_name", "@string/app_name_benchmark")
+            isProfileable = true
+            signingConfig = signingConfigs.getByName("debug")
+        }
+    }
+
+    // TODO: remove this when lightcompressor uses one MP4 parser only
+    packaging {
+        resources {
+            pickFirsts.add("builddef.lst")
+            pickFirsts.add("META-INF/LICENSE.md")
+            pickFirsts.add("META-INF/LICENSE-notice.md")
+        }
+    }
+
+    flavorDimensions += "channel"
+
+    productFlavors {
+        create("play") {
+            isDefault = true
+            dimension = "channel"
+            buildConfigField("boolean", "IS_CASTING_AVAILABLE", "true")
+        }
+
+        create("fdroid") {
+            dimension = "channel"
+            buildConfigField("boolean", "IS_CASTING_AVAILABLE", "false")
+        }
+    }
+
+    splits {
+        abi {
+            isEnable = !disableAbiSplits
+            reset()
+            include("x86", "x86_64", "arm64-v8a", "armeabi-v7a")
+            isUniversalApk = !disableUniversalApk
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+
+    buildFeatures {
+        compose = true
+        buildConfig = true
+        resValues = true
+    }
+
+    packaging {
+        resources {
+            excludes += listOf("/META-INF/{AL2.0,LGPL2.1}", "**/libscrypt.dylib")
+        }
+    }
+
+    lint {
+        disable += "MissingTranslation"
+    }
+
+    testOptions {
+        unitTests.isReturnDefaultValues = true
+        // Lets TorArtiNativeIntegrationTest's System.loadLibrary("arti_android")
+        // find the desktop-host build of our Arti JNI shim. The Android .so
+        // variants live in src/main/jniLibs/{arm64-v8a,x86_64}/ and are loaded
+        // on-device — this Linux x86_64 .so is just for JVM unit-test runs.
+        // -Pamethyst.arti.integration=true opts the (slow, network-dependent)
+        // tests in; see TorArtiNativeIntegrationTest.kdoc.
+        unitTests.all { test ->
+            test.systemProperty(
+                "java.library.path",
+                "$projectDir/src/test/native-libs/x86_64-linux",
+            )
+            project
+                .findProperty("amethyst.arti.integration")
+                ?.let { test.systemProperty("amethyst.arti.integration", it.toString()) }
+        }
+    }
+}
+
+// androidx.appfunctions-compiler runs in a per-module mode by default,
+// emitting only the dispatcher Kotlin code. The aggregator that builds
+// the `app_functions.xml` asset (which the system reads to discover our
+// @AppFunction methods) is gated behind this KSP argument — without it,
+// the manifest's `android.app.appfunctions` property points at a file
+// that doesn't exist and the System UI logs "Unable to resolve
+// AppFunctionMetadata." Set on the app module only; library modules
+// (commons/quartz) would set it to "false".
+ksp {
+    arg("appfunctions:aggregateAppFunctions", "true")
+}
+
+// TODO: until google merges and unifiedpush updates https://github.com/tink-crypto/tink-java-apps/pull/5
+configurations.all {
+    val tink = "com.google.crypto.tink:tink-android:1.17.0"
+    resolutionStrategy {
+        force(tink)
+        dependencySubstitution {
+            substitute(module("com.google.crypto.tink:tink")).using(module(tink))
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_21)
+    }
+}
+
+composeCompiler {
+    reportsDestination = layout.buildDirectory.dir("compose_compiler")
+    metricsDestination = layout.buildDirectory.dir("compose_compiler")
+}
+
+dependencies {
+    implementation(platform(libs.androidx.compose.bom))
+
+    implementation(project(":quartz"))
+    implementation(project(":commons"))
+    implementation(project(":nestsClient"))
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.activity.compose)
+
+    implementation(libs.androidx.ui)
+    implementation(libs.androidx.ui.graphics)
+    implementation(libs.androidx.ui.tooling.preview)
+
+    // Needs this to open gallery / image upload
+    implementation(libs.androidx.fragment.ktx)
+
+    // Navigation
+    implementation(libs.androidx.navigation.compose)
+
+    // Material 3 Design
+    implementation(libs.androidx.material3)
+
+    // Adaptive Layout / Two Pane
+    implementation(libs.androidx.material3.windowSize)
+    implementation(libs.accompanist.adaptive)
+
+    // Lifecycle
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.lifecycle.runtime.compose)
+    implementation(libs.androidx.lifecycle.viewmodel.compose)
+
+    // Zoomable images
+    implementation(libs.zoomable)
+
+    // Biometrics
+    implementation(libs.androidx.biometric.ktx)
+
+    // Background Work
+    implementation(libs.androidx.work.runtime.ktx)
+
+    // Reads workouts from Android Health Connect (Samsung Health, Google Fit, Fitbit, Garmin, …)
+    implementation(libs.androidx.health.connect.client)
+
+    // Websockets API
+    implementation(libs.okhttp)
+    implementation(libs.okhttpCoroutines)
+
+    // Encrypted Key Storage
+    implementation(libs.androidx.security.crypto.ktx)
+    implementation(libs.androidx.datastore.preferences)
+
+    // view videos
+    implementation(libs.androidx.media3.exoplayer)
+    implementation(libs.androidx.media3.exoplayer.hls)
+    implementation(libs.androidx.media3.ui.compose.material3)
+    implementation(libs.androidx.media3.session)
+
+    // important for proxy / tor
+    implementation(libs.androidx.media3.datasource.okhttp)
+
+    // Load images from the web.
+    implementation(libs.coil.compose)
+    // view gifs
+    implementation(libs.coil.gif)
+    // view svgs
+    implementation(libs.coil.svg)
+    // enables network for coil
+    implementation(libs.coil.okhttp)
+    // loads thumbnails for media3
+    // TODO: Replace this to the FrameExtractor in media 3
+    // when FrameExtractor accepts custom data sources.
+    implementation(libs.coil.video)
+
+    // Permission to upload pictures:
+    implementation(libs.accompanist.permissions)
+
+    // For QR generation
+    implementation(libs.zxing)
+    implementation(libs.zxing.embedded)
+
+    // OpenStreetMap tiles for road event location maps (kind 1315/1316)
+    implementation(libs.osmdroid.android)
+
+    // Markdown
+    // implementation "com.halilibo.compose-richtext:richtext-ui:0.16.0"
+    // implementation "com.halilibo.compose-richtext:richtext-ui-material:0.16.0"
+    // implementation "com.halilibo.compose-richtext:richtext-commonmark:0.16.0"
+
+    // Markdown (With fix for full-image bleeds)
+    implementation(libs.markdown.ui)
+    implementation(libs.markdown.ui.material3)
+    implementation(libs.markdown.commonmark)
+
+    // LaTeX math rendering ($...$ and $$...$$ inline equations)
+    implementation(libs.jlatexmath.android)
+    implementation(libs.jlatexmath.font.greek)
+    implementation(libs.jlatexmath.font.cyrillic)
+
+    // Language picker and Theme chooser
+    implementation(libs.androidx.appcompat)
+
+    // Dynamically adjust between phone and tablet UI
+    implementation(libs.androidx.window.core.android)
+
+    // Local model for language identification
+    "playImplementation"(libs.google.mlkit.language.id)
+
+    // Google services model the translate text
+    "playImplementation"(libs.google.mlkit.translate)
+
+    // On-device AI writing assistance (Gemini Nano via AICore)
+    "playImplementation"(libs.google.mlkit.genai.proofreading)
+    "playImplementation"(libs.google.mlkit.genai.prompt)
+    "playImplementation"(libs.google.mlkit.genai.rewriting)
+
+    // On-device alt-text suggestions: genai image description (preferred, descriptive sentences)
+    // with image-labeling as a keyword-join fallback for devices without AICore.
+    "playImplementation"(libs.google.mlkit.genai.image.description)
+
+    // PushNotifications
+    "playImplementation"(platform(libs.firebase.bom))
+    "playImplementation"(libs.firebase.messaging)
+
+    // PushNotifications(FDroid)
+    "fdroidImplementation"(libs.unifiedpush)
+
+    // Google Cast SDK — Chromecast support. Play flavor only because the
+    // framework hard-depends on Google Play services, which is unavailable
+    // on de-Googled / GrapheneOS devices that ship the F-Droid build.
+    "playImplementation"(libs.play.services.cast.framework)
+
+    // androidx.appfunctions — Gemini App Functions adapter. Pre-stable
+    // (alpha) as of May 2026 — scoped to the play channel so the F-Droid
+    // build stays free of Google AI dependencies. Surface is an
+    // AppFunctionService registered in amethyst/src/play/AndroidManifest.xml,
+    // generated at compile time by the KSP-driven appfunctions-compiler.
+    "playImplementation"(libs.androidx.appfunctions)
+    "playImplementation"(libs.androidx.appfunctions.service)
+    "kspPlay"(libs.androidx.appfunctions.compiler)
+
+    // Charts
+    implementation(libs.vico.charts.compose)
+    implementation(libs.vico.charts.m3)
+
+    // Waveform visualizer
+    implementation(libs.audiowaveform)
+
+    // Video compression lib
+    implementation(libs.abedElazizShe.video.compressor.fork)
+    // Image compression lib
+    implementation(libs.zelory.image.compressor)
+
+    // EXIF metadata stripping
+    implementation(libs.androidx.exifinterface)
+
+    // WebRTC for voice/video calls
+    implementation(libs.stream.webrtc.android)
+
+    // Cbor for cashuB format
+    implementation(libs.kotlinx.serialization.cbor)
+
+    // Kotlin serialization for the times where we need the Json tree and performance is not that important.
+    implementation(libs.kotlinx.serialization.json)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.mockk)
+    testImplementation(libs.kotlinx.coroutines.test)
+
+    androidTestImplementation(platform(libs.androidx.compose.bom))
+    androidTestImplementation(libs.androidx.junit)
+    androidTestImplementation(libs.androidx.junit.ktx)
+    androidTestImplementation(libs.androidx.espresso.core)
+    androidTestImplementation(libs.androidx.ui.test.junit4)
+    androidTestImplementation(libs.mockk.android)
+
+    debugImplementation(platform(libs.androidx.compose.bom))
+    debugImplementation(libs.androidx.ui.tooling)
+    debugImplementation(libs.androidx.ui.test.manifest)
+
+    implementation(libs.androidx.camera.core)
+    implementation(libs.androidx.camera.camera2)
+    implementation(libs.androidx.camera.lifecycle)
+    implementation(libs.androidx.camera.view)
+    implementation(libs.androidx.camera.extensions)
+}

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

@@ -0,0 +1,367 @@
+# Onchain Zaps in Amethyst
+
+**Date:** 2026-05-14
+**Status:** Active
+
+Implementation plan for NIP-BC (kind 8333) onchain Bitcoin zaps in Amethyst Android.
+Quartz now ships the `OnchainZapEvent` data model; this document describes the
+rest of the system.
+
+## Design decisions
+
+- **Wallet model.** Non-custodial. The user's Nostr pubkey IS the BIP-341
+  internal key of a P2TR output, so every account has exactly one onchain
+  address derived from its identity. No seed phrase, no separate wallet
+  creation.
+- **Signers.** v1 supports `NostrSignerInternal` (local keypair) and
+  `NostrSignerExternal` (NIP-55 Android external signer). The NIP-55 path is
+  broken until Amber implements `sign_psbt`; surface "update your signer"
+  there. `NostrSignerRemote` (NIP-46) is deferred.
+- **Chain backend.** User-configured Esplora-compatible API
+  (mempool.space, blockstream.info, self-hosted). The configured server sees
+  the user's UTXO queries — accepted tradeoff for v1. **Spec PR
+  nostr-protocol/nips#2332 adds optional `["block", …]` and
+  `["proof", …]` tags on `kind:8333` that let a verifier with only the
+  Bitcoin header chain check a zap end-to-end without trusting the
+  explorer. Amethyst already parses both tags (see `BlockTag.kt` /
+  `ProofTag.kt`) but no production code path produces or consumes them
+  yet — see the "Inline SPV proofs" section below.** The explorer
+  endpoint is shared with OpenTimestamps via `BitcoinExplorerEndpoint`:
+  same user-configured server, same Tor-aware default selection.
+- **Scope.** Full send + receive + display loop on Android. Desktop is out of
+  scope for v1.
+
+### Architecture decision: hand-rolled Bitcoin consensus code (2026-05-14)
+
+**Decision:** keep the hand-rolled Bitcoin consensus layer in
+`quartz/.../nipBCOnchainZaps/{psbt,taproot}/` — the transaction codec,
+serialization/txid, BIP-341 sighash, BIP-174 PSBT codec/signer/finalizer, and
+BIP-341/350 address derivation. Do **not** pull in `fr.acinq.bitcoin-kmp`.
+
+**Considered alternative:** replace the `psbt/` + transaction + sighash layer
+with `fr.acinq.bitcoin-kmp` (mature, same vendor as the `secp256k1` binding
+already in the build).
+
+**Rationale for keeping it hand-rolled:**
+- It is a deliberately small, constrained subset — single-key-path P2TR only,
+  no script trees, one transaction shape.
+- It is pinned to authoritative external test vectors at *every* layer:
+  BIP-341 sighash (all 7 vectors + ANYONECANPAY), the BIP-341 tweak, the full
+  BIP-341 witness *signature bytes*, the 7 BIP-341/350 P2TR mainnet addresses,
+  and tx serialization against the genesis coinbase. It is "matches the
+  authoritative vectors," not "trust our code."
+- Consistent with the project's stance on minimal dependencies (cf. the
+  from-scratch `quic` module).
+- No new transitive dependencies or version-conflict surface.
+
+**Consequence / what this commits us to:** we own the correctness of this code
+forever. If the scope ever expands beyond single-key-path P2TR (script-path
+spends, multisig, PSBT fields we don't model), revisit this decision — at that
+point a vetted library is the better trade. The `nipBCOnchainZaps/{psbt,taproot}/`
+packages carry a pointer back to this section.
+
+
+## Architecture
+
+| Layer | Concerns | Location |
+|---|---|---|
+| Quartz | Address derivation, PSBT codec, Esplora client, NIP-BC verifier, `signPsbt` on signer hierarchy | `quartz/.../nipBCOnchainZaps/{taproot,psbt,chain,build,verify}/` |
+| Commons | Send/wallet ViewModels, shared composables | `commons/.../onchain/` |
+| Amethyst | `OnchainSection` in existing `WalletScreen`, `LocalCache.consume(OnchainZapEvent)`, kind list edits in 8 filter files, NIP-55 intent plumbing | `amethyst/.../ui/onchain/`, `amethyst/.../model/LocalCache.kt`, existing filter files |
+
+## Merging into the existing wallet UI
+
+The existing `WalletScreen` is a NIP-47 NWC multi-wallet manager. Onchain wallet
+fits as a separate top section, since it has different semantics (single
+deterministic wallet per account, no NWC URI, chain-backed).
+
+```
+WalletScreen
+├── TopAppBar
+├── BitcoinSection           ← NEW, single card
+│   └── OnchainWalletCard    (balance, bc1p address, tap → OnchainWalletDetailScreen)
+└── LightningSection         ← existing MultiWalletHomeContent
+    ├── NoWalletSetup
+    └── NwcWalletCard × N
+```
+
+The "+" `Add wallet` icon still adds NWC entries only — onchain is implicit.
+Section labels: "Bitcoin" and "Lightning".
+
+## Subscription edits — extend existing kind lists
+
+No new assemblers. Add `OnchainZapEvent.KIND` (8333) to the existing
+`LnZapEvent.KIND` (9735) sites:
+
+| File | Edit |
+|---|---|
+| `amethyst/.../FilterRepliesAndReactionsToNotes.kt:48-60` | Add to `RepliesAndReactionsKinds` (note `#e`) |
+| `amethyst/.../FilterUserProfileZapReceived.kt:30` | Add to `UserProfileZapReceiverKinds` (profile `#p`) |
+| `amethyst/.../zaps/dal/UserProfileZapsViewModel.kt:55` | Add to inline `kinds = listOf(...)` |
+| `amethyst/.../FilterNotificationsToPubkey.kt:58-65` | Add to `SummaryKinds` (notifications `#p`) |
+| `amethyst/.../NotificationFeedFilter.kt:123` | Add to `NOTIFICATION_KINDS` |
+| `amethyst/.../NotificationDispatcher.kt:98` | Add to `NOTIFICATION_KINDS` |
+| `amethyst/.../FilterMessagesToLiveStream.kt:46` | Add to live-activity zap kinds (`#a`) |
+| `amethyst/.../FilterGoalForLiveActivity.kt:58` | Add to goal-zap kinds (`#e`) |
+
+## Display path — fold into `Note.zapsAmount`
+
+Today: `LocalCache.consume(LnZapEvent)` → `Note.addZap()` → `Note.updateZapTotal()`
+sums lightning amounts into `Note.zapsAmount`, which `ReactionsRow` /
+`ObserveZapAmountText` / `SlidingAnimationAmount` render. We add onchain zap
+sats to the same `Note.zapsAmount` — no UI changes required.
+
+- `commons/.../model/Note.kt:154-157, 621-632`
+  - Add `var onchainZaps = mapOf<...>()` (separate map from `zaps`).
+  - Extend `updateZapTotal()` to add **verified** onchain sats. Unverified or
+    pending tx amounts are NOT counted.
+- `amethyst/.../model/LocalCache.kt` (after the `consume(LnZapEvent)` block ~line 1667)
+  - New `consume(event: OnchainZapEvent)` handler.
+  - Reject self-zap.
+  - Enqueue verification against the configured `OnchainBackend`.
+  - On success: `Note.addOnchainZap(event, verifiedSats)` on each `repliesTo`.
+  - On failure or zero verified amount: discard.
+  - Dedupe by `(txid, target)`.
+
+## Quartz additions
+
+- `nipBCOnchainZaps/taproot/`
+  - `SegwitAddress.kt` — bech32m segwit address encoder/decoder
+  - `TaprootAddress.kt` — Nostr pubkey → bc1p P2TR address via BIP-341
+    key-path-only tweak (uses `Secp256k1Instance.pubKeyTweakAdd`)
+- `nipBCOnchainZaps/chain/`
+  - `OnchainBackend` interface — `getTx`, `getUtxos`, `broadcast`,
+    `tipHeight`, `feeEstimates`
+  - `BitcoinTx`, `BitcoinTxOutput`, `Utxo` data models
+  - `BitcoinTxParser` — minimal raw-tx parser (just enough for verification)
+  - `EsploraBackend` (jvmAndroid) — OkHttp impl
+- `nipBCOnchainZaps/verify/`
+  - `OnchainZapVerifier` — implements all spec rules: reject self-zap, sum
+    only outputs paying the derived recipient address, dedupe `(txid, target)`,
+    cap claimed amount at verified amount
+- `nipBCOnchainZaps/psbt/` (Phase A.2)
+  - Minimal BIP-174 codec
+  - `PsbtTaprootKeyPathSigner` — BIP-341 TapTweak + Schnorr sign
+- `nipBCOnchainZaps/build/` (Phase A.2)
+  - `OnchainZapBuilder` — given (sender, recipient, sats, feeRate, utxos),
+    build a PSBT with change back to sender's Taproot
+- `NostrSigner.signPsbt` (Phase A.2)
+  - Internal: signs directly
+  - External (NIP-55): launches `sign_psbt` intent — needs Amber update
+  - Remote (NIP-46): `NotSupportedException` stub
+
+## Commons additions
+
+- `OnchainWalletViewModel` — derived address, balance, UTXO list
+- `OnchainZapSendViewModel` — build → sign → broadcast → publish kind 8333
+- `OnchainZapSendDialog`, `OnchainAddressQrCard`, `FeeRatePicker`
+
+## Account state
+
+In `AccountSettings.kt` next to `nwcWallets`:
+
+```kotlin
+val onchainEsploraEndpoint: MutableStateFlow<String>   // default mempool.space
+val onchainDefaultFeeTier: MutableStateFlow<FeeTier>   // SLOW / NORMAL / FAST
+```
+
+Derived `Account.onchainBalance: StateFlow<Long?>` populated by
+`OnchainWalletViewModel`.
+
+## Send-from-note merge
+
+Existing `ZapAmountChoicePopup` (`ReactionsRow.kt:1877-1977`) stays as the
+Lightning fast path. Two minimal hooks:
+
+1. Append `[ ⛓ Onchain… ]` row to the popup. Tapping it opens
+   `OnchainZapSendDialog` (fee picker + confirmation), separate from the
+   instant-tap Lightning UX.
+2. Optional settings toggle "Show onchain zap option" — defaults off until a
+   balance is observed.
+
+## Phased delivery
+
+| Phase | Deliverable | Status |
+|---|---|---|
+| **A.1** | Quartz foundation (receive side): taproot address, bech32m segwit, Esplora client, verifier + tests | **Shipped** |
+| **C**   | Receive + display: `OnchainSection` in `WalletScreen` (address + live balance), Esplora sync, `LocalCache.consume(OnchainZapEvent)`, `updateZapTotal` fold-in, kind-list edits in all 7 in-scope filter files | **Shipped** |
+| **A.2** | Quartz foundation (send side): BIP-174 PSBT codec, BIP-341 sighash, `OnchainZapBuilder`, `signPsbt` on the `NostrSigner` hierarchy. All crypto validated against BIP-341 wallet test vectors (31 tests). | **Shipped** |
+| **D**   | Send flow: `OnchainZapSender` orchestrator, `Account.sendOnchainZap`, `OnchainZapSendDialog`, "Send" button on the wallet `OnchainSection`. | **Shipped** |
+| **B**   | NIP-55 `sign_psbt` Intent + ContentResolver contract, wired through `NostrSignerExternal.signPsbt`. Works once the external signer app (Amber etc.) ships `sign_psbt` support — older signers reply with no `result`, surfaced as a send failure. | **Shipped** |
+
+### Phase A.2 — shipped
+
+- `nipBCOnchainZaps/psbt/`: `BitcoinIO` (LE byte codec + varint), `BitcoinTransaction`
+  (legacy + segwit serialization, witness-stripped txid), `TaprootSigHash`
+  (BIP-341 SigMsg + TapSighash, all sighash types), `Psbt` (BIP-174 subset,
+  unknown-record-preserving), `PsbtSigner` (key-path signing), `PsbtFinalizer`.
+- `nipBCOnchainZaps/build/OnchainZapBuilder`: largest-first coin selection +
+  unsigned-PSBT assembly with dust-aware change.
+- `TaprootAddress.tweakSecretKey`: BIP-341 `taproot_tweak_seckey`.
+- `Secp256k1Instance.privKeyNegate`: new primitive (commonMain + 3 actuals).
+- `NostrSigner.signPsbt`: real impl on internal signer; delegated by the
+  client-tag wrapper; `UnsupportedMethodException` stubs on NIP-46 / NIP-55.
+
+### Phase D — shipped
+
+- `commons/onchain/OnchainZapSender`: stateless orchestrator —
+  load UTXOs → `OnchainZapBuilder.build` → `signer.signPsbt` →
+  `PsbtFinalizer` → `OnchainBackend.broadcast` → publish kind:8333 via an
+  injected callback. Per-stage `OnchainZapSendResult.Failure`; broadcast txid
+  preserved when only the receipt-publish stage fails.
+- `Account.sendOnchainZap`: binds the account signer, `LocalCache.onchainBackend`,
+  and `signAndComputeBroadcast` into the orchestrator.
+- `OnchainZapSendDialog`: recipient npub (or fixed recipient + `zappedEvent`
+  for a future note-zap-menu entry), amount, fee tier from the backend's
+  estimates, comment; runs the send and shows progress + result.
+- `OnchainSection`: "Send" button on the wallet-screen Bitcoin card.
+
+### Phase B — shipped
+
+- `CommandType.SIGN_PSBT` (`sign_psbt`) — also usable in NIP-55 `perms` lists
+  via `Permission`, which wraps `CommandType` directly.
+- `SignPsbtResult` result type; `SignPsbtQuery` (background ContentResolver),
+  `SignPsbtRequest` / `SignPsbtResponse` (foreground Intent), mirroring the
+  `derive_key` string-in/string-out shape — the PSBT hex rides the
+  `nostrsigner:` URI, the signed PSBT comes back in `result`.
+- `BackgroundRequestHandler.signPsbt` / `ForegroundRequestHandler.signPsbt`;
+  `NostrSignerExternal.signPsbt` now does the real background-then-foreground
+  query instead of throwing. External signers that predate `sign_psbt` reply
+  with no `result` → `CouldNotPerformException`, surfaced by the send dialog.
+
+### What's still pending
+
+1. **Note-zap-menu entry point.** `OnchainZapSendDialog` already accepts
+   `recipientPubKey` + `zappedEvent`; wiring an "Onchain" option into the
+   existing `ZapAmountChoicePopup` is the remaining UI hook for event zaps.
+2. **NIP-46 `sign_psbt`.** `NostrSignerRemote.signPsbt` still throws
+   `UnsupportedMethodException` — the bunker-side command is not standardized
+   yet.
+3. **Send-side `block` + `proof` emit.** See "Inline SPV proofs" below.
+4. **Receive-side SPV verification.** See "Inline SPV proofs" below.
+
+## Inline SPV proofs (`block` + `proof` tags) — pending
+
+### Spec status (2026-05-19)
+
+`nostr-protocol/nips#2332` adds two new optional tags on `kind:8333`:
+
+```
+["block", "<block-hash-hex>", "<height>"]
+["proof", "<raw-tx-hex>", "<merkle-proof-hex>"]
+```
+
+Together they let a verifier with only the Bitcoin header chain check a
+zap end-to-end without trusting the chain backend. The recipient hashes
+`raw-tx-hex` to recover the txid, walks the merkle proof from that leaf
+up to the header's `merkleRoot`, parses outputs from `raw-tx-hex`, and
+sums those that pay the recipient's derived Taproot script.
+
+**One spec ambiguity outstanding** (raised back to the PR author):
+direction-at-each-step encoding for `<merkle-proof-hex>` — Bitcoin's
+merkle tree is tx-order-sensitive, so concatenated siblings alone don't
+specify left vs right. Suggested resolution: `1-byte direction || 32-byte
+sibling` per step (33 B stride). This blocks Phase G.2 (walker
+implementation), nothing else.
+
+### Current state in Amethyst
+
+| Layer | Status | Location |
+|---|---|---|
+| `BlockTag(blockHashHex, height: Long)` | ✅ shipped | `quartz/.../nipBCOnchainZaps/zap/tags/BlockTag.kt` |
+| `ProofTag(rawTxHex, merkleProofHex)` | ✅ shipped | `…/zap/tags/ProofTag.kt` |
+| `OnchainZapEvent.block()` / `.proof()` accessors | ✅ shipped | `…/zap/OnchainZapEvent.kt:89-93` |
+| TagArray + TagArrayBuilder helpers | ✅ shipped | `…/zap/TagArrayExt.kt`, `…/zap/TagArrayBuilderExt.kt` |
+| Tx parser + witness-stripped txid (reusable for the walker) | ✅ shipped | `…/psbt/BitcoinTransaction.kt` |
+| Recipient scriptPubKey derivation | ✅ shipped | `taproot/TaprootAddress.scriptPubKeyHexForRecipient` |
+| `OnchainZapSender` populates `block` / `proof` after broadcast | ❌ gap | `commons/.../onchain/OnchainZapSender.kt:209-214` (calls `build()` / `buildProfileZap()` with no SPV tags) |
+| `OnchainBackend.getMerkleProof(txid)` to source the proof on send | ❌ gap | `chain/OnchainBackend.kt` |
+| Merkle-proof parser + walker | ❌ gap | new `verify/MerkleProofVerifier.kt` |
+| `OnchainZapVerifier` prefers inline proof when present | ❌ gap | `verify/OnchainZapVerifier.kt` |
+| Validated `header.merkleRoot` lookup by block hash | ❌ gap | depends on the headers-explorer plan (S1) at `quartz/plans/2026-05-08-local-headers-explorer.md` |
+
+### Send-side: Design B (two-publish)
+
+`OnchainZapSender` publishes the `kind:8333` receipt **immediately** after
+`backend.broadcast(rawTxHex)` returns, when confirmations = 0. The chosen
+design keeps that instant UX and adds a second publish after the tx
+confirms:
+
+1. Today's path stays. Publish `kind:8333` right after broadcast, with
+   `i`/`p`/`amount`/`alt` only — no `block`, no `proof`.
+2. A new post-confirmation worker watches the tx via the backend. When it
+   sees ≥1 confirmation:
+   - Call `backend.getMerkleProof(txid)` → `(block_hash, height, siblings, pos)`.
+   - Encode `siblings + pos` into the spec's `<merkle-proof-hex>` wire format
+     (depends on the resolved spec encoding).
+   - Build a second `kind:8333` referencing the same `i` tag, with `block`
+     and `proof` filled in. Publish.
+3. Verifiers MUST dedupe by `(txid, target)` and prefer the variant
+   carrying a valid SPV proof. (This dedupe rule is also in the suggested
+   spec amendment.)
+
+Two relay broadcasts per zap, ~2 KB extra each. The post-confirmation
+worker is per-account, persists across app restarts, and exits cleanly
+once each pending tx is either confirmed (publish second receipt) or
+abandoned (after some timeout — TBD).
+
+### Receive-side
+
+`OnchainZapVerifier.verify(event)` gets a new fast path:
+
+1. If `event.block() != null && event.proof() != null`:
+   - Look up header by hash via `LocalHeadersBitcoinExplorer.byHash()` (S1).
+     If unavailable yet, fall through to the existing `backend.getTx()` path.
+   - `BitcoinTransaction.parse(rawTxHex)` → tx; recompute
+     `dsha256(stripWitness(tx))` → expected_txid; check it matches the
+     `i` tag's txid.
+   - `MerkleProofVerifier.verify(expected_txid, proofBytes, header.merkleRoot)` → boolean.
+   - Parse outputs from the same parsed tx; sum outputs paying the
+     recipient's `scriptPubKeyHexForRecipient`, skipping outputs paying
+     the sender's own derived script (change).
+   - Confirmations = `tip.height − block.height + 1`.
+   - Return `Confirmed`.
+2. If the inline path fails verification (bad proof, missing header,
+   tx-mismatch), the event is treated as if `block` / `proof` were
+   absent — fall back to the existing Esplora path. **Never** treat a
+   failed SPV proof as a hard-reject of the whole event; that would let
+   a buggy producer poison legitimate zaps.
+3. If neither tag is present (old-shape events), the existing
+   `backend.getTx()` path runs unchanged.
+
+The end state: a strict-mode user with HTTP fallback disabled can verify
+any zap whose sender included `block` + `proof`, and only those.
+
+### Phased delivery for the SPV work
+
+| Phase | Deliverable | Depends on | Effort |
+|---|---|---|---|
+| **G.1** | `MerkleProofVerifier` in `nipBCOnchainZaps/verify/`; test vectors per the resolved spec encoding | spec encoding locked | ½ d |
+| **G.2** | `OnchainZapVerifier` consumes inline proof, falls back on failure; needs `LocalHeadersBitcoinExplorer.byHash()` from S1 | S1 Phase 2 (storage) | ½ d |
+| **G.3** | `OnchainBackend.getMerkleProof(txid)` interface + `EsploraBackend` impl (`/tx/{txid}/merkle-proof`) | — | ½ d |
+| **G.4** | Post-confirmation worker + second-publish flow in `OnchainZapSender` | G.3 | 1 d |
+| **G.5** | Dedupe by `(txid, target)` preferring SPV-attached variant; `Note.zapsAmount` only counts the winner | — | ½ d |
+| **G.6** | End-to-end tests: real mainnet block + proof + zap; negative cases (wrong root, truncated, wrong direction) | G.1 | 1 d |
+| **G.7** | (Optional) Settings toggle "Verify zaps trustlessly when possible" — off by default until S1 ships | S1 Phase 7 | ½ d |
+| **Total** | | | ~3–4 d (after S1 ships and spec encoding lands) |
+
+S1 (the headers explorer at `quartz/plans/2026-05-08-local-headers-explorer.md`)
+is the long pole. The SPV work itself is small — every primitive needed
+already exists in the codebase, the only new thing is the merkle walker.
+
+## Risks / open questions
+
+- **secp256k1-kmp tweak coverage** — pubKeyTweakAdd exists on JVM/Android/JNI
+  but not on the pure-Kotlin native impl. iOS support deferred until upstream
+  ships it or we contribute.
+- **PSBT correctness** — single-key-path-only is a small surface; still needs
+  thorough testing against BIP-174 test vectors before any user funds move.
+- **Esplora privacy** — the configured server sees user UTXO queries. Default
+  to a reputable provider, make user-configurable, consider future Tor option.
+- **NIP-55 ecosystem** — Amber must implement `sign_psbt` for external signer
+  accounts to use this feature.
+- **`Note.zaps` shape** — separate `onchainZaps` map vs sealed-type fold-in.
+  Leaning separate map for v1.
+- **Verification network calls from `LocalCache`** — `consume` runs on the
+  relay thread; verification needs a coroutine scope + `OnchainBackend`
+  instance injected from `Account` on app start.

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

@@ -0,0 +1,390 @@
+# iOS Support for Amethyst
+
+**Date:** 2026-05-24
+**Status:** Phase 1 complete; Phase 2 in flight
+**Owner:** TBD
+
+Plan to incrementally bring Amethyst to iOS by extending the existing
+KMP layers from the bottom up. Each phase is independently shippable —
+we can pause between any two phases without leaving the tree in a
+broken state.
+
+## Why this is tractable today
+
+The structural work that usually dooms a KMP-to-iOS effort is already
+done:
+
+- `quartz/` has `iosArm64` + `iosSimulatorArm64` targets configured,
+  a working `Platform.ios.kt` actual, and 6 iOS test files that pass.
+- Jackson and OkHttp — the two big JVM-only dependencies — are *already
+  isolated to `jvmAndroid`* in quartz (`quartz/src/jvmAndroid/.../jackson/`,
+  `quartz/src/jvmAndroid/.../okhttp/`). `commonMain` is JVM-free except
+  for the obvious `kotlinx.*` stack.
+- `commons/commonMain` has exactly **one** Jackson reference
+  (`FeedDefinitionSerializer.kt`) and zero OkHttp references. The rest
+  of the JVM stickiness lives in `jvmAndroid` / `jvmMain` / `androidMain`,
+  which is where it belongs.
+- Compose Multiplatform 1.10.3 is in use, which supports iOS officially.
+- `secp256k1-kmp` ships iOS targets. `androidx.collection` (LruCache) and
+  `androidx.lifecycle.viewmodel.compose` are KMP since 2.8.
+
+What this means: we are not embarking on a months-long "purify
+commonMain" migration before any iOS code can compile. Phase 1 is
+mostly **add iOS to CI** and **patch the last few leaks**.
+
+## Module-by-module dep matrix
+
+Status legend:
+- ✅ iOS-ready (targets configured, no JVM-only deps in shared code)
+- 🟡 Partial (intermediate source sets need adding, but no major dep blockers)
+- 🔴 Blocked (significant native work required)
+- ⛔ Out of scope (won't ship on iOS)
+
+| Module | Today | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 |
+|---|---|---|---|---|---|---|
+| `quartz/` | ✅ | CI + audit | — | — | — | — |
+| `commons/` (non-UI) | 🟡 | — | ✅ | — | — | — |
+| `commons/` (UI) | 🟡 | — | — | ✅ | — | — |
+| `iosApp/` (new) | n/a | — | — | scaffold | feature-complete | — |
+| `quic/` | 🔴 | — | — | — | — | iOS actuals |
+| `nestsClient/` | 🔴 | — | — | — | — | iOS actuals |
+| `amethyst/` (app) | ⛔ | — | — | — | — | — |
+| `desktopApp/` | ⛔ | — | — | — | — | — |
+| `cli/` | ⛔ | — | — | — | — | — |
+
+## Source-set diagram (target end state)
+
+```
+commons/src/
+├── commonMain/              ── all targets
+│   ├── coreMain/            ── ViewModels, state, DAL (no Compose)
+│   │   ├── jvmAndroidCore/  ── Android + Desktop
+│   │   │   ├── androidCore/
+│   │   │   └── jvmCore/
+│   │   └── nativeCore/      ── iOS
+│   │       ├── iosArm64Core/
+│   │       └── iosSimArm64Core/
+│   └── uiMain/              ── Compose UI, icons, resources
+│       ├── jvmAndroidUi/
+│       │   ├── androidUi/
+│       │   └── jvmUi/
+│       └── nativeUi/        ── iOS Compose
+```
+
+(Names sketched for clarity; in practice we'll fold `coreMain` /
+`uiMain` together once *every* file in `uiMain` compiles for iOS —
+the split is a transitional scaffold for Phase 2 ↔ Phase 3.)
+
+`quartz/`, `quic/`, `nestsClient/` already use a `jvmAndroid` shared
+source set; we'll add a sibling `nativeMain` (or just `iosMain` where
+that's simpler) when each module turns on iOS.
+
+---
+
+## Phase 1 — Lock down Quartz on iOS
+
+**Duration estimate:** 1–2 weeks
+**Deliverable:** `./gradlew :quartz:iosSimulatorArm64Test` runs in CI on every PR.
+
+### Tasks
+
+1. **Add iOS to CI for `:quartz`.**
+   - GitHub Actions macOS runner step: `iosSimulatorArm64Test` +
+     `iosArm64SourceSetTest` (compile only).
+   - This is the single most valuable change in the entire plan — it
+     prevents anyone from accidentally re-adding a JVM-only import to
+     `commonMain`.
+
+2. **Audit the `jvmAndroid` boundary.**
+   - Confirm everything Jackson/OkHttp-related lives in `jvmAndroid`
+     (it does today — keep it that way).
+   - Add a checkstyle / detekt rule, or a simple grep gate in CI, that
+     fails the build if `com.fasterxml.jackson` or `okhttp3` shows up
+     in `commonMain`.
+
+3. **Validate `secp256k1` iOS path.**
+   - Make sure `KeyPair`, `SchnorrSigner`, NIP-44 v2 vectors run green
+     on `iosSimulatorArm64Test`.
+   - The iOS tests already cover NIP-04 / NIP-17 / NIP-19 / NIP-49 — we
+     just need to surface them in CI.
+
+4. **Plan the `expect`/`actual` for iOS HTTP.**
+   - Phase 1 only sketches the design; the actual `Ktor-darwin` wiring
+     lands in Phase 2 when `:commons` needs it.
+   - Decide: Ktor everywhere, vs OkHttp on JVM/Android + Ktor on iOS.
+     **Recommendation:** keep OkHttp on JVM/Android (we use OkHttp-specific
+     features in relay reconnect logic) and add an iOS-only Ktor actual.
+
+### Risks
+
+- None major. The work here is mostly defensive.
+
+---
+
+## Phase 2 — Bring `:commons` to iOS, non-UI first
+
+**Duration estimate:** 2–3 weeks
+**Deliverable:** `./gradlew :commons:iosSimulatorArm64Test` compiles every
+shared ViewModel and state class.
+
+### Tasks
+
+1. **Add iOS targets to `commons/build.gradle.kts`.**
+   - `iosArm64()` + `iosSimulatorArm64()`.
+   - Introduce intermediate source sets `coreMain` (all targets) and
+     `uiMain` (JVM + Android only, for now).
+
+2. **Migrate `FeedDefinitionSerializer.kt` off Jackson.**
+   - Move to `kotlinx.serialization`, OR
+   - Push it down into `jvmAndroidCore` and create a `nativeCore` actual.
+     **Recommendation:** migrate. It's one file; one-time cost is small;
+     reduces split-actual surface area forever.
+
+3. **Add `expect`/`actual` wrappers for JVM-only deps used by ViewModels.**
+
+   | Concern | JVM/Android | iOS actual |
+   |---|---|---|
+   | HTTP client | OkHttp | Ktor + `Ktor-darwin` |
+   | Secure key storage | Android Keystore / java-keyring | Keychain Services |
+   | EXIF strip (image upload) | `commons-imaging` | `ImageIO` (`CGImageSourceCopyPropertiesAtIndex`) |
+   | File I/O paths | `java.io.File` | `NSFileManager` / `okio` |
+   | Logging | `android.util.Log` / SLF4J | `os_log` via cinterop, or plain `println` to start |
+
+4. **Compile-only iOS for `:commons` ViewModels.**
+   - At the end of Phase 2 we have ViewModels, account state, LocalCache
+     wrappers, filter assemblers, and `ComposeSubscriptionManager` building
+     on iOS — but no UI yet.
+   - Smoke test: write a small `commonTest` that constructs an `Account`,
+     subscribes to a stub relay, and verifies a follow event lands in
+     `LocalCache`. Run it on iOS simulator.
+
+### Risks
+
+- **Ktor migration scope creep.** Hold the line: Phase 2 only wraps HTTP
+  behind `expect`. Don't refactor the relay pool. That's a separate PR.
+- **Coroutines dispatcher differences.** `Dispatchers.IO` does not exist on
+  Kotlin/Native by default — code that explicitly references it needs a
+  `KmpDispatchers.IO` shim. Audit before Phase 2 starts.
+
+### Phase 2 audit (2026-05-24): commons/commonMain iOS-blocker inventory
+
+Audit of all 335 .kt files in `commons/src/commonMain/`. Better than feared
+— most files are already KMP-clean. The actual blockers are 21 files
+across ~6 distinct concerns. Each row below is a small mergeable PR.
+
+**By blocker category:**
+
+| Blocker | Files | Fix |
+|---|---|---|
+| `java.util.Base64` | 1 (`Base64Image.kt`) | `kotlin.io.encoding.Base64` (stdlib since 1.8) |
+| `AtomicLong` / `AtomicInteger` | 2 (`ChessLobbyState.kt`, `SigningState.kt`) | `kotlinx.atomicfu.atomic` |
+| `ConcurrentHashMap` | 4 (`ChessRelayFetchHelper.kt`, `ChessEventCollector.kt`, `ComposeSubscriptionManager.kt`, `MutableComposeSubscriptionManager.kt`) | `androidx.collection.MutableScatterMap` (KMP) — synchronization most likely already provided by enclosing scope; audit per file |
+| `SortedSet` + `ConcurrentSkipListSet` | 2 (`EventListMatchingFilter.kt`, `NoteListMatchingFilter.kt`) | Switch to `mutableListOf` + sort-on-access, or `androidx.collection.MutableScatterSet` with manual order |
+| `WeakReference` | 5 (`Channel.kt`, `Chatroom.kt`, `MarmotGroupChatroom.kt`, `UserRelaysCache.kt`, **+1**) | `expect class KmpWeakReference<T>` actuals: JVM `java.lang.ref.WeakReference`; iOS `kotlin.native.ref.WeakReference` |
+| `BigDecimal` | 1 (`Note.kt`) | Either KMP bignum lib (`com.ionspin:bignum`) or move the BigDecimal-using helper to `jvmAndroid` and stub on iOS |
+| `java.io.File` | 1 (`MediaContentModels.kt`) | Replace with `String` path, or `okio.Path` |
+| `java.net.URI` / `MalformedURLException` | 2 (`RichTextParser.kt`, `UrlInfoItem.kt`) | KMP URL lib (`io.ktor:ktor-http`) or stay JVM via expect/actual `parseUrl()` |
+| `java.nio.charset.Charset` | 1 (`HtmlCharsetParser.kt`) | `kotlin.text.Charsets` for UTF-8/16; for arbitrary charsets, expect/actual |
+| `:nestsClient` project dep | 2 (`NestViewModel.kt`, `ActiveSubscription.kt`) | Move both files to `jvmAndroid` source set (audio rooms are Phase 5 anyway) |
+| `com.halilibo.richtext.*` | 1 (`RenderMarkdown.kt`) | Verify iOS artifact; if missing, move to `jvmAndroid` until Phase 3 markdown decision |
+
+**Files that look scary but aren't:**
+- 183 files import `androidx.compose.*` — these all map to JetBrains Compose
+  Multiplatform's iOS artifacts (identical package paths). No work needed.
+- 7 files import `androidx.lifecycle.*` — KMP since 2.8.0. No work needed.
+- 0 files import `coil3.network.okhttp` (Coil network is already isolated).
+- 0 files import `javax.*` or `android.*` directly from commonMain.
+
+**Recommended PR order** (ascending cost, descending obviousness):
+
+1. ✅ Phase 1 complete (gates + iOS CI for quartz, Jackson migration).
+2. **Base64** (1 file, ~2 LOC change). Demonstrates the pattern.
+3. **Atomics** (2 files, atomicfu plugin + ~10 LOC).
+4. **ConcurrentHashMap** (4 files; needs concurrency audit per file).
+5. **WeakReference** (5 files + 1 new expect/actual).
+6. **`:nestsClient` files → jvmAndroid** (2 files; pure source-set move).
+7. **`RenderMarkdown.kt` → jvmAndroid OR iOS verification** (1 file; depends on lib check).
+8. **URL parsing** (2 files; either ktor-http dep or expect/actual).
+9. **Charsets, BigDecimal, File** (3 files; small per-file decisions).
+10. After ~9 lands: add iOS targets to `:commons`, expect failures to be down
+    to ~zero, run `compileKotlinIosSimulatorArm64` to confirm.
+11. Then proceed with the original Phase 2 plan items (Ktor for HTTP,
+    SecureKeyStore expect/actual, etc.) for the cross-cutting deps.
+
+---
+
+## Phase 3 — Compose Multiplatform UI on iOS
+
+**Duration estimate:** 3–4 weeks
+**Deliverable:** A read-only iOS `.ipa` on TestFlight internal that connects
+to relays and renders a feed.
+
+### Tasks
+
+1. **Flip `uiMain` to target = all (including iOS).**
+   - Compose Multiplatform 1.10.3 supports iOS. The Material Symbols font
+     and other Compose Resources already work cross-platform.
+
+2. **Audit UI deps for iOS.**
+
+   | Dep | Status | Action |
+   |---|---|---|
+   | `jetbrains.compose.*` (1.10.3) | ✅ | None |
+   | `androidx.lifecycle.viewmodel.compose` 2.8+ | ✅ KMP | None |
+   | `coil3` | ✅ iOS | Swap network fetcher from `coil-okhttp` to `coil-ktor` on iOS via source-set split |
+   | `markdown-ui` / `markdown-ui-material3` | ⚠️ Verify | Likely OK on iOS; if not, fall back to commonmark + custom renderer |
+   | `kotlinx-collections-immutable` | ✅ | None |
+   | Material Symbols font | ✅ | None (already via Compose Resources) |
+
+3. **Create the `iosApp/` module.**
+   - SwiftUI `App` + `UIViewControllerRepresentable` hosting
+     `ComposeUIViewController { App() }`.
+   - Tab bar (UIKit) for top-level navigation, Compose for each tab's
+     content area. **Same split philosophy as Desktop**: native shell,
+     shared content.
+   - Add Xcode project + Gradle Kotlin/Native framework wiring (no
+     CocoaPods; use the JetBrains-recommended `embedAndSignAppleFrameworkForXcode`).
+
+4. **Ship a "read-only Nostr browser" first cut.**
+   - Profile view, single-feed home, NoteCard rendering, image loading,
+     basic navigation.
+   - No posting, no DMs, no audio rooms.
+   - This validates the *entire* stack — relay client, LocalCache, feed DAL,
+     NoteCard composable, Coil 3, Compose Resources, font rendering — without
+     touching signing.
+
+### Risks
+
+- **Compose iOS performance on large feeds.** Profile early with a realistic
+  `LocalCache` (10k+ notes) before locking screen architecture. If recomposition
+  storms appear, lean harder on `compose-stability-diagnostics` and
+  `compose-state-deferred-reads` skills.
+- **Touch interactions vs Android conventions.** Pull-to-refresh, swipe
+  back, long-press menus all differ on iOS. Some screens may need
+  platform-specific gesture handling.
+- **Markdown rendering library iOS support.** If `markdown-ui-material3`
+  doesn't ship iOS artifacts, this is a half-week detour to switch
+  renderers. Verify in week 1 of Phase 3.
+
+---
+
+## Phase 4 — Write paths: signing, posting, settings
+
+**Duration estimate:** 2–3 weeks
+**Deliverable:** Fully read/write iOS client, minus audio rooms.
+
+### Tasks
+
+1. **Wire `NostrSignerInternal` to Keychain.**
+   - The signer is already KMP — only the key storage actual needs
+     adding (done in Phase 2's `SecureKeyStore` abstraction).
+
+2. **Make `NostrSignerRemote` (NIP-46 bunker) work on iOS.**
+   - Should be KMP-clean once Ktor migration is done. Audit for any
+     stray Jackson / OkHttp inside the NIP-46 path.
+
+3. **NIP-55 alternative.**
+   - **There is no Amber on iOS.** Plan replacements:
+     - Push users toward NIP-46 bunkers (Nsec.app, Amber-as-bunker,
+       remote nostr-connect URIs).
+     - URL-scheme handoff to native iOS signers (`nos2x-fhe`, `Nostore`)
+       *if* they expose a sign API. Track separately.
+   - Onboarding screen needs an iOS-specific copy variant.
+
+4. **Posting, reactions, zaps.**
+   - Mostly free — ViewModels already in `:commons`. Wire UI buttons and
+     test end-to-end on TestFlight.
+
+5. **Settings UI.**
+   - Share via Compose. iOS-native preference screens are a polish item
+     for later.
+
+### Risks
+
+- **Apple App Review on cryptocurrency / zaps.** Lightning zaps via LNURL
+  are fine (no in-app crypto purchase). Anything that looks like an
+  in-app wallet or onchain send may need legal review and / or feature
+  gating per-region. Start review conversations early.
+- **Push notifications.** APNs is the only path on iOS. Nostr DM push
+  relays don't speak APNs natively. Likely needs a small relay-proxy
+  (similar to `notify.damus.io`'s architecture). Design doc in
+  `amethyst/plans/` before Phase 4 ends.
+
+---
+
+## Phase 5 — `:quic` + `:nestsClient` for audio rooms (optional)
+
+**Duration estimate:** 4–6 weeks
+**Status:** Defer until 1–4 are solid. App is shippable on iOS without
+audio rooms.
+
+### Tasks
+
+1. **`:quic` — add iOS actuals.**
+   - UDP socket via `Network.framework` (`NWConnection` with `.udp`).
+   - AEAD (AES-GCM, ChaCha20-Poly1305) via Apple CryptoKit
+     (`AES.GCM.SealedBox`, `ChaChaPoly`).
+   - TLS state machine is already pure Kotlin in `commonMain` — no change.
+
+2. **`:nestsClient` — add iOS actuals.**
+   - Opus encode/decode: `libopus` via cinterop, or pull `opus.framework`
+     from a Swift Package / CocoaPods spec.
+   - Mic + speaker: `AVAudioEngine` (input/output nodes) instead of
+     `AudioRecord` / `AudioTrack`.
+
+3. **moq-lite listener path first** (the production path per CLAUDE.md),
+   then speaker.
+
+### Risks
+
+- **Background audio on iOS.** Audio rooms in the background need a
+  proper `AVAudioSession` category + the `audio` background mode in
+  `Info.plist`. Apple sometimes rejects apps that abuse this. Worth a
+  separate audit before submission.
+- **Opus framework distribution.** `libopus` via Swift Package is
+  cleanest; CocoaPods is fine but pulls in a build-time dep on Ruby.
+  Decide before Phase 5 starts.
+
+---
+
+## Phase 6 — Ship polish (ongoing, post-Phase 4)
+
+- App Store metadata, screenshots, privacy manifest
+  (`NSPrivacyAccessedAPI*` declarations — file access, user defaults).
+- Localizations carry over automatically via Compose Resources.
+- Background fetch limits — iOS is far stricter than Android. Tune
+  feed prefetch + relay reconnect for background launch budgets.
+- TestFlight beta → public release.
+
+---
+
+## Cross-cutting risks (track from day one)
+
+| Risk | Mitigation | First chance to catch |
+|---|---|---|
+| `commonMain` regresses with a JVM-only import | Add iOS to CI on every PR | Phase 1, task 1 |
+| Coroutines `Dispatchers.IO` ergonomics on iOS | Audit + introduce `KmpDispatchers` shim | Phase 2, task 3 |
+| Compose iOS performance on big feeds | Early profiling with realistic `LocalCache` | Phase 3 risk section |
+| App Store review (zaps, onchain) | Talk to legal / read App Store guidelines early | Phase 4 risk section |
+| No NIP-55 equivalent on iOS | Lean on NIP-46; document in onboarding | Phase 4, task 3 |
+| Push notifications via APNs | Relay-proxy design doc | Phase 4, end of phase |
+| Background audio policy | `AVAudioSession` audit + `Info.plist` review | Phase 5 risk section |
+
+## Suggested first PR
+
+Smallest useful start: **Phase 1, tasks 1 + 2** — add `:quartz` iOS to
+CI and add the import-gate that prevents Jackson / OkHttp regressions
+in `commonMain`. That single PR de-risks the rest of the plan without
+touching any product code.
+
+## Open questions
+
+- Do we want a `:cli` analogue on iOS (a "headless" Nostr daemon)? Out
+  of scope for this plan, but iosArm64 *could* host one if we ever need
+  a CLI-on-phone story.
+- Mac Catalyst vs native macOS: Desktop is already JVM-Compose. We
+  could theoretically also ship Catalyst from the iOS build, but that's
+  three "desktop"-ish targets to maintain. Recommendation: punt.
+- iPad layout: do we want a separate split-view UI like `desktopApp`,
+  or just scale up the iPhone layout? Phase 3 keeps the iPhone layout;
+  iPad polish is a Phase 6 item.

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

@@ -0,0 +1,239 @@
+# AppFunctions signer prompts — design
+
+**Date:** 2026-05-25
+**Status:** Draft — no code yet
+
+How write verbs invoked from background Gemini context (via
+`androidx.appfunctions` 1.0.0-alpha09 → `PlatformAppFunctionService`)
+acquire a signature from each of Amethyst's three signer types. This
+is the gating concern that has us only exposing read-only verbs so far
+(`searchProfiles`, `searchNotes`, `getFollowing`).
+
+## The three signer types and what each needs
+
+| Signer | Where the private key lives | Sign call latency | Needs user interaction? |
+|---|---|---|---|
+| **`NostrSignerInternal`** | In-process keypair, loaded at login | Synchronous, microseconds | No |
+| **`NostrSignerRemote`** (NIP-46 bunker) | Remote process — a wallet app, browser tab, separate device | Network round-trip via relays, seconds | Yes — the bunker app pops a confirmation on the user's other device |
+| **`NostrSignerExternal`** (NIP-55, e.g. Amber) | Another Android app on the same device | Bound-service IPC + activity bounce | Yes — Amber shows an activity in the foreground asking the user to approve |
+
+Each signer surfaces the same `suspend fun sign(...)` API. The difference is
+**what happens to the foreground UI** while the sign is in flight.
+
+## What App Functions gives us to work with
+
+From the alpha09 artifact (`androidx.appfunctions:appfunctions-service`):
+
+- **Suspending dispatch.** `executeFunction` is a suspend function — a slow
+  signer (NIP-46 round-trip) doesn't block the system shell.
+- **Typed exceptions.** `AppFunctionPermissionRequiredException`,
+  `AppFunctionDeniedException`, `AppFunctionCancelledException`,
+  `AppFunctionAppException`. The non-default constructors take a `Bundle` —
+  the system shell can interpret known keys (e.g. a `PendingIntent` to launch
+  an in-app confirmation). Concrete bundle contract is undocumented in
+  alpha09; needs a sample-app check or an experiment.
+- **`PendingIntent`** is listed as a supported parameter type, which strongly
+  implies a returned `PendingIntent` can prompt the system to launch the
+  app's UI for follow-up.
+- **No streaming.** Functions return one value or throw. There's no native
+  "in progress" / "user is approving" signal back to Gemini.
+
+## Per-signer approach
+
+### NostrSignerInternal — just works
+
+Verb runs end-to-end inside the dispatch coroutine. `signer.sign(...)` is
+synchronous. Publish via `client.publish(...)`. Return success.
+
+**Verbs this covers immediately:** post, follow/unfollow, search-relay
+list updates, kind:10002 changes — anything where the signed event is
+sent and forgotten.
+
+**Edge case — background `app.client`.** When the app process is
+foreground-bound but the user is in Gemini, the client should be
+connected. When the user has killed Amethyst recently, the service
+process might be cold-started and the client not yet connected to any
+relay. The verb needs to either:
+- Wait for `client.connect()` (~hundreds of ms once the WebSocket is
+  established) — acceptable inside the 5-10s window.
+- Use `INostrClient.publish(...)` which queues the publish for when the
+  connection comes up. Quartz needs to confirm this is the actual
+  behavior; might require `withTimeout` around the publish.
+
+### NostrSignerRemote — the cleanest async case
+
+The bunker sends a NIP-46 request to a relay, the bunker app sees it on
+the user's other device, the user approves, the signed event comes back.
+`signer.sign(...)` suspends until the response arrives or its internal
+timeout fires (default 30s).
+
+**Approach:** call `signer.sign(...)` from within the verb, with a
+`withTimeout` budget aligned to App Functions UX expectations (Gemini
+typically waits ~30s before showing the user "no response"). On
+timeout, throw `AppFunctionCancelledException`. On success, publish and
+return.
+
+**Open question — concurrent foreground signing.** If the user is also
+trying to send a post from the foreground UI at the same moment, the
+bunker app gets two simultaneous requests. NIP-46 handles this — each
+request has a unique id — but Amber-like bunker apps may queue both
+prompts confusingly. Worth a manual test.
+
+### NostrSignerExternal — the hard case
+
+NIP-55 bounces to a separate Android app's activity. From a background
+`PlatformAppFunctionService`, we can't directly `startActivity(...)` —
+there's no foreground intent stack to attach to.
+
+**Two viable approaches:**
+
+#### Option A — throw a typed exception with a PendingIntent
+
+```kotlin
+@AppFunction
+suspend fun postNote(ctx: AppFunctionContext, text: String): PostResult {
+    val account = activeAccount() ?: throw AppFunctionDeniedException("not signed in")
+    if (account.signer is NostrSignerExternal) {
+        // Build a PendingIntent that opens Amethyst at a "approve this
+        // post" screen, with the draft text passed through extras.
+        val approvalIntent = buildApprovePostPendingIntent(account, text)
+        throw AppFunctionPermissionRequiredException(
+            message = "Amethyst needs to launch the external signer to approve this post.",
+            extras = bundleOf("pending_intent" to approvalIntent),
+        )
+    }
+    // … happy path for the in-process signer
+}
+```
+
+The system shell renders "Open Amethyst to continue", user taps,
+Amethyst opens, user approves through Amber's activity, post lands. The
+Gemini conversation doesn't see the final result — the user has to come
+back to Gemini and re-confirm.
+
+**UX gap.** No way to communicate the eventual outcome back to Gemini's
+chat. Acceptable for v1.
+
+#### Option B — refuse write verbs when the signer is NIP-55
+
+Throw `AppFunctionNotSupportedException` immediately. User configures a
+different signer (local or NIP-46) to enable Gemini-driven writes.
+Simpler, cleaner, but limits the audience — many Amethyst users on
+Amber would lose the feature.
+
+**Recommendation:** start with Option B, ship Internal + Remote support,
+then add Option A behind a feature flag in a follow-up. Option B
+unblocks the feature for ~70% of users today; Option A is more work
+and has the unresolved "result doesn't get back to Gemini" wrinkle.
+
+## Per-write-verb concerns
+
+### postNote(text)
+- Internal: sign → publish to outbox. Done.
+- Remote: sign (suspends) → publish. Done.
+- External: throw NotSupported, or PendingIntent dance.
+- Side concern: should this go into the user's drafts vs immediately
+  publish? Gemini-issued posts feel like they should publish (the
+  user asked for it), but a "review before post" screen via PendingIntent
+  is a nice safety net even for the local-signer path.
+
+### follow(npub) / unfollow(npub)
+- Same signer paths as postNote, simpler payload.
+- Reads the current kind:3, modifies, signs, publishes — `FollowActions`
+  is ready.
+- **No** "preview" step needed — follow/unfollow is reversible.
+
+### sendDm(recipient, text)
+- Same signer paths.
+- `DmActions.buildTextDm` is ready, plus `resolveDmRelays`.
+- **Concern**: strict mode (default) refuses to send when recipient has
+  no kind:10050. Should Gemini's `sendDm` default to strict or
+  permissive? Argument for strict: it's NIP-17 spec behavior. Argument
+  for permissive: Gemini users won't know what kind:10050 is and will
+  see confusing failures. **Lean: permissive by default**, surface the
+  source in the result.
+
+### zapUser(npub, sats, comment?)
+- Same signer paths for the kind:9734 zap request.
+- But there's a *second* signing-like step: an LN payment via NWC
+  (if configured). NWC has its own permission model and can also fail.
+- For v1: build the zap request, fetch the BOLT11 invoice, return the
+  invoice in the result. User pays via their wallet. Skip NWC
+  auto-payment.
+
+### zapEvent(eventId, sats, comment?)
+- Same as zapUser but uses `ZapActions.buildEventZapRequestsForSplits`
+  so multi-party notes route correctly.
+- May return multiple invoices (one per split recipient).
+
+## Account selection
+
+All verbs read `Amethyst.instance.sessionManager.loggedInAccount()` once
+at entry. **Multi-account question**: should Gemini be able to specify
+*which* account to act as? Two answers:
+
+- v1: no — always act as the currently-active account. Matches what the
+  user sees in the foreground UI. Simpler.
+- Later: add an optional `accountNpub: String?` parameter to each write
+  verb. Defaults to the active account.
+
+Start with v1.
+
+## Permissions surfaced to Gemini
+
+The App Functions schema XML (auto-generated by KSP) lists each verb
+plus its parameters. Gemini's tool picker shows these to the user. We
+should add a `description` (via `isDescribedByKDoc = true`, which we
+already do) that makes write verbs sound consequential — "Publishes a
+note to your Nostr followers", not "Calls postNote".
+
+## Open questions for an experiment day
+
+1. What concrete `Bundle` keys does the system shell respect on
+   `AppFunctionPermissionRequiredException`? Run a tiny test app, throw
+   the exception with various bundle contents, observe what Gemini
+   surfaces.
+2. Can the user approve a Gemini-issued write from within the Gemini
+   chat (inline confirmation) or only by opening Amethyst? Affects
+   Option A's UX.
+3. Does `INostrClient.publish(...)` actually queue when the relay
+   pool is disconnected, or does it return immediately with no
+   delivery? Determines whether the verb needs an explicit
+   "wait for at least one OK" gate.
+4. NWC and Gemini: if the user has a NWC wallet configured, should
+   `zapUser` auto-pay? Adds another consent layer.
+
+## Minimum viable first write verb
+
+Pick **`postNote(text)`** as the pilot.
+
+Why:
+- Simplest: one signed event, one publish, one ack.
+- Read-back is straightforward: return the event id + the relays it
+  landed on. Gemini can compose "Posted! Here's the link: nostr:nevent…".
+- Failure modes are well-bounded (signer error, no outbox relays, all
+  relays rejected).
+- No multi-party complexity (zap splits, DM strict mode).
+
+Scope of the pilot:
+- `NostrSignerInternal` only (Option B for NIP-55, Remote in a
+  follow-up). Document the cutoff in kdoc.
+- Returns `PostNoteResult(eventId, publishedTo, rejectedBy)` — an
+  `@AppFunctionSerializable`.
+- Builds on the existing `commons/.../quartz/.../TextNoteEvent.build`
+  and `client.publish` — no new actions needed.
+- ~50 lines of new code in `AmethystAppFunctions.kt`, plus the result
+  class.
+
+Once shipped, follow-ups in order:
+1. `follow(npub)` / `unfollow(npub)` — same signer caveat.
+2. NIP-46 (Remote) signer support — change the gate from "signer is
+   internal" to "signer can sign in-process".
+3. `sendDm(recipient, text)` — first write verb that uses encryption.
+4. `zapUser` / `zapEvent` — non-trivial because of LN flow.
+5. NIP-55 support via PendingIntent (Option A) once the system-shell
+   contract is understood.
+
+No write-verb code lands until question (1) above is answered —
+otherwise the NIP-55 path is undefined and we ship something that
+"sort of works" for half our users.

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

@@ -0,0 +1,131 @@
+# Verifying Gemini-side AppFunctions discovery
+
+**Date:** 2026-05-26
+**Status:** Active — answers the open question from
+`2026-05-25-appfunctions-signer-prompts.md`
+
+The Phase 2 work proves the app side: 21 `@AppFunction` verbs are
+registered, indexed by `AppFunctionManagerService`, and dispatchable
+via `adb shell cmd app_function execute-app-function`. The remaining
+unknown is whether **Gemini's chat UI** actually surfaces our verbs to
+the user — that's a separate layer (model-side tool picker) we can't
+exercise from the test command.
+
+## What we know
+
+* **Library state.** Built against `androidx.appfunctions
+  1.0.0-alpha09`. Schemas (`@AppFunctionSchemaDefinition`) are
+  optional and the official Google sample (`android/appfunctions`
+  ChatApp) doesn't use them — meaning we're not at a structural
+  disadvantage by not defining our own. There's no canonical
+  `nostr.social` schema registry yet.
+* **Discovery strategy.** Without schemas, Gemini's tool picker
+  matches on the function's natural-language description (KDoc, via
+  `@AppFunction(isDescribedByKDoc = true)`) and the parameter
+  descriptions. We've reworked every verb's first sentence to be a
+  use-when imperative — "Find a person on Nostr by name…" — instead
+  of an implementation description ("Searches kind:0 metadata…").
+
+## What we don't know yet
+
+* Whether Gemini's model picks up our verbs at all from a typical
+  user query.
+* Whether Gemini's `AppFunctionSearchSpec` filters by
+  `schemaCategory` / `schemaName` (in which case we're invisible
+  until we annotate) or by description (in which case we should
+  surface).
+* What feature flags / Gemini-app versions are required. App
+  Functions is generally available on Android 16+, but Gemini's
+  third-party tool picker has shipped in waves.
+
+## Verification protocol
+
+### 1. Confirm the device is set up
+
+```bash
+# Pixel 8 or newer on Android 16 QPR1+
+adb shell getprop ro.build.version.release
+adb shell pm list packages | grep -i gemini   # com.google.android.apps.bard
+```
+
+### 2. Reinstall the Play debug APK with the new descriptions
+
+```bash
+./gradlew :amethyst:assemblePlayDebug
+adb install -r amethyst/build/outputs/apk/play/debug/amethyst-play-universal-debug.apk
+adb shell am start -n com.vitorpamplona.amethyst.debug/com.vitorpamplona.amethyst.ui.MainActivity
+# sign in if needed, give Amethyst a few seconds to register
+```
+
+### 3. Confirm metadata is indexed end-to-end
+
+```bash
+adb shell cmd app_function list-app-functions | grep -c amethyst
+# should print ≥ 21 — one entry per @AppFunction across our class
+```
+
+### 4. Test prompts in Gemini
+
+These are deliberately mapped to one specific verb each. Run them in
+order, take notes on which surface a tool call and which don't.
+
+| Prompt to Gemini | Should pick |
+|---|---|
+| "Find vitorpamplona on Nostr" | searchProfiles |
+| "What's happening on Nostr today?" | getRecentFromFollows |
+| "Who am I logged in as on Nostr?" | getActiveAccountInfo |
+| "Did anyone DM me on Nostr recently?" | getRecentDms |
+| "How many sats did I earn on Nostr this week?" | getZapsReceived |
+| "Show me Nostr posts about bitcoin" | searchByHashtag |
+| "Tell me about npub1xq5eqwlhxy3ldakahsfglccvzy4j6ayyxje5a92zu90hc05dxn7qrsns90" | getProfile |
+| "What are people I follow saying on Nostr?" | getRecentFromFollows |
+| "Catch me up on what Snowden's been posting" | getNotesByUser |
+
+For each: did Gemini offer to call the tool? Did it call the right
+one? Did it render the result?
+
+### 5. Diagnose any miss
+
+If Gemini doesn't surface a verb:
+
+1. **Check Gemini's tools view.** In the Gemini app:
+   Settings → Apps. Our package should appear in the list of apps
+   the assistant can interact with. If it's not there at all, the
+   system hasn't told Gemini about us yet — wait a few minutes after
+   install or force-reindex by clearing AppSearch.
+2. **Force a re-index.**
+   ```bash
+   adb shell pm clear --user 0 com.android.appsearch || true
+   adb shell am force-stop com.vitorpamplona.amethyst.debug
+   adb shell am start -n com.vitorpamplona.amethyst.debug/com.vitorpamplona.amethyst.ui.MainActivity
+   ```
+3. **Verify per-prompt.** If the package is listed but a specific
+   prompt doesn't trigger a tool call, the issue is description
+   matching — our use-when phrasing isn't catching that query.
+   Adjust the kdoc and rebuild.
+
+## When schemas become worth doing
+
+We'll move from "skipped" to "implement" if:
+
+1. Step 4 above shows Gemini consistently fails to surface verbs that
+   should obviously match (suggesting it's filtering by schema, not
+   description), OR
+2. Another Nostr Android client ships AppFunctions and wants to
+   co-implement a shared schema namespace (so a Nostr-aware agent
+   could route to whichever client is installed).
+
+Until either of those happens, the simpler description-matching path
+is in place and is what every public AppFunctions sample uses today.
+
+## Open follow-ups (independent of this verification)
+
+* NIP-55 (Amber) signer support — write verbs currently refuse with
+  `AppFunctionNotSupportedException` because we can't launch Amber's
+  approval activity from a background dispatch. The PendingIntent
+  escape hatch (Option A in the signer-prompt plan) is the next move
+  if NIP-55 usage matters.
+* NWC auto-pay for `zapUser` / `zapEvent` — today we return the
+  BOLT11 invoice; the caller pastes it into a wallet. With NWC
+  configured we could pay automatically.
+* Schema definitions if step 4 above shows we need them.

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

@@ -0,0 +1,191 @@
+# All Amethyst screens as AppFunctions / MCP endpoints
+
+**Date:** 2026-05-26
+**Status:** Active — informs the v1 read-verb surface and guides
+future MCP work
+
+## The principle
+
+Every screen in Amethyst has a dedicated `FeedContentState` driven by
+a `*FeedFilter` that reads from `LocalCache`. The list is in
+`amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/AccountFeedContentStates.kt`
+— there are ~30 entries today.
+
+> Every Amethyst screen → one AppFunction verb. The verb invokes the
+> same `*FeedFilter` the screen uses, runs `feed()` against
+> `LocalCache`, and projects the result into a Gemini-friendly
+> `NoteHit` / `ProfileHit` / etc.
+
+This keeps the agent surface in sync with what the user sees, with no
+duplicate filtering logic.
+
+## Why this works
+
+* `*FeedFilter.feed()` is stateless and idempotent — it reads
+  `LocalCache` (a global singleton) and `account` state. Safe to
+  invoke from any thread, any process state, no UI lifecycle
+  required.
+* `AccountFeedContentStates` itself is owned by `AccountViewModel`,
+  but we don't need the precached state — we just need the filter
+  class. Invoking it on each AppFunction call is acceptable (a few
+  ms even on large caches).
+* The catch: `LocalCache` only contains what the foreground app
+  subscriptions have already fetched. If the user hasn't opened
+  Amethyst in days, the cache may be sparse. Acceptable trade-off:
+  the agent reflects "what's on your screen now", not "what exists
+  on Nostr right now". For freshness, the user can open the app or
+  the verb can fall back to a relay drain.
+
+## Existing verb → feed mapping
+
+| AppFunction verb | Feed source | Notes |
+|---|---|---|
+| `getFeedDigest` | `HomeNewThreadFeedFilter` | Matches the home page (new threads only, all kinds, mute-filtered) |
+| `getRecentFromFollows` | direct `INostrClient.fetchAll` (kind:1 only) | Pure kind:1 from kind:3 follows. Different shape than home — keeping both: `getRecentFromFollows` is fast / always fresh, `getFeedDigest` is "what's on my screen" |
+| `getMyMentions` | direct relay drain | Could move to `NotificationFeedFilter` |
+| `getRecentDms` | direct relay drain + decrypt | Could move to `ChatroomListKnownFeedFilter` / `ChatroomListNewFeedFilter` |
+| `getLiveStreams` | direct relay drain | Could move to `LiveStreamsFeedFilter` |
+| `searchArticles` | direct relay drain (NIP-50) | Read-side only; users already in cache via `ArticlesFeedFilter` could be merged |
+
+## Unmapped feeds (proposed verbs)
+
+These all have existing `FeedContentState`s. Adding a verb each is
+~30 lines of glue.
+
+| Screen | FeedContentState | Proposed verb name | User intent |
+|---|---|---|---|
+| Home — replies | `homeReplies` | `getRecentReplies` | "what conversations am I in?" |
+| Home — everything | `homeEverything` | `getEverythingFeed` | "the full firehose of my follows" |
+| Home — live | `homeLive` | `getLiveActivityFromFollows` | "what's live from my follows?" |
+| Video | `videoFeed` | `getVideoFeed` | "show me Nostr videos" |
+| Pictures | `picturesFeed` | `getPictureFeed` | "what photos are people posting?" |
+| Shorts | `shortsFeed` | `getShortVideoFeed` | NIP-71 short video |
+| Long-form (your follows) | `longsFeed` | `getLongFormFromFollows` | "what articles are my follows publishing?" |
+| Long-form (discover) | `discoverReads` | `discoverArticles` | "find interesting Nostr articles" |
+| Marketplace | `discoverMarketplace` | `discoverMarketplaceListings` | "what's for sale on Nostr?" |
+| Communities (discover) | `discoverCommunities` | `discoverCommunities` | "find Nostr communities" |
+| Communities (list) | `communitiesList` | `getMyCommunities` | "communities I'm a member of" |
+| Public chats (discover) | `discoverPublicChats` | `discoverPublicChats` | "find Nostr chat channels" |
+| Public chats (list) | `publicChatsFeed` | `getMyPublicChats` | "chats I'm in" |
+| DVMs | `discoverDVMs` | `discoverDvms` | "what compute services are available?" |
+| Follow sets | `discoverFollowSets` | `discoverFollowSets` | "find curated follow lists" |
+| Live streams | `liveStreamsFeed` | (replace `getLiveStreams`) | already exists |
+| Nests | `nestsFeed` | `getNests` | "audio rooms" |
+| Articles (mine + follows) | `articlesFeed` | `getMyArticles` | combined long-form |
+| Polls (open) | `openPollsFeed` | `getOpenPolls` | "what should I vote on?" |
+| Polls (closed) | `closedPollsFeed` | `getRecentPollResults` | "what did people vote on?" |
+| All polls | `pollsFeed` | (combined; less useful as a verb) | — |
+| Badges | `badgesFeed` | `getBadges` | "show me my Nostr badges" |
+| Software apps | `softwareAppsFeed` | `discoverNostrApps` | "what apps exist on Nostr?" |
+| Emoji packs | `browseEmojiSetsFeed` | `discoverEmojiPacks` | "find custom emoji" |
+| Follow packs | `followPacksFeed` | `discoverFollowPacks` | "find people to follow by topic" |
+| Products | `productsFeed` | `getProductListings` | "what products are listed?" |
+| Calendar appointments | `calendarAppointmentsFeed` | `getUpcomingEvents` | "what Nostr events are coming up?" |
+| Calendar collections | `calendarCollectionsFeed` | `getEventCollections` | "what conferences are happening?" |
+| Notifications (all) | `notifications` | `getRecentNotifications` | "what's happened to me on Nostr?" |
+| Notifications (follows) | `notificationsFollowing` | (variant param) | "notifications from follows" |
+| Notifications (everyone) | `notificationsEveryone` | (variant param) | "all notifications" |
+| Drafts | `drafts` | `getMyDrafts` | "what did I start writing?" |
+| Web bookmarks | `webBookmarks` | `getMyBookmarks` | "what did I bookmark?" |
+
+That's ~25 unmapped feeds. Each verb is a ~30-line wrapper following
+the `getFeedDigest` shape — read filter, project to result type,
+return.
+
+## Implementation pattern
+
+```kotlin
+@AppFunction(isDescribedByKDoc = true)
+suspend fun getMyBookmarks(
+    appFunctionContext: AppFunctionContext,
+    hoursBack: Int = 168,
+    maxNotes: Int = 50,
+): SearchNotesResult {
+    val account = Amethyst.instance.sessionManager.loggedInAccount()
+        ?: return SearchNotesResult.empty()
+    val sinceSecs = TimeUtils.now() - hoursBack.coerceIn(1, 24 * 365).toLong() * 3600L
+
+    val feed = WebBookmarkFeedFilter(account).feed()
+        .asSequence()
+        .mapNotNull { it.event }
+        .filter { it.createdAt >= sinceSecs }
+        .sortedByDescending { it.createdAt }
+        .take(maxNotes.coerceIn(1, 200))
+        .map { it.toFeedNoteHit() }
+        .toList()
+
+    return SearchNotesResult(matches = feed)
+}
+```
+
+The pattern is genuinely uniform. Most verbs would even share a
+helper like `feedAsResult(filter, sinceHours, max) -> SearchNotesResult`.
+
+## Result-type strategy
+
+Most feeds project to `SearchNotesResult` since the screen is "a list
+of notes." A few need bespoke types:
+* Notifications — could return a `NotificationHit` carrying the
+  notification kind (reply, mention, zap, repost, reaction) since
+  the LLM needs to know "you got 3 zaps and 1 reply".
+* Calendar events — natural fit for an `EventHit` with start/end
+  times.
+* Communities / public chats — list-of-rooms more than list-of-notes.
+
+Default to reusing `NoteHit` (now carries `kind`); add bespoke types
+only when the LLM needs structure the LLM can't derive from `kind` +
+`content`.
+
+## What doesn't fit cleanly
+
+Some screens are too interactive for a single AppFunction call:
+* **Chats / DMs** — sending and reading a stream of messages is
+  more conversational; the agent loop should handle it. `sendDm` +
+  `getRecentDms` cover the basics.
+* **Profile pages** — already covered by `getProfile` +
+  `getNotesByUser` rather than a "profile feed."
+* **Settings screens** — out of scope; the agent shouldn't mutate
+  user prefs.
+
+## When the cache is cold
+
+For verbs backed by `LocalCache` (the screens), the result is sparse
+when the user hasn't opened the app recently. The mitigation strategy
+is:
+
+1. The relay-drain verbs (`searchProfiles`, `searchNotes`,
+   `searchByHashtag`, `searchArticles`, `getRecentFromFollows`,
+   `getNotesByUser`, `getProfile`, `getRecentDms`,
+   `getZapsReceived`, `getLiveStreams`) all do their own fetch.
+   Use these when freshness matters.
+2. The screen-mirror verbs (`getFeedDigest` and the proposed
+   additions) reflect what the foreground saw. Use these when
+   "what was the user looking at?" is the semantic.
+
+Both shapes have value. The agent's prompt-matching kdoc decides
+which gets called.
+
+## MCP angle
+
+When we add an MCP server for Amethyst (separate effort), the same
+`*FeedFilter.feed()` calls power the MCP tool implementations. The
+AppFunctions adapter and the MCP server share the projection
+helpers (`toFeedNoteHit`, `toProfileHit`, etc.) and the result
+types. The transport layer is the only difference.
+
+The screen-feed mapping above is the source of truth for both
+surfaces.
+
+## Concrete next steps
+
+Highest user-value follow-ups (each ~30 min):
+
+1. `getRecentNotifications` — answers "what's been happening to me
+   on Nostr?" without a per-kind walk.
+2. `getMyBookmarks` — agent recall over saved Nostr content.
+3. `getOpenPolls` — "what should I vote on?"
+4. `getMyDrafts` — "what was I writing?"
+5. `getUpcomingEvents` — calendar / agenda integration.
+
+After these, the rest are mostly "discover X" variants that follow
+the same template.

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

@@ -0,0 +1,314 @@
+# AVIF support — comprehensive design
+
+**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)
+**Author:** davotoula
+**Manual test plan:** `~/docs/amethyst/2026-05-26-avif-manual-test-plan.md`
+
+---
+
+## 1. Goal
+
+Make AVIF (still and animated) a first-class image format in Amethyst, working on every surface where any other image format works — uploads, feeds, profiles, DMs, emoji packs, reactions, gallery, caching — with a graceful no-crash fallback on Android API < 31 where the platform decoder cannot handle AVIF at all.
+
+This is **not** a minimum-merge or bounty-targeted effort. The goal is a full solution.
+
+---
+
+## 2. Context
+
+### 2.1 What works today on `main`
+
+AVIF is **already partially supported**:
+
+- `commons/.../richtext/RichTextParser.kt` recognizes `.avif` extension and `image/avif` MIME — links in note text render as image embeds.
+- `amethyst/.../video/datasource/FeedBasis.kt` includes `image/avif` in `SUPPORTED_VIDEO_FEED_MIME_TYPES` — AVIF posts are eligible for the media feed.
+- `commons/.../jvmMain/.../upload/MediaMetadata.kt` maps the `.avif` extension to `image/avif`.
+- Desktop file pickers (`DesktopFilePicker.kt`, `ComposeNoteDialog.kt`, `ChatPane.kt`) accept `.avif`.
+- `amethyst/.../service/images/ImageLoaderSetup.kt` registers `coil3.gif.AnimatedImageDecoder.Factory()`. On Android **API 31+** this routes through the platform `ImageDecoder`, which supports both still and animated AVIF natively.
+
+Net: on Android 12+, display of still and animated AVIF should mostly already work via Coil. The original issue author may not realize this.
+
+### 2.2 What's broken today
+
+The upload pipeline does not know about AVIF:
+
+- `amethyst/src/main/java/.../service/uploads/MediaCompressor.kt::compressImage()` re-encodes every non-GIF/SVG image as `Bitmap.CompressFormat.JPEG` at 640 px width. An uploaded animated AVIF is **destroyed** — flattened to a single JPEG frame.
+- `amethyst/src/main/java/.../service/uploads/MetadataStripper.kt` uses `ExifInterface` to rewrite metadata. `ExifInterface` does not reliably handle AVIF containers, so AVIFs either fail or are corrupted.
+- `amethyst/src/main/java/.../service/uploads/PreviewMetadataCalculator.kt` uses `BitmapFactory.decodeStream` / `decodeByteArray`. **`BitmapFactory` does not support AVIF on any Android version.** Result: AVIFs upload with no blurhash, no thumbhash, no dimensions — receivers see a blank placeholder until the full image downloads.
+- `amethyst/src/main/java/.../service/uploads/nip96/Nip96Uploader.kt` falls back to a no-extension multipart filename when `MimeTypeMap` is silent (which it can be for AVIF on older Android). Some NIP-96 servers reject extension-less uploads.
+
+### 2.3 Prior work
+
+Four PRs were opened against #837 and all closed without merge:
+
+| PR | Author | Verdict |
+|---|---|---|
+| #2825 | KingParmenides | Added a parallel `AnimatedUrlImage` composable that bypassed loading/thumbhash/blurhash slots. Vitor: "delivered very little." **Discard.** |
+| #3008 | alan747271363-art | Narrow MediaCompressor + MetadataStripper skip. No on-device test. |
+| #3010 | ProtonsAndElectrons | Skip compression + ImageDecoder previews + AVIF EXIF inspection + `.avif` filename fallback. Emulator boot only. |
+| #3016 | cybercraftsolutionsllc | Same as #3010 plus `image/avif-sequence` MIME (not real) and an instrumented test. Closed because contributor never did a manual signed-in upload via the UI. |
+
+All upload-pipeline PRs converged on roughly the same fix. They were rejected for **lack of manual on-device verification**, not for being wrong. We will draw inspiration from #3016's diff structure but write the production code from scratch on current main.
+
+### 2.4 Inbound branches that could matter later
+
+Four Claude-Code experimental branches exist but have **no PR opened**, so they are not on any merge path today:
+
+- `upstream/claude/amethyst-kmp-conversion-zYNmg` — would move `amethyst/src/main/` → `amethyst/src/androidMain/`. If this lands later, all file paths in this spec need a search-and-replace.
+- `upstream/claude/add-crop-trim-uploads-RuQBe` — would add UCrop image crop + media3-transformer video trim before upload. If it lands, a new AVIF surface decision is needed: UCrop almost certainly does not handle AVIF input.
+- `origin/claude/fix-video-deletion-timing-LGFn4` — introduces `TempFileTracker` in `UploadOrchestrator`. If it lands, the AVIF passthrough (`MediaCompressorResult(uri, contentType, null)`) needs reverification against the new lifecycle.
+
+None of these are scheduled. Re-check them at PR-ready time.
+
+---
+
+## 3. Architecture and guiding principle
+
+**AVIF is not a new subsystem.** It is the act of making AVIF behave like animated WebP everywhere. The right mental model: find every place WebP/GIF gets special-cased and make sure AVIF lands in the same branch.
+
+Production code change: small (estimated ~150–250 LoC, ~5 files).
+Verification surface: large — see §5 for the ~12 display surfaces; each is exercised against {still, animated} × {API 31+, API < 31}, against two upload protocols (Blossom and NIP-96). The full row count in the manual test plan is 50.
+
+**Explicit non-goals:**
+
+- Shipping a JNI libavif decoder for API < 31. Too much APK weight (~3 MB) for too little gain. API < 31 gets graceful placeholder behavior (existing Coil error slot), documented as a known limitation.
+- Adding new composables. PR #2825 made that mistake. Existing `MyAsyncImage` / `RobohashAsyncImage` / `ZoomableContentView` / `AsyncImage` paths must handle AVIF unchanged.
+- Supporting `image/avif-sequence`. Not IANA-registered. RFC 9081 defines `image/avif` for both still and animated.
+
+---
+
+## 4. Upload-pipeline changes (Android, `amethyst/`)
+
+Concrete file-level diff. All paths verified against current main on branch `feat/avif-support`.
+
+| File | Change |
+|---|---|
+| `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/MediaMimeTypes.kt` *(new)* | Centralize AVIF MIME helpers: `isAvif(contentType: String?): Boolean`, `const val AVIF_MIME = "image/avif"`, `const val AVIF_EXTENSION = "avif"`. Keep the four consumer files below honest. |
+| `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/MediaCompressor.kt` | In `compressImage()`, branch early on `isAvif(contentType)`: return `MediaCompressorResult(uri, contentType, null)` — same pattern SVG already follows. Verify SVG branch as the reference pattern. |
+| `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/MetadataStripper.kt` | For AVIF: inspect EXIF via `ExifInterface(stream)`. If no sensitive tags → pass through unchanged. If sensitive tags found OR inspection fails for any reason → **fail closed** (reject upload, surface error to user). Do not attempt to rewrite the AVIF container. |
+| `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/PreviewMetadataCalculator.kt` | For AVIF on API ≥ 28, decode via `ImageDecoder.createSource(...).decodeBitmap()`. For animated AVIF this returns the first frame — which is exactly what we want for static hashes. Use the same decoded bitmap to compute blurhash + thumbhash + dimensions. On API < 28, skip preview metadata (return nulls, log warning). The "decoded once, both hashes computed from same pixels" invariant in the existing code is preserved. |
+| `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/nip96/Nip96Uploader.kt` | When `MimeTypeMap` returns null for the AVIF content type, fall back to `.avif` (or `AVIF_EXTENSION` from `MediaMimeTypes`) for the multipart filename. |
+| `amethyst/src/main/java/com/vitorpamplona/amethyst/service/uploads/blossom/...` | Same filename fallback if the Blossom uploader has equivalent logic. Inspect first; may be no-op. |
+
+### 4.1 Cross-references for sanity
+
+The same `MediaMimeTypes.isAvif(...)` helper should also be used by the existing `RichTextParser.kt` and `FeedBasis.kt` if practical — but only as a follow-up cleanup, not as part of this change. Adding it now creates churn that's hard to review.
+
+---
+
+## 5. Display surface
+
+### 5.1 Expected zero-code-change surfaces (verify only)
+
+These should work today on API 31+ through Coil's `AnimatedImageDecoder.Factory()`. Verification only:
+
+- Note body images via `MyAsyncImage` / `ZoomableContentView`.
+- Profile pictures via `RobohashAsyncImage` (`AnimatedImageDrawable` should route through).
+- Profile banner.
+- DM images.
+- Profile media tab / gallery.
+- Long-form (NIP-23) post body.
+- Compose preview thumbnail.
+- Emoji pack image rendering (`Emoji.kt`, `ShowEmojiSuggestionList.kt`, `EmojiPackCard.kt`, `EmojiPackScreen.kt`).
+- Emoji suggestion popup.
+- Custom emoji inline in note text.
+- Custom emoji as a reaction.
+
+If any of these fail on a real device, the fix is in `ImageLoaderSetup.kt` configuration, not in adding new composables.
+
+### 5.2 Coil decoder factory order
+
+In `amethyst/src/main/java/.../service/images/ImageLoaderSetup.kt`, `AnimatedImageDecoder.Factory()` must run **before** `GifDecoder.Factory()` so AVIFs aren't accidentally routed to the GIF decoder. Verify the current order matches.
+
+### 5.3 Desktop (`desktopApp/`)
+
+Desktop uses Coil-JVM which does **not** include `AnimatedImageDecoder` (no platform `ImageDecoder` outside Android). Animated AVIF on Desktop will likely show first-frame only. Still AVIF: unknown — may require additional Coil decoder. **Verify, then document as known limitation if confirmed.** Do not add JVM libavif binding in this PR.
+
+---
+
+## 6. Animation lifecycle (pause off-screen, resume on-screen)
+
+PR #2825 attempted this for AVIF and broke loading/blurhash slots in the process. The correct approach: discover the **existing** pause/resume mechanism for animated WebP and ensure AVIF lands in the same branch.
+
+### 6.1 Verification step (before any code change)
+
+1. Locate the pause/resume mechanism. Likely candidates: `MyAsyncImage`, `ZoomableContentView`, `GifVideoView`, or a `DisposableEffect` on visibility that calls `AnimatedImageDrawable.start()` / `stop()`.
+2. Check the predicate:
+   - **If it branches on `drawable is AnimatedImageDrawable`** → MIME-agnostic, AVIF works for free, **zero code change**.
+   - **If it branches on a hardcoded MIME list** (e.g. `setOf("image/gif", "image/webp")`) → add `"image/avif"`.
+3. Same audit for the emoji composables modified by PR #2825 (`Emoji.kt`, `ShowEmojiSuggestionList.kt`, `EmojiPackCard.kt`, `EmojiPackScreen.kt`).
+
+### 6.2 Hard constraint
+
+**Do not introduce a parallel `AnimatedUrlImage` composable.** That was PR #2825's mistake and the reason it was closed. Any new abstraction must be additive to existing composables, not a replacement.
+
+---
+
+## 7. Caching
+
+Coil 3's `ImageLoader` (configured in `ImageLoaderSetup.kt`) caches in two layers: memory (bitmaps) and disk (raw bytes). Both are URL-keyed, format-agnostic.
+
+**Expected: zero code change.** Verification:
+
+- First load of an AVIF URL downloads; second load hits memory cache (no network).
+- Background → return → load hits disk cache; no network.
+- Force-stop → relaunch → load hits disk cache; no network.
+- Confirm Coil's memory budget accounts for animated AVIF frame buffers (an animated AVIF avatar can be 5–15 MB decoded). If thrashing observed, adjust `ImageLoader.Builder.memoryCache { ... }` in `ImageLoaderSetup.kt`.
+- Confirm the disk cache survives app restart (`coil_image_cache` under app cache dir).
+- For animated AVIF in scroll-heavy feeds: confirm Coil doesn't decode every frame from disk on every scroll-into-view. If it does, that's a Coil-level concern and may require either a feature request to Coil or a workaround in the composable (cache the drawable, not just the bytes).
+
+---
+
+## 8. Pre-API-31 fallback
+
+Amethyst's `minSdk = 26`. Five API levels (26–30) have **no platform AVIF support at all**.
+
+**Decision: accept Coil's existing error slot.** AVIF fails to decode → Coil falls through to its built-in error placeholder (broken-image icon, same UX as a 404). Avatar surfaces fall back to the existing robohash placeholder. No new strings, no new dialogs, no JNI libavif.
+
+Document in PR description and §11 below.
+
+---
+
+## 9. Testing & hardening
+
+### 9.1 Three layers
+
+**Layer 1 — JVM unit tests** (in `amethyst/src/test/`):
+
+- `MediaCompressorTest`: AVIF URI returns unchanged; MIME preserved; not converted to JPEG.
+- `MetadataStripperTest`: clean AVIF passes; AVIF with synthetic GPS EXIF rejected; AVIF that ExifInterface can't parse → fails closed.
+- `PreviewMetadataCalculatorTest`: AVIF input via a fake `ImageDecoder.Source` → blurhash + thumbhash + dimensions returned (or skipped on API < 28 with no crash).
+- `Nip96UploaderTest` (or equivalent): filename fallback to `.avif` when `MimeTypeMap` is silent.
+
+Runs via the standard pre-push hook scope: `:amethyst:testPlayDebugUnitTest`.
+
+**Layer 2 — Android instrumented tests** (in `amethyst/src/androidTest/`):
+
+- `AvifUploadPipelineInstrumentedTest`: generate an 8×8 still AVIF in app cache, drive it through `MediaCompressor` → `MetadataStripper` → `PreviewMetadataCalculator` → `Nip96Uploader` filename helper. Assert: bytes preserved, blurhash + thumbhash non-null, no JPEG output.
+- `AvifAnimatedDecodeInstrumentedTest`: tiny 8×8 / 3-frame animated AVIF, assert Coil's `ImageLoader.execute()` returns an `AnimatedImageDrawable` with `numberOfFrames > 1`.
+- Run on at least two emulators: API 35 (modern path) and API 28 (pre-API-31 path), to confirm both code branches are exercised.
+
+**Layer 3 — Manual on-device verification.** This is the gate that killed prior PRs.
+
+See **`~/docs/amethyst/2026-05-26-avif-manual-test-plan.md`** for the full 50-row checklist covering:
+
+- §2.1 Compose / upload flow (8 rows)
+- §2.2 Display in feeds / notes (6 rows)
+- §2.3 Profile pictures and banner (6 rows)
+- §2.4 Direct messages (3 rows)
+- §2.5 Emoji packs / NIP-30 — the original use case (8 rows)
+- §2.6 Caching (5 rows)
+- §3.1–3.5 Hardening (corrupted, large, EXIF, API < 31, animation lifecycle)
+- §4 Desktop spot-check
+- §5 PR sign-off checklist
+
+### 9.2 Upload protocol matrix
+
+Each upload row of the manual checklist runs against **both**:
+
+- A Blossom server (e.g. `blossom.primal.net`).
+- A NIP-96 server (e.g. `nostr.build`).
+
+Bytes downloaded post-upload are binary-compared to the local source. Server-side transcoding (some NIP-96 servers do this) is documented as a server-side caveat, not a regression.
+
+### 9.3 Test asset corpus
+
+Generated via `avifenc` (libavif), `ffmpeg`, and `exiftool`:
+
+- `still-medium.avif` — 800×600 still
+- `animated-medium.avif` — animated from GIF source
+- `animated-tiny-3frames.avif` — 8×8, 3 frames (committed as test fixture)
+- `still-tiny-8x8.avif` — 8×8 still (committed as test fixture)
+- `emote-64.avif` — 64×64 animated, for the emoji-pack proof point
+- `still-with-gps.avif` — synthetic GPS EXIF for the hardening test
+- `corrupted.avif` — truncated for the decoder-failure test
+- `large-animated.avif` — >20 MB for OOM/ANR hardening
+
+Tiny fixtures committed under `amethyst/src/androidTest/assets/avif/`. Larger files referenced by local path in the manual checklist only.
+
+### Running the AVIF tests locally
+
+The AVIF test layer is **not wired into CI** — run it locally on an emulator before merging any
+AVIF-touching change. See `amethyst/plans/2026-05-27-avif-instrumented-tests-plan.md` for the
+full plan.
+
+**JVM unit tests** (no emulator needed):
+
+```bash
+./gradlew :amethyst:testPlayDebugUnitTest --tests 'com.vitorpamplona.amethyst.service.uploads.MediaMimeTypesTest'
+./gradlew :amethyst:testPlayDebugUnitTest --tests 'com.vitorpamplona.amethyst.service.images.ThumbnailDiskCacheAvifTest'
+```
+
+**Instrumented tests** (boot an API 31+ emulator first — API 35 recommended):
+
+```bash
+./gradlew :amethyst:connectedPlayDebugAndroidTest \
+  '-Pandroid.testInstrumentationRunnerArguments.package=com.vitorpamplona.amethyst.service.uploads'
+
+./gradlew :amethyst:connectedPlayDebugAndroidTest \
+  '-Pandroid.testInstrumentationRunnerArguments.package=com.vitorpamplona.amethyst.service.images'
+```
+
+**Regenerating fixtures** (only if you change the fixtures themselves):
+
+```bash
+brew install libavif ffmpeg exiftool   # one-time
+# See Task 1 in 2026-05-27-avif-instrumented-tests-plan.md for the full generation recipe.
+```
+
+---
+
+## 10. Headline proof artifact
+
+Per §2.5 of the manual test plan: generate `emote-64.avif`, upload via the app to a NIP-96 or Blossom server, build a NIP-30 emoji pack event (kind 30030) referencing it from the **Amethyst tester** account, attach to the account, compose a note using `:emote_name:`, react to a note with it. Record a 30-second screen capture.
+
+This becomes the headline artifact in the PR description — direct answer to RedNumber1's original ask ("animated AVIFs for my emotes").
+
+---
+
+## 11. Known limitations to document in the PR
+
+- **Android API < 31:** AVIF doesn't render — neither `AnimatedImageDecoder` (Android 8.0/API 26 doesn't have it) nor `BitmapFactory` can decode AVIF. Verified on API 26 emulator: posts containing AVIF URLs show the URL as a clickable link inline in the note body, no crash, no UI hang. When scrolling an AVIF post into view, Coil briefly renders the blurhash placeholder (via `BlurHashFetcher`) before the failed decode transitions to the link fallback — that's a small UX win, not a regression. Avatar slots fall back to robohash. No JNI libavif shipped.
+- **Android API < 31 picker:** the Android gallery picker greys AVIF out because `MediaStore` only recognises AVIF as a picker-supported image type from API 31+. This is an OS-level filter, not an Amethyst limitation. Workaround for users on older Android: use the **Files** (Storage Access Framework) picker root, which doesn't apply the MIME-handler filter. The upload pipeline itself is API-agnostic — bytes pushed via SAF would upload successfully even on API 26, but the resulting AVIF wouldn't render on the same device's feed for the reason above.
+- **Desktop (JVM):** Animated AVIF likely still-frame only. Upload works. Confirm with §4 of manual test plan and document.
+- **Desktop AVIF preview metadata:** `commons/src/jvmMain/.../MediaMetadata.kt` uses `javax.imageio.ImageIO.read(file)` which has no AVIF support in the standard JDK. Desktop-posted AVIF notes therefore ship without `blurhash`, `thumbhash`, or `dim` in the `imeta` tag. Bytes round-trip correctly; receivers on Android still decode and render the AVIF — only the loading-placeholder UX is degraded (blank slot until the network fetch completes instead of a blurhash blur and pre-allocated aspect-ratio box). Fixable later either by hand-parsing the ISOBMFF `ispe` box for dimensions, or by adding a JVM AVIF ImageIO plugin to `desktopApp`. Out of scope for this PR.
+- **Desktop AVIF display:** Coil-JVM has no AVIF decoder. Posts containing AVIF URLs show no image on Desktop (whether posted from Desktop or Android). Verified by spot-check: a 200x200 single-frame AVIF posted from Amethyst Desktop did not render in the Desktop client either. Android receivers display normally.
+- **NIP-96 server transcoding:** If a chosen NIP-96 server transcodes AVIF → JPEG/WebP server-side, that is outside Amethyst's control. PR description must name the servers tested and the observed behavior.
+- **`image/avif-sequence` MIME:** Intentionally rejected. RFC 9081 says `image/avif` covers both still and animated. PR #3016 introduced this; we don't.
+- **Coil-level frame re-decoding:** If observed under §7 verification, treat as a follow-up issue. Out of scope for this PR.
+- **Animated AVIF playback smoothness:** Frame advancement is driven by `android.graphics.drawable.AnimatedImageDrawable` (the platform decoder), not Amethyst code. On most Android devices including Pixel, the AV1 path is software-only (`dav1d`) — the hardware AV1 decoder is wired for video, not for `ImageDecoder`. Per-frame decode cost is orders of magnitude higher than GIF (LZW) or animated WebP (VP8). Expect lower effective frame rates for large source images at high frame counts. Mitigation is encoder-side: small dimensions, low fps, modest frame counts. Not a regression — animated AVIF could not render at all before this PR.
+- **Animated AVIF playback machinery:** Coil 3's bundled `AnimatedImageDecoder.Factory` only recognizes HEIF brands (msf1/hevc/hevx) at offset 8 and misses AVIF's `avis`/`avif`/`avo1` brands. We ship `AvifAnimatedDecoderFactory` to plug the gap and an upstream Coil fix is separate. Verified against Coil 3.4.0 and 3.5.0-beta01.
+- **Profile picture thumbnail cache:** `ThumbnailDiskCache` skips animated AVIF (`ftyp avis`) so the avatar always re-decodes through the AVIF path. Side effect: animated AVIF avatars don't benefit from the 256x256 JPEG thumbnail cache that other formats enjoy, costing some decode CPU per re-render. Acceptable trade-off vs. permanently freezing the avatar on its first frame.
+- **Strip-metadata toggle OFF on AVIF leaks EXIF:** the fail-closed AVIF inspector only runs when the user has strip-metadata enabled (the default). If the user toggles strip-metadata off, AVIF is uploaded as-is — including any GPS / device-serial / datetime EXIF tags it carries. This matches the existing behavior for JPEG/PNG (the toggle universally means "trust me, upload as-is") but is worth knowing: AVIF cannot be safely stripped in-place, so toggle-off is the only way to upload an AVIF whose EXIF the user wants preserved. Users who want privacy guarantees should leave the toggle on.
+
+---
+
+## 12. Implementation sequence (rough)
+
+To be expanded by `writing-plans` into a step-by-step plan. High-level:
+
+1. Branch `feat/avif-support` (done — based on `d1610bf97`).
+2. Add `MediaMimeTypes.kt` (new file, helpers only).
+3. Patch `MediaCompressor.kt` (early return for AVIF).
+4. Patch `MetadataStripper.kt` (fail-closed EXIF inspection).
+5. Patch `PreviewMetadataCalculator.kt` (`ImageDecoder` for AVIF on API ≥ 28).
+6. Patch `Nip96Uploader.kt` (and Blossom uploader if applicable) for filename fallback.
+7. JVM unit tests for steps 2–6.
+8. Audit animation-lifecycle code paths (§6.1) — patch or skip per findings.
+9. Generate test corpus, commit tiny fixtures.
+10. Write `AvifUploadPipelineInstrumentedTest`, `AvifAnimatedDecodeInstrumentedTest`. Run on API 35 + API 28 emulators.
+11. Manual on-device verification per `~/docs/amethyst/2026-05-26-avif-manual-test-plan.md`.
+12. Record §10 proof artifact.
+13. `./gradlew spotlessApply`, run pre-push hook scope, push, open PR with checklist + recording.
+
+---
+
+## 13. Out of scope
+
+- iOS AVIF support (`iosMain/`) — there is iOS work in flight on a separate branch; coordinate later.
+- Server-side AVIF transcoding tooling. Server choice belongs to the user.
+- JNI libavif for API < 31.
+- New abstractions or composables.
+- Cleanup of existing AVIF references in `RichTextParser.kt` / `FeedBasis.kt` to use the new `MediaMimeTypes` helpers. Follow-up only.

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

@@ -0,0 +1,156 @@
+# Design — AVIF instrumented tests
+
+**Date:** 2026-05-27
+**Status:** Design (pre-implementation)
+**Owning module:** `amethyst/`
+**Parent work:** `feat/avif-support` (Phase D — instrumented coverage)
+**Source handover:** `~/docs/amethyst/2026-05-27-avif-instrumented-tests-handover.md`
+**Related plan:** `amethyst/plans/2026-05-26-avif-support.md` §9, `amethyst/plans/2026-05-26-avif-implementation-plan.md` Phase D
+
+---
+
+## 1. Goal
+
+Add an Android on-device test layer that catches regressions in the AVIF upload pipeline and the
+Phase E bugs that were fixed manually (`C2`–`C8` plus follow-ups in commits `df84475d4`,
+`5a760c046`, `b9112550b`, `1db110cdf`). JVM unit tests already cover what they can; the rest of
+this design covers what can only be exercised on a real Android runtime — `android.graphics.ImageDecoder`,
+Coil's image-loader pipeline, `ExifInterface`, and the real upload-side ViewModels.
+
+Scope is deliberately narrow: **AVIF upload pipeline + the specific Phase E regressions**, not
+broader instrumented coverage of the app.
+
+## 2. Constraints
+
+- **No new tooling on CI.** Fixtures are pre-generated and committed as binary blobs; tests never
+  shell out to `avifenc`/`ffmpeg` at run time.
+- **No Compose UI tests.** Amethyst has zero Compose UI tests today
+  (confirmed via grep for `createComposeRule`); we keep that pattern. Compose-only AVIF behaviors
+  (slider hide, avatar `contentScale` default, animate-by-URL-extension) are explicitly out of
+  scope here.
+- **No CI wiring.** Tests run locally on an emulator before merging an AVIF-touching change.
+  Adding an emulator job to CI is a separate, future change.
+
+## 3. Test inventory
+
+Five test files (four instrumented + one JVM unit) plus three fixtures.
+
+### 3.1 Fixtures (committed once)
+
+Under `amethyst/src/androidTest/assets/avif/`:
+
+| File | Content | Size | Purpose |
+|---|---|---|---|
+| `still-tiny-8x8.avif` | 8×8 single-frame, red | ~300 B | Still-AVIF pipeline + decode paths |
+| `animated-tiny-3frames.avif` | 8×8 3-frame (red/green/blue, 10 fps) | ~1 KB | Animated detection + `AnimatedImageDrawable` decode + animated-profile-pic cache skip |
+| `still-tiny-8x8-exif-gps.avif` | Still fixture with GPS EXIF metadata | ~1 KB | Triggers `AvifMetadataNotVerifiableException` fail-closed path in `MetadataStripper` |
+
+Generated once with:
+
+```bash
+mkdir -p ~/avif-test-assets && cd ~/avif-test-assets
+
+# Still + animated
+ffmpeg -y -hide_banner -loglevel error -f lavfi -i 'color=red:s=8x8' -frames:v 1 still-8x8.png
+avifenc -q 60 --min 30 --max 50 still-8x8.png still-tiny-8x8.avif
+
+ffmpeg -y -hide_banner -loglevel error -f lavfi -i 'color=red:s=8x8'    -frames:v 1 a1.png
+ffmpeg -y -hide_banner -loglevel error -f lavfi -i 'color=green:s=8x8'  -frames:v 1 a2.png
+ffmpeg -y -hide_banner -loglevel error -f lavfi -i 'color=blue:s=8x8'   -frames:v 1 a3.png
+avifenc --fps 10 a1.png a2.png a3.png animated-tiny-3frames.avif
+
+# EXIF-poisoned fixture (GPS metadata is the canonical sensitive tag)
+cp still-tiny-8x8.avif still-tiny-8x8-exif-gps.avif
+exiftool -overwrite_original -GPSLatitude=12.345 -GPSLongitude=67.89 still-tiny-8x8-exif-gps.avif
+```
+
+Requires `brew install libavif ffmpeg exiftool` locally. The generated bytes are the source of truth;
+tests do not depend on these tools at run time.
+
+### 3.2 Test files
+
+**From handover (mostly verbatim; pipeline test gains one assertion on the EXIF-poisoned fixture):**
+
+| File | Covers |
+|---|---|
+| `service/uploads/AvifUploadPipelineInstrumentedTest.kt` | `MediaCompressor` byte preservation (still + animated), `MetadataStripper.stripImageMetadata` clean-AVIF path **and** fail-closed `AvifMetadataNotVerifiableException` on the EXIF-poisoned fixture, `PreviewMetadataCalculator` blurhash/thumbhash/dim on API 31+ |
+| `service/images/AvifAnimatedDecodeInstrumentedTest.kt` | Custom `AvifAnimatedDecoderFactory` — still AVIF → `Bitmap` 8×8, animated AVIF → `AnimatedImageDrawable` (not `BitmapDrawable`) |
+
+**New (this design):**
+
+| File | Location | Covers / regression source |
+|---|---|---|
+| `service/uploads/MediaMimeTypesTest.kt` | `amethyst/src/test/` (JVM unit) | `isAvif()` and `extensionFromMimeType()` — pure-Kotlin helpers. Covers BlossomUploader/NIP-96 extension-fallback regression (commit `df84475d4`) by testing the helper both call sites delegate to. |
+| `service/images/ThumbnailDiskCacheAvifInstrumentedTest.kt` | `amethyst/src/androidTest/` | Commit `5a760c046` — `generateFromFile()` returns `false` and writes nothing to cache for animated AVIF; returns `true` and produces a cached Bitmap for still AVIF. Public API is friendly — no seam needed. |
+| `service/uploads/AvifMetadataStripperPoisonedFixtureInstrumentedTest.kt` | `amethyst/src/androidTest/` | Commit `b9112550b` — `MetadataStripper.strip(...)` throws `AvifMetadataNotVerifiableException` on the EXIF-poisoned fixture. Verifies the fail-closed contract that the ViewModel error-string binding depends on. (The ViewModel→string-resource wiring at `NewUserMetadataViewModel.kt:223` is single-line and compile-checked; not separately tested.) |
+
+## 4. Explicitly out of scope
+
+- Compose UI tests for slider-hide (`ImageVideoDescription.kt`, `ChatFileUploadDialog.kt`), avatar
+  `contentScale` default (`RobohashAsyncImage.kt`), or animate-profile-pic-by-URL-extension.
+- A CI workflow change. The existing `build.yml` runs no emulator step; this design does not add one.
+- Desktop/JVM upload-pipeline instrumented tests in `commons/jvmMain/`.
+- iOS test coverage in `iosTest/`.
+- Performance benchmarks.
+
+## 5. Run instructions
+
+Local-only, no CI. Recommended: API 35 emulator (primary), API 28 second pass to verify
+`assumeTrue(SDK_INT >= 31)` skips decode-required tests cleanly.
+
+```bash
+# JVM unit test (no emulator needed)
+./gradlew :amethyst:testPlayDebugUnitTest --tests 'com.vitorpamplona.amethyst.service.uploads.MediaMimeTypesTest'
+
+# Instrumented tests, by package
+./gradlew :amethyst:connectedPlayDebugAndroidTest \
+  '-Pandroid.testInstrumentationRunnerArguments.package=com.vitorpamplona.amethyst.service.uploads'
+
+./gradlew :amethyst:connectedPlayDebugAndroidTest \
+  '-Pandroid.testInstrumentationRunnerArguments.package=com.vitorpamplona.amethyst.service.images'
+```
+
+A short "AVIF — running instrumented tests" subsection will be added to
+`amethyst/plans/2026-05-26-avif-support.md` §9 with the same commands.
+
+When CI gains an emulator step for any reason in the future, these tests run automatically with
+no further change — they are standard `androidTest/` files.
+
+## 6. Risks / unknowns
+
+Most risks from the original draft were resolved by audit during design. Remaining items:
+
+1. **API 28 + `MetadataStripper` on the clean fixtures.** `ExifInterface` on API 28 may throw
+   `AvifMetadataNotVerifiableException` even for the clean fixtures (the fail-closed path triggers
+   on "unreadable EXIF", which older ExifInterface may produce for AVIF). The pipeline test
+   should accept either the clean-strip result or the fail-closed exception on API 28 —
+   `assumeTrue(SDK_INT >= 31)` is the simplest gate.
+2. **EXIF-poisoned fixture portability.** `exiftool` writing EXIF into an AVIF container is
+   well-supported but exact byte layout varies across exiftool versions. The test should only
+   assert that the exception class + message-prefix are correct, not byte-for-byte stripper
+   output.
+3. **`ThumbnailDiskCache` cache-dir setup.** The cache uses a singleton-ish `cacheDir`. The test
+   must point it at a fresh `context.cacheDir` subdir per test and clean up afterwards. Confirm
+   the constructor/init shape during implementation; if singleton-only, the test uses
+   `context.cacheDir` directly and asserts on filenames there.
+
+## 7. Definition of done
+
+- 4 instrumented test files compile under `./gradlew :amethyst:compilePlayDebugAndroidTestKotlin`.
+- 1 JVM unit test file passes under `./gradlew :amethyst:testPlayDebugUnitTest`.
+- All instrumented tests pass on an API 35 emulator. On API 28, decode-dependent tests skip
+  cleanly via `assumeTrue`; non-decode tests pass.
+- All 3 AVIF fixtures committed under `amethyst/src/androidTest/assets/avif/`, < 10 KB total.
+- `amethyst/plans/2026-05-26-avif-support.md` §9 updated with run instructions.
+- `./gradlew spotlessApply` clean.
+
+## 8. Implementation order (preview — full plan to follow)
+
+1. Generate and commit the 3 fixtures (isolated, reviewable commit).
+2. Drop in handover D3 + D4 test files (pipeline + decode); compile; run on API 35.
+3. Extend the pipeline test to assert `AvifMetadataNotVerifiableException` on the poisoned fixture.
+4. Add `MediaMimeTypesTest` (JVM unit, under `amethyst/src/test/`).
+5. Add `ThumbnailDiskCacheAvifInstrumentedTest`.
+6. Add `AvifMetadataStripperPoisonedFixtureInstrumentedTest`.
+7. Update `amethyst/plans/2026-05-26-avif-support.md` §9 with run commands.
+8. Spotless + final API 35 pass + API 28 spot-check.

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

@@ -0,0 +1,332 @@
+# DM loading: live tail + per-relay history paging
+
+> **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
+> **Design evolution (historical)** — they are superseded and no longer match
+> the code; don't trust them for how it works today.
+
+## Problem
+
+The DM loaders used a single subscription whose `since` floor grew as the user
+scrolled (`loadMore`: 7d → 14d → 28d → …). The filter carried **only `since`,
+no `until`**, so every widen re-requested the whole window and the relay
+re-streamed the entire history from the new floor. Traces showed this directly:
+
+```
+[giftwrap] load summary: 589 event(s)  (14d)
+[giftwrap] load summary: 1486 event(s) (28d)
+[giftwrap] load summary: 2609 event(s) (56d)
+```
+
+Each step re-downloaded everything it already had plus the new slice — the
+"getting all events over and over again" the owner reported. It also cascaded:
+a few pixels of scroll walked the window to the 10-year backstop, because
+widening pulls older *messages* but the rooms list is keyed by *conversation*,
+so a handful of busy correspondents flood thousands of events without adding a
+single new row, and the "scrolled near the oldest room" trigger never clears.
+
+---
+
+## Current architecture
+
+### Two layers per protocol
+
+Each DM protocol — **NIP-17** gift wraps (kind 1059) and **NIP-04** legacy DMs
+(kind 4) — is split into two independent responsibilities:
+
+1. **Live tail** — a fixed ~1-week floor with **no `until`**, open to the
+   future. Never widens. New messages always arrive here. Backed by the
+   **round model** (`WindowLoadTracker`): one REQ fanned to every relay, "done"
+   when all settle, drives the boot spinner.
+2. **History** — everything *older* than the week floor, paged **backward by
+   `until`+`limit`, per relay, on demand**. Backed by the **per-relay model**
+   (`RelayLoadingCursors` + `PerRelayLoadTracker`), driven by on-screen markers.
+
+The two are disjoint in time, so re-issuing a history page never re-streams the
+live tail, and consecutive history pages never re-stream each other.
+
+| Surface | Live-tail manager (round) | History manager (per-relay) |
+|---|---|---|
+| Account gift wraps (NIP-17) | `AccountGiftWrapsEoseManager` | `AccountGiftWrapsHistoryEoseManager` |
+| Conversation NIP-04 | `ChatroomNip04SubAssembler` | `ChatroomNip04HistorySubAssembler` |
+| Rooms-list NIP-04 | `ChatroomListNip04SubAssembler` | `ChatroomListNip04HistorySubAssembler` |
+
+Accessed from the UI via `accountViewModel.dataSources()` as
+`.account.giftWrapsHistory`, `.chatroom.nip04History`,
+`.chatroomList.nip04History`.
+
+### The history paging primitive: `RelayLoadingCursors`
+
+The time-window model can't tell "this relay is empty" from "this is a gap" — a
+`since`/`until` slice that returns nothing might just be a quiet stretch above
+older messages. Paging by `until`+`limit` removes that ambiguity: a relay
+returns up to `limit` (**10000**) of its newest events older than the cursor,
+**skipping gaps**, so an **empty page + EOSE is a gap-proof "nothing older"**.
+
+Per relay, two cursors are kept deliberately decoupled:
+
+- `requestedUntil` — the `until` the REQ carries. Moves **only** in `advance()`.
+  Leaving it untouched on EOSE is what makes paging demand-driven: a relay that
+  finished a page just **parks** at the same filter (no re-REQ) until advanced.
+- `reachedUntil` — the oldest `created_at` actually delivered. Moves on EOSE.
+  The in-stream markers sit here; the next page starts at `reachedUntil − 1`.
+
+Stop signals: an empty page marks the relay **`done`**. A relay returning fewer
+than `limit` is treated as its own cap, **not** exhaustion. A misbehaving relay
+that returns events but none older than already reached (echoing its newest
+events) is also treated as the bottom, so its marker can't re-request the same
+window forever. Tested in `RelayLoadingCursorsTest.kt`.
+
+### The two completion models (and where each lives)
+
+**Round model — `WindowLoadTracker` (live tail only).** One REQ is fanned to all
+relays; the window is "done" only when **every** expected relay reaches a
+terminal signal (`settled ⊇ expected`), with backstops for stragglers (idle /
+silence / connect-grace / absolute cap). `loading` starts **`true`**. This is a
+*barrier*: nobody moves on until the cohort answers. It is the right shape for
+the one-shot fixed-window backfill the live tail does.
+
+> Note: the silence + connect-grace backstops are gated behind `tracksReqSends`,
+> and **none of the three live-tail managers pass `tracksReqSends = true`**, so
+> in current use only the settle / idle / cap paths ever fire. The REQ-aware
+> machinery is dormant in production — see "Things to scrutinize".
+
+**Per-relay model — `RelayLoadingCursors` + `PerRelayLoadTracker` (all history).**
+Each relay advances to its next page the instant *it* EOSEs, independent of the
+others; the subscription layer diffs per relay, so re-issuing only re-REQs the
+relay whose cursor moved. `loading` starts **`false`** (a `true` start would
+wedge the scroll loader's `!loading` gate on first open). Fast relays race to
+the bottom in back-to-back pages; slow / auth-walled relays catch up at their
+own pace and **none are abandoned** — a stalled relay keeps its subscription
+open and resumes when re-advanced. This removes the round model's
+slowest-relay coupling, which matters most on the conversation screen where the
+fan-out includes correspondents' (often auth-walled, slow) relays.
+
+`exhausted` (per history manager) flips true when **every relay is `done` OR
+`stalled`** — "nothing more reachable right now". A merely *parked* relay (more
+to load, just not advancing) keeps it false.
+
+> All three history managers (`AccountGiftWrapsHistoryEoseManager`,
+> `ChatroomNip04HistorySubAssembler`, `ChatroomListNip04HistorySubAssembler`)
+> were structurally the same per-relay loader, so that bookkeeping is now a
+> single reusable engine — **`BackwardRelayPager`** (keyless, single-active). It
+> does **not** hold the cursors: the per-relay `RelayLoadingCursors` live on the
+> scope's own domain object (a `Chatroom` per conversation, a `ChatroomList` per
+> account), so they share the cached messages' lifetime and survive an account
+> switch. The orchestrator owns only the transient bits — in-flight + silence
+> tracking, the stalled set, and the display flows — and
+> `bind(cursors, scope, relaysFor)`s to whichever scope is active. Each manager
+> supplies its REQ-filter builder, a `relaysFor` lookup, and the subscription
+> wiring (forwards relay callbacks via `onEvent`/`onEose`/`onClosed`/`onCannotConnect`,
+> re-issues filters after `advance`/`advanceAll`). The earlier round-model history
+> (and the rooms-list "stall-gate") was fully removed — see Design evolution.
+
+### What drives `advance()`: on-screen markers, off viewport visibility
+
+History paging is demand-driven by **per-relay window-limit markers** placed in
+the message stream, not by a scroll-position trigger:
+
+- **`RelayReachCursor`** — one per (protocol, relay): its `reachedUntil` depth,
+  its `RelayReachState` (`REACHING ↓` / `STALLED …` / `DONE ✓`), and the
+  `advance()` that pulls *that relay's* next page. Built in the feed views from
+  each history manager's `relayProgress` map (gift wraps + NIP-04 combined; a
+  protocol drops out of the list once `exhausted`).
+- **`RelayReachSentinels`** — the load *driver*, **hoisted above the
+  `LazyColumn`** (via `ChatFeedView`'s `sentinels` slot). Each non-done limit
+  gets one stable effect (keyed by `protocol:url`) that watches `listState` and
+  fires `advance()` when its gap is among the **currently visible rows** AND
+  either it just scrolled into view OR its `reachedUntil` moved (a page landed —
+  keep paging while visible). Driving off **viewport visibility** instead of row
+  composition is deliberate: an earlier version placed the sentinel *inside* the
+  hosting row, so any feed reorder (a live DM, a slow relay dribbling a page)
+  tore the effect down and re-fired `advance()` on a static screen — re-arming
+  stalled relays into a silence-watchdog storm. (commit `0394ec2a`)
+- **`RelayReachMarkers` / `RelayReachMarker`** — pure UI (via the
+  `markersInGap` slot): the "Relay sync: ✓ 8 · ↓ 1" divider at each relay's
+  reached depth. Can be re-placed on every reorder without triggering paging.
+- **`BootstrapHistoryWhenEmpty`** — when the feed is genuinely `Empty` (the live
+  tail came back empty for a thread/list whose newest message is older than a
+  week) there are no rows to host markers, so this steps every relay one page at
+  a time (debounced 1200ms, gated per loader on `!loading && !exhausted`) until
+  messages appear and the markers take over, or the protocol exhausts.
+
+### NIP-04 per-relay filter scoping (`Nip04DmRelayRouting`)
+
+A conversation's NIP-04 filters previously named the whole participant set on
+every relay, so a relay belonging to one correspondent was asked about all of
+them, and the `from-me` leg (`authors:[me]`) was sent to correspondents' inbox
+relays — which auth-walled relays reject outright ("all authors must be
+authenticated"), stalling the load.
+
+`Nip04DmRelayRouting` (in `FilterNip04DMs.kt`) is now two **per-relay key maps**
+(`relay → which keys to name there`), built from the outbox model:
+
+- **to me** (`#p:[me]`) — my inbox carries the whole group; each correspondent's
+  outbox carries only that correspondent.
+- **from me** (`authors:[me]`) — my outbox carries the whole group; each
+  correspondent's inbox carries only that correspondent.
+
+So a relay only ever sees the keys that actually own it. The **conversation**
+history manager scopes its REQ to the armed relays' key sets this way; the
+**rooms-list** and **gift-wrap** history managers query only the account's *own*
+relays (home outbox `from-me` + DM inbox `to-me`, via `filterNip04DMsFromMe` /
+`filterNip04DMsToMe` and `filterGiftWrapsToPubkey`), which is why their fan-out
+stays fast and reachable.
+
+### Status card terminal states (`DmHistoryLoadingCard`)
+
+One card per protocol at its oldest-loaded boundary. While paging it shows the
+protocol tag, "N relays" being asked, and the reach-back date; it is tappable
+into a per-relay popup (`DmHistoryRelayDialog`) listing every relay with
+`✓` done / `…` stalled / `↓` reaching and how far back each paged.
+
+Because `exhausted` conflates `done` and `stalled`, the terminal state is split
+on `stalledCount` so it can't overclaim (commit `813110cc`):
+
+- **caught up** (every relay `done`, `stalledCount == 0`) → "All caught up",
+  lingers ~2.2s then collapses.
+- **incomplete** (≥1 stalled) → "Some relays didn't respond · N unreachable",
+  error-coloured `…`, **stays put** (no collapse), tappable to see which.
+
+### Reply placeholder (`LoadingReplyNote`)
+
+A reply whose target message hasn't been paged in yet isn't *missing*, it's
+older than the loaded window (and for gift wraps the rumor id isn't even
+queryable — only the outer 1059 wrap is). Instead of the generic `BlankNote`
+("post not found"), `LoadingReplyNote` actively walks the relevant protocol's
+history backward (kicking `advanceAll` each time a page settles) until the
+target decrypts (the surrounding `WatchNoteEvent` crossfades the real message in
+and disposes this) or the protocol exhausts. Its terminal state mirrors the
+card: "Couldn't find this message" + an honest subtitle ("N relays unreachable ·
+tap to see which" when stalled, "Searched every relay · tap to see" when
+genuinely done), tappable into the same per-relay popup. Wired via
+`ChatMessageCompose.RenderReply` → `WatchNoteEvent(onBlank = …)`, with the pager
+chosen by the parent event's protocol (`DmReplyProtocol.NIP17` / `NIP04`).
+
+### Diagnostics
+
+Everything logs under one tag, **`DMPagination`** (debug builds):
+`DmRelayDiagnosticsLogger` folds the per-relay connection timeline (REQ sent,
+connect/disconnect, CLOSED/NOTICE/OK-fail) into it; `DmRelayLog` prints the
+"relays by source" breakdown (NIP-65 in/out, DM list, private storage, local)
+per subscription so an unexpected relay can be traced to the list it leaks in
+from; and each assembler logs its milestones (paging start, a relay reaching
+the bottom / stalling with the reason, the "window settled" summary of
+done-vs-still-trying, each marker fire).
+
+### Related fix: Tor guard-sample self-heal
+
+`TorService` gained a `noUsableGuards()` check that, on init, inspects Arti's
+persisted `guards.json` and wipes the on-disk state if a non-empty guard set has
+**zero** usable guards (all `disabled` / `unlisted`). This recovers the
+long-standing "can't connect to Tor → relays permanently unreachable" wedge
+(Arti disables guards past a 0.7 indeterminate-failure ratio, never re-enables
+them, and can't replenish once the 60-slot sample is full). Orthogonal to
+pagination, but it lived here because unreachable relays were part of the same
+"DM history stuck / relays never answer" symptom this branch chased.
+
+---
+
+## Component map (vs `origin/main`)
+
+**Paging primitives (quartz, `nip01Core/relay/client/paging/`, `commonMain`)** —
+the pure, protocol-level paging *state*; iOS-clean, reusable by any KMP target.
+- `RelayLoadingCursors.kt` — per-relay `until`+`limit` cursor state + pinned floor;
+  held on the scope's domain object. *(+ `RelayLoadingCursorsTest` in amethyst; the
+  `until`+`limit` wire contract is covered by `UntilLimitPagingRelayTest` against
+  the quartz `jvmAndroidTest` geode relay)*
+- `RelayPagingProgress.kt` — `(reachedUntil, done, stalled)` per relay.
+
+**Paging orchestrators (commons, `relayClient/paging/`, `jvmAndroid`)** — the
+StateFlow-backed, subscription-loading state holders. Moved out of amethyst **and**
+out of quartz (per `commons/ARCHITECTURE.md`: the relay-subscription client +
+`StateFlow` state holders live in commons) so desktop / CLI / any feed can reuse
+them; `jvmAndroid` (uses `java.util.concurrent` + `@Synchronized`) → Android +
+Desktop, not iOS.
+- `BackwardRelayPager.kt` — the keyless single-active orchestrator the three
+  history managers `bind` to. *(+ `BackwardRelayPagerTest` state-machine in commons
+  `jvmTest`)*
+- `PerRelayLoadTracker.kt` — per-relay in-flight tracker + silence watchdog.
+- `WindowLoadTracker.kt` — round/barrier completion tracker (live tail). *(+ `WindowLoadTrackerIdleTest` in amethyst)*
+
+**Diagnostics (amethyst)** — `service/relayClient/eoseManagers/DmRelayLog.kt`,
+`service/relayClient/diagnostics/DmRelayDiagnosticsLogger.kt` — the `DMPagination` logs.
+
+**Managers / assemblers**
+- `AccountGiftWrapsEoseManager.kt` (live tail) + `AccountGiftWrapsHistoryEoseManager.kt` (new, history).
+- `ChatroomNip04SubAssembler.kt` (live tail) + `ChatroomNip04HistorySubAssembler.kt` (new, history).
+- `ChatroomListNip04SubAssembler.kt` (live tail) + `ChatroomListNip04HistorySubAssembler.kt` (new, history).
+- `FilterNip04DMs.kt` (per-relay `Nip04DmRelayRouting`, live + history builders), `FilterNip04DMsFromMe/ToMe.kt`, `FilterGiftWrapsToPubkey.kt` — `until`/`limit` added.
+- `AccountFilterAssembler`, `ChatroomFilterAssembler`, `ChatroomListFilterAssembler` — wire the new managers.
+
+**Shared UI (commons, `commons/ui/feeds/`)** — extracted from amethyst so Android +
+Desktop (and any per-relay feed) render the same widgets; CMP `composeResources`
+strings, no app-theme / `java.time` deps.
+- `RelayReachMarker.kt` — `RelayReachCursor` + sentinels (the hoisted, visibility-driven
+  paging driver) + markers (pure UI) + `RelayReachMarker`/`RelayReachState`.
+- `DmHistoryLoadingCard.kt` — the boundary status card + per-relay tap dialog +
+  `historySubtitle`/`incompleteSubtitle`. Takes a `formatReachDate: (epochSeconds) -> String`
+  so each platform supplies its locale date formatter.
+
+**Android UI (`amethyst/ui/screen/loggedIn/chats/`)**
+- `feed/LoadingReplyNote.kt` — history-walking reply placeholder (uses the shared subtitle helpers/dialog).
+- `feed/HistoryDateFormat.kt` — `formatHistoryReachDate`, the Android locale formatter passed into the shared card.
+- `feed/ChatFeedView.kt` — `markersInGap` + `sentinels` slots.
+- `feed/ChatMessageCompose.kt` — reply `onBlank` wiring.
+- `privateDM/ChatroomView.kt`, `rooms/feed/ChatroomListFeedView.kt` — assemble cards/markers/sentinels, `BootstrapHistoryWhenEmpty`.
+- `res/values/strings.xml` — `chats_reply_*` (the card's `chats_history_*` now live in commons).
+
+---
+
+## Things to scrutinize (review notes)
+
+1. **`exhausted` conflates `done` + `stalled`** at the manager level. The cards
+   now distinguish them via `stalledCount`, but other consumers (the scroll
+   `!loading` gates, `LoadingReplyNote`'s advance loop) treat stalled as
+   terminal. Intentional (don't hammer dead relays), but confirm it's desired.
+2. **`PerRelayLoadTracker.lastActivityMs` is global, not per-relay** — once the
+   chatty relays finish, a legitimately-slow relay gets the full 15s silence
+   window and can be marked stalled mid-delivery of a 10000-event page.
+3. **"All caught up" can still be technically-true-but-misleading** when
+   `stalledCount == 0` yet a chat's messages live on a relay *not in the
+   account's NIP-17 inbox list* — an outbox-coverage gap the card can't detect.
+4. **`WindowLoadTracker`'s REQ-aware backstops are dormant** in production
+   (no live-tail manager sets `tracksReqSends`). Either the live tail should
+   adopt them or the round model could be slimmer for its current role.
+5. **`PAGE_LIMIT = 10000`** caps per-request volume but a single page can still
+   be a large payload on a dense relay.
+
+---
+
+## Design evolution (historical — superseded, do not trust for current behavior)
+
+These sections describe earlier iterations, kept for context. The code has
+moved past all of them.
+
+### v1 — time-slice history (superseded by `RelayLoadingCursors`)
+
+History was first loaded in bounded `since`+`until` **time slices**
+(`TimeWindowPagination`, now deleted): `loadMore` fetched only the new band
+`[newFloor, previousFloor]`, with a NIP-17 ±2-day wrapper-timestamp margin on
+the slice `since` for gift wraps. This bounded re-downloads but still couldn't
+tell an empty relay from a gap (an empty slice might sit above older messages),
+so the only stop was a 10-year `maxLookback`, and a wide late slice could pull a
+20k-event firehose. Replaced by per-relay `until`+`limit` paging.
+
+### v2 — round-model history + rooms-list "stall-gate" (both removed)
+
+History paging once used the **round model** (`WindowLoadTracker`): each
+`loadMore` issued one page to all active relays and waited for the slowest to
+settle before the next — pacing every relay at the slowest one. The rooms list
+additionally had a **stall-gate**: an auto-fill loop that widened only while it
+brought in new private rooms, stopping once a widen added none (to avoid the
+conversation-keyed cascade).
+
+Both are gone. All history paging is now per-relay independent
+(`PerRelayLoadTracker`), and the rooms list pages to exhaustion off marker
+visibility like the conversation (commit `98fb8720` dropped the stall-gate;
+`60b8629a` / `9f0ecd54` moved gift-wrap and rooms-list history onto the per-relay
+model). `WindowLoadTracker` survives **only** as the live-tail completion
+barrier. An earlier revision of this doc ("Update 3") still claimed rooms-list
+and gift-wrap history used the round model — that is no longer true.

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

@@ -0,0 +1,59 @@
+/*
+ * 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
+
+import android.content.Context
+import android.net.Uri
+import androidx.core.content.FileProvider
+import androidx.test.platform.app.InstrumentationRegistry
+import java.io.File
+import java.util.UUID
+
+/**
+ * Shared helpers for AVIF instrumented tests.
+ *
+ * [copyAssetToCache] always uses a UUID-prefixed filename so concurrent or
+ * back-to-back test runs cannot collide on a shared cache path.
+ *
+ * [contentUriFor] wraps a file with FileProvider so `ContentResolver.getType()`
+ * returns the correct MIME — it returns null for `file://` URIs, which makes
+ * `MetadataStripper` skip the AVIF branch entirely.
+ */
+object AvifInstrumentedTestSupport {
+    val appContext: Context get() = InstrumentationRegistry.getInstrumentation().targetContext
+    val testContext: Context get() = InstrumentationRegistry.getInstrumentation().context
+
+    fun copyAssetToCache(assetPath: String): File {
+        val cacheDir = appContext.cacheDir.also { it.mkdirs() }
+        val out = File(cacheDir, "${UUID.randomUUID()}-${assetPath.substringAfterLast('/')}")
+        testContext.assets.open(assetPath).use { input ->
+            out.outputStream().use { output -> input.copyTo(output) }
+        }
+        return out
+    }
+
+    fun contentUriFor(file: File): Uri =
+        FileProvider.getUriForFile(
+            appContext,
+            "${appContext.packageName}.provider",
+            file,
+        )
+}

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

@@ -0,0 +1,463 @@
+/*
+ * 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
+
+import android.util.Log
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.vitorpamplona.quartz.nip01Core.crypto.Nip01Crypto
+import com.vitorpamplona.quartz.nip44Encryption.Nip44v2
+import com.vitorpamplona.quartz.nip60Cashu.bdhke.Bdhke
+import com.vitorpamplona.quartz.utils.secp256k1.Secp256k1
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.runBlocking
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * Regression suite for the ART JIT optimizer SIGSEGV that hit Cashu's
+ * cryptographic hot path on Android 15+ (Jit thread pool SIGSEGV at
+ * `HBasicBlock::RemoveInstruction +32`, fault addr `0x48`, inside
+ * `InstructionSimplifierVisitor::Run`).
+ *
+ * Root cause: `U256.uLtInline` was `internal inline`, so its body
+ * `(a xor MIN_VALUE) < (b xor MIN_VALUE)` was duplicated at every call
+ * site. With 199 sites across U256 / ScalarN / FieldP — and 12 sequential
+ * `if (uLtInline(...)) 1L else 0L` patterns inside `ScalarN.reduceWideTo`
+ * alone — ART's InstructionSimplifier tried to fold them as a group and
+ * null-deref'd. Fix: drop `inline`, so the function-call boundary blocks
+ * the fold path.
+ *
+ * Each test runs 2048 iterations to force ART tier-1 JIT (threshold for
+ * this code is ~48 invocations). Crash-mode tests check for `Jit thread
+ * pool` SIGSEGV; correctness-mode tests cross-check against
+ * `fr.acinq.secp256k1` JNI or do roundtrip verification.
+ *
+ * Run all:
+ *   ./gradlew :amethyst:connectedPlayDebugAndroidTest \
+ *     -Pandroid.testInstrumentationRunnerArguments.class=com.vitorpamplona.amethyst.BdhkeJitCrashTest
+ *
+ * Run single variant:
+ *   adb shell am instrument -w -e class \
+ *     com.vitorpamplona.amethyst.BdhkeJitCrashTest#a_warmupOnly \
+ *     com.vitorpamplona.amethyst.debug.test/androidx.test.runner.AndroidJUnitRunner
+ *
+ * On crash:
+ *   adb logcat -d | grep -E "SIGSEGV|tombstone|BdhkeJitCrashTest"
+ *   adb pull /data/tombstones/tombstone_NN /tmp/
+ */
+@RunWith(AndroidJUnit4::class)
+class BdhkeJitCrashTest {
+    private val tag = "BdhkeJitCrashTest"
+
+    /** Generator point G in 33-byte compressed form — always parses, never touches wallet state. */
+    private val mintPubKey =
+        byteArrayOf(
+            0x02.toByte(),
+            0x79.toByte(),
+            0xBE.toByte(),
+            0x66.toByte(),
+            0x7E.toByte(),
+            0xF9.toByte(),
+            0xDC.toByte(),
+            0xBB.toByte(),
+            0xAC.toByte(),
+            0x55.toByte(),
+            0xA0.toByte(),
+            0x62.toByte(),
+            0x95.toByte(),
+            0xCE.toByte(),
+            0x87.toByte(),
+            0x0B.toByte(),
+            0x07.toByte(),
+            0x02.toByte(),
+            0x9B.toByte(),
+            0xFC.toByte(),
+            0xDB.toByte(),
+            0x2D.toByte(),
+            0xCE.toByte(),
+            0x28.toByte(),
+            0xD9.toByte(),
+            0x59.toByte(),
+            0xF2.toByte(),
+            0x81.toByte(),
+            0x5B.toByte(),
+            0x16.toByte(),
+            0xF8.toByte(),
+            0x17.toByte(),
+            0x98.toByte(),
+        )
+
+    /**
+     * The startup-shape regression. An earlier branch had a `Bdhke.warmup()`
+     * that ran 2048 blind+unblind cycles eagerly from
+     * `CashuWalletState.start()` to dodge what was thought to be a load-
+     * sensitive JIT crash. The real bug was [uLtInline][com.vitorpamplona.quartz.utils.secp256k1.uLtInline]
+     * inline-expansion (see `U256.kt`), and the warmup is gone — but the
+     * workload it ran is exactly what the unblind path stresses, so we
+     * keep it as a regression test under the same name.
+     */
+    @Test
+    fun a_warmupOnly() {
+        runBlindUnblind(2048)
+    }
+
+    /**
+     * Raw loop — bypasses the at-most-once guard so it always actually runs.
+     * Lets you bisect the iteration count where the JIT crash kicks in.
+     */
+    @Test
+    fun b_blindUnblindLoop_2048() {
+        runBlindUnblind(2048)
+    }
+
+    /**
+     * Original commit history blamed [Bdhke.unblind] specifically. Isolate it:
+     * mint one B' up front, then unblind it N times against the same fixed
+     * mintPubKey / r. Same allocation profile as the real restore loop.
+     */
+    @Test
+    fun e_unblindOnly_2048() {
+        val r = Bdhke.randomScalar()
+        val secret = Bdhke.randomScalar()
+        val bTick = Bdhke.blind(secret, r)
+        Log.i(tag, "unblindOnly_2048: priming done, beginning loop")
+        repeat(2048) { i ->
+            Bdhke.unblind(bTick, r, mintPubKey)
+            if (i % 256 == 255) Log.i(tag, "unblindOnly_2048: ${i + 1} done")
+        }
+        Log.i(tag, "unblindOnly_2048: survived")
+    }
+
+    /**
+     * Multiple coroutines on Dispatchers.Default hammering blind+unblind in
+     * parallel — closer to the real startup shape (two accounts each kicking
+     * off CashuWalletState.start concurrently) and a higher-stress JIT load.
+     */
+    @Test
+    fun f_blindUnblindLoop_concurrent_x4() {
+        runBlocking {
+            Log.i(tag, "concurrent_x4: 4 workers × 512 cycles on Dispatchers.Default")
+            val workers =
+                (0 until 4).map { id ->
+                    async(Dispatchers.Default) {
+                        repeat(512) { i ->
+                            val secret = Bdhke.randomScalar()
+                            val r = Bdhke.randomScalar()
+                            val bTick = Bdhke.blind(secret, r)
+                            Bdhke.unblind(bTick, r, mintPubKey)
+                            if (i % 128 == 127) Log.i(tag, "concurrent_x4: worker=$id ${i + 1} done")
+                        }
+                    }
+                }
+            workers.awaitAll()
+            Log.i(tag, "concurrent_x4: survived")
+        }
+    }
+
+    private fun runBlindUnblind(iterations: Int) {
+        Log.i(tag, "runBlindUnblind: $iterations cycles")
+        repeat(iterations) { i ->
+            val secret = Bdhke.randomScalar()
+            val r = Bdhke.randomScalar()
+            val bTick = Bdhke.blind(secret, r)
+            Bdhke.unblind(bTick, r, mintPubKey)
+            if (i % 256 == 255) Log.i(tag, "runBlindUnblind: ${i + 1} / $iterations done")
+        }
+        Log.i(tag, "runBlindUnblind: $iterations survived")
+    }
+
+    // ==================== Isolation tests ====================
+    //
+    // Each variant hammers ONE public entry point so the JIT can only compile
+    // that entry's call tree. If a variant crashes with the same `Jit thread
+    // pool` SIGSEGV signature, the offending method is reachable from that
+    // entry and not from any narrower one. Order from leaf to deep:
+    //
+    //   g_hashToCurveOnly      → tests hashToCurveInto (SHA256 + KeyCodec.liftX + Int-side shift+mask)
+    //   h_blindOnly            → adds ECPoint.mulG + ECPoint.addPoints
+    //   i_signOnly             → tests ONLY Secp256k1.pubKeyTweakMul (JNI, control)
+    //   j_secp256k1PubkeyOnly  → tests ONLY Secp256k1.pubkeyCreate (JNI, control)
+    //
+    // Run order: g, h, i, j.
+
+    @Test
+    fun g_hashToCurveOnly() {
+        Log.i(tag, "hashToCurveOnly: 2048 calls to Bdhke.hashToCurveCompressed")
+        repeat(2048) { i ->
+            val secret = Bdhke.randomScalar()
+            Bdhke.hashToCurveCompressed(secret)
+            if (i % 256 == 255) Log.i(tag, "hashToCurveOnly: ${i + 1} done")
+        }
+        Log.i(tag, "hashToCurveOnly: survived")
+    }
+
+    @Test
+    fun h_blindOnly() {
+        Log.i(tag, "blindOnly: 2048 calls to Bdhke.blind")
+        repeat(2048) { i ->
+            val secret = Bdhke.randomScalar()
+            val r = Bdhke.randomScalar()
+            Bdhke.blind(secret, r)
+            if (i % 256 == 255) Log.i(tag, "blindOnly: ${i + 1} done")
+        }
+        Log.i(tag, "blindOnly: survived")
+    }
+
+    @Test
+    fun i_signOnly() {
+        Log.i(tag, "signOnly: 2048 calls to Bdhke.sign (Secp256k1.pubKeyTweakMul, JNI)")
+        val r = Bdhke.randomScalar()
+        val bTick = Bdhke.blind(Bdhke.randomScalar(), r)
+        val mintPriv = Bdhke.randomScalar()
+        repeat(2048) { i ->
+            Bdhke.sign(bTick, mintPriv)
+            if (i % 256 == 255) Log.i(tag, "signOnly: ${i + 1} done")
+        }
+        Log.i(tag, "signOnly: survived")
+    }
+
+    @Test
+    fun j_secp256k1PubkeyOnly() {
+        Log.i(tag, "secp256k1PubkeyOnly: 2048 calls to Secp256k1.pubkeyCreate (pure Kotlin)")
+        val priv = Bdhke.randomScalar()
+        repeat(2048) { i ->
+            Secp256k1.pubkeyCreate(priv)
+            if (i % 256 == 255) Log.i(tag, "secp256k1PubkeyOnly: ${i + 1} done")
+        }
+        Log.i(tag, "secp256k1PubkeyOnly: survived")
+    }
+
+    // ==================== Cashu cryptographic coverage ====================
+    //
+    // Two-axis regression net for the rest of the crypto surface Cashu actually
+    // touches (beyond blind/unblind). Each test does both:
+    //
+    //   1. CRASH: 2048 iterations to force ART tier-1 JIT compile (the same
+    //      threshold that surfaced the InstructionSimplifier bug on
+    //      ECPoint.mul → uLtInline).
+    //   2. CORRECTNESS: every iteration cross-checks against
+    //      fr.acinq.secp256k1 JNI, or self-verifies via roundtrip / sign+
+    //      verify, depending on whether the primitive is standard secp256k1
+    //      (ACINQ-equivalent) or Cashu-specific (no native reference).
+    //
+    // A JIT miscompile that produces wrong-but-non-crashing code would fail
+    // here even though no SIGSEGV fires.
+
+    /** NIP-44 ECDH path. Our [Secp256k1.ecdhXOnly] vs acinq's pubKeyTweakMul. */
+    @Test
+    fun n_ecdhXOnly_2048() {
+        val acinq =
+            fr.acinq.secp256k1.Secp256k1
+                .get()
+        val scalar = Bdhke.randomScalar()
+        val peerPriv = Bdhke.randomScalar()
+        val peerPubUncompressed = Secp256k1.pubkeyCreate(peerPriv)
+        val peerPubCompressed = byteArrayOf(0x02.toByte()) + peerPubUncompressed.copyOfRange(1, 33)
+        val peerXOnly = peerPubUncompressed.copyOfRange(1, 33)
+        // ACINQ reference: x-coordinate of (scalar · peerPubCompressed)
+        val acinqOut = acinq.pubKeyTweakMul(peerPubCompressed, scalar)
+        val acinqX = acinqOut.copyOfRange(1, 33)
+        Log.i(tag, "ecdhXOnly: 2048 calls, comparing X coord vs acinq")
+        repeat(2048) { i ->
+            val ours = Secp256k1.ecdhXOnly(peerXOnly, scalar)
+            check(ours.contentEquals(acinqX)) {
+                "iter $i: ecdhXOnly diverged from acinq.pubKeyTweakMul X"
+            }
+            if (i % 256 == 255) Log.i(tag, "ecdhXOnly: ${i + 1} done")
+        }
+    }
+
+    /** NIP-01 / NUT-20 Schnorr sign. Deterministic — bytes must match acinq. */
+    @Test
+    fun o_signSchnorr_2048() {
+        val acinq =
+            fr.acinq.secp256k1.Secp256k1
+                .get()
+        val sk = Bdhke.randomScalar()
+        val msg = Bdhke.randomScalar() // 32 bytes
+        val aux = Bdhke.randomScalar()
+        val acinqSig = acinq.signSchnorr(msg, sk, aux)
+        Log.i(tag, "signSchnorr: 2048 calls, comparing 64-byte sig vs acinq")
+        repeat(2048) { i ->
+            val oursSig = Secp256k1.signSchnorr(msg, sk, aux)
+            check(oursSig.contentEquals(acinqSig)) {
+                "iter $i: signSchnorr diverged from acinq"
+            }
+            if (i % 256 == 255) Log.i(tag, "signSchnorr: ${i + 1} done")
+        }
+    }
+
+    /** Every consumed Nostr event (Cashu or otherwise) verifies through this. */
+    @Test
+    fun p_verifySchnorr_2048() {
+        val acinq =
+            fr.acinq.secp256k1.Secp256k1
+                .get()
+        val sk = Bdhke.randomScalar()
+        val msg = Bdhke.randomScalar()
+        val aux = Bdhke.randomScalar()
+        val sig = acinq.signSchnorr(msg, sk, aux)
+        val pubXOnly = Secp256k1.pubkeyCreate(sk).copyOfRange(1, 33)
+        // Sanity: acinq must accept its own signature.
+        check(acinq.verifySchnorr(sig, msg, pubXOnly))
+        Log.i(tag, "verifySchnorr: 2048 calls, must return true each time")
+        repeat(2048) { i ->
+            val ok = Secp256k1.verifySchnorr(sig, msg, pubXOnly)
+            check(ok) { "iter $i: verifySchnorr returned false on valid sig" }
+            if (i % 256 == 255) Log.i(tag, "verifySchnorr: ${i + 1} done")
+        }
+    }
+
+    /** NUT-13 deterministic-secret derivation tweaks scalars; must match acinq byte-for-byte. */
+    @Test
+    fun q_privKeyTweakAdd_2048() {
+        val acinq =
+            fr.acinq.secp256k1.Secp256k1
+                .get()
+        val sk = Bdhke.randomScalar()
+        val tweak = Bdhke.randomScalar()
+        val acinqOut = acinq.privKeyTweakAdd(sk.copyOf(), tweak)
+        Log.i(tag, "privKeyTweakAdd: 2048 calls, comparing 32 bytes vs acinq")
+        repeat(2048) { i ->
+            val ours = Secp256k1.privKeyTweakAdd(sk, tweak)
+            check(ours.contentEquals(acinqOut)) {
+                "iter $i: privKeyTweakAdd diverged from acinq"
+            }
+            if (i % 256 == 255) Log.i(tag, "privKeyTweakAdd: ${i + 1} done")
+        }
+    }
+
+    /**
+     * NUT-12 mint-side DLEQ verification (Alice). Cashu-specific — no JNI
+     * reference exists. Self-consistency: a freshly signed DLEQ tuple must
+     * verify; corrupting any byte must reject.
+     */
+    @Test
+    fun r_verifyDleq_2048() {
+        val mintPriv = Bdhke.randomScalar()
+        val mintPubCompressed = Secp256k1.pubKeyCompress(Secp256k1.pubkeyCreate(mintPriv))
+        val r = Bdhke.randomScalar()
+        val bTick = Bdhke.blind(Bdhke.randomScalar(), r)
+        val (cTick, e, s) = Bdhke.signFull(bTick, mintPriv)
+        check(Bdhke.verifyDleq(e, s, bTick, cTick, mintPubCompressed)) {
+            "setup: signFull→verifyDleq must roundtrip"
+        }
+        val tampered = e.copyOf().also { it[0] = (it[0].toInt() xor 0xFF).toByte() }
+        check(!Bdhke.verifyDleq(tampered, s, bTick, cTick, mintPubCompressed)) {
+            "setup: tampered e must be rejected"
+        }
+        Log.i(tag, "verifyDleq: 2048 calls — accept-valid + reject-tampered each iter")
+        repeat(2048) { i ->
+            check(Bdhke.verifyDleq(e, s, bTick, cTick, mintPubCompressed)) {
+                "iter $i: valid DLEQ rejected"
+            }
+            check(!Bdhke.verifyDleq(tampered, s, bTick, cTick, mintPubCompressed)) {
+                "iter $i: tampered DLEQ accepted"
+            }
+            if (i % 256 == 255) Log.i(tag, "verifyDleq: ${i + 1} done")
+        }
+    }
+
+    /**
+     * NIP-44 v2 cipher roundtrip. Cashu wallet/token/history events
+     * (kind:17375, 7375, 7376, 17376) are all encrypted with NIP-44 v2.
+     * The pipeline: secp256k1 ECDH (pure Kotlin) → HKDF-SHA256 → ChaCha20
+     * → HMAC-SHA256. ECDH path is already covered by [n_ecdhXOnly_2048] —
+     * this catches a JIT miscompile in the symmetric layer, or a key-
+     * derivation drift in the HKDF/HMAC primitives.
+     *
+     * Each iteration uses a fresh random nonce so ciphertext varies, but
+     * decrypt(encrypt(p)) must always return `p`.
+     */
+    @Test
+    fun t_nip44CipherRoundtrip_2048() {
+        val nip44 = Nip44v2()
+        val alicePriv = Bdhke.randomScalar()
+        val bobPriv = Bdhke.randomScalar()
+        val bobPub = Nip01Crypto.pubKeyCreate(bobPriv)
+        val conversationKey = nip44.getConversationKey(alicePriv, bobPub)
+        // ~200 byte plaintext is representative of a NIP-60 kind:7375 token
+        // payload (cashu proof array, mint URL, unit, memo).
+        val plaintext =
+            "Cashu kind:7375 token: mint=https://mint.example/v1 unit=sat proofs=[" +
+                "{a:1,id:00aabb,s:" + "deadbeef".repeat(8) + ",C:" + "ab".repeat(33) + "}]"
+        Log.i(tag, "nip44Cipher: 2048 encrypt+decrypt roundtrips (plaintext=${plaintext.length}B)")
+        repeat(2048) { i ->
+            val encrypted = nip44.encrypt(plaintext, conversationKey)
+            val decrypted = nip44.decrypt(encrypted, conversationKey)
+            check(decrypted == plaintext) {
+                "iter $i: nip44 roundtrip diverged — got '${decrypted.take(60)}…'"
+            }
+            if (i % 256 == 255) Log.i(tag, "nip44Cipher: ${i + 1} done")
+        }
+        Log.i(tag, "nip44Cipher: survived")
+    }
+
+    /**
+     * NUT-12 §3 Carol-side DLEQ verification. Composite path: internally
+     * calls `blind`, `addRTimesA`, and `verifyDleq`, so covers the private
+     * `addRTimesA` (also `ECPoint.mul`-bound) which has no other entry point.
+     */
+    @Test
+    fun s_verifyDleqCarol_2048() {
+        val mintPriv = Bdhke.randomScalar()
+        val mintPubCompressed = Secp256k1.pubKeyCompress(Secp256k1.pubkeyCreate(mintPriv))
+        val r = Bdhke.randomScalar()
+        val secret = Bdhke.randomScalar()
+        val bTick = Bdhke.blind(secret, r)
+        val (cTick, e, s) = Bdhke.signFull(bTick, mintPriv)
+        val unblindedC = Bdhke.unblind(cTick, r, mintPubCompressed)
+        check(Bdhke.verifyDleqCarol(secret, r, e, s, unblindedC, mintPubCompressed)) {
+            "setup: Carol-side DLEQ must roundtrip"
+        }
+        Log.i(tag, "verifyDleqCarol: 2048 calls — must verify each iter")
+        repeat(2048) { i ->
+            check(Bdhke.verifyDleqCarol(secret, r, e, s, unblindedC, mintPubCompressed)) {
+                "iter $i: Carol-side DLEQ rejected"
+            }
+            if (i % 256 == 255) Log.i(tag, "verifyDleqCarol: ${i + 1} done")
+        }
+    }
+
+    /**
+     * Same workload as [i_signOnly] but uses ACINQ's libsecp256k1 JNI binding
+     * instead of our pure-Kotlin [Secp256k1.pubKeyTweakMul]. If this is clean
+     * while `i_signOnly` crashes, we have direct proof the JIT crash lives in
+     * Kotlin code that ART tries to optimize — and the JNI swap is the fix.
+     */
+    @Test
+    fun l_signOnlyAcinq() {
+        val acinq =
+            fr.acinq.secp256k1.Secp256k1
+                .get()
+        Log.i(tag, "signOnlyAcinq: 2048 calls to acinq.pubKeyTweakMul (JNI libsecp256k1)")
+        val r = Bdhke.randomScalar()
+        val bTick = Bdhke.blind(Bdhke.randomScalar(), r)
+        val mintPriv = Bdhke.randomScalar()
+        repeat(2048) { i ->
+            acinq.pubKeyTweakMul(bTick, mintPriv)
+            if (i % 256 == 255) Log.i(tag, "signOnlyAcinq: ${i + 1} done")
+        }
+        Log.i(tag, "signOnlyAcinq: survived")
+    }
+}

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.model.nip60Cashu.CashuToken
 import com.vitorpamplona.amethyst.service.cashu.CashuParser
-import com.vitorpamplona.amethyst.service.cashu.CashuToken
 import com.vitorpamplona.amethyst.ui.components.GenericLoadable
 import kotlinx.collections.immutable.ImmutableList
 import kotlinx.coroutines.runBlocking

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

@@ -21,6 +21,8 @@
 package com.vitorpamplona.amethyst
 
 import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuMintDirectoryFilterAssembler
+import com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuWalletFilterAssembler
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.LocalCache
@@ -52,9 +54,10 @@ import org.junit.runner.RunWith
  * Asserts the three contracts the feature relies on:
  *   1. `feedKey` is mode-discriminated so each pinned tab caches independently.
  *   2. `followList()` honors `modeOverride` when set; falls back to the spinner setting otherwise.
- *   3. `buildFilterParams()` returns a GlobalTopNavFilter-backed FilterByListParams for
- *      `TopFilter.Global` (so `isGlobal()` is true, allowing non-follower notifications through),
- *      and a non-Global filter for `TopFilter.AllFollows` (forcing the follow-membership gate).
+ *   3. `buildFilterParams()` returns a GlobalTopNavFilter-backed FilterByListParams for both
+ *      `TopFilter.Global` and `TopFilter.Selected` (so `isGlobal()` is true, allowing
+ *      non-follower notifications through), and a non-Global filter for `TopFilter.AllFollows`
+ *      (forcing the follow-membership gate).
  */
 @RunWith(AndroidJUnit4::class)
 class NotificationFeedFilterModeOverrideTest {
@@ -80,6 +83,9 @@ class NotificationFeedFilterModeOverrideTest {
                 signer = NostrSignerInternal(keyPair),
                 geolocationFlow = { MutableStateFlow<LocationState.LocationResult>(LocationState.LocationResult.Loading) },
                 nwcFilterAssembler = { NWCPaymentFilterAssembler(client) },
+                cashuWalletFilterAssembler = { CashuWalletFilterAssembler(client) },
+                cashuMintDirectoryFilterAssembler = { CashuMintDirectoryFilterAssembler(client) },
+                okHttpClientForMoney = { OkHttpClient() },
                 otsResolverBuilder = { EmptyOtsResolverBuilder.build() },
                 cache = LocalCache,
                 client = client,
@@ -125,8 +131,8 @@ class NotificationFeedFilterModeOverrideTest {
     fun followListFallsBackToSpinnerWhenOverrideNull() {
         val spinner = NotificationFeedFilter(account)
 
-        account.settings.defaultNotificationFollowList.value = TopFilter.Global
-        assertEquals(TopFilter.Global, spinner.followList())
+        account.settings.defaultNotificationFollowList.value = TopFilter.Selected
+        assertEquals(TopFilter.Selected, spinner.followList())
 
         account.settings.defaultNotificationFollowList.value = TopFilter.AllFollows
         assertEquals(TopFilter.AllFollows, spinner.followList())
@@ -146,6 +152,22 @@ class NotificationFeedFilterModeOverrideTest {
         )
     }
 
+    @Test
+    fun buildFilterParamsForSelectedOverrideReportsGlobal() {
+        val selected = NotificationFeedFilter(account, TopFilter.Selected)
+
+        val params = selected.buildFilterParams(account)
+
+        // Selected rides the same GlobalFeedFlow relay set as Global, so it must
+        // also report isGlobal and let non-followers through; the difference is
+        // that acceptableEvent applies the per-kind relevance heuristics, which
+        // Global skips.
+        assertTrue(
+            "Selected mode's FilterByListParams must report isGlobal so non-followers pass the gate",
+            params.isGlobal(),
+        )
+    }
+
     @Test
     fun buildFilterParamsForAllFollowsOverrideIsNotGlobal() {
         val following = NotificationFeedFilter(account, TopFilter.AllFollows)

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

@@ -22,6 +22,8 @@ package com.vitorpamplona.amethyst
 
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import com.fasterxml.jackson.module.kotlin.readValue
+import com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuMintDirectoryFilterAssembler
+import com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuWalletFilterAssembler
 import com.vitorpamplona.amethyst.commons.viewmodels.thread.ThreadFeedFilter
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AccountSettings
@@ -72,6 +74,9 @@ class ThreadDualAxisChartAssemblerTest {
                 signer = NostrSignerInternal(keyPair),
                 geolocationFlow = { MutableStateFlow<LocationState.LocationResult>(LocationState.LocationResult.Loading) },
                 nwcFilterAssembler = { NWCPaymentFilterAssembler(client) },
+                cashuWalletFilterAssembler = { CashuWalletFilterAssembler(client) },
+                cashuMintDirectoryFilterAssembler = { CashuMintDirectoryFilterAssembler(client) },
+                okHttpClientForMoney = { OkHttpClient() },
                 otsResolverBuilder = { EmptyOtsResolverBuilder.build() },
                 cache = LocalCache,
                 client = client,

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

@@ -1,225 +0,0 @@
-/*
- * 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
-
-import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.text.AnnotatedString
-import androidx.test.ext.junit.runners.AndroidJUnit4
-import androidx.test.platform.app.InstrumentationRegistry
-import com.vitorpamplona.amethyst.model.LocalCache
-import com.vitorpamplona.amethyst.ui.actions.buildAnnotatedStringWithUrlHighlighting
-import com.vitorpamplona.quartz.nip01Core.core.toHexKey
-import com.vitorpamplona.quartz.nip01Core.metadata.MetadataEvent
-import com.vitorpamplona.quartz.nip01Core.metadata.UserMetadata
-import com.vitorpamplona.quartz.nip19Bech32.decodePublicKey
-import org.junit.Assert.assertEquals
-import org.junit.Test
-import org.junit.runner.RunWith
-
-/**
- * Instrumented test, which will execute on an Android device.
- *
- * See [testing documentation](http://d.android.com/tools/testing).
- */
-@RunWith(AndroidJUnit4::class)
-class UrlUserTagTransformationTest {
-    @Test
-    fun useAppContext() {
-        // Context of the app under test.
-        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
-        assertEquals("com.vitorpamplona.amethyst", appContext.packageName.removeSuffix(".debug"))
-    }
-
-    @Test
-    fun testKeepTransformedIndexFullyInsideTransformedText() {
-        val user =
-            LocalCache.getOrCreateUser(
-                decodePublicKey("npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z")
-                    .toHexKey(),
-            )
-        user.metadata().newMetadata(
-            UserMetadata().also {
-                it.displayName = "Vitor Pamplona"
-            },
-            MetadataEvent(
-                id = "",
-                pubKey = "",
-                createdAt = 0,
-                tags = emptyArray(),
-                content = "",
-                sig = "",
-            ),
-        )
-
-        val original = "@npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z"
-
-        val transformedText =
-            buildAnnotatedStringWithUrlHighlighting(
-                AnnotatedString(original),
-                Color.Red,
-            )
-
-        val expected = "@Vitor Pamplona"
-        assertEquals(expected, transformedText.text.text)
-
-        // The mention is treated as an atomic wedge: any cursor strictly inside the
-        // underlying npub snaps to the trailing edge of the displayed "@Vitor Pamplona"
-        // (and vice versa). This prevents an IME from placing the cursor in the middle
-        // of the bech32 and corrupting it on backspace.
-        assertEquals(0, transformedText.offsetMapping.originalToTransformed(0))
-        for (i in 1..63) {
-            assertEquals("originalToTransformed($i)", 15, transformedText.offsetMapping.originalToTransformed(i))
-        }
-        assertEquals(15, transformedText.offsetMapping.originalToTransformed(64))
-
-        assertEquals(0, transformedText.offsetMapping.transformedToOriginal(0))
-        for (i in 1..14) {
-            assertEquals("transformedToOriginal($i)", 64, transformedText.offsetMapping.transformedToOriginal(i))
-        }
-        assertEquals(64, transformedText.offsetMapping.transformedToOriginal(15))
-    }
-
-    @Test
-    fun transformationText() {
-        val user =
-            LocalCache.getOrCreateUser(
-                decodePublicKey("npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z")
-                    .toHexKey(),
-            )
-        user.metadata().newMetadata(
-            UserMetadata().also {
-                it.displayName = "Vitor Pamplona"
-            },
-            MetadataEvent(
-                id = "",
-                pubKey = "",
-                createdAt = 0,
-                tags = emptyArray(),
-                content = "",
-                sig = "",
-            ),
-        )
-
-        val transformedText =
-            buildAnnotatedStringWithUrlHighlighting(
-                AnnotatedString("New Hey @npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z"),
-                Color.Red,
-            )
-
-        assertEquals("New Hey @Vitor Pamplona", transformedText.text.text)
-
-        // Outside the wedge: identity mapping.
-        assertEquals(0, transformedText.offsetMapping.originalToTransformed(0)) // Before N
-        assertEquals(4, transformedText.offsetMapping.originalToTransformed(4)) // Before H
-        assertEquals(8, transformedText.offsetMapping.originalToTransformed(8)) // Before @ (boundary)
-
-        // Strictly inside the underlying npub: snaps to the end of "@Vitor Pamplona" (offset 23).
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(9)) // Before n
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(12)) // Before b
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(13)) // Before 1
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(71)) // Before z
-
-        // End-of-wedge boundary maps to end of displayed mention.
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(72))
-
-        // Outside the wedge in displayed: identity.
-        assertEquals(0, transformedText.offsetMapping.transformedToOriginal(0))
-        assertEquals(4, transformedText.offsetMapping.transformedToOriginal(4))
-        assertEquals(8, transformedText.offsetMapping.transformedToOriginal(8)) // Before @ (boundary)
-
-        // Strictly inside displayed "@Vitor Pamplona": snaps to end of underlying npub (offset 72).
-        assertEquals(72, transformedText.offsetMapping.transformedToOriginal(9))
-        assertEquals(72, transformedText.offsetMapping.transformedToOriginal(22))
-
-        // End-of-wedge boundary maps to end of underlying mention; past it shifts by deltas.
-        assertEquals(72, transformedText.offsetMapping.transformedToOriginal(23))
-        assertEquals(73, transformedText.offsetMapping.transformedToOriginal(24))
-    }
-
-    @Test
-    fun transformationTextTwoKeys() {
-        val user =
-            LocalCache.getOrCreateUser(
-                decodePublicKey("npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z")
-                    .toHexKey(),
-            )
-
-        user.metadata().newMetadata(
-            UserMetadata().also {
-                it.displayName = "Vitor Pamplona"
-            },
-            MetadataEvent(
-                id = "",
-                pubKey = "",
-                createdAt = 0,
-                tags = emptyArray(),
-                content = "",
-                sig = "",
-            ),
-        )
-
-        val transformedText =
-            buildAnnotatedStringWithUrlHighlighting(
-                AnnotatedString(
-                    "New Hey @npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z and @npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z",
-                ),
-                Color.Red,
-            )
-
-        assertEquals("New Hey @Vitor Pamplona and @Vitor Pamplona", transformedText.text.text)
-
-        // Strictly inside the first underlying npub [8, 72): snap to end of first
-        // displayed "@Vitor Pamplona" (offset 23).
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(11))
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(12))
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(13))
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(70))
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(71))
-
-        // Boundary at end of first wedge: end of first displayed mention.
-        assertEquals(23, transformedText.offsetMapping.originalToTransformed(72)) // Before <space>
-        assertEquals(24, transformedText.offsetMapping.originalToTransformed(73)) // Before a
-        assertEquals(25, transformedText.offsetMapping.originalToTransformed(74)) // Before n
-        assertEquals(26, transformedText.offsetMapping.originalToTransformed(75)) // Before d
-        assertEquals(27, transformedText.offsetMapping.originalToTransformed(76)) // Before <space>
-        assertEquals(28, transformedText.offsetMapping.originalToTransformed(77)) // Before @ (boundary, second wedge)
-
-        // Strictly inside the second underlying npub [77, 141): snap to end of second
-        // displayed "@Vitor Pamplona" (offset 43).
-        assertEquals(43, transformedText.offsetMapping.originalToTransformed(78)) // Before n
-        assertEquals(43, transformedText.offsetMapping.originalToTransformed(140))
-
-        // Strictly inside first displayed "@Vitor Pamplona" [8, 23): snap to end of
-        // first underlying npub (offset 72).
-        assertEquals(72, transformedText.offsetMapping.transformedToOriginal(22)) // Before a (display)
-        assertEquals(72, transformedText.offsetMapping.transformedToOriginal(23)) // Before <space>
-        assertEquals(73, transformedText.offsetMapping.transformedToOriginal(24)) // Before a
-        assertEquals(74, transformedText.offsetMapping.transformedToOriginal(25)) // Before n
-        assertEquals(75, transformedText.offsetMapping.transformedToOriginal(26)) // Before d
-        assertEquals(76, transformedText.offsetMapping.transformedToOriginal(27)) // Before <space>
-        assertEquals(77, transformedText.offsetMapping.transformedToOriginal(28)) // Before @ (boundary, second wedge)
-
-        // Strictly inside second displayed "@Vitor Pamplona" [28, 43): snap to end of
-        // second underlying npub (offset 141).
-        assertEquals(141, transformedText.offsetMapping.transformedToOriginal(29))
-        assertEquals(141, transformedText.offsetMapping.transformedToOriginal(42))
-    }
-}

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

@@ -0,0 +1,98 @@
+/*
+ * 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.service.images
+
+import android.graphics.drawable.Animatable
+import android.graphics.drawable.AnimatedImageDrawable
+import android.os.Build
+import androidx.core.net.toUri
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import coil3.ImageLoader
+import coil3.asDrawable
+import coil3.gif.AnimatedImageDecoder
+import coil3.request.ImageRequest
+import coil3.request.SuccessResult
+import coil3.size.ScaleDrawable
+import coil3.toBitmap
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.appContext
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.copyAssetToCache
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class AvifAnimatedDecodeInstrumentedTest {
+    private val avifLoader: ImageLoader by lazy {
+        ImageLoader
+            .Builder(appContext)
+            .components {
+                add(AvifAnimatedDecoderFactory())
+                add(AnimatedImageDecoder.Factory())
+            }.build()
+    }
+
+    @Test
+    fun stillAvifDecodesToBitmap() =
+        runBlocking {
+            assumeTrue("AVIF requires API 31+", Build.VERSION.SDK_INT >= 31)
+            val avif = copyAssetToCache("avif/still-tiny-8x8.avif")
+
+            val result =
+                avifLoader.execute(
+                    ImageRequest.Builder(appContext).data(avif.toUri()).build(),
+                )
+
+            assertTrue("Expected SuccessResult, got ${result::class.simpleName}", result is SuccessResult)
+            val bitmap = (result as SuccessResult).image.toBitmap()
+            assertEquals(8, bitmap.width)
+            assertEquals(8, bitmap.height)
+        }
+
+    @Test
+    fun animatedAvifDecodesToAnimatedImageDrawable() =
+        runBlocking {
+            assumeTrue("Animated AVIF requires API 31+", Build.VERSION.SDK_INT >= 31)
+            val avif = copyAssetToCache("avif/animated-tiny-3frames.avif")
+
+            val result =
+                avifLoader.execute(
+                    ImageRequest.Builder(appContext).data(avif.toUri()).build(),
+                )
+
+            assertTrue("Expected SuccessResult", result is SuccessResult)
+            val drawable = (result as SuccessResult).image.asDrawable(appContext.resources)
+            // AnimatedImageDecoder wraps AnimatedImageDrawable in a ScaleDrawable.
+            // Both are Animatable; a BitmapDrawable (the failure case) is not.
+            assertTrue(
+                "Animated AVIF must be Animatable — Coil's AvifAnimatedDecoderFactory was not invoked if this fails (got ${drawable::class.simpleName})",
+                drawable is Animatable,
+            )
+            // Unwrap ScaleDrawable to confirm the inner drawable is AnimatedImageDrawable.
+            val inner = if (drawable is ScaleDrawable) drawable.child else drawable
+            assertTrue(
+                "Inner drawable must be AnimatedImageDrawable, got ${inner::class.simpleName}",
+                inner is AnimatedImageDrawable,
+            )
+        }
+}

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

@@ -0,0 +1,89 @@
+/*
+ * 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.service.images
+
+import android.os.Build
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.appContext
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.copyAssetToCache
+import org.junit.After
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.io.File
+import java.util.UUID
+
+@RunWith(AndroidJUnit4::class)
+class ThumbnailDiskCacheAvifInstrumentedTest {
+    private lateinit var cacheDir: File
+    private lateinit var cache: ThumbnailDiskCache
+
+    @Before
+    fun setUp() {
+        cacheDir = File(appContext.cacheDir, "thumbnail-test-${UUID.randomUUID()}")
+        cache = ThumbnailDiskCache(cacheDir)
+    }
+
+    @After
+    fun tearDown() {
+        cacheDir.deleteRecursively()
+    }
+
+    @Test
+    fun animatedAvifIsNotCached() {
+        val url = "https://example.com/profile-pic-${UUID.randomUUID()}.avif"
+        val source = copyAssetToCache("avif/animated-tiny-3frames.avif")
+
+        val saved = cache.generateFromFile(url, source)
+
+        assertFalse(
+            "generateFromFile must return false for animated AVIF (would otherwise freeze avatar on first frame)",
+            saved,
+        )
+        assertNull(
+            "load() must return null for an animated-AVIF URL that was skipped",
+            cache.load(url),
+        )
+    }
+
+    @Test
+    fun stillAvifIsCachedAsBitmap() {
+        // generateFromFile uses BitmapFactory.decodeFile to read the source,
+        // which requires platform AVIF decode support (API 31+). On older
+        // devices the still-AVIF path returns false because decode fails,
+        // not because of the animated-skip branch.
+        assumeTrue("Still AVIF decode requires API 31+", Build.VERSION.SDK_INT >= 31)
+
+        val url = "https://example.com/profile-pic-${UUID.randomUUID()}.avif"
+        val source = copyAssetToCache("avif/still-tiny-8x8.avif")
+
+        val saved = cache.generateFromFile(url, source)
+
+        assertTrue("generateFromFile must return true for still AVIF", saved)
+        val bitmap = cache.load(url)
+        assertNotNull("load() must return a non-null Bitmap for a cached still AVIF", bitmap)
+    }
+}

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

@@ -0,0 +1,80 @@
+/*
+ * 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.service.images
+
+import android.graphics.Bitmap
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.After
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.io.File
+import java.util.UUID
+
+@RunWith(AndroidJUnit4::class)
+class ThumbnailDiskCacheInstrumentedTest {
+    private val appContext = InstrumentationRegistry.getInstrumentation().targetContext
+    private lateinit var cacheDir: File
+    private lateinit var cache: ThumbnailDiskCache
+    private lateinit var sourceFile: File
+
+    @Before
+    fun setUp() {
+        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)
+        sourceFile.outputStream().use { bitmap.compress(Bitmap.CompressFormat.JPEG, 90, it) }
+        bitmap.recycle()
+    }
+
+    @After
+    fun tearDown() {
+        cacheDir.deleteRecursively()
+        sourceFile.delete()
+    }
+
+    @Test
+    fun generatesThumbnailFromJpeg() {
+        val url = "https://example.com/profile-pic-${UUID.randomUUID()}.jpg"
+
+        assertTrue("generateFromFile must return true for a valid JPEG", cache.generateFromFile(url, sourceFile))
+        assertNotNull("load() must return a non-null Bitmap for a cached JPEG", cache.load(url))
+    }
+
+    @Test
+    fun recreatesCacheDirClearedAtRuntime() {
+        // The system (cache trim) or the user (Settings > Clear cache) can delete
+        // the cache dir while the app runs; the next write must recreate it
+        // instead of failing with ENOENT.
+        val url = "https://example.com/profile-pic-${UUID.randomUUID()}.jpg"
+        assertTrue(cacheDir.deleteRecursively())
+
+        assertTrue(
+            "generateFromFile must recreate the cache dir after it is cleared at runtime",
+            cache.generateFromFile(url, sourceFile),
+        )
+        assertNotNull("load() must return the thumbnail written after dir recreation", cache.load(url))
+    }
+}

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/service/uploads/AvifMetadataStripperPoisonedFixtureInstrumentedTest.kt

@@ -0,0 +1,54 @@
+/*
+ * 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.service.uploads
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.appContext
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.contentUriFor
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.copyAssetToCache
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertThrows
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class AvifMetadataStripperPoisonedFixtureInstrumentedTest {
+    @Test
+    fun stripDispatcherThrowsAvifMetadataNotVerifiableExceptionForPoisonedAvif() {
+        // Regression for commit b9112550b: NewUserMetadataViewModel calls
+        // MetadataStripper.strip(uri, "image/avif", context) at line 218.
+        // The viewmodel only catches AvifMetadataNotVerifiableException to
+        // surface the AVIF-specific error string; any other exception type
+        // would fall through to "Upload cancelled" and confuse the user.
+        //
+        // Note: strip() dispatches by mimeType param, then internally
+        // stripImageMetadata() re-resolves via contentResolver.getType(uri).
+        // A content:// URI (FileProvider) is required so getType() returns
+        // "image/avif" and the AVIF inspection branch is reached.
+        val avif = copyAssetToCache("avif/still-tiny-8x8-exif-gps.avif")
+        val uri = contentUriFor(avif)
+        val ex =
+            assertThrows(AvifMetadataNotVerifiableException::class.java) {
+                MetadataStripper.strip(uri, AVIF_MIME, appContext)
+            }
+        assertNotNull("Exception must have a non-null message for UI display", ex.message)
+    }
+}

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/service/uploads/AvifUploadPipelineInstrumentedTest.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.service.uploads
+
+import android.os.Build
+import androidx.core.net.toUri
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.appContext
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.contentUriFor
+import com.vitorpamplona.amethyst.AvifInstrumentedTestSupport.copyAssetToCache
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.io.File
+
+@RunWith(AndroidJUnit4::class)
+class AvifUploadPipelineInstrumentedTest {
+    /**
+     * Drives [assetPath] through [MediaCompressor.compress] with [AVIF_MIME] and asserts the
+     * bytes survive unchanged. AVIF must bypass JPEG re-encoding regardless of whether the
+     * source is still or animated.
+     */
+    private fun assertAvifBytesPreserved(
+        assetPath: String,
+        description: String,
+    ) = runBlocking {
+        val avif = copyAssetToCache(assetPath)
+        val originalBytes = avif.readBytes()
+
+        val result =
+            MediaCompressor().compress(
+                uri = avif.toUri(),
+                contentType = AVIF_MIME,
+                applicationContext = appContext,
+                mediaQuality = CompressorQuality.MEDIUM,
+            )
+
+        assertEquals(AVIF_MIME, result.contentType)
+        val resultBytes = File(result.uri.path!!).readBytes()
+        assertTrue(description, originalBytes.contentEquals(resultBytes))
+    }
+
+    @Test
+    fun stillAvifPassesThroughMediaCompressorUnchanged() =
+        assertAvifBytesPreserved(
+            "avif/still-tiny-8x8.avif",
+            "Still AVIF bytes must be preserved through MediaCompressor",
+        )
+
+    @Test
+    fun animatedAvifPassesThroughMediaCompressorUnchanged() =
+        assertAvifBytesPreserved(
+            "avif/animated-tiny-3frames.avif",
+            "Animated AVIF bytes must be preserved (headline regression to prevent)",
+        )
+
+    @Test
+    fun avifMetadataStripperReturnsCleanFile() {
+        // Use a content:// URI via FileProvider so contentResolver.getType() returns AVIF_MIME.
+        // ContentResolver.getType() returns null for file:// URIs even on API 36 (AVIF is not
+        // recognised via MimeTypeMap for the file:// scheme). FileProvider uses
+        // MimeTypeMap.getSingleton().getMimeTypeFromExtension("avif") which returns "image/avif"
+        // on API 31+, matching production behaviour (gallery pickers always deliver content://).
+        val avif = copyAssetToCache("avif/still-tiny-8x8.avif")
+        val uri = contentUriFor(avif)
+        val result = MetadataStripper.stripImageMetadata(uri, appContext)
+        assertTrue("Clean AVIF should be marked stripped=true", result.stripped)
+        assertEquals("Clean AVIF URI should be the original", uri, result.uri)
+    }
+
+    @Test
+    fun avifPreviewMetadataGeneratesBlurhashAndThumbhash() {
+        assumeTrue("AVIF decoding requires API 31+", Build.VERSION.SDK_INT >= 31)
+        val avif = copyAssetToCache("avif/still-tiny-8x8.avif")
+
+        val result =
+            PreviewMetadataCalculator.computeFromUri(
+                context = appContext,
+                uri = avif.toUri(),
+                mimeType = AVIF_MIME,
+            )
+
+        assertNotNull("PreviewMetadataCalculator must return non-null on API 31+", result)
+        assertNotNull("AVIF blurhash should be generated via ImageDecoder", result!!.blurhash)
+        assertNotNull("AVIF thumbhash should be generated via ImageDecoder", result.thumbhash)
+        assertNotNull("AVIF dimensions should be returned", result.dim)
+        assertEquals(8, result.dim!!.width)
+        assertEquals(8, result.dim.height)
+    }
+
+    @Test
+    fun poisonedAvifMetadataStripperThrowsAvifMetadataNotVerifiableException() {
+        val avif = copyAssetToCache("avif/still-tiny-8x8-exif-gps.avif")
+        val ex =
+            assertThrows(AvifMetadataNotVerifiableException::class.java) {
+                MetadataStripper.stripImageMetadata(contentUriFor(avif), appContext)
+            }
+        assertNotNull("Exception must have a non-null message", ex.message)
+    }
+}

amethyst/src/androidTest/java/com/vitorpamplona/amethyst/tor/TorBootstrapInstrumentedTest.kt

@@ -0,0 +1,176 @@
+/*
+ * 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.tor
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.filters.LargeTest
+import androidx.test.platform.app.InstrumentationRegistry
+import com.vitorpamplona.amethyst.ui.tor.TorService
+import com.vitorpamplona.amethyst.ui.tor.TorServiceStatus
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeout
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Ignore
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.net.InetSocketAddress
+import java.net.Proxy
+import java.util.concurrent.TimeUnit
+import kotlin.system.measureTimeMillis
+
+/**
+ * Real-Arti bootstrap + SOCKS round trip on-device. Verifies that the self-heal /
+ * destroy / re-init paths work end-to-end against the actual native lib.
+ *
+ * **This test is [Ignore]'d by default** because:
+ *   - It needs network egress to the Tor network from the device/emulator. Many CI
+ *     environments don't have it.
+ *   - Bootstrap on a cold device can take 30-120s; the test costs real wall-clock time.
+ *   - It depends on `check.torproject.org` being reachable.
+ *
+ * **To run manually:**
+ *   1. Connect a device or start an emulator that has internet egress to Tor.
+ *   2. Remove the `@Ignore` annotation below.
+ *   3. `./gradlew :amethyst:connectedPlayDebugAndroidTest -P android.testInstrumentationRunnerArguments.class=com.vitorpamplona.amethyst.tor.TorBootstrapInstrumentedTest`
+ *
+ * **What it covers that [TorManagerTest] does not:**
+ *   - Real `ArtiNative.initialize` → `create_bootstrapped` → SOCKS listener bind.
+ *   - Real rustls `CryptoProvider` install (regression check after the arti-v2.3.0 bump).
+ *   - Real `destroy()` releasing the state file lock so a second `initialize()` succeeds.
+ *   - OkHttp routing traffic through the SOCKS port and Arti exiting through the
+ *     Tor network.
+ *
+ * **Companion fast tests:** `amethyst/src/test/.../tor/TorManagerTest.kt` covers the
+ * Kotlin-side self-heal logic (watchdog, cooldown, network change, status routing)
+ * with virtual time and in-memory fakes — no Arti required.
+ */
+@RunWith(AndroidJUnit4::class)
+@LargeTest
+@Ignore("Tier-3 integration test — requires on-device network access to Tor. See class kdoc to enable.")
+class TorBootstrapInstrumentedTest {
+    private val context = InstrumentationRegistry.getInstrumentation().targetContext
+    private val torService = TorService(context)
+
+    @After
+    fun tearDown() =
+        runBlocking {
+            // Drop the native client so this test's state file lock doesn't bleed into
+            // the next instrumented run on the same device.
+            torService.reset()
+        }
+
+    /**
+     * Cold-start bootstrap. The whole point of the custom Arti build is that this
+     * works at all — if create_bootstrapped panics (e.g., because we forgot to install
+     * a rustls CryptoProvider after an arti bump) the test catches it.
+     */
+    @Test
+    fun bootstraps_to_Active_within_120s() =
+        runBlocking(Dispatchers.IO) {
+            val elapsed =
+                measureTimeMillis {
+                    torService.start()
+                    val active =
+                        withTimeout(BOOTSTRAP_TIMEOUT_MS) {
+                            torService.status.first { it is TorServiceStatus.Active }
+                        } as TorServiceStatus.Active
+                    assertTrue("SOCKS port should be > 0", active.port > 0)
+                }
+            // Logged via assertEquals failure-on-too-slow; an actual `Log.i` would be invisible.
+            // Bootstrap should comfortably fit in 120s on a healthy network.
+            assertTrue("Bootstrap took ${elapsed}ms, expected < ${BOOTSTRAP_TIMEOUT_MS}ms", elapsed < BOOTSTRAP_TIMEOUT_MS)
+        }
+
+    /**
+     * SOCKS round-trip through Tor. Hits `check.torproject.org` which returns a JSON
+     * payload including `"IsTor":true` when the request actually exited via Tor.
+     * Catches regressions where the listener binds but no traffic flows (e.g., a
+     * broken handler-spawn race, or a crypto provider mismatch on the TLS handshake).
+     */
+    @Test
+    fun proxies_HTTPS_through_Tor_and_reports_IsTor_true() =
+        runBlocking(Dispatchers.IO) {
+            torService.start()
+            val active =
+                withTimeout(BOOTSTRAP_TIMEOUT_MS) {
+                    torService.status.first { it is TorServiceStatus.Active }
+                } as TorServiceStatus.Active
+
+            val client =
+                OkHttpClient
+                    .Builder()
+                    .proxy(Proxy(Proxy.Type.SOCKS, InetSocketAddress("127.0.0.1", active.port)))
+                    .connectTimeout(30, TimeUnit.SECONDS)
+                    .readTimeout(30, TimeUnit.SECONDS)
+                    .build()
+
+            val request =
+                Request
+                    .Builder()
+                    .url("https://check.torproject.org/api/ip")
+                    .build()
+
+            val body =
+                client.newCall(request).execute().use { resp ->
+                    assertEquals("HTTP 200", 200, resp.code)
+                    resp.body.string()
+                }
+            assertTrue(
+                "Response should report IsTor:true — actual body: $body",
+                body.contains("\"IsTor\":true"),
+            )
+        }
+
+    /**
+     * Verifies the destroy → re-init cycle that backs the self-heal path. After
+     * [TorService.reset], the next [TorService.start] must rebuild the TorClient and
+     * bring SOCKS back to Active — without a "state file already locked" error from
+     * the still-alive previous client.
+     */
+    @Test
+    fun reset_then_re_start_brings_SOCKS_back_to_Active() =
+        runBlocking(Dispatchers.IO) {
+            torService.start()
+            withTimeout(BOOTSTRAP_TIMEOUT_MS) {
+                torService.status.first { it is TorServiceStatus.Active }
+            }
+
+            torService.reset()
+            assertEquals(TorServiceStatus.Off, torService.status.value)
+
+            torService.start()
+            val second =
+                withTimeout(BOOTSTRAP_TIMEOUT_MS) {
+                    torService.status.first { it is TorServiceStatus.Active }
+                } as TorServiceStatus.Active
+            assertTrue("Second bootstrap port valid", second.port > 0)
+        }
+
+    companion object {
+        private const val BOOTSTRAP_TIMEOUT_MS: Long = 120_000L
+    }
+}

amethyst/src/fdroid/java/com/vitorpamplona/amethyst/service/notifications/PushNotificationUtils.kt

@@ -21,7 +21,7 @@
 package com.vitorpamplona.amethyst.service.notifications
 
 import com.vitorpamplona.amethyst.AccountInfo
-import com.vitorpamplona.amethyst.service.retryIfException
+import com.vitorpamplona.amethyst.commons.util.retryIfException
 import kotlinx.coroutines.Dispatchers
 import okhttp3.OkHttpClient
 

amethyst/src/fdroid/java/com/vitorpamplona/amethyst/ui/components/SelectNotificationProvider.kt

@@ -59,7 +59,7 @@ import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.model.UiSettingsFlow
 import com.vitorpamplona.amethyst.service.notifications.PushDistributorHandler
-import com.vitorpamplona.amethyst.ui.screen.loggedIn.settings.SettingsRow
+import com.vitorpamplona.amethyst.ui.screen.loggedIn.settings.SettingsBlockTile
 import com.vitorpamplona.amethyst.ui.stringRes
 import com.vitorpamplona.quartz.utils.Log
 import kotlinx.collections.immutable.ImmutableList
@@ -207,24 +207,34 @@ fun LoadDistributors(onInner: @Composable (String, ImmutableList<String>, Immuta
     )
 }
 
+fun hasPushNotificationProvider(): Boolean = true
+
 @Composable
-fun PushNotificationSettingsRow(sharedPrefs: UiSettingsFlow) {
+fun PushNotificationProviderTile(sharedPrefs: UiSettingsFlow) {
     val context = LocalContext.current
 
     LoadDistributors { currentDistributor, list, readableListWithExplainer ->
-        SettingsRow(
-            R.string.push_server_title,
-            R.string.push_server_explainer,
-            selectedItems = readableListWithExplainer,
-            selectedIndex = list.indexOf(currentDistributor),
-        ) { index ->
-            if (list[index] == "None") {
-                sharedPrefs.dontAskForNotificationPermissions()
-                sharedPrefs.dontShowPushNotificationSelector()
-                PushDistributorHandler.forceRemoveDistributor(context)
-            } else {
-                PushDistributorHandler.saveDistributor(list[index])
-            }
+        val selectedIndex = list.indexOf(currentDistributor).coerceAtLeast(0)
+        SettingsBlockTile(
+            icon = MaterialSymbols.CloudSync,
+            title = stringRes(R.string.push_server_title),
+            description = stringRes(R.string.push_server_explainer),
+        ) {
+            TextSpinner(
+                label = null,
+                placeholder = readableListWithExplainer[selectedIndex].title,
+                options = readableListWithExplainer,
+                onSelect = { index ->
+                    if (list[index] == "None") {
+                        sharedPrefs.dontAskForNotificationPermissions()
+                        sharedPrefs.dontShowPushNotificationSelector()
+                        PushDistributorHandler.forceRemoveDistributor(context)
+                    } else {
+                        PushDistributorHandler.saveDistributor(list[index])
+                    }
+                },
+                modifier = Modifier.fillMaxWidth(),
+            )
         }
     }
 }

amethyst/src/fdroid/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/settings/LegalSettingsSection.kt

@@ -0,0 +1,27 @@
+/*
+ * 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.ui.screen.loggedIn.settings
+
+import androidx.compose.ui.platform.UriHandler
+
+// F-Droid distributes Amethyst as MIT-licensed free software; the build must
+// not surface links to external (e.g. GitHub-hosted) policy documents.
+fun legalSettingsCategory(uriHandler: UriHandler): SettingsCategory? = null

amethyst/src/fdroid/java/com/vitorpamplona/amethyst/ui/screen/loggedOff/legal/TermsGate.kt

@@ -0,0 +1,35 @@
+/*
+ * 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.ui.screen.loggedOff.legal
+
+import androidx.compose.runtime.Composable
+
+// F-Droid distributes Amethyst as MIT-licensed free software; there is no
+// terms-of-use acceptance layered on top of the source license, and the build
+// must not link to any external (e.g. GitHub) policy document.
+@Composable
+@Suppress("UNUSED_PARAMETER")
+fun TermsGate(
+    checked: Boolean,
+    onCheckedChange: (Boolean) -> Unit,
+    showError: Boolean,
+) {
+}

amethyst/src/main/AndroidManifest.xml

@@ -3,6 +3,11 @@
     xmlns:tools="http://schemas.android.com/tools">
     <queries>
         <package android:name="org.torproject.android"/>
+        <!-- Health Connect data store (Android 8–13 ships it as a separate system app) -->
+        <package android:name="com.google.android.apps.healthdata" />
+        <intent>
+            <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
+        </intent>
         <intent>
             <action android:name="android.intent.action.VIEW" />
             <category android:name="android.intent.category.BROWSABLE" />
@@ -73,6 +78,16 @@
     <!-- Adds Geohash to posts if active -->
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 
+    <!-- Reads finished workouts from Health Connect to suggest a kind 1301 post.
+         Read-only; requested on demand, never on cold start. -->
+    <uses-permission android:name="android.permission.health.READ_EXERCISE" />
+    <uses-permission android:name="android.permission.health.READ_DISTANCE" />
+    <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED" />
+    <uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED" />
+    <uses-permission android:name="android.permission.health.READ_HEART_RATE" />
+    <uses-permission android:name="android.permission.health.READ_STEPS" />
+    <uses-permission android:name="android.permission.health.READ_ELEVATION_GAINED" />
+
     <!-- Old permission to access media -->
     <uses-permission
         android:name="android.permission.WRITE_EXTERNAL_STORAGE"
@@ -109,6 +124,11 @@
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
 
+            <!-- Health Connect privacy-policy rationale (required by Google when reading health data) -->
+            <intent-filter>
+                <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
+            </intent-filter>
+
             <intent-filter android:label="Amethyst">
                 <action android:name="android.intent.action.VIEW" />
                 <category android:name="android.intent.category.DEFAULT" />
@@ -218,6 +238,50 @@
             </intent-filter>
         </activity>
 
+        <!-- "Send as DM" share target. The android:name simple class ("ShareAsDMAlias")
+             is matched at runtime by ShareIntentRouting.SHARE_AS_DM_ALIAS_SIMPLE_NAME;
+             keep the two in sync when renaming. -->
+        <activity-alias
+            android:name=".ui.ShareAsDMAlias"
+            android:exported="true"
+            android:label="@string/share_target_as_dm"
+            android:targetActivity=".ui.MainActivity">
+
+            <intent-filter android:label="@string/share_target_as_dm">
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="text/plain" />
+            </intent-filter>
+
+            <intent-filter android:label="@string/share_target_as_dm">
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="image/*" />
+            </intent-filter>
+
+            <intent-filter android:label="@string/share_target_as_dm">
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="video/*" />
+            </intent-filter>
+        </activity-alias>
+
+        <!-- Health Connect privacy-policy rationale on Android 14+. Without this activity-alias
+             the permission request fails silently (no dialog appears). The system launches it,
+             guarded by START_VIEW_PERMISSION_USAGE, to show our privacy policy; it routes into
+             MainActivity. Android 13 and lower use the ACTION_SHOW_PERMISSIONS_RATIONALE
+             intent-filter declared on MainActivity above. -->
+        <activity-alias
+            android:name="ViewPermissionUsageActivity"
+            android:exported="true"
+            android:targetActivity=".ui.MainActivity"
+            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
+                <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
+            </intent-filter>
+        </activity-alias>
+
         <activity
             android:name="com.journeyapps.barcodescanner.CaptureActivity"
             android:screenOrientation="fullSensor"

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

@@ -26,11 +26,13 @@ import coil3.disk.DiskCache
 import coil3.memory.MemoryCache
 import com.vitorpamplona.amethyst.commons.model.NoteState
 import com.vitorpamplona.amethyst.commons.robohash.CachedRobohash
+import com.vitorpamplona.amethyst.commons.service.lnurl.OkHttpLnurlEndpointResolver
 import com.vitorpamplona.amethyst.commons.tor.TorSettings
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.UiSettings
 import com.vitorpamplona.amethyst.model.accountsCache.AccountCacheState
+import com.vitorpamplona.amethyst.model.nip03Timestamp.BitcoinExplorerEndpoint
 import com.vitorpamplona.amethyst.model.nip03Timestamp.IncomingOtsEventVerifier
 import com.vitorpamplona.amethyst.model.nip03Timestamp.TorAwareOkHttpOtsResolverBuilder
 import com.vitorpamplona.amethyst.model.nip11RelayInfo.Nip11CachedRetriever
@@ -66,6 +68,7 @@ import com.vitorpamplona.amethyst.service.playback.pip.BackgroundMedia
 import com.vitorpamplona.amethyst.service.playback.service.PlaybackServiceClient
 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.notifyCommand.model.NotifyCoordinator
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.RelaySubscriptionsCoordinator
@@ -83,6 +86,7 @@ import com.vitorpamplona.amethyst.ui.screen.AccountSessionManager
 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.quartz.nip01Core.core.Address
 import com.vitorpamplona.quartz.nip01Core.relay.client.INostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
@@ -91,14 +95,24 @@ import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.RelayOfflineT
 import com.vitorpamplona.quartz.nip01Core.relay.client.reqs.stats.RelayReqStats
 import com.vitorpamplona.quartz.nip01Core.relay.client.stats.RelayStats
 import com.vitorpamplona.quartz.nip03Timestamp.VerificationStateCache
+import com.vitorpamplona.quartz.nip03Timestamp.okhttp.OkHttpBitcoinExplorer
 import com.vitorpamplona.quartz.nip03Timestamp.ots.OtsBlockHeightCache
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.Nip05Client
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.OkHttpNip05Fetcher
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.CompositeNamecoinBackend
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.DEFAULT_ELECTRUMX_SERVERS
 import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.ElectrumXClient
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.ElectrumxNameBackend
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.ElectrumxServer
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.IElectrumXClient
+import com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.NameShowResult
+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.nipB7Blossom.BlossomServersEvent
+import com.vitorpamplona.quartz.nipBCOnchainZaps.chain.CachingOnchainBackend
+import com.vitorpamplona.quartz.nipBCOnchainZaps.chain.EsploraBackend
 import com.vitorpamplona.quartz.utils.Log
 import kotlinx.coroutines.CoroutineExceptionHandler
 import kotlinx.coroutines.CoroutineScope
@@ -185,12 +199,12 @@ class AppModules(
         UiSettingsState(uiPrefs.value, connManager.isMobileOrFalse, applicationIOScope)
     }
 
-    val torManager = TorManager(torPrefs, appContext, applicationIOScope)
+    val torManager = TorManager(torPrefs, TorService(appContext), applicationIOScope)
 
-    // Whenever the underlying network identity changes (wifi↔cellular, regained from
-    // offline, etc.) we clear any active Tor session bypass so the manager re-attempts
-    // bootstrap on the new network. The remembered-approval window is unaffected: if Tor
-    // stays stuck we will silently bypass again after the timeout fires.
+    // Network identity change (wifi↔cellular, regained from offline, captive portal
+    // cleared) — the old network's guards/circuits are dead, and Arti's in-memory
+    // client + on-disk state/ both need a fresh start. onNetworkChange drops the
+    // TorClient, clears the bypass + persisted approval, and triggers a full re-init.
     init {
         applicationIOScope.launch {
             connManager.status
@@ -198,7 +212,7 @@ class AppModules(
                 .filterNotNull()
                 .distinctUntilChanged()
                 .drop(1)
-                .collect { torManager.clearSessionBypass() }
+                .collect { torManager.onNetworkChange() }
         }
     }
 
@@ -260,13 +274,105 @@ class AppModules(
         client
     }
 
+    /**
+     * Long-lived Namecoin Core JSON-RPC client. The current
+     * [NamecoinCoreRpcConfig] is pushed in via [setConfig] each time the
+     * user saves settings; this avoids reading SharedPreferences on the
+     * hot lookup path.
+     */
+    val namecoinCoreRpcClient by lazy {
+        Log.d("AppModules", "NamecoinCoreRpcClient Init")
+        val client =
+            NamecoinCoreRpcClient(
+                httpClientForUrl = roleBasedHttpClientBuilder::okHttpClientForNip05,
+            )
+        // Bootstrap the active config and the pinned trust store from the
+        // same shared SharedPreferences entry the ElectrumX client uses.
+        // Mirrors the ElectrumXClient init path above so user-pinned certs
+        // are available on both backends after process restart.
+        applicationIOScope.launch {
+            try {
+                client.setConfig(namecoinPrefs.current.namecoinCoreRpc)
+                val pinnedCerts = namecoinPrefs.loadPinnedCerts()
+                if (pinnedCerts.isNotEmpty()) {
+                    client.setDynamicCerts(pinnedCerts)
+                }
+            } catch (_: Exception) {
+                // Non-fatal — user can re-pin via Settings.
+            }
+        }
+        client
+    }
+
+    /**
+     * Compose the active Namecoin lookup backend based on user settings.
+     *
+     * The returned [IElectrumXClient] is what the resolver actually calls.
+     * It dispatches to either Namecoin Core RPC or ElectrumX (custom-only,
+     * default-only, or both) and applies the user's fallback policy.
+     *
+     * The function builds a fresh composite per call so that settings
+     * changes take effect immediately (no app restart required).
+     */
+    fun buildNamecoinBackend(): IElectrumXClient {
+        val settings = namecoinPrefs.current
+        val custom = settings.toElectrumxServers()
+        val defaults =
+            if (roleBasedHttpClientBuilder.shouldUseTorForNIP05("https://electrumx.example.com")) {
+                TOR_ELECTRUMX_SERVERS
+            } else {
+                DEFAULT_ELECTRUMX_SERVERS
+            }
+
+        val customExBackend =
+            custom?.let { servers -> ElectrumxNameBackend(electrumXClient) { servers } }
+        val defaultExBackend = ElectrumxNameBackend(electrumXClient) { defaults }
+
+        return when (settings.backend) {
+            NamecoinBackend.NAMECOIN_CORE_RPC -> {
+                // Refresh client config in case the user just saved it.
+                namecoinCoreRpcClient.setConfig(settings.namecoinCoreRpc)
+                CompositeNamecoinBackend(
+                    primary = namecoinCoreRpcClient,
+                    customElectrumx = customExBackend,
+                    defaultElectrumx = defaultExBackend,
+                    policy = settings.toFallbackPolicy(),
+                    isPrimaryCoreRpc = true,
+                )
+            }
+
+            NamecoinBackend.ELECTRUMX -> {
+                // Custom servers first (if any). If the user only has the public
+                // defaults configured, primary == defaultElectrumx and the
+                // fallback toggle is moot.
+                val primary: com.vitorpamplona.quartz.nip05DnsIdentifiers.namecoin.NamecoinNameBackend =
+                    customExBackend ?: defaultExBackend
+                CompositeNamecoinBackend(
+                    primary = primary,
+                    customElectrumx = null,
+                    defaultElectrumx = if (customExBackend != null) defaultExBackend else null,
+                    policy = settings.toFallbackPolicy(),
+                    isPrimaryCoreRpc = false,
+                )
+            }
+        }
+    }
+
     val namecoinResolver by
         lazy {
             Log.d("AppModules", "Namecoin Resolver Init")
             NamecoinNameResolver(
-                electrumxClient = electrumXClient,
+                electrumxClient =
+                    object : IElectrumXClient {
+                        override suspend fun nameShowWithFallback(
+                            identifier: String,
+                            servers: List<ElectrumxServer>,
+                        ): NameShowResult? = buildNamecoinBackend().nameShowWithFallback(identifier, servers)
+                    },
                 serverListProvider = {
-                    // User-configured custom servers take priority
+                    // Kept for compatibility with NamecoinNameResolver's API;
+                    // the composite backend ignores this and consults user
+                    // settings directly via buildNamecoinBackend().
                     namecoinPrefs.customServersOrNull
                         ?: if (roleBasedHttpClientBuilder.shouldUseTorForNIP05("https://electrumx.example.com")) {
                             TOR_ELECTRUMX_SERVERS
@@ -322,24 +428,80 @@ class AppModules(
 
     // Connects the INostrClient class with okHttp
     val websocketBuilder =
-        OkHttpWebSocket.Builder { url ->
-            val useTor = torEvaluatorFlow.flow.value.useTor(url)
-            okHttpClientForRelays.getHttpClient(useTor)
-        }
+        OkHttpWebSocket.Builder(
+            httpClient = { url ->
+                val useTor = torEvaluatorFlow.shouldUseTorForRelay(url)
+                okHttpClientForRelays.getHttpClient(useTor)
+            },
+            // Don't dial Tor-routed relays until Tor's SOCKS port is up. Otherwise the
+            // whole Tor-routed relay set is hammered with doomed dials against the dead
+            // proxy during bootstrap. RelayProxyClientConnector reconnects them (with
+            // ignoreRetryDelays=true) the instant Tor flips to Active.
+            canDial = { url ->
+                !torEvaluatorFlow.shouldUseTorForRelay(url) || torManager.isSocksReady()
+            },
+        )
 
     // Caches all events in Memory
     val cache: LocalCache = LocalCache
 
+    // NIP-BC onchain zap verification backend. Wired up once at app init so
+    // LocalCache.consume(OnchainZapEvent) can sum the on-chain output values
+    // that pay the recipient's derived Taproot address. Wrapped in a caching
+    // decorator so a feed full of onchain zaps doesn't fan out into one HTTP
+    // request per event.
+    //
+    // The explorer endpoint is shared with OpenTimestamps: it honours the same
+    // user-configured server (OTS settings) and the same Tor-aware default
+    // selection, via BitcoinExplorerEndpoint — onchain zaps must not silently
+    // bypass the user's Tor preference.
+    init {
+        cache.onchainBackend =
+            CachingOnchainBackend(
+                EsploraBackend(
+                    baseUrl = {
+                        BitcoinExplorerEndpoint.resolveNormalized(
+                            customExplorerUrl = otsPrefs.current.normalizedUrl(),
+                            usingTor =
+                                roleBasedHttpClientBuilder.shouldUseTorForMoneyOperations(
+                                    OkHttpBitcoinExplorer.MEMPOOL_API_URL,
+                                ),
+                        )
+                    },
+                    client = roleBasedHttpClientBuilder.okHttpClientForMoney(OkHttpBitcoinExplorer.MEMPOOL_API_URL),
+                ),
+            )
+
+        // NIP-57 Appendix F: validates incoming zap receipts against the
+        // recipient's LNURL provider's advertised `nostrPubkey`. Reuses the
+        // money-tier http client so Tor preferences and proxy settings apply.
+        cache.lnurlEndpointResolver =
+            OkHttpLnurlEndpointResolver(roleBasedHttpClientBuilder::okHttpClientForMoney)
+    }
+
     // Provides a relay pool
     val client: INostrClient = NostrClient(websocketBuilder, applicationIOScope)
 
+    // 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
+    // fail with zero successes in the window, pokes TorManager to drop + re-init Arti.
+    val torCircuitHealthTracker =
+        TorCircuitHealthTracker(
+            client = client,
+            isTorRouted = { torEvaluatorFlow.shouldUseTorForRelay(it) },
+            isTorActive = { torManager.isSocksReady() },
+            isConnectivityActive = { connManager.status.value is ConnectivityStatus.Active },
+            onCircuitsDead = { torManager.onTorCircuitsDead() },
+        ).also { it.register() }
+
     // Watches for changes on Tor and Relay List Settings
     val relayProxyClientConnector =
         RelayProxyClientConnector(
             torEvaluatorFlow.flow,
-            okHttpClientForRelays,
-            connManager,
-            torManager,
+            okHttpClientForRelays.defaultHttpClient,
+            okHttpClientForRelays.defaultHttpClientWithoutProxy,
+            connManager.status,
+            torManager.status,
             client,
             applicationIOScope,
         )
@@ -372,6 +534,9 @@ class AppModules(
     val relayReqStats = if (isDebug) RelayReqStats(client) else null
     val logger = if (isDebug) RelaySpeedLogger(client) else null
 
+    // Focused timeline for the DM / gift-wrap loading path (tag: DMPagination).
+    // val dmDiagnostics = if (isDebug) DmRelayDiagnosticsLogger(client) else null
+
     // Coordinates all subscriptions for the Nostr Client
     val sources: RelaySubscriptionsCoordinator =
         RelaySubscriptionsCoordinator(
@@ -387,6 +552,9 @@ class AppModules(
         AccountCacheState(
             geolocationFlow = { locationManager.geohashStateFlow },
             nwcFilterAssembler = { sources.nwc },
+            cashuWalletFilterAssembler = { sources.cashuWallet },
+            cashuMintDirectoryFilterAssembler = { sources.cashuMintDirectory },
+            okHttpClientForMoney = roleBasedHttpClientBuilder::okHttpClientForMoney,
             contentResolverFn = { appContext.contentResolver },
             otsResolverBuilder = { otsResolverBuilder.build() },
             cache = cache,
@@ -609,6 +777,12 @@ class AppModules(
         ScheduledPostWorker.schedule(appContext)
         ScheduledPostWorker.scheduleCatchUp(appContext)
 
+        // 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)
+
         // Watch for account login and start/stop always-on notification service
         applicationIOScope.launch {
             sessionManager.accountContent.collectLatest { state ->

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

@@ -25,11 +25,12 @@ import android.content.Context
 import android.content.SharedPreferences
 import androidx.compose.runtime.Immutable
 import androidx.core.content.edit
+import com.vitorpamplona.amethyst.commons.model.clink.ClinkDebitWalletEntry
+import com.vitorpamplona.amethyst.commons.model.nip47WalletConnect.NwcWalletEntry
+import com.vitorpamplona.amethyst.commons.model.nip47WalletConnect.NwcWalletEntryNorm
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.TopFilter
 import com.vitorpamplona.amethyst.model.UiSettings
-import com.vitorpamplona.amethyst.model.nip47WalletConnect.NwcWalletEntry
-import com.vitorpamplona.amethyst.model.nip47WalletConnect.NwcWalletEntryNorm
 import com.vitorpamplona.amethyst.service.checkNotInMainThread
 import com.vitorpamplona.amethyst.ui.actions.mediaServers.DEFAULT_MEDIA_SERVERS
 import com.vitorpamplona.amethyst.ui.actions.mediaServers.ServerName
@@ -104,6 +105,8 @@ private object PrefKeys {
     const val DEFAULT_DISCOVERY_FOLLOW_LIST = "defaultDiscoveryFollowList"
     const val DEFAULT_POLLS_FOLLOW_LIST = "defaultPollsFollowList"
     const val DEFAULT_PICTURES_FOLLOW_LIST = "defaultPicturesFollowList"
+    const val DEFAULT_WORKOUTS_FOLLOW_LIST = "defaultWorkoutsFollowList"
+    const val DEFAULT_CALENDARS_FOLLOW_LIST = "defaultCalendarsFollowList"
     const val DEFAULT_PRODUCTS_FOLLOW_LIST = "defaultProductsFollowList"
     const val DEFAULT_SHORTS_FOLLOW_LIST = "defaultShortsFollowList"
     const val DEFAULT_PUBLIC_CHATS_FOLLOW_LIST = "defaultPublicChatsFollowList"
@@ -111,13 +114,20 @@ private object PrefKeys {
     const val DEFAULT_NESTS_FOLLOW_LIST = "defaultNestsFollowList"
     const val DEFAULT_LONGS_FOLLOW_LIST = "defaultLongsFollowList"
     const val DEFAULT_ARTICLES_FOLLOW_LIST = "defaultArticlesFollowList"
+    const val DEFAULT_MUSIC_TRACKS_FOLLOW_LIST = "defaultMusicTracksFollowList"
+    const val DEFAULT_MUSIC_PLAYLISTS_FOLLOW_LIST = "defaultMusicPlaylistsFollowList"
+    const val DEFAULT_PODCAST_EPISODES_FOLLOW_LIST = "defaultPodcastEpisodesFollowList"
+    const val DEFAULT_PODCASTS_FOLLOW_LIST = "defaultPodcastsFollowList"
+    const val DEFAULT_SOFTWARE_APPS_FOLLOW_LIST = "defaultSoftwareAppsFollowList"
     const val DEFAULT_BADGES_FOLLOW_LIST = "defaultBadgesFollowList"
     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 ZAP_PAYMENT_REQUEST_SERVER = "zapPaymentServer" // legacy, kept for migration
     const val NWC_WALLETS = "nwcWallets"
-    const val DEFAULT_NWC_WALLET_ID = "defaultNwcWalletId"
+    const val DEFAULT_NWC_WALLET_ID = "defaultNwcWalletId" // legacy, migrated into DEFAULT_PAYMENT_SOURCE_ID
+    const val CLINK_DEBIT_WALLETS = "clinkDebitWallets"
+    const val DEFAULT_PAYMENT_SOURCE_ID = "defaultPaymentSourceId"
     const val LATEST_USER_METADATA = "latestUserMetadata"
     const val LATEST_CONTACT_LIST = "latestContactList"
     const val LATEST_DM_RELAY_LIST = "latestDMRelayList"
@@ -142,6 +152,10 @@ private object PrefKeys {
     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 SPLIT_NOTIFICATIONS_ENABLED = "split_notifications_enabled"
+
+    // One-shot stamp: set once an account has gone through the notifications
+    // Global -> Selected (Curated) migration (or was created after it shipped).
+    const val NOTIF_GLOBAL_TO_CURATED_MIGRATED = "notif_global_to_curated_migrated"
     const val TOR_SETTINGS = "tor_settings"
     const val USE_PROXY = "use_proxy"
     const val PROXY_PORT = "proxy_port"
@@ -156,6 +170,8 @@ private object PrefKeys {
     const val ALL_ACCOUNT_INFO = "all_saved_accounts_info"
     const val SHARED_SETTINGS = "shared_settings"
     const val LATEST_PAYMENT_TARGETS = "latestPaymentTargets"
+    const val LATEST_CASHU_WALLET = "latestCashuWallet"
+    const val LATEST_NUTZAP_INFO = "latestNutzapInfo"
 }
 
 object LocalPreferences {
@@ -309,6 +325,9 @@ object LocalPreferences {
     suspend fun deleteAccount(accountInfo: AccountInfo) {
         Log.d("LocalPreferences") { "Saving to encrypted storage updatePrefsForLogout ${accountInfo.npub}" }
         withContext(Dispatchers.IO) {
+            // Drop the in-memory copy as well; otherwise re-adding the same account later
+            // would resurrect the deleted settings from this cache.
+            mutex.withLock { cachedAccounts.remove(accountInfo.npub) }
             encryptedPreferences(accountInfo.npub).edit(commit = true) { clear() }
             removeAccount(accountInfo)
             deleteUserPreferenceFile(accountInfo.npub)
@@ -322,8 +341,16 @@ object LocalPreferences {
     }
 
     suspend fun setDefaultAccount(accountSettings: AccountSettings) {
-        setCurrentAccount(accountSettings)
+        // 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
+        // written, get null back, and poison `cachedAccounts[npub] = null` for the
+        // 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)
     }
 
     suspend fun allSavedAccounts(): List<AccountInfo> = savedAccounts()
@@ -361,6 +388,8 @@ 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_WORKOUTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultWorkoutsFollowList.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))
                     putString(PrefKeys.DEFAULT_PUBLIC_CHATS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultPublicChatsFollowList.value))
@@ -368,6 +397,11 @@ object LocalPreferences {
                     putString(PrefKeys.DEFAULT_NESTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultNestsFollowList.value))
                     putString(PrefKeys.DEFAULT_LONGS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultLongsFollowList.value))
                     putString(PrefKeys.DEFAULT_ARTICLES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultArticlesFollowList.value))
+                    putString(PrefKeys.DEFAULT_MUSIC_TRACKS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultMusicTracksFollowList.value))
+                    putString(PrefKeys.DEFAULT_MUSIC_PLAYLISTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultMusicPlaylistsFollowList.value))
+                    putString(PrefKeys.DEFAULT_PODCAST_EPISODES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultPodcastEpisodesFollowList.value))
+                    putString(PrefKeys.DEFAULT_PODCASTS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultPodcastsFollowList.value))
+                    putString(PrefKeys.DEFAULT_SOFTWARE_APPS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultSoftwareAppsFollowList.value))
                     putString(PrefKeys.DEFAULT_BADGES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultBadgesFollowList.value))
                     putString(PrefKeys.DEFAULT_BROWSE_EMOJI_SETS_FOLLOW_LIST, JsonMapper.toJson(settings.defaultBrowseEmojiSetsFollowList.value))
                     putString(PrefKeys.DEFAULT_COMMUNITIES_FOLLOW_LIST, JsonMapper.toJson(settings.defaultCommunitiesFollowList.value))
@@ -379,9 +413,19 @@ object LocalPreferences {
                     } else {
                         remove(PrefKeys.NWC_WALLETS)
                     }
-                    settings.defaultNwcWalletId.value?.let {
-                        putString(PrefKeys.DEFAULT_NWC_WALLET_ID, it)
-                    } ?: remove(PrefKeys.DEFAULT_NWC_WALLET_ID)
+
+                    val debitEntries = settings.clinkDebitWallets.value.map { it.denormalize() }
+                    if (debitEntries.isNotEmpty()) {
+                        putString(PrefKeys.CLINK_DEBIT_WALLETS, JsonMapper.toJson(debitEntries))
+                    } else {
+                        remove(PrefKeys.CLINK_DEBIT_WALLETS)
+                    }
+
+                    settings.defaultPaymentSourceId.value?.let {
+                        putString(PrefKeys.DEFAULT_PAYMENT_SOURCE_ID, it)
+                    } ?: remove(PrefKeys.DEFAULT_PAYMENT_SOURCE_ID)
+                    // Legacy NWC-only default key is superseded by DEFAULT_PAYMENT_SOURCE_ID.
+                    remove(PrefKeys.DEFAULT_NWC_WALLET_ID)
 
                     // Remove legacy key after migration
                     remove(PrefKeys.ZAP_PAYMENT_REQUEST_SERVER)
@@ -414,6 +458,8 @@ object LocalPreferences {
                     putOrRemove(PrefKeys.LATEST_EPHEMERAL_LIST, settings.backupEphemeralChatList)
                     putOrRemove(PrefKeys.LATEST_TRUST_PROVIDER_LIST, settings.backupTrustProviderList)
                     putOrRemove(PrefKeys.LATEST_PAYMENT_TARGETS, settings.backupNipA3PaymentTargets)
+                    putOrRemove(PrefKeys.LATEST_CASHU_WALLET, settings.backupCashuWallet)
+                    putOrRemove(PrefKeys.LATEST_NUTZAP_INFO, settings.backupNutzapInfo)
 
                     putBoolean(PrefKeys.HIDE_DELETE_REQUEST_DIALOG, settings.hideDeleteRequestDialog)
                     putBoolean(PrefKeys.HIDE_NIP_17_WARNING_DIALOG, settings.hideNIP17WarningDialog)
@@ -421,6 +467,11 @@ object LocalPreferences {
                     putBoolean(PrefKeys.CALLS_ENABLED, settings.callsEnabled.value)
                     putBoolean(PrefKeys.ALWAYS_ON_NOTIFICATION_SERVICE, settings.alwaysOnNotificationService.value)
                     putBoolean(PrefKeys.SPLIT_NOTIFICATIONS_ENABLED, settings.splitNotificationsEnabled.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
+                    // deliberate raw-Global choice (including on brand-new accounts).
+                    putBoolean(PrefKeys.NOTIF_GLOBAL_TO_CURATED_MIGRATED, true)
 
                     // migrating from previous design
                     remove(PrefKeys.USE_PROXY)
@@ -487,19 +538,20 @@ object LocalPreferences {
 
     suspend fun loadAccountConfigFromEncryptedStorage(npub: String): AccountSettings? {
         // if already loaded, return right away
-        if (cachedAccounts.containsKey(npub)) {
-            return cachedAccounts[npub]
-        }
+        cachedAccounts[npub]?.let { return it }
 
         return withContext(Dispatchers.IO) {
             mutex.withLock {
-                if (cachedAccounts.containsKey(npub)) {
-                    return@withContext cachedAccounts.get(npub)
-                }
+                cachedAccounts[npub]?.let { return@withContext it }
 
                 val accountSettings = innerLoadCurrentAccountFromEncryptedStorage(npub)
 
-                cachedAccounts.put(npub, accountSettings)
+                // Only cache successful loads. Caching null would leave the account
+                // permanently unreachable for the rest of the session if a reader
+                // raced in before the per-npub file finished being written.
+                if (accountSettings != null) {
+                    cachedAccounts.put(npub, accountSettings)
+                }
 
                 return@withContext accountSettings
             }
@@ -540,6 +592,8 @@ object LocalPreferences {
                     val zapPaymentRequestServerStr = getString(PrefKeys.ZAP_PAYMENT_REQUEST_SERVER, null)
                     val nwcWalletsStr = getString(PrefKeys.NWC_WALLETS, null)
                     val defaultNwcWalletIdStr = getString(PrefKeys.DEFAULT_NWC_WALLET_ID, null)
+                    val clinkDebitWalletsStr = getString(PrefKeys.CLINK_DEBIT_WALLETS, null)
+                    val defaultPaymentSourceIdStr = getString(PrefKeys.DEFAULT_PAYMENT_SOURCE_ID, null)
                     val defaultFileServerStr = getString(PrefKeys.DEFAULT_FILE_SERVER, null)
 
                     val pendingAttestationsStr = getString(PrefKeys.PENDING_ATTESTATIONS, null)
@@ -562,6 +616,8 @@ object LocalPreferences {
                     val latestEphemeralListStr = getString(PrefKeys.LATEST_EPHEMERAL_LIST, null)
                     val latestTrustProviderListStr = getString(PrefKeys.LATEST_TRUST_PROVIDER_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)
                     val lastReadPerRouteStr = getString(PrefKeys.LAST_READ_PER_ROUTE, null)
 
                     Log.d("LocalPreferences") { "Load account from file $npub - before parsing events" }
@@ -592,6 +648,10 @@ object LocalPreferences {
                                 }
                             }
                         }
+                    val clinkDebitsLoaded =
+                        async {
+                            parseOrNull<List<ClinkDebitWalletEntry>>(clinkDebitWalletsStr)?.mapNotNull { it.normalize() } ?: emptyList()
+                        }
                     val defaultFileServer = async { parseOrNull<ServerName>(defaultFileServerStr) ?: DEFAULT_MEDIA_SERVERS[0] }
 
                     val viewedPollResultNoteIds = async { parseOrNull<Map<String, Long>>(viewedPollResultNoteIdsStr) ?: mapOf() }
@@ -615,6 +675,14 @@ object LocalPreferences {
                     val latestEphemeralList = async { parseEventOrNull<EphemeralChatListEvent>(latestEphemeralListStr) }
                     val latestTrustProviderList = async { parseEventOrNull<TrustProviderListEvent>(latestTrustProviderListStr) }
                     val latestPaymentTargets = async { parseEventOrNull<PaymentTargetsEvent>(latestPaymentTargetsStr) }
+                    val latestCashuWallet =
+                        async {
+                            parseEventOrNull<com.vitorpamplona.quartz.nip60Cashu.wallet.CashuWalletEvent>(latestCashuWalletStr)
+                        }
+                    val latestNutzapInfo =
+                        async {
+                            parseEventOrNull<com.vitorpamplona.quartz.nip61Nutzaps.info.NutzapInfoEvent>(latestNutzapInfoStr)
+                        }
 
                     val lastReadPerRoute =
                         async {
@@ -641,19 +709,34 @@ object LocalPreferences {
                         defaultDiscoveryFollowList = MutableStateFlow(followListPrefs.discovery),
                         defaultPollsFollowList = MutableStateFlow(followListPrefs.polls),
                         defaultPicturesFollowList = MutableStateFlow(followListPrefs.pictures),
+                        defaultWorkoutsFollowList = MutableStateFlow(followListPrefs.workouts),
+                        defaultCalendarsFollowList = MutableStateFlow(followListPrefs.calendars),
                         defaultProductsFollowList = MutableStateFlow(followListPrefs.products),
                         defaultShortsFollowList = MutableStateFlow(followListPrefs.shorts),
                         defaultPublicChatsFollowList = MutableStateFlow(followListPrefs.publicChats),
                         defaultLiveStreamsFollowList = MutableStateFlow(followListPrefs.liveStreams),
                         defaultNestsFollowList = MutableStateFlow(followListPrefs.nests),
                         defaultLongsFollowList = MutableStateFlow(followListPrefs.longs),
+                        defaultMusicTracksFollowList = MutableStateFlow(followListPrefs.musicTracks),
+                        defaultMusicPlaylistsFollowList = MutableStateFlow(followListPrefs.musicPlaylists),
+                        defaultPodcastEpisodesFollowList = MutableStateFlow(followListPrefs.podcastEpisodes),
+                        defaultPodcastsFollowList = MutableStateFlow(followListPrefs.podcasts),
                         defaultArticlesFollowList = MutableStateFlow(followListPrefs.articles),
+                        defaultSoftwareAppsFollowList = MutableStateFlow(followListPrefs.softwareApps),
                         defaultBadgesFollowList = MutableStateFlow(followListPrefs.badges),
                         defaultBrowseEmojiSetsFollowList = MutableStateFlow(followListPrefs.browseEmojiSets),
                         defaultCommunitiesFollowList = MutableStateFlow(followListPrefs.communities),
                         defaultFollowPacksFollowList = MutableStateFlow(followListPrefs.followPacks),
                         nwcWallets = MutableStateFlow(nwcWalletsLoaded.await().first),
-                        defaultNwcWalletId = MutableStateFlow(nwcWalletsLoaded.await().second),
+                        clinkDebitWallets = MutableStateFlow(clinkDebitsLoaded.await()),
+                        // 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,
+                            ),
                         hideDeleteRequestDialog = hideDeleteRequestDialog,
                         hideBlockAlertDialog = hideBlockAlertDialog,
                         hideNIP17WarningDialog = hideNIP17WarningDialog,
@@ -683,6 +766,8 @@ object LocalPreferences {
                         viewedPollResultNoteIds = MutableStateFlow(viewedPollResultNoteIds.await()),
                         pendingAttestations = MutableStateFlow(pendingAttestations.await()),
                         backupNipA3PaymentTargets = latestPaymentTargets.await(),
+                        backupCashuWallet = latestCashuWallet.await(),
+                        backupNutzapInfo = latestNutzapInfo.await(),
                         callsEnabled = MutableStateFlow(callsEnabled),
                     )
                 }
@@ -712,6 +797,8 @@ object LocalPreferences {
         val discovery: TopFilter,
         val polls: TopFilter,
         val pictures: TopFilter,
+        val workouts: TopFilter,
+        val calendars: TopFilter,
         val products: TopFilter,
         val shorts: TopFilter,
         val publicChats: TopFilter,
@@ -719,20 +806,51 @@ object LocalPreferences {
         val nests: TopFilter,
         val longs: TopFilter,
         val articles: TopFilter,
+        val musicTracks: TopFilter,
+        val musicPlaylists: TopFilter,
+        val podcastEpisodes: TopFilter,
+        val podcasts: TopFilter,
+        val softwareApps: TopFilter,
         val badges: TopFilter,
         val browseEmojiSets: TopFilter,
         val communities: TopFilter,
         val followPacks: TopFilter,
     )
 
+    /**
+     * One-shot migration of the notifications filter.
+     *
+     * The notifications "Global" mode was split into a raw [TopFilter.Global]
+     * (every event that p-tags the user) and a curated [TopFilter.Selected].
+     * Existing users who had selected the old, curated "Global" keep a value
+     * that now deserializes to the much-more-permissive raw Global. Move them to
+     * [TopFilter.Selected] exactly once, then stamp the account so a later,
+     * deliberate raw-Global choice is never reverted. Accounts created after the
+     * split are stamped at save time, so they are never touched here.
+     */
+    private fun SharedPreferences.migrateNotificationFilter(current: TopFilter): TopFilter {
+        if (getBoolean(PrefKeys.NOTIF_GLOBAL_TO_CURATED_MIGRATED, false)) return current
+
+        val migrated = if (current is TopFilter.Global) TopFilter.Selected else current
+        edit {
+            if (migrated !== current) {
+                putString(PrefKeys.DEFAULT_NOTIFICATION_FOLLOW_LIST, JsonMapper.toJson(migrated))
+            }
+            putBoolean(PrefKeys.NOTIF_GLOBAL_TO_CURATED_MIGRATED, true)
+        }
+        return migrated
+    }
+
     private fun SharedPreferences.loadFollowListPrefs(): FollowListPrefs =
         FollowListPrefs(
             home = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_HOME_FOLLOW_LIST, null), TopFilter.AllFollows),
             stories = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_STORIES_FOLLOW_LIST, null), TopFilter.Global),
-            notification = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_NOTIFICATION_FOLLOW_LIST, null), TopFilter.Global),
+            notification = migrateNotificationFilter(parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_NOTIFICATION_FOLLOW_LIST, null), TopFilter.Selected)),
             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),
+            workouts = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_WORKOUTS_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),
             publicChats = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_PUBLIC_CHATS_FOLLOW_LIST, null), TopFilter.Global),
@@ -740,6 +858,11 @@ object LocalPreferences {
             nests = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_NESTS_FOLLOW_LIST, null), TopFilter.Global),
             longs = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_LONGS_FOLLOW_LIST, null), TopFilter.Global),
             articles = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_ARTICLES_FOLLOW_LIST, null), TopFilter.AllFollows),
+            musicTracks = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_MUSIC_TRACKS_FOLLOW_LIST, null), TopFilter.Global),
+            musicPlaylists = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_MUSIC_PLAYLISTS_FOLLOW_LIST, null), TopFilter.Global),
+            podcastEpisodes = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_PODCAST_EPISODES_FOLLOW_LIST, null), TopFilter.Global),
+            podcasts = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_PODCASTS_FOLLOW_LIST, null), TopFilter.Global),
+            softwareApps = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_SOFTWARE_APPS_FOLLOW_LIST, null), TopFilter.Global),
             badges = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_BADGES_FOLLOW_LIST, null), TopFilter.Mine),
             browseEmojiSets = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_BROWSE_EMOJI_SETS_FOLLOW_LIST, null), TopFilter.Global),
             communities = parseTopFilterOrDefault(getString(PrefKeys.DEFAULT_COMMUNITIES_FOLLOW_LIST, null), TopFilter.AllFollows),

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

@@ -23,6 +23,7 @@ package com.vitorpamplona.amethyst.model
 import androidx.compose.runtime.Stable
 import com.vitorpamplona.amethyst.BuildConfig
 import com.vitorpamplona.amethyst.LocalPreferences
+import com.vitorpamplona.amethyst.commons.audio.VisualizerStyle
 import com.vitorpamplona.amethyst.commons.marmot.MarmotManager
 import com.vitorpamplona.amethyst.commons.model.IAccount
 import com.vitorpamplona.amethyst.commons.model.emphChat.EphemeralChatChannel
@@ -35,7 +36,18 @@ import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatListD
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatListState
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
 import com.vitorpamplona.amethyst.commons.model.nip38UserStatuses.UserStatusAction
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.favoriteAlgoFeedsLists.FavoriteAlgoFeedsListDecryptionCache
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.hashtagLists.HashtagListDecryptionCache
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.muteList.MuteListDecryptionCache
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.peopleList.PeopleListDecryptionCache
 import com.vitorpamplona.amethyst.commons.model.nip56Reports.ReportAction
+import com.vitorpamplona.amethyst.commons.model.nip72Communities.CommunityListDecryptionCache
+import com.vitorpamplona.amethyst.commons.model.nip85TrustedAssertions.TrustProviderListDecryptionCache
+import com.vitorpamplona.amethyst.commons.onchain.OnchainZapSendError
+import com.vitorpamplona.amethyst.commons.onchain.OnchainZapSendResult
+import com.vitorpamplona.amethyst.commons.onchain.OnchainZapSendStage
+import com.vitorpamplona.amethyst.commons.onchain.OnchainZapSender
+import com.vitorpamplona.amethyst.commons.onchain.OnchainZapShare
 import com.vitorpamplona.amethyst.commons.richtext.RichTextParser
 import com.vitorpamplona.amethyst.logTime
 import com.vitorpamplona.amethyst.model.algoFeeds.FavoriteAlgoFeedsOrchestrator
@@ -68,20 +80,16 @@ import com.vitorpamplona.amethyst.model.nip51Lists.blockedRelays.BlockedRelayLis
 import com.vitorpamplona.amethyst.model.nip51Lists.blockedRelays.BlockedRelayListState
 import com.vitorpamplona.amethyst.model.nip51Lists.broadcastRelays.BroadcastRelayListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.broadcastRelays.BroadcastRelayListState
-import com.vitorpamplona.amethyst.model.nip51Lists.favoriteAlgoFeedsLists.FavoriteAlgoFeedsListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.favoriteAlgoFeedsLists.FavoriteAlgoFeedsListState
 import com.vitorpamplona.amethyst.model.nip51Lists.geohashLists.GeohashListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.geohashLists.GeohashListState
-import com.vitorpamplona.amethyst.model.nip51Lists.hashtagLists.HashtagListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.hashtagLists.HashtagListState
 import com.vitorpamplona.amethyst.model.nip51Lists.indexerRelays.IndexerRelayListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.indexerRelays.IndexerRelayListState
 import com.vitorpamplona.amethyst.model.nip51Lists.interestSets.InterestSetsState
 import com.vitorpamplona.amethyst.model.nip51Lists.labeledBookmarkLists.LabeledBookmarkListsState
-import com.vitorpamplona.amethyst.model.nip51Lists.muteList.MuteListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.muteList.MuteListState
 import com.vitorpamplona.amethyst.model.nip51Lists.peopleList.FollowListsState
-import com.vitorpamplona.amethyst.model.nip51Lists.peopleList.PeopleListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.peopleList.PeopleListsState
 import com.vitorpamplona.amethyst.model.nip51Lists.proxyRelays.ProxyRelayListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip51Lists.proxyRelays.ProxyRelayListState
@@ -93,9 +101,9 @@ import com.vitorpamplona.amethyst.model.nip51Lists.trustedRelays.TrustedRelayLis
 import com.vitorpamplona.amethyst.model.nip51Lists.trustedRelays.TrustedRelayListState
 import com.vitorpamplona.amethyst.model.nip62Vanish.VanishRequestsState
 import com.vitorpamplona.amethyst.model.nip65RelayList.Nip65RelayListState
-import com.vitorpamplona.amethyst.model.nip72Communities.CommunityListDecryptionCache
 import com.vitorpamplona.amethyst.model.nip72Communities.CommunityListState
 import com.vitorpamplona.amethyst.model.nip78AppSpecific.AppSpecificState
+import com.vitorpamplona.amethyst.model.nip89AppHandlers.AppRecommendationsState
 import com.vitorpamplona.amethyst.model.nipA3PaymentTargets.NipA3PaymentTargetsState
 import com.vitorpamplona.amethyst.model.nipB7Blossom.BlossomServerListState
 import com.vitorpamplona.amethyst.model.serverList.MergedFollowListsState
@@ -107,7 +115,6 @@ import com.vitorpamplona.amethyst.model.topNavFeeds.FeedDecryptionCaches
 import com.vitorpamplona.amethyst.model.topNavFeeds.FeedTopNavFilterState
 import com.vitorpamplona.amethyst.model.topNavFeeds.IFeedTopNavFilter
 import com.vitorpamplona.amethyst.model.topNavFeeds.OutboxLoaderState
-import com.vitorpamplona.amethyst.model.trustedAssertions.TrustProviderListDecryptionCache
 import com.vitorpamplona.amethyst.model.trustedAssertions.TrustProviderListState
 import com.vitorpamplona.amethyst.service.location.LocationState
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.nwc.NWCPaymentFilterAssembler
@@ -173,6 +180,8 @@ import com.vitorpamplona.quartz.nip10Notes.content.findNostrUris
 import com.vitorpamplona.quartz.nip10Notes.content.findURLs
 import com.vitorpamplona.quartz.nip10Notes.threadRootIdOrSelf
 import com.vitorpamplona.quartz.nip17Dm.NIP17Factory
+import com.vitorpamplona.quartz.nip17Dm.base.BaseDMGroupEvent
+import com.vitorpamplona.quartz.nip17Dm.base.ChatroomKey
 import com.vitorpamplona.quartz.nip17Dm.base.NIP17Group
 import com.vitorpamplona.quartz.nip17Dm.files.ChatMessageEncryptedFileHeaderEvent
 import com.vitorpamplona.quartz.nip17Dm.messages.ChatMessageEvent
@@ -188,6 +197,7 @@ import com.vitorpamplona.quartz.nip19Bech32.entities.NProfile
 import com.vitorpamplona.quartz.nip19Bech32.entities.NPub
 import com.vitorpamplona.quartz.nip19Bech32.entities.NRelay
 import com.vitorpamplona.quartz.nip19Bech32.entities.NSec
+import com.vitorpamplona.quartz.nip32Labeling.LabelEvent
 import com.vitorpamplona.quartz.nip36SensitiveContent.contentWarning
 import com.vitorpamplona.quartz.nip37Drafts.DraftEventCache
 import com.vitorpamplona.quartz.nip37Drafts.DraftWrapEvent
@@ -216,8 +226,8 @@ import com.vitorpamplona.quartz.nip58Badges.award.BadgeAwardEvent
 import com.vitorpamplona.quartz.nip58Badges.definition.BadgeDefinitionEvent
 import com.vitorpamplona.quartz.nip58Badges.definition.tags.ThumbTag
 import com.vitorpamplona.quartz.nip58Badges.profile.ProfileBadgesEvent
-import com.vitorpamplona.quartz.nip59Giftwrap.WrappedEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.rumors.RumorAssembler
+import com.vitorpamplona.quartz.nip59Giftwrap.seals.SealedRumorEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.wraps.EphemeralGiftWrapEvent
 import com.vitorpamplona.quartz.nip59Giftwrap.wraps.GiftWrapEvent
 import com.vitorpamplona.quartz.nip62RequestToVanish.RequestToVanishEvent
@@ -280,6 +290,8 @@ import kotlin.coroutines.cancellation.CancellationException
 import com.vitorpamplona.quartz.experimental.nip95.header.thumbhash as nip95thumbhash
 import com.vitorpamplona.quartz.experimental.profileGallery.thumbhash as galleryThumbhash
 
+private const val ONCHAIN_BACKEND_NOT_CONFIGURED = "Bitcoin chain backend is not configured"
+
 @OptIn(DelicateCoroutinesApi::class)
 @Stable
 class Account(
@@ -287,6 +299,9 @@ class Account(
     override val signer: NostrSigner,
     val geolocationFlow: () -> StateFlow<LocationState.LocationResult>,
     val nwcFilterAssembler: () -> NWCPaymentFilterAssembler,
+    val cashuWalletFilterAssembler: () -> com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuWalletFilterAssembler,
+    val cashuMintDirectoryFilterAssembler: () -> com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuMintDirectoryFilterAssembler,
+    val okHttpClientForMoney: (String) -> okhttp3.OkHttpClient,
     val otsResolverBuilder: () -> OtsResolver,
     val cache: LocalCache,
     val client: INostrClient,
@@ -379,6 +394,7 @@ class Account(
 
     val labeledBookmarkLists = LabeledBookmarkListsState(signer, cache, scope)
     val interestSets = InterestSetsState(signer, cache, scope)
+    val appRecommendations = AppRecommendationsState(signer, cache, scope)
     val oldBookmarkState = OldBookmarkListState(signer, cache, scope)
     val bookmarkState = BookmarkListState(signer, cache, scope)
     val pinState = PinListState(signer, cache, scope)
@@ -401,7 +417,37 @@ class Account(
     val dmRelays = DmInboxRelayState(dmRelayList, nip65RelayList, privateStorageRelayList, localRelayList, scope)
     val notificationRelays = NotificationInboxRelayState(nip65RelayList, localRelayList, scope)
 
-    val trustedRelays = TrustedRelayListsState(nip65RelayList, privateStorageRelayList, localRelayList, dmRelayList, searchRelayList, trustedRelayList, broadcastRelayList, scope)
+    val cashuWalletState =
+        com.vitorpamplona.amethyst.model.nip60Cashu.CashuWalletState(
+            pubKey = signer.pubKey,
+            signer = signer,
+            cache = cache,
+            scope = scope,
+            assembler = cashuWalletFilterAssembler(),
+            outboxRelaysFlow = outboxRelays.flow,
+            settings = settings,
+            okHttpClient = okHttpClientForMoney,
+        )
+
+    /**
+     * NIP-87 cashu mint directory — populated on-demand while the mint
+     * picker is on screen. ViewModels call open()/close() ref-counted, the
+     * relay subscription only runs while at least one opener is active.
+     */
+    val cashuMintDirectoryState =
+        com.vitorpamplona.amethyst.model.nip60Cashu.CashuMintDirectoryState(
+            cache = cache,
+            scope = scope,
+            assembler = cashuMintDirectoryFilterAssembler(),
+            followsFlow =
+                kotlinx.coroutines.flow.MutableStateFlow(kind3FollowList.flow.value.authors).also { authorSet ->
+                    scope.launch {
+                        kind3FollowList.flow.collect { authorSet.value = it.authors }
+                    }
+                },
+        )
+
+    val trustedRelays = TrustedRelayListsState(nip65RelayList, privateStorageRelayList, localRelayList, dmRelayList, searchRelayList, indexerRelayList, proxyRelayList, trustedRelayList, broadcastRelayList, scope)
 
     // Follows Relays
     val followOutboxesOrProxy = FollowListOutboxOrProxyRelays(kind3FollowList, blockedRelayList, proxyRelayList, cache, scope)
@@ -486,6 +532,12 @@ class Account(
     val livePicturesFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultPicturesFollowList)
     val livePicturesFollowListsPerRelay = OutboxLoaderState(livePicturesFollowLists, cache, scope).flow
 
+    val liveWorkoutsFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultWorkoutsFollowList)
+    val liveWorkoutsFollowListsPerRelay = OutboxLoaderState(liveWorkoutsFollowLists, cache, scope).flow
+
+    val liveCalendarsFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultCalendarsFollowList)
+    val liveCalendarsFollowListsPerRelay = OutboxLoaderState(liveCalendarsFollowLists, cache, scope).flow
+
     val liveProductsFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultProductsFollowList)
     val liveProductsFollowListsPerRelay = OutboxLoaderState(liveProductsFollowLists, cache, scope).flow
 
@@ -507,6 +559,21 @@ class Account(
     val liveArticlesFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultArticlesFollowList)
     val liveArticlesFollowListsPerRelay = OutboxLoaderState(liveArticlesFollowLists, cache, scope).flow
 
+    val liveMusicTracksFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultMusicTracksFollowList)
+    val liveMusicTracksFollowListsPerRelay = OutboxLoaderState(liveMusicTracksFollowLists, cache, scope).flow
+
+    val liveMusicPlaylistsFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultMusicPlaylistsFollowList)
+    val liveMusicPlaylistsFollowListsPerRelay = OutboxLoaderState(liveMusicPlaylistsFollowLists, cache, scope).flow
+
+    val livePodcastEpisodesFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultPodcastEpisodesFollowList)
+    val livePodcastEpisodesFollowListsPerRelay = OutboxLoaderState(livePodcastEpisodesFollowLists, cache, scope).flow
+
+    val livePodcastsFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultPodcastsFollowList)
+    val livePodcastsFollowListsPerRelay = OutboxLoaderState(livePodcastsFollowLists, cache, scope).flow
+
+    val liveSoftwareAppsFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultSoftwareAppsFollowList)
+    val liveSoftwareAppsFollowListsPerRelay = OutboxLoaderState(liveSoftwareAppsFollowLists, cache, scope).flow
+
     val liveBadgesFollowLists: StateFlow<IFeedTopNavFilter> = topNavFilterFlow(settings.defaultBadgesFollowList)
     val liveBadgesFollowListsPerRelay = OutboxLoaderState(liveBadgesFollowLists, cache, scope).flow
 
@@ -595,6 +662,17 @@ class Account(
         }
     }
 
+    suspend fun changeAudioVisualizer(style: VisualizerStyle) {
+        if (settings.changeAudioVisualizer(style)) {
+            sendNewAppSpecificData()
+        }
+    }
+
+    suspend fun toggleChatroomPin(room: ChatroomKey) {
+        settings.toggleChatroomPin(room)
+        sendNewAppSpecificData()
+    }
+
     suspend fun updateZapAmounts(
         amountSet: List<Long>,
         selectedZapType: LnZapEvent.ZapType,
@@ -669,8 +747,10 @@ class Account(
 
         val eventHint = note.toEventHint<Event>() ?: return null
 
-        // For NIP-17 private groups, we don't support tracked mode (too complex)
-        if (eventHint.event is NIP17Group) return null
+        // For NIP-17 private groups, we don't support tracked mode (too complex).
+        // Unsealed rumors (empty sig) must never get a public reaction —
+        // the e-tag would leak the private rumor id to public relays.
+        if (eventHint.event is NIP17Group || eventHint.event.sig.isEmpty()) return null
 
         val event = ReactionAction.reactTo(eventHint, reaction, signer)
         val relays = computeRelayListToBroadcast(event)
@@ -686,6 +766,48 @@ class Account(
         cache.justConsumeMyOwnEvent(event)
     }
 
+    /**
+     * NIP-32: tags [note] with [hashtag] by publishing a kind 1985 label event using the
+     * `#t` tag-association namespace. Fire-and-forget; signs and broadcasts immediately.
+     */
+    suspend fun labelHashtag(
+        note: Note,
+        hashtag: String,
+    ) {
+        createLabelHashtagEvent(note, hashtag)?.let { (event, relays) ->
+            cache.justConsumeMyOwnEvent(event)
+            client.publish(event, relays)
+        }
+    }
+
+    /**
+     * Builds and signs a NIP-32 hashtag label event for [note] without sending it.
+     * Returns the signed event and target relays for tracked broadcasting, or null if
+     * the account can't write or the note has no underlying event.
+     */
+    suspend fun createLabelHashtagEvent(
+        note: Note,
+        hashtag: String,
+    ): Pair<Event, Set<NormalizedRelayUrl>>? {
+        if (!signer.isWriteable()) return null
+
+        val eventHint = note.toEventHint<Event>() ?: return null
+
+        val template = LabelEvent.buildHashtagLabel(eventHint, hashtag)
+
+        val event = signer.sign(template)
+        val relays = computeRelayListToBroadcast(event)
+
+        return event to relays
+    }
+
+    /**
+     * Consumes a label event into local cache. Called when tracked broadcasting succeeds.
+     */
+    fun consumeLabelEvent(event: Event) {
+        cache.justConsumeMyOwnEvent(event)
+    }
+
     suspend fun createZapRequestFor(
         event: Event,
         pollOption: Int?,
@@ -693,6 +815,8 @@ class Account(
         zapType: LnZapEvent.ZapType,
         toUser: User?,
         additionalRelays: Set<NormalizedRelayUrl>? = null,
+        amountMillisats: Long? = null,
+        lnurl: String? = null,
     ) = LnZapRequestEvent.create(
         zappedEvent = event,
         relays = nip65RelayList.inboxFlow.value + (additionalRelays ?: emptySet()),
@@ -701,6 +825,8 @@ class Account(
         message = message,
         zapType = zapType,
         toUserPubHex = toUser?.pubkeyHex,
+        amountMillisats = amountMillisats,
+        lnurl = lnurl,
     )
 
     suspend fun calculateIfNoteWasZappedByAccount(
@@ -722,11 +848,24 @@ class Account(
         walletUri: Nip47WalletConnect.Nip47URINorm,
         request: Request,
         onResponse: (Response?) -> Unit,
-    ) {
+    ): HexKey {
         val (event, relay) = nip47SignerState.sendNwcRequestToWallet(walletUri, request, onResponse)
         client.publish(event, setOf(relay))
+        return event.id
     }
 
+    /**
+     * Number of spoofed (wrong-author) NIP-47 replies that have arrived for
+     * the given request id. 0 if the request is unknown or already resolved.
+     */
+    fun nwcSpoofAttempts(requestId: HexKey): Int = LocalCache.paymentTracker.spoofAttemptsFor(requestId)
+
+    /**
+     * Removes a pending NIP-47 request from the tracker. Call this when the
+     * UI gives up waiting (timeout) so the entry doesn't stick around.
+     */
+    fun cleanupNwcRequest(requestId: HexKey) = LocalCache.paymentTracker.cleanup(requestId)
+
     suspend fun sendZapPaymentRequestFor(
         bolt11: String,
         zappedNote: Note?,
@@ -740,6 +879,8 @@ class Account(
         user: User,
         message: String = "",
         zapType: LnZapEvent.ZapType,
+        amountMillisats: Long? = null,
+        lnurl: String? = null,
     ): LnZapRequestEvent {
         val zapRequest =
             LnZapRequestEvent.create(
@@ -748,17 +889,110 @@ class Account(
                 signer = signer,
                 message = message,
                 zapType = zapType,
+                amountMillisats = amountMillisats,
+                lnurl = lnurl,
             )
 
         cache.justConsumeMyOwnEvent(zapRequest)
         return zapRequest
     }
 
+    private fun onchainBackendNotConfigured() =
+        OnchainZapSendResult.Failure(
+            OnchainZapSendStage.LOADING_UTXOS,
+            OnchainZapSendError.BACKEND_NOT_CONFIGURED,
+            ONCHAIN_BACKEND_NOT_CONFIGURED,
+        )
+
+    /**
+     * Send a NIP-BC onchain zap: build a Bitcoin transaction paying the recipient's
+     * derived Taproot address, sign it, broadcast it, and publish the kind:8333
+     * zap receipt. Pass [zappedEvent] to attribute the zap to a specific event, or
+     * leave it null for a profile zap.
+     */
+    suspend fun sendOnchainZap(
+        recipientPubKey: HexKey,
+        amountSats: Long,
+        feeRateSatPerVByte: Double,
+        comment: String = "",
+        zappedEvent: EventHintBundle<out Event>? = null,
+    ): OnchainZapSendResult {
+        val backend =
+            cache.onchainBackend
+                ?: return onchainBackendNotConfigured()
+        return OnchainZapSender.send(
+            backend = backend,
+            signer = signer,
+            senderPubKey = signer.pubKey,
+            recipientPubKey = recipientPubKey,
+            amountSats = amountSats,
+            feeRateSatPerVByte = feeRateSatPerVByte,
+            comment = comment,
+            zappedEvent = zappedEvent,
+        ) { template -> signAndComputeBroadcast(template) }
+    }
+
+    /**
+     * Pay an explicit Bitcoin address (e.g. a profile's NIP-A3 `bitcoin`
+     * payment target) from the NIP-BC Taproot wallet. A plain wallet send —
+     * no kind:8333 receipt is published. See [OnchainZapSender.sendToAddress].
+     */
+    suspend fun sendOnchainToAddress(
+        recipientAddress: String,
+        amountSats: Long,
+        feeRateSatPerVByte: Double,
+    ): OnchainZapSendResult {
+        val backend =
+            cache.onchainBackend
+                ?: return onchainBackendNotConfigured()
+        return OnchainZapSender.sendToAddress(
+            backend = backend,
+            signer = signer,
+            senderPubKey = signer.pubKey,
+            recipientAddress = recipientAddress,
+            amountSats = amountSats,
+            feeRateSatPerVByte = feeRateSatPerVByte,
+        )
+    }
+
+    /**
+     * Send a NIP-BC onchain split zap: a single Bitcoin transaction paying
+     * each recipient their precomputed share, plus one kind:8333 receipt per
+     * recipient. See [OnchainZapSender.sendSplit] for failure semantics.
+     */
+    suspend fun sendOnchainZapWithSplits(
+        recipients: List<OnchainZapShare>,
+        feeRateSatPerVByte: Double,
+        comment: String = "",
+        zappedEvent: EventHintBundle<out Event>? = null,
+    ): OnchainZapSendResult {
+        val backend =
+            cache.onchainBackend
+                ?: return onchainBackendNotConfigured()
+        return OnchainZapSender.sendSplit(
+            backend = backend,
+            signer = signer,
+            senderPubKey = signer.pubKey,
+            recipients = recipients,
+            feeRateSatPerVByte = feeRateSatPerVByte,
+            comment = comment,
+            zappedEvent = zappedEvent,
+        ) { template -> signAndComputeBroadcast(template) }
+    }
+
     suspend fun report(
         note: Note,
         type: ReportType,
         content: String = "",
-    ) = sendMyPublicAndPrivateOutbox(ReportAction.report(note, type, content, userProfile(), signer))
+    ) {
+        if (note.isPrivateRumor()) {
+            // A kind-1984 e-tagging the rumor would leak the private id onto
+            // public relays. Report the author instead (p-tag only).
+            note.author?.let { report(it, type, content) }
+        } else {
+            sendMyPublicAndPrivateOutbox(ReportAction.report(note, type, content, userProfile(), signer))
+        }
+    }
 
     suspend fun report(
         user: User,
@@ -788,6 +1022,28 @@ class Account(
         }
     }
 
+    /**
+     * Retracts rumor-only events (private reactions/replies) with a
+     * gift-wrapped NIP-09 deletion delivered to the same participants as
+     * the [target] rumor they referenced. A public deletion would e-tag
+     * the private rumor ids onto public relays.
+     */
+    suspend fun deletePrivately(
+        notes: List<Note>,
+        target: Note,
+    ) {
+        if (!isWriteable()) return
+        val targetEvent = target.event ?: return
+
+        val myRumors = notes.filter { it.author == userProfile() }.mapNotNull { it.event }
+        if (myRumors.isEmpty()) return
+
+        val recipients = (targetEvent.taggedUserIds() + targetEvent.pubKey).distinct().minus(signer.pubKey)
+        broadcastPrivately(
+            NIP17Factory().createDeletionNIP17(DeletionEvent.build(myRumors), recipients, signer),
+        )
+    }
+
     suspend fun delete(
         event: Event,
         additionalRelays: Set<NormalizedRelayUrl>,
@@ -988,7 +1244,9 @@ class Account(
                 emptySet()
             }
         }
-        if (event is WrappedEvent) {
+        // Seals, inner DM messages, and unsigned rumors never get broadcast
+        // relays: they only travel inside gift wraps.
+        if (event is SealedRumorEvent || event is BaseDMGroupEvent || event.sig.isEmpty()) {
             return emptySet()
         }
 
@@ -1111,26 +1369,39 @@ class Account(
 
     suspend fun broadcast(note: Note) {
         note.event?.let { noteEvent ->
-            if (noteEvent is WrappedEvent && noteEvent.host != null) {
-                // download the event and send it.
-                noteEvent.host?.let { host ->
-                    client
-                        .fetchFirst(
-                            filters =
-                                note.relays.associateWith { _ ->
-                                    listOf(
-                                        Filter(
-                                            kinds = listOf(host.kind),
-                                            tags = mapOf("p" to listOf(pubKey)),
-                                            ids = listOf(host.id),
-                                        ),
-                                    )
-                                },
-                        )?.let { downloadedEvent ->
-                            val toRelays = computeRelayListToBroadcast(downloadedEvent)
-                            client.publish(downloadedEvent, toRelays)
-                        }
-                }
+            val host = note.rumorHost
+            if (host != null) {
+                // Rumors are rebroadcast as their delivering envelope: the
+                // cached copy is content-stripped, so download it and send it.
+                // A just-sent note has no relays until its self-wrap echoes
+                // back — fall back to our own DM inbox relays. Bare seals
+                // (kind 13) carry no p tag, so that filter is wrap-only.
+                val relays = note.relays.ifEmpty { dmRelays.flow.value.toList() }
+                val filter =
+                    if (host.kind == SealedRumorEvent.KIND) {
+                        Filter(
+                            kinds = listOf(host.kind),
+                            ids = listOf(host.id),
+                        )
+                    } else {
+                        Filter(
+                            kinds = listOf(host.kind),
+                            tags = mapOf("p" to listOf(pubKey)),
+                            ids = listOf(host.id),
+                        )
+                    }
+                client
+                    .fetchFirst(
+                        filters = relays.associateWith { _ -> listOf(filter) },
+                    )?.let { downloadedEvent ->
+                        val toRelays = computeRelayListToBroadcast(downloadedEvent)
+                        client.publish(downloadedEvent, toRelays)
+                    }
+            } else if (noteEvent.sig.isEmpty()) {
+                // Rumor with no known wrap: publishing it would disclose the
+                // private content to relays even though they reject the
+                // missing signature.
+                return
             } else {
                 client.publish(noteEvent, computeRelayListToBroadcast(note))
             }
@@ -1710,8 +1981,8 @@ class Account(
     suspend fun <T : Event> signAnonymouslyAndBroadcast(
         template: EventTemplate<T>,
         broadcast: List<Event> = emptyList(),
+        anonymousSigner: NostrSigner = NostrSignerInternal(KeyPair()),
     ): T {
-        val anonymousSigner = NostrSignerInternal(KeyPair())
         val event = anonymousSigner.sign(template)
 
         cache.justConsumeMyOwnEvent(event)
@@ -2060,6 +2331,18 @@ class Account(
         broadcastPrivately(events)
     }
 
+    /**
+     * Publishes a kind-1 note privately: signs the template, then gift-wraps
+     * the rumor to every p-tagged user plus a self-copy and sends each wrap
+     * to the recipient's DM relays. Used for private replies (the parent's
+     * author and participants are already p-tagged) and for private posts
+     * (the Notify list is the audience). Nothing reaches public relays.
+     */
+    suspend fun sendPrivateNote(template: EventTemplate<TextNoteEvent>) {
+        if (!isWriteable()) return
+        broadcastPrivately(NIP17Factory().createNoteNIP17(template, signer))
+    }
+
     override suspend fun sendGiftWraps(wraps: List<GiftWrapEvent>) {
         wraps.forEach { wrap ->
             val relayList = computeRelayListToBroadcast(wrap)
@@ -2090,6 +2373,28 @@ class Account(
 
     // --- Marmot Group Messaging ---
 
+    /**
+     * Resolve the relay set for a Marmot group. Prefer the relays carried in
+     * the MLS GroupContext metadata so every member converges on the same
+     * canonical set; fall back to the account's outbox relays if the group
+     * has none (e.g. a group joined before MIP-01 metadata existed).
+     *
+     * Lives on Account (not AccountViewModel) so that headless callers —
+     * notifications' BroadcastReceiver, background workers — can resolve
+     * relays without spinning up a ViewModel.
+     */
+    fun marmotGroupRelays(nostrGroupId: HexKey): Set<NormalizedRelayUrl> {
+        val groupRelays =
+            marmotManager
+                ?.groupMetadata(nostrGroupId)
+                ?.relays
+                ?.mapNotNull {
+                    com.vitorpamplona.quartz.nip01Core.relay.normalizer.RelayUrlNormalizer
+                        .normalizeOrNull(it)
+                }?.toSet()
+        return if (!groupRelays.isNullOrEmpty()) groupRelays else outboxRelays.flow.value
+    }
+
     /**
      * Send a message to a Marmot MLS group.
      * Encrypts the inner event and publishes the GroupEvent to group relays.
@@ -3033,8 +3338,10 @@ class Account(
 
     fun isKnown(user: HexKey): Boolean = user in allFollows.flow.value.authors
 
-    private fun hasExcessiveHashtags(note: Note): Boolean {
-        val limit = settings.syncedSettings.security.maxHashtagLimit.value
+    fun maxHashtagLimit(): Int = settings.syncedSettings.security.maxHashtagLimit.value
+
+    fun hasExcessiveHashtags(note: Note): Boolean {
+        val limit = maxHashtagLimit()
         return limit > 0 && note.event?.hasMoreHashtagsThan(limit) == true
     }
 
@@ -3275,6 +3582,14 @@ class Account(
     init {
         Log.d("AccountRegisterObservers", "Init")
 
+        // Start the Cashu wallet state observers AFTER all field initializers
+        // complete — auto-redeem can fire as soon as start() returns, and it
+        // calls back into sendLiterallyEverywhere which depends on
+        // followPlusAllMineWithIndex (initialized after cashuWalletState).
+        // Doing this in start() rather than in the state's own init { } closes
+        // the race where a publish would land on a half-built Account.
+        cashuWalletState.start { event -> sendLiterallyEverywhere(event) }
+
         // Restore Marmot MLS group state on startup
         if (marmotManager != null) {
             scope.launch(Dispatchers.IO) {
@@ -3332,11 +3647,12 @@ class Account(
                                 if (isNew) {
                                     innerNote.event = innerEvent
                                 }
-                                marmotGroupList.restoreMessage(groupId, innerNote)
+                                marmotGroupList.addMessage(groupId, innerNote)
                             } catch (e: Exception) {
                                 Log.w(
                                     "Account",
-                                    "Failed to restore persisted Marmot message for $groupId: ${e.message}",
+                                    "Failed to restore persisted Marmot message for $groupId",
+                                    e,
                                 )
                             }
                         }

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

@@ -21,9 +21,14 @@
 package com.vitorpamplona.amethyst.model
 
 import androidx.compose.runtime.Stable
+import com.vitorpamplona.amethyst.commons.audio.VisualizerStyle
+import com.vitorpamplona.amethyst.commons.model.clink.ClinkDebitWalletEntryNorm
 import com.vitorpamplona.amethyst.commons.model.emphChat.EphemeralChatRepository
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatListRepository
-import com.vitorpamplona.amethyst.model.nip47WalletConnect.NwcWalletEntryNorm
+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.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
@@ -35,7 +40,9 @@ import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.crypto.KeyPair
 import com.vitorpamplona.quartz.nip01Core.metadata.MetadataEvent
 import com.vitorpamplona.quartz.nip02FollowList.ContactListEvent
+import com.vitorpamplona.quartz.nip17Dm.base.ChatroomKey
 import com.vitorpamplona.quartz.nip17Dm.settings.ChatMessageRelayListEvent
+import com.vitorpamplona.quartz.nip19Bech32.toNpub
 import com.vitorpamplona.quartz.nip28PublicChat.list.ChannelListEvent
 import com.vitorpamplona.quartz.nip37Drafts.DraftWrapEvent
 import com.vitorpamplona.quartz.nip37Drafts.privateOutbox.PrivateOutboxRelayListEvent
@@ -53,6 +60,8 @@ import com.vitorpamplona.quartz.nip51Lists.relayLists.TrustedRelayListEvent
 import com.vitorpamplona.quartz.nip55AndroidSigner.api.CommandType
 import com.vitorpamplona.quartz.nip55AndroidSigner.api.permission.Permission
 import com.vitorpamplona.quartz.nip57Zaps.LnZapEvent
+import com.vitorpamplona.quartz.nip60Cashu.wallet.CashuWalletEvent
+import com.vitorpamplona.quartz.nip61Nutzaps.info.NutzapInfoEvent
 import com.vitorpamplona.quartz.nip65RelayList.AdvertisedRelayListEvent
 import com.vitorpamplona.quartz.nip72ModCommunities.follow.CommunityListEvent
 import com.vitorpamplona.quartz.nip78AppData.AppSpecificDataEvent
@@ -80,9 +89,23 @@ val DefaultSignerPermissions =
 sealed class TopFilter(
     val code: String,
 ) {
+    interface AddressableTopFilter {
+        val address: Address
+    }
+
     @Serializable
     object Global : TopFilter(" Global ")
 
+    /**
+     * Notifications-only curated mode: like [Global] it admits authors the
+     * user doesn't follow, but it also applies per-kind relevance heuristics
+     * to remove less interesting notes (reactions/reposts that don't target
+     * the user's own notes, unrelated thread replies, etc.). In Notifications,
+     * [Global] shows every event that p-tags the user instead.
+     */
+    @Serializable
+    object Selected : TopFilter(" Selected ")
+
     @Serializable
     object AllFollows : TopFilter(" All Follows ")
 
@@ -100,18 +123,21 @@ sealed class TopFilter(
 
     @Serializable
     class PeopleList(
-        val address: Address,
-    ) : TopFilter(address.toValue())
+        override val address: Address,
+    ) : TopFilter(address.toValue()),
+        AddressableTopFilter
 
     @Serializable
     class MuteList(
-        val address: Address,
-    ) : TopFilter(address.toValue())
+        override val address: Address,
+    ) : TopFilter(address.toValue()),
+        AddressableTopFilter
 
     @Serializable
     class Community(
-        val address: Address,
-    ) : TopFilter("Community/${address.toValue()}")
+        override val address: Address,
+    ) : TopFilter("Community/${address.toValue()}"),
+        AddressableTopFilter
 
     @Serializable
     class Hashtag(
@@ -159,10 +185,12 @@ class AccountSettings(
     val hideCommunityRulesViolations: MutableStateFlow<Boolean> = MutableStateFlow(false),
     val defaultHomeFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.AllFollows),
     val defaultStoriesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
-    val defaultNotificationFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultNotificationFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Selected),
     val defaultDiscoveryFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultPollsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultPicturesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultWorkoutsFollowList: 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),
     val defaultPublicChatsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
@@ -170,12 +198,20 @@ class AccountSettings(
     val defaultNestsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultLongsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultArticlesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.AllFollows),
+    val defaultMusicTracksFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultMusicPlaylistsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultPodcastEpisodesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultPodcastsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
+    val defaultSoftwareAppsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultBadgesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Mine),
     val defaultBrowseEmojiSetsFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val defaultCommunitiesFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.AllFollows),
     val defaultFollowPacksFollowList: MutableStateFlow<TopFilter> = MutableStateFlow(TopFilter.Global),
     val nwcWallets: MutableStateFlow<List<NwcWalletEntryNorm>> = MutableStateFlow(emptyList()),
-    val defaultNwcWalletId: MutableStateFlow<String?> = MutableStateFlow(null),
+    val clinkDebitWallets: MutableStateFlow<List<ClinkDebitWalletEntryNorm>> = MutableStateFlow(emptyList()),
+    // The unified default spend rail (an NWC wallet OR a CLINK debit). Persisted under a
+    // new key, migrated from the legacy NWC-only `defaultNwcWalletId`.
+    val defaultPaymentSourceId: MutableStateFlow<String?> = MutableStateFlow(null),
     var hideDeleteRequestDialog: Boolean = false,
     var hideBlockAlertDialog: Boolean = false,
     var hideNIP17WarningDialog: Boolean = false,
@@ -201,6 +237,21 @@ class AccountSettings(
     var backupGeohashList: GeohashListEvent? = null,
     var backupEphemeralChatList: EphemeralChatListEvent? = null,
     var backupTrustProviderList: TrustProviderListEvent? = null,
+    var backupCashuWallet: CashuWalletEvent? = null,
+    var backupNutzapInfo: NutzapInfoEvent? = null,
+    /**
+     * NUT-13 deterministic-secret counter map, keyed by keyset id. The
+     * wallet derives every blind message from `(seed, keysetId, counter)`,
+     * incrementing the counter every time it consumes one; reusing a
+     * counter would expose the secret. Persisted here so the counter
+     * survives app restart even though the wallet's seed is also stored
+     * in kind:17375 (which would otherwise be the only persistence).
+     *
+     * Empty map = no NUT-13 usage yet (e.g. wallet created before this
+     * feature shipped). Per-keyset; the same counter under different
+     * keysets is fine because the derivation includes the keyset id.
+     */
+    var cashuKeysetCounters: MutableMap<String, Long> = mutableMapOf(),
     val lastReadPerRoute: MutableStateFlow<Map<String, MutableStateFlow<Long>>> = MutableStateFlow(mapOf()),
     val hasDonatedInVersion: MutableStateFlow<Set<String>> = MutableStateFlow(setOf()),
     val dismissedPollNoteIds: MutableStateFlow<Set<String>> = MutableStateFlow(setOf()),
@@ -293,14 +344,26 @@ class AccountSettings(
         return false
     }
 
-    fun defaultNwcWallet(): NwcWalletEntryNorm? {
-        val id = defaultNwcWalletId.value
-        val wallets = nwcWallets.value
-        return if (id != null) {
-            wallets.firstOrNull { it.id == id }
-        } else {
-            wallets.firstOrNull()
+    fun changeAudioVisualizer(style: VisualizerStyle): Boolean {
+        if (syncedSettings.media.audioVisualizer.value != style) {
+            syncedSettings.media.audioVisualizer.tryEmit(style)
+            saveAccountSettings()
+            return true
         }
+        return false
+    }
+
+    /** The selected default spend rail across both NWC wallets and CLINK debits. */
+    fun defaultPaymentSource(): PaymentSource? = PaymentSourceResolver.resolveDefault(nwcWallets.value, clinkDebitWallets.value, defaultPaymentSourceId.value)
+
+    /**
+     * The NWC wallet to use for NWC-only flows (balance display, mint top-up). Resolves
+     * the unified default when it points at an NWC wallet, otherwise falls back to the
+     * first NWC wallet so those flows keep working even when a debit is the zap default.
+     */
+    fun defaultNwcWallet(): NwcWalletEntryNorm? {
+        val wallets = nwcWallets.value
+        return wallets.firstOrNull { it.id == defaultPaymentSourceId.value } ?: wallets.firstOrNull()
     }
 
     fun defaultZapPaymentRequest(): Nip47WalletConnect.Nip47URINorm? = defaultNwcWallet()?.uri
@@ -311,8 +374,10 @@ class AccountSettings(
             nwcWallets.tryEmit(nwcWallets.value.toMutableList().apply { set(existing, wallet) })
         } else {
             nwcWallets.tryEmit(nwcWallets.value + wallet)
-            if (nwcWallets.value.size == 1) {
-                defaultNwcWalletId.tryEmit(wallet.id)
+            // First configured source of any kind becomes the default; adding more never
+            // silently changes an existing default.
+            if (defaultPaymentSourceId.value == null) {
+                defaultPaymentSourceId.tryEmit(wallet.id)
             }
         }
         saveAccountSettings()
@@ -322,16 +387,68 @@ class AccountSettings(
     fun removeNwcWallet(walletId: String): Boolean {
         val wallets = nwcWallets.value.filter { it.id != walletId }
         nwcWallets.tryEmit(wallets)
-        if (defaultNwcWalletId.value == walletId) {
-            defaultNwcWalletId.tryEmit(wallets.firstOrNull()?.id)
+        reassignDefaultIfRemoved(walletId)
+        saveAccountSettings()
+        return true
+    }
+
+    fun addClinkDebitWallet(wallet: ClinkDebitWalletEntryNorm): Boolean {
+        val existing = clinkDebitWallets.value.indexOfFirst { it.id == wallet.id }
+        if (existing >= 0) {
+            clinkDebitWallets.tryEmit(clinkDebitWallets.value.toMutableList().apply { set(existing, wallet) })
+        } else {
+            clinkDebitWallets.tryEmit(clinkDebitWallets.value + wallet)
+            if (defaultPaymentSourceId.value == null) {
+                defaultPaymentSourceId.tryEmit(wallet.id)
+            }
         }
         saveAccountSettings()
         return true
     }
 
-    fun setDefaultNwcWallet(walletId: String): Boolean {
-        if (defaultNwcWalletId.value != walletId && nwcWallets.value.any { it.id == walletId }) {
-            defaultNwcWalletId.tryEmit(walletId)
+    fun removeClinkDebitWallet(walletId: String): Boolean {
+        clinkDebitWallets.tryEmit(clinkDebitWallets.value.filter { it.id != walletId })
+        reassignDefaultIfRemoved(walletId)
+        saveAccountSettings()
+        return true
+    }
+
+    fun renameClinkDebitWallet(
+        walletId: String,
+        newName: String,
+    ): Boolean {
+        val wallets = clinkDebitWallets.value.toMutableList()
+        val index = wallets.indexOfFirst { it.id == walletId }
+        if (index >= 0) {
+            wallets[index] = wallets[index].copy(name = newName)
+            clinkDebitWallets.tryEmit(wallets)
+            saveAccountSettings()
+            return true
+        }
+        return false
+    }
+
+    /** When the removed source was the default, fall back to the first remaining source. */
+    private fun reassignDefaultIfRemoved(walletId: String) {
+        if (defaultPaymentSourceId.value == walletId) {
+            defaultPaymentSourceId.tryEmit(PaymentSourceResolver.resolveDefault(nwcWallets.value, clinkDebitWallets.value, null)?.id)
+        }
+    }
+
+    /** Resets the default to the first remaining source if it no longer points at anything. */
+    private fun reassignDefaultIfMissing() {
+        val id = defaultPaymentSourceId.value ?: return
+        val exists = nwcWallets.value.any { it.id == id } || clinkDebitWallets.value.any { it.id == id }
+        if (!exists) {
+            defaultPaymentSourceId.tryEmit(PaymentSourceResolver.resolveDefault(nwcWallets.value, clinkDebitWallets.value, null)?.id)
+        }
+    }
+
+    /** Selects the unified default across both NWC wallets and CLINK debits. */
+    fun setDefaultPaymentSource(sourceId: String): Boolean {
+        val exists = nwcWallets.value.any { it.id == sourceId } || clinkDebitWallets.value.any { it.id == sourceId }
+        if (defaultPaymentSourceId.value != sourceId && exists) {
+            defaultPaymentSourceId.tryEmit(sourceId)
             saveAccountSettings()
             return true
         }
@@ -353,26 +470,11 @@ class AccountSettings(
         return false
     }
 
-    fun moveNwcWallet(
-        fromIndex: Int,
-        toIndex: Int,
-    ): Boolean {
-        val wallets = nwcWallets.value.toMutableList()
-        if (fromIndex in wallets.indices && toIndex in wallets.indices && fromIndex != toIndex) {
-            val item = wallets.removeAt(fromIndex)
-            wallets.add(toIndex, item)
-            nwcWallets.tryEmit(wallets)
-            saveAccountSettings()
-            return true
-        }
-        return false
-    }
-
     fun changeZapPaymentRequest(newServer: Nip47WalletConnect.Nip47URINorm?): Boolean {
         if (newServer == null) {
             if (nwcWallets.value.isNotEmpty()) {
                 nwcWallets.tryEmit(emptyList())
-                defaultNwcWalletId.tryEmit(null)
+                reassignDefaultIfMissing()
                 saveAccountSettings()
                 return true
             }
@@ -529,6 +631,28 @@ class AccountSettings(
         }
     }
 
+    fun changeDefaultWorkoutsFollowList(name: FeedDefinition) {
+        changeDefaultWorkoutsFollowList(name.code)
+    }
+
+    fun changeDefaultWorkoutsFollowList(name: TopFilter) {
+        if (defaultWorkoutsFollowList.value != name) {
+            defaultWorkoutsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultCalendarsFollowList(name: FeedDefinition) {
+        changeDefaultCalendarsFollowList(name.code)
+    }
+
+    fun changeDefaultCalendarsFollowList(name: TopFilter) {
+        if (defaultCalendarsFollowList.value != name) {
+            defaultCalendarsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
     fun changeDefaultProductsFollowList(name: FeedDefinition) {
         changeDefaultProductsFollowList(name.code)
     }
@@ -606,6 +730,61 @@ class AccountSettings(
         }
     }
 
+    fun changeDefaultMusicTracksFollowList(name: FeedDefinition) {
+        changeDefaultMusicTracksFollowList(name.code)
+    }
+
+    fun changeDefaultMusicTracksFollowList(name: TopFilter) {
+        if (defaultMusicTracksFollowList.value != name) {
+            defaultMusicTracksFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultMusicPlaylistsFollowList(name: FeedDefinition) {
+        changeDefaultMusicPlaylistsFollowList(name.code)
+    }
+
+    fun changeDefaultMusicPlaylistsFollowList(name: TopFilter) {
+        if (defaultMusicPlaylistsFollowList.value != name) {
+            defaultMusicPlaylistsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultPodcastEpisodesFollowList(name: FeedDefinition) {
+        changeDefaultPodcastEpisodesFollowList(name.code)
+    }
+
+    fun changeDefaultPodcastEpisodesFollowList(name: TopFilter) {
+        if (defaultPodcastEpisodesFollowList.value != name) {
+            defaultPodcastEpisodesFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultPodcastsFollowList(name: FeedDefinition) {
+        changeDefaultPodcastsFollowList(name.code)
+    }
+
+    fun changeDefaultPodcastsFollowList(name: TopFilter) {
+        if (defaultPodcastsFollowList.value != name) {
+            defaultPodcastsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
+    fun changeDefaultSoftwareAppsFollowList(name: FeedDefinition) {
+        changeDefaultSoftwareAppsFollowList(name.code)
+    }
+
+    fun changeDefaultSoftwareAppsFollowList(name: TopFilter) {
+        if (defaultSoftwareAppsFollowList.value != name) {
+            defaultSoftwareAppsFollowList.tryEmit(name)
+            saveAccountSettings()
+        }
+    }
+
     fun changeDefaultBadgesFollowList(name: FeedDefinition) {
         changeDefaultBadgesFollowList(name.code)
     }
@@ -752,6 +931,96 @@ class AccountSettings(
         }
     }
 
+    fun updateCashuWallet(newWallet: CashuWalletEvent?) {
+        if (newWallet == null) return
+        // Replaceable: keep the latest by id (id changes on each re-sign).
+        if (backupCashuWallet?.id != newWallet.id) {
+            backupCashuWallet = newWallet
+            saveAccountSettings()
+        }
+    }
+
+    fun updateNutzapInfo(newNutzapInfo: NutzapInfoEvent?) {
+        if (newNutzapInfo == null || newNutzapInfo.tags.isEmpty()) return
+        // A mints-less kind:10019 is the "stop receiving nutzaps" tombstone
+        // (an empty replacement carrying only an `alt` tag). Don't restore it
+        // on next launch — backing it up would undo clearNutzapInfo() once the
+        // empty event round-trips back through LocalCache.
+        if (newNutzapInfo.mints().isEmpty()) {
+            clearNutzapInfo()
+            return
+        }
+        if (backupNutzapInfo?.id != newNutzapInfo.id) {
+            backupNutzapInfo = newNutzapInfo
+            saveAccountSettings()
+        }
+    }
+
+    /**
+     * Drop the cached kind:17375 so a relaunch doesn't restore a wallet the
+     * user just deleted. Called when the wallet event is NIP-09 deleted —
+     * without this the [backupCashuWallet] would be re-consumed into
+     * LocalCache on next launch and resurrect the deleted wallet.
+     */
+    fun clearCashuWallet() {
+        if (backupCashuWallet != null) {
+            backupCashuWallet = null
+            saveAccountSettings()
+        }
+    }
+
+    /** Drop the cached kind:10019. Mirror of [clearCashuWallet] for the nutzap info. */
+    fun clearNutzapInfo() {
+        if (backupNutzapInfo != null) {
+            backupNutzapInfo = null
+            saveAccountSettings()
+        }
+    }
+
+    /**
+     * NUT-13 keyset counters live in [CashuPreferences], a dedicated
+     * SharedPreferences file with synchronous (`commit = true`) writes.
+     * AccountSettings goes through a 1-second debounce on its own save
+     * path; the cashu counter cannot tolerate that window because the
+     * mint persists signed (keyset, blind_message) pairs the moment it
+     * sees them, so any local lag → "outputs already signed" on retry.
+     * See [CashuPreferences] for the full rationale.
+     */
+    private val cashuPrefs: CashuPreferences by lazy {
+        CashuPreferences.forAccount(keyPair.pubKey.toNpub())
+    }
+
+    /**
+     * Reserve [count] consecutive NUT-13 counters for [keysetId],
+     * returning the first one. Caller derives `(secret, r)` from
+     * `(seed, keysetId, i)` for `i in [returned .. returned+count-1]`.
+     * Persisted synchronously before returning — see [CashuPreferences].
+     *
+     * One-time migration: when this keyset has a non-zero value in the
+     * legacy [cashuKeysetCounters] map (from a build that persisted
+     * counters inside AccountSettings) and the dedicated store is
+     * still at zero, the legacy value is copied over before we reserve
+     * so an upgrade doesn't reset the counter.
+     */
+    fun reserveCashuCounters(
+        keysetId: String,
+        count: Int,
+    ): Long {
+        migrateLegacyCashuCounter(keysetId)
+        return cashuPrefs.reserveCounters(keysetId, count)
+    }
+
+    /** Inspect the next counter for [keysetId] without consuming any. */
+    fun peekCashuCounter(keysetId: String): Long {
+        migrateLegacyCashuCounter(keysetId)
+        return cashuPrefs.peekCounter(keysetId)
+    }
+
+    private fun migrateLegacyCashuCounter(keysetId: String) {
+        val legacy = cashuKeysetCounters[keysetId] ?: return
+        cashuPrefs.seedCounterIfMissing(keysetId, legacy)
+    }
+
     fun updateNIPA3PaymentTargets(newNIPA3PaymentTargets: PaymentTargetsEvent?) {
         if (newNIPA3PaymentTargets == null || newNIPA3PaymentTargets.tags.isEmpty()) return
 
@@ -984,6 +1253,17 @@ class AccountSettings(
         }
     }
 
+    // ---
+    // pinned chatrooms
+    // ---
+
+    fun toggleChatroomPin(room: ChatroomKey) {
+        syncedSettings.chats.pinnedChatrooms.update {
+            if (room in it) it - room else it + room
+        }
+        saveAccountSettings()
+    }
+
     // ---
     // viewed poll results
     // ---

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

@@ -21,7 +21,9 @@
 package com.vitorpamplona.amethyst.model
 
 import androidx.compose.runtime.Stable
+import com.vitorpamplona.amethyst.commons.audio.VisualizerStyle
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.notifications.equalImmutableLists
+import com.vitorpamplona.quartz.nip17Dm.base.ChatroomKey
 import com.vitorpamplona.quartz.nip57Zaps.LnZapEvent
 import kotlinx.collections.immutable.ImmutableList
 import kotlinx.collections.immutable.toImmutableList
@@ -35,11 +37,11 @@ class AccountSyncedSettings(
     val reactions =
         AccountReactionPreferences(
             MutableStateFlow(internalSettings.reactions.reactionChoices.toImmutableList()),
-            MutableStateFlow(internalSettings.reactions.reactionRowItems.toImmutableList()),
+            MutableStateFlow(mergeWithDefaultReactionRowItems(internalSettings.reactions.reactionRowItems).toImmutableList()),
         )
     val zaps =
         AccountZapPreferences(
-            MutableStateFlow(internalSettings.zaps.zapAmountChoices.toImmutableList()),
+            MutableStateFlow(mergeZapAmounts(internalSettings.zaps).toImmutableList()),
             MutableStateFlow(internalSettings.zaps.defaultZapType),
         )
     val languages =
@@ -62,6 +64,14 @@ class AccountSyncedSettings(
         AccountVideoPlayerPreferences(
             MutableStateFlow(mergeWithDefaultVideoPlayerButtons(internalSettings.videoPlayer.buttonItems).toImmutableList()),
         )
+    val media =
+        AccountMediaPreferences(
+            MutableStateFlow(VisualizerStyle.fromName(internalSettings.media.audioVisualizer)),
+        )
+    val chats =
+        AccountChatPreferences(
+            MutableStateFlow(internalSettings.chats.toChatroomKeys()),
+        )
 
     fun toInternal(): AccountSyncedSettingsInternal =
         AccountSyncedSettingsInternal(
@@ -69,6 +79,10 @@ class AccountSyncedSettings(
             zaps =
                 AccountZapPreferencesInternal(
                     zaps.zapAmountChoices.value,
+                    // Write the on-chain-eligible subset into the legacy field so
+                    // older clients still get sensible on-chain presets. Unioning
+                    // it back on load is idempotent (subset ⊆ full list).
+                    zaps.zapAmountChoices.value.filter { it >= MIN_ONCHAIN_ZAP_SATS },
                     zaps.defaultZapType.value,
                 ),
             languages =
@@ -88,6 +102,8 @@ class AccountSyncedSettings(
                     security.addClientTag.value,
                 ),
             videoPlayer = AccountVideoPlayerPreferencesInternal(videoPlayer.buttonItems.value),
+            media = AccountMediaPreferencesInternal(media.audioVisualizer.value.name),
+            chats = AccountChatPreferencesInternal(chats.pinnedChatrooms.value.map { it.users.sorted() }),
         )
 
     fun updateFrom(syncedSettingsInternal: AccountSyncedSettingsInternal) {
@@ -96,12 +112,13 @@ class AccountSyncedSettings(
             reactions.reactionChoices.tryEmit(newReactionChoices)
         }
 
-        val newReactionRowItems = syncedSettingsInternal.reactions.reactionRowItems.toImmutableList()
+        val newReactionRowItems =
+            mergeWithDefaultReactionRowItems(syncedSettingsInternal.reactions.reactionRowItems).toImmutableList()
         if (!equalImmutableLists(reactions.reactionRowItems.value, newReactionRowItems)) {
             reactions.reactionRowItems.tryEmit(newReactionRowItems)
         }
 
-        val newZapChoices = syncedSettingsInternal.zaps.zapAmountChoices.toImmutableList()
+        val newZapChoices = mergeZapAmounts(syncedSettingsInternal.zaps).toImmutableList()
         if (!equalImmutableLists(zaps.zapAmountChoices.value, newZapChoices)) {
             zaps.zapAmountChoices.tryEmit(newZapChoices)
         }
@@ -155,6 +172,16 @@ class AccountSyncedSettings(
         if (!equalImmutableLists(videoPlayer.buttonItems.value, newVideoPlayerButtonItems)) {
             videoPlayer.buttonItems.tryEmit(newVideoPlayerButtonItems)
         }
+
+        val newAudioVisualizer = VisualizerStyle.fromName(syncedSettingsInternal.media.audioVisualizer)
+        if (media.audioVisualizer.value != newAudioVisualizer) {
+            media.audioVisualizer.tryEmit(newAudioVisualizer)
+        }
+
+        val newPinnedChatrooms = syncedSettingsInternal.chats.toChatroomKeys()
+        if (chats.pinnedChatrooms.value != newPinnedChatrooms) {
+            chats.pinnedChatrooms.tryEmit(newPinnedChatrooms)
+        }
     }
 
     fun dontTranslateFromFilteredBySpokenLanguages(): Set<String> = languages.dontTranslateFrom.value - getLanguagesSpokenByUser()
@@ -177,6 +204,15 @@ class AccountZapPreferences(
     val defaultZapType: MutableStateFlow<LnZapEvent.ZapType>,
 )
 
+/**
+ * Union the (historically separate) zap and on-chain preset lists into the
+ * single sorted set the app now uses everywhere. Preserves amounts customized
+ * on either side and amounts synced from an older client that still writes the
+ * legacy `onchainZapAmountChoices`. Idempotent: [AccountSyncedSettings.toInternal]
+ * re-derives the on-chain field as a subset of this list.
+ */
+internal fun mergeZapAmounts(zaps: AccountZapPreferencesInternal): List<Long> = (zaps.zapAmountChoices + zaps.onchainZapAmountChoices).distinct()
+
 @Stable
 class AccountLanguagePreferences(
     var dontTranslateFrom: MutableStateFlow<Set<String>>,
@@ -239,13 +275,25 @@ class AccountLanguagePreferences(
     ): String? = languagePreferences.value["$source,$target"]
 }
 
+@Stable
+class AccountMediaPreferences(
+    val audioVisualizer: MutableStateFlow<VisualizerStyle>,
+)
+
+@Stable
+class AccountChatPreferences(
+    val pinnedChatrooms: MutableStateFlow<Set<ChatroomKey>>,
+)
+
+internal fun AccountChatPreferencesInternal.toChatroomKeys(): Set<ChatroomKey> = pinnedRooms.mapTo(mutableSetOf()) { ChatroomKey(it.toSet()) }
+
 @Stable
 class AccountSecurityPreferences(
     val showSensitiveContent: MutableStateFlow<Boolean?> = MutableStateFlow(null),
     val warnAboutPostsWithReports: MutableStateFlow<Boolean> = MutableStateFlow(true),
     val reportWarningThreshold: MutableStateFlow<Int> = MutableStateFlow(DefaultReportWarningThreshold),
     var filterSpamFromStrangers: MutableStateFlow<Boolean> = MutableStateFlow(true),
-    val maxHashtagLimit: MutableStateFlow<Int> = MutableStateFlow(5),
+    val maxHashtagLimit: MutableStateFlow<Int> = MutableStateFlow(8),
     var sendKind0EventsToLocalRelay: MutableStateFlow<Boolean> = MutableStateFlow(false),
     val addClientTag: MutableStateFlow<Boolean> = MutableStateFlow(true),
 ) {

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

@@ -37,9 +37,27 @@ val DefaultReactions =
         "\uD83D\uDE31",
     )
 
-val DefaultZapAmounts = listOf(100L, 500L, 1000L)
+val DefaultZapAmounts = listOf(21L, 50L, 100L)
+val DefaultOnchainZapAmounts = listOf(5_000L)
 val DefaultReportWarningThreshold = 5
 
+/**
+ * Product floor for the on-chain rail — stricter than the protocol-level
+ * dust threshold (OnchainZapBuilder.DUST_THRESHOLD_SATS). The unified zap
+ * picker offers the on-chain logo only for amounts at or above this, and the
+ * on-chain send dialog draws its presets from the single zap-amount list
+ * filtered by it. Single source of truth for everywhere that gates on-chain
+ * by amount.
+ */
+const val MIN_ONCHAIN_ZAP_SATS = 1_000L
+
+/**
+ * Default on-chain quick-pick amount, used when the user's unified zap-amount
+ * list contains nothing at or above [MIN_ONCHAIN_ZAP_SATS]. Matches the legacy
+ * dedicated on-chain default so the send dialog always offers one preset.
+ */
+const val DEFAULT_ONCHAIN_ZAP_SATS = 5_000L
+
 @Serializable
 enum class ReactionRowAction {
     Reply,
@@ -67,6 +85,16 @@ val DefaultReactionRowItems =
         ReactionRowItem(ReactionRowAction.Share, showCounter = false),
     )
 
+// Existing accounts have a reaction-row list serialized before some actions
+// existed (e.g. Pay was added later). Append any default items the saved list
+// is missing so new actions surface without forcing a settings reset — the
+// user's existing order/toggles for actions they already have are preserved.
+fun mergeWithDefaultReactionRowItems(saved: List<ReactionRowItem>): List<ReactionRowItem> {
+    val knownActions = saved.mapTo(mutableSetOf()) { it.action }
+    val missing = DefaultReactionRowItems.filter { it.action !in knownActions }
+    return if (missing.isEmpty()) saved else saved + missing
+}
+
 @Serializable
 enum class VideoPlayerAction {
     Fullscreen,
@@ -127,6 +155,8 @@ class AccountSyncedSettingsInternal(
     val languages: AccountLanguagePreferencesInternal = AccountLanguagePreferencesInternal(),
     val security: AccountSecurityPreferencesInternal = AccountSecurityPreferencesInternal(),
     val videoPlayer: AccountVideoPlayerPreferencesInternal = AccountVideoPlayerPreferencesInternal(),
+    val media: AccountMediaPreferencesInternal = AccountMediaPreferencesInternal(),
+    val chats: AccountChatPreferencesInternal = AccountChatPreferencesInternal(),
 )
 
 @Serializable
@@ -143,6 +173,12 @@ class AccountReactionPreferencesInternal(
 @Serializable
 class AccountZapPreferencesInternal(
     var zapAmountChoices: List<Long> = DefaultZapAmounts,
+    // Legacy field: the on-chain rail no longer has its own editable preset
+    // list — amounts live in [zapAmountChoices] and on-chain just filters by
+    // [MIN_ONCHAIN_ZAP_SATS]. Kept (de)serialized so older clients still sync
+    // and so the on-chain-eligible subset round-trips back for them; on load it
+    // is unioned into [zapAmountChoices]. See AccountSyncedSettings.
+    var onchainZapAmountChoices: List<Long> = DefaultOnchainZapAmounts,
     val defaultZapType: LnZapEvent.ZapType = LnZapEvent.ZapType.PUBLIC,
 )
 
@@ -159,7 +195,21 @@ class AccountSecurityPreferencesInternal(
     var warnAboutPostsWithReports: Boolean = true,
     val reportWarningThreshold: Int = DefaultReportWarningThreshold,
     var filterSpamFromStrangers: Boolean = true,
-    val maxHashtagLimit: Int = 5,
+    val maxHashtagLimit: Int = 8,
     var sendKind0EventsToLocalRelay: Boolean = false,
     var addClientTag: Boolean = true,
 )
+
+@Serializable
+class AccountMediaPreferencesInternal(
+    // Stored as VisualizerStyle.name; defaults to CLASSIC (the app's classic audio animation).
+    var audioVisualizer: String = "CLASSIC",
+)
+
+@Serializable
+class AccountChatPreferencesInternal(
+    // Rooms pinned to the top of the chat list. Each room is its member
+    // pubkeys (hex) sorted ascending, so the serialized form is deterministic
+    // regardless of set iteration order.
+    var pinnedRooms: List<List<String>> = emptyList(),
+)

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

@@ -52,6 +52,8 @@ data class UiSettings(
     val showProfileAppRecommendations: Boolean = true,
     val showProfileZapReceivedFeed: Boolean = true,
     val showProfileFollowersFeed: Boolean = true,
+    val dontShowOnchainPublicWarning: Boolean = false,
+    val suggestWorkoutsFromHealthConnect: BooleanType = BooleanType.ALWAYS,
 )
 
 enum class ThemeType(

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

@@ -52,6 +52,8 @@ class UiSettingsFlow(
     val showProfileAppRecommendations: MutableStateFlow<Boolean> = MutableStateFlow(true),
     val showProfileZapReceivedFeed: MutableStateFlow<Boolean> = MutableStateFlow(true),
     val showProfileFollowersFeed: MutableStateFlow<Boolean> = MutableStateFlow(true),
+    val dontShowOnchainPublicWarning: MutableStateFlow<Boolean> = MutableStateFlow(false),
+    val suggestWorkoutsFromHealthConnect: MutableStateFlow<BooleanType> = MutableStateFlow(BooleanType.ALWAYS),
 ) {
     val listOfFlows: List<Flow<Any?>> =
         listOf<Flow<Any?>>(
@@ -78,6 +80,8 @@ class UiSettingsFlow(
             showProfileAppRecommendations,
             showProfileZapReceivedFeed,
             showProfileFollowersFeed,
+            dontShowOnchainPublicWarning,
+            suggestWorkoutsFromHealthConnect,
         )
 
     // emits at every change in any of the propertyes.
@@ -108,6 +112,8 @@ class UiSettingsFlow(
                 flows[20] as Boolean,
                 flows[21] as Boolean,
                 flows[22] as Boolean,
+                flows[23] as Boolean,
+                flows[24] as BooleanType,
             )
         }
 
@@ -136,6 +142,8 @@ class UiSettingsFlow(
             showProfileAppRecommendations.value,
             showProfileZapReceivedFeed.value,
             showProfileFollowersFeed.value,
+            dontShowOnchainPublicWarning.value,
+            suggestWorkoutsFromHealthConnect.value,
         )
 
     fun update(torSettings: UiSettings): Boolean {
@@ -233,6 +241,14 @@ class UiSettingsFlow(
             showProfileFollowersFeed.tryEmit(torSettings.showProfileFollowersFeed)
             any = true
         }
+        if (dontShowOnchainPublicWarning.value != torSettings.dontShowOnchainPublicWarning) {
+            dontShowOnchainPublicWarning.tryEmit(torSettings.dontShowOnchainPublicWarning)
+            any = true
+        }
+        if (suggestWorkoutsFromHealthConnect.value != torSettings.suggestWorkoutsFromHealthConnect) {
+            suggestWorkoutsFromHealthConnect.tryEmit(torSettings.suggestWorkoutsFromHealthConnect)
+            any = true
+        }
 
         return any
     }
@@ -249,6 +265,12 @@ class UiSettingsFlow(
         }
     }
 
+    fun dontShowOnchainPublicWarning() {
+        if (!dontShowOnchainPublicWarning.value) {
+            dontShowOnchainPublicWarning.tryEmit(true)
+        }
+    }
+
     companion object {
         fun build(uiSettings: UiSettings): UiSettingsFlow =
             UiSettingsFlow(
@@ -275,6 +297,8 @@ class UiSettingsFlow(
                 MutableStateFlow(uiSettings.showProfileAppRecommendations),
                 MutableStateFlow(uiSettings.showProfileZapReceivedFeed),
                 MutableStateFlow(uiSettings.showProfileFollowersFeed),
+                MutableStateFlow(uiSettings.dontShowOnchainPublicWarning),
+                MutableStateFlow(uiSettings.suggestWorkoutsFromHealthConnect),
             )
     }
 }

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

@@ -22,7 +22,7 @@ package com.vitorpamplona.amethyst.model
 
 import android.util.LruCache
 import androidx.compose.runtime.Stable
-import com.vitorpamplona.amethyst.service.previews.UrlPreview
+import com.vitorpamplona.amethyst.commons.preview.UrlPreview
 import com.vitorpamplona.amethyst.ui.components.UrlPreviewState
 import okhttp3.OkHttpClient
 

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

@@ -22,3 +22,5 @@ package com.vitorpamplona.amethyst.model
 
 // Re-export from commons for backwards compatibility
 typealias User = com.vitorpamplona.amethyst.commons.model.User
+
+typealias UserContext = com.vitorpamplona.amethyst.commons.model.UserContext

amethyst/src/main/java/com/vitorpamplona/amethyst/model/accountsCache/AccountCacheState.kt

@@ -53,6 +53,9 @@ import java.io.File
 class AccountCacheState(
     val geolocationFlow: () -> StateFlow<LocationState.LocationResult>,
     val nwcFilterAssembler: () -> NWCPaymentFilterAssembler,
+    val cashuWalletFilterAssembler: () -> com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuWalletFilterAssembler,
+    val cashuMintDirectoryFilterAssembler: () -> com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuMintDirectoryFilterAssembler,
+    val okHttpClientForMoney: (String) -> okhttp3.OkHttpClient,
     val contentResolverFn: () -> ContentResolver,
     val otsResolverBuilder: () -> OtsResolver,
     val cache: LocalCache,
@@ -191,6 +194,9 @@ class AccountCacheState(
             signer = signerWithClientTag,
             geolocationFlow = geolocationFlow,
             nwcFilterAssembler = nwcFilterAssembler,
+            cashuWalletFilterAssembler = cashuWalletFilterAssembler,
+            cashuMintDirectoryFilterAssembler = cashuMintDirectoryFilterAssembler,
+            okHttpClientForMoney = okHttpClientForMoney,
             otsResolverBuilder = otsResolverBuilder,
             cache = cache,
             client = client,

amethyst/src/main/java/com/vitorpamplona/amethyst/model/marmot/AndroidMarmotMessageStore.kt

@@ -78,6 +78,10 @@ class AndroidMarmotMessageStore(
         writeMutex.withLock {
             try {
                 val existing = readAll(nostrGroupId).toMutableList()
+                if (innerEventJson in existing) {
+                    Log.d(TAG) { "appendMessage($nostrGroupId): duplicate entry skipped" }
+                    return@withLock
+                }
                 existing.add(innerEventJson)
                 writeAll(nostrGroupId, existing)
                 Log.d(TAG) {

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip01UserMetadata/UserMetadataState.kt

@@ -68,6 +68,7 @@ class UserMetadataState(
         nip05: String? = null,
         lnAddress: String? = null,
         lnURL: String? = null,
+        clinkOffer: String? = null,
     ): MetadataEvent {
         val latest = getUserMetadataEvent()
 
@@ -85,6 +86,7 @@ class UserMetadataState(
                     nip05 = nip05,
                     lnAddress = lnAddress,
                     lnURL = lnURL,
+                    clinkOffer = clinkOffer,
                 )
             } else {
                 MetadataEvent.createNew(
@@ -98,6 +100,7 @@ class UserMetadataState(
                     nip05 = nip05,
                     lnAddress = lnAddress,
                     lnURL = lnURL,
+                    clinkOffer = clinkOffer,
                 )
             }
 

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip03Timestamp/BitcoinExplorerEndpoint.kt

@@ -0,0 +1,64 @@
+/*
+ * 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.nip03Timestamp
+
+import com.vitorpamplona.quartz.nip03Timestamp.okhttp.OkHttpBitcoinExplorer
+
+/**
+ * Picks the Bitcoin block-explorer (Esplora) base URL.
+ *
+ * This is the single source of truth shared by two features that both talk to
+ * the same Esplora API:
+ * - OpenTimestamps verification ([TorAwareOkHttpOtsResolverBuilder]).
+ * - NIP-BC onchain zaps (the `EsploraBackend` wired in `AppModules`).
+ *
+ * So a user who configures a custom explorer in the OTS settings gets it for
+ * onchain zaps too, and both honour the same Tor preference: a configured
+ * [OtsSettings] custom URL always wins; otherwise mempool.space is used when
+ * Tor is active (it is reachable over Tor) and blockstream.info when it is not.
+ */
+object BitcoinExplorerEndpoint {
+    /**
+     * @param customExplorerUrl A user-configured explorer base URL, or null/blank
+     *        for the automatic Tor-aware default. Typically
+     *        `OtsSettings.normalizedUrl()`.
+     * @param usingTor Whether Bitcoin/"money" traffic is currently routed over Tor.
+     */
+    fun resolve(
+        customExplorerUrl: String?,
+        usingTor: Boolean,
+    ): String =
+        customExplorerUrl?.takeIf { it.isNotBlank() }
+            ?: if (usingTor) {
+                OkHttpBitcoinExplorer.MEMPOOL_API_URL
+            } else {
+                OkHttpBitcoinExplorer.BLOCKSTREAM_API_URL
+            }
+
+    /**
+     * Same as [resolve] but with any trailing slash stripped, for callers that
+     * join request paths with a leading `/` (e.g. `"$base/tx/$txid"`).
+     */
+    fun resolveNormalized(
+        customExplorerUrl: String?,
+        usingTor: Boolean,
+    ): String = resolve(customExplorerUrl, usingTor).trimEnd('/')
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip03Timestamp/TorAwareOkHttpOtsResolverBuilder.kt

@@ -33,13 +33,7 @@ class TorAwareOkHttpOtsResolverBuilder(
     val cache: OtsBlockHeightCache,
     val customExplorerUrl: () -> String? = { null },
 ) : OtsResolverBuilder {
-    fun getAPI(usingTor: Boolean): String =
-        customExplorerUrl()
-            ?: if (usingTor) {
-                OkHttpBitcoinExplorer.MEMPOOL_API_URL
-            } else {
-                OkHttpBitcoinExplorer.BLOCKSTREAM_API_URL
-            }
+    fun getAPI(usingTor: Boolean): String = BitcoinExplorerEndpoint.resolve(customExplorerUrl(), usingTor)
 
     override fun build(): OtsResolver =
         OtsResolver(

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip11RelayInfo/Nip11Retriever.kt

@@ -45,46 +45,51 @@ class Nip11Retriever(
         relay: NormalizedRelayUrl,
         onInfo: (Nip11RelayInformation) -> Unit,
         onError: (NormalizedRelayUrl, ErrorCode, String?) -> Unit,
-    ) {
+    ) = withContext(Dispatchers.IO) {
         val url = relay.toHttp()
-        try {
-            val request: Request =
+        val request =
+            try {
                 Request
                     .Builder()
                     .header("Accept", "application/nostr+json")
                     .url(url)
                     .build()
+            } catch (e: Exception) {
+                if (e is CancellationException) throw e
+                Log.e("RelayInfoFail", "Invalid URL ${relay.url}", e)
+                onError(relay, ErrorCode.FAIL_TO_ASSEMBLE_URL, e.message)
+                return@withContext
+            }
 
+        try {
             val client = okHttpClient(relay)
 
             client.newCall(request).executeAsync().use { response ->
-                withContext(Dispatchers.IO) {
-                    val body = response.body.string()
-                    try {
-                        if (response.isSuccessful) {
-                            if (body.startsWith("{")) {
-                                onInfo(Nip11RelayInformation.fromJson(body))
-                            } else {
-                                onError(relay, ErrorCode.FAIL_TO_PARSE_RESULT, body)
-                            }
+                val body = response.body.string()
+                try {
+                    if (response.isSuccessful) {
+                        if (body.startsWith("{")) {
+                            onInfo(Nip11RelayInformation.fromJson(body))
                         } else {
-                            onError(relay, ErrorCode.FAIL_WITH_HTTP_STATUS, response.code.toString())
+                            onError(relay, ErrorCode.FAIL_TO_PARSE_RESULT, body)
                         }
-                    } catch (e: Exception) {
-                        if (e is CancellationException) throw e
-                        Log.e(
-                            "RelayInfoFail",
-                            "Resulting Message from Relay ${relay.url} in not parseable: $body",
-                            e,
-                        )
-                        onError(relay, ErrorCode.FAIL_TO_PARSE_RESULT, e.message)
+                    } else {
+                        onError(relay, ErrorCode.FAIL_WITH_HTTP_STATUS, response.code.toString())
                     }
+                } catch (e: Exception) {
+                    if (e is CancellationException) throw e
+                    Log.e(
+                        "RelayInfoFail",
+                        "Resulting Message from Relay ${relay.url} in not parseable: $body",
+                        e,
+                    )
+                    onError(relay, ErrorCode.FAIL_TO_PARSE_RESULT, e.message)
                 }
             }
         } catch (e: Exception) {
             if (e is CancellationException) throw e
-            Log.e("RelayInfoFail", "Invalid URL ${relay.url}", e)
-            onError(relay, ErrorCode.FAIL_TO_ASSEMBLE_URL, e.message)
+            Log.e("RelayInfoFail", "Failed to fetch NIP-11 from ${relay.url}", e)
+            onError(relay, ErrorCode.FAIL_TO_REACH_SERVER, e.message ?: e::class.simpleName)
         }
     }
 }

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip30CustomEmojis/OwnedEmojiPacksState.kt

@@ -23,6 +23,7 @@ package com.vitorpamplona.amethyst.model.nip30CustomEmojis
 import com.vitorpamplona.amethyst.commons.model.anyNotNullEvent
 import com.vitorpamplona.amethyst.commons.model.eventIdSet
 import com.vitorpamplona.amethyst.commons.model.events
+import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.OwnedEmojiPack
 import com.vitorpamplona.amethyst.commons.model.updateFlow
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AddressableNote

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip47WalletConnect/NwcSignerState.kt

@@ -65,12 +65,10 @@ class NwcSignerState(
      * Flow of the default wallet's NWC URI, derived from multi-wallet settings.
      */
     val defaultWalletUri: StateFlow<Nip47WalletConnect.Nip47URINorm?> =
-        combine(settings.nwcWallets, settings.defaultNwcWalletId) { wallets, defaultId ->
-            if (defaultId != null) {
-                wallets.firstOrNull { it.id == defaultId }?.uri
-            } else {
-                wallets.firstOrNull()?.uri
-            }
+        combine(settings.nwcWallets, settings.defaultPaymentSourceId) { wallets, defaultId ->
+            // Use the NWC wallet the unified default points at; otherwise fall back to the
+            // first NWC wallet so NWC zap routing is unchanged for NWC-only users.
+            (wallets.firstOrNull { it.id == defaultId } ?: wallets.firstOrNull())?.uri
         }.flowOn(Dispatchers.IO)
             .stateIn(scope, SharingStarted.Eagerly, settings.defaultZapPaymentRequest())
 
@@ -144,7 +142,6 @@ class NwcSignerState(
 
         val filter =
             NWCPaymentQueryState(
-                fromServiceHex = walletService.pubKeyHex,
                 toUserHex = event.pubKey,
                 replyingToHex = event.id,
                 relay = walletService.relayUri,
@@ -152,16 +149,26 @@ class NwcSignerState(
 
         val assembler = nwcFilterAssembler()
 
-        assembler.subscribe(filter)
+        // Synchronous flush so the REQ frame is queued on the WebSocket before
+        // the EVENT is published. Without this, the bundler may delay REQ up
+        // to 500ms, and the wallet service's ephemeral kind 23195 reply can
+        // be missed.
+        assembler.subscribeAndFlush(filter)
 
-        scope.launch(Dispatchers.IO) {
-            delay(60000)
-            assembler.unsubscribe(filter)
-        }
+        // Safety net: drop the filter after 60s if the wallet never replies.
+        // The happy path (response arrives) cancels this job and unsubscribes
+        // through assembler.unsubscribeSoon, which debounces.
+        val timeoutJob =
+            scope.launch(Dispatchers.IO) {
+                delay(60000)
+                assembler.unsubscribe(filter)
+            }
 
         val responseCache = NostrWalletConnectResponseCache(walletSigner)
         cache.consume(event, null, true, walletService.relayUri) {
+            timeoutJob.cancel()
             onResponse(responseCache.decryptResponse(it))
+            assembler.unsubscribeSoon(filter)
         }
 
         return Pair(event, walletService.relayUri)
@@ -181,7 +188,6 @@ class NwcSignerState(
 
         val filter =
             NWCPaymentQueryState(
-                fromServiceHex = walletService.pubKeyHex,
                 toUserHex = event.pubKey,
                 replyingToHex = event.id,
                 relay = walletService.relayUri,
@@ -189,15 +195,23 @@ class NwcSignerState(
 
         val assembler = nwcFilterAssembler()
 
-        assembler.subscribe(filter)
+        // Synchronous flush so the REQ frame is queued before the EVENT.
+        // See sendNwcRequestToWallet above for the rationale.
+        assembler.subscribeAndFlush(filter)
 
-        scope.launch(Dispatchers.IO) {
-            delay(60000) // waits 1 minute to complete payment.
-            assembler.unsubscribe(filter)
-        }
+        // Safety net: drop the filter after 60s if the wallet never replies.
+        // The happy path (response arrives) cancels this job and instead
+        // hands off to assembler.unsubscribeSoon, which debounces.
+        val timeoutJob =
+            scope.launch(Dispatchers.IO) {
+                delay(60000) // waits 1 minute to complete payment.
+                assembler.unsubscribe(filter)
+            }
 
         cache.consume(event, zappedNote, true, walletService.relayUri) {
+            timeoutJob.cancel()
             onResponse(decryptResponse(it))
+            assembler.unsubscribeSoon(filter)
         }
 
         return Pair(event, walletService.relayUri)

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/blockPeopleList/BlockPeopleListState.kt

@@ -20,10 +20,10 @@
  */
 package com.vitorpamplona.amethyst.model.nip51Lists.blockPeopleList
 
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.peopleList.PeopleListDecryptionCache
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note
 import com.vitorpamplona.amethyst.model.NoteState
-import com.vitorpamplona.amethyst.model.nip51Lists.peopleList.PeopleListDecryptionCache
 import com.vitorpamplona.quartz.nip01Core.signers.NostrSigner
 import com.vitorpamplona.quartz.nip51Lists.muteList.tags.MuteTag
 import com.vitorpamplona.quartz.nip51Lists.muteList.tags.UserTag

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/favoriteAlgoFeedsLists/FavoriteAlgoFeedsListState.kt

@@ -20,6 +20,7 @@
  */
 package com.vitorpamplona.amethyst.model.nip51Lists.favoriteAlgoFeedsLists
 
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.favoriteAlgoFeedsLists.FavoriteAlgoFeedsListDecryptionCache
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.AddressableNote
 import com.vitorpamplona.amethyst.model.LocalCache

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/hashtagLists/HashtagListState.kt

@@ -20,6 +20,7 @@
  */
 package com.vitorpamplona.amethyst.model.nip51Lists.hashtagLists
 
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.hashtagLists.HashtagListDecryptionCache
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/interestSets/InterestSetsState.kt

@@ -23,6 +23,7 @@ package com.vitorpamplona.amethyst.model.nip51Lists.interestSets
 import com.vitorpamplona.amethyst.commons.model.anyNotNullEvent
 import com.vitorpamplona.amethyst.commons.model.eventIdSet
 import com.vitorpamplona.amethyst.commons.model.events
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.interestSets.InterestSet
 import com.vitorpamplona.amethyst.commons.model.updateFlow
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AddressableNote

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/labeledBookmarkLists/LabeledBookmarkListsState.kt

@@ -23,6 +23,7 @@ package com.vitorpamplona.amethyst.model.nip51Lists.labeledBookmarkLists
 import com.vitorpamplona.amethyst.commons.model.anyNotNullEvent
 import com.vitorpamplona.amethyst.commons.model.eventIdSet
 import com.vitorpamplona.amethyst.commons.model.events
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.labeledBookmarkLists.LabeledBookmarkList
 import com.vitorpamplona.amethyst.commons.model.updateFlow
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AddressableNote

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/muteList/MuteListState.kt

@@ -20,6 +20,7 @@
  */
 package com.vitorpamplona.amethyst.model.nip51Lists.muteList
 
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.muteList.MuteListDecryptionCache
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip51Lists/peopleList/PeopleListsState.kt

@@ -23,6 +23,7 @@ package com.vitorpamplona.amethyst.model.nip51Lists.peopleList
 import com.vitorpamplona.amethyst.commons.model.anyNotNullEvent
 import com.vitorpamplona.amethyst.commons.model.eventIdSet
 import com.vitorpamplona.amethyst.commons.model.events
+import com.vitorpamplona.amethyst.commons.model.nip51Lists.peopleList.PeopleListDecryptionCache
 import com.vitorpamplona.amethyst.commons.model.updateFlow
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AddressableNote

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip60Cashu/CashuMintDirectoryState.kt

@@ -0,0 +1,324 @@
+/*
+ * 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.nip60Cashu
+
+import androidx.compose.runtime.Immutable
+import com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuMintDirectoryFilterAssembler
+import com.vitorpamplona.amethyst.commons.relayClient.assemblers.CashuMintDirectoryQueryState
+import com.vitorpamplona.amethyst.model.LocalCache
+import com.vitorpamplona.quartz.nip01Core.core.HexKey
+import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
+import com.vitorpamplona.quartz.nip87Ecash.cashu.CashuMintEvent
+import com.vitorpamplona.quartz.nip87Ecash.recommendation.MintRecommendationEvent
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.flow.flowOn
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.launch
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * One mint as it appears in the NIP-87 directory.
+ *
+ * The same mint URL can be announced more than once (different operators,
+ * different keysets, different metadata). Picker UI typically shows the most
+ * recent announcement and aggregates recommendation counts across all
+ * announcements for the same URL.
+ */
+@Immutable
+data class CashuMintDirectoryEntry(
+    val url: String,
+    /** Most recent announcement we've seen for this URL, if any. */
+    val announcement: CashuMintEvent?,
+    /** Total kind:38000 recommendations targeting this mint's announcement. */
+    val recommendationCount: Int,
+    /** Recommendations specifically by [followedPubkeys] — surfaced first in the picker. */
+    val followsRecommendationCount: Int,
+    /**
+     * Pubkeys of followed users who have recommended this mint, capped at
+     * [MAX_FOLLOWS_RECOMMENDER_AVATARS] for cheap rendering. Length equals
+     * `min(followsRecommendationCount, MAX_FOLLOWS_RECOMMENDER_AVATARS)`.
+     * The remaining `followsRecommendationCount - size` followers are
+     * implied by the count, not enumerated here.
+     */
+    val followsRecommenderPubkeys: List<HexKey>,
+) {
+    companion object {
+        const val MAX_FOLLOWS_RECOMMENDER_AVATARS: Int = 6
+    }
+}
+
+/**
+ * Account-scoped index of cashu mint announcements + recommendations.
+ *
+ * Reactive: backfills from [LocalCache.notes] on first observer + listens to
+ * [LocalCache.live.newEventBundles] for incremental updates. The relay-side
+ * subscription is started/stopped via [open] / [close] so the directory only
+ * costs network bandwidth while a picker is on screen.
+ *
+ * Recommendation counts are derived per refresh from the latest snapshot —
+ * duplicate kind:38000 events from the same (pubkey, mint) pair are
+ * deduplicated so a single recommender can't inflate counts by re-posting.
+ */
+class CashuMintDirectoryState(
+    private val cache: LocalCache,
+    private val scope: CoroutineScope,
+    private val assembler: CashuMintDirectoryFilterAssembler,
+    private val followsFlow: StateFlow<Set<HexKey>>,
+) {
+    /** Mint announcements keyed by the announcement event id. */
+    private val announcements = ConcurrentHashMap<HexKey, CashuMintEvent>()
+
+    /** Recommendations keyed by event id — value is the parsed event. */
+    private val recommendations = ConcurrentHashMap<HexKey, MintRecommendationEvent>()
+
+    private val _entries = MutableStateFlow<List<CashuMintDirectoryEntry>>(emptyList())
+
+    /**
+     * Mint directory sorted by:
+     *   1. Number of recommendations from users we follow (descending)
+     *   2. Total recommendation count (descending)
+     *   3. Mint URL (ascending — stable tiebreaker)
+     */
+    val entries: StateFlow<List<CashuMintDirectoryEntry>> =
+        combine(_entries, followsFlow) { all, follows -> rank(all, follows) }
+            .flowOn(Dispatchers.Default)
+            .stateIn(scope, SharingStarted.Eagerly, emptyList())
+
+    val size: StateFlow<Int> =
+        entries.map { it.size }.stateIn(scope, SharingStarted.Eagerly, 0)
+
+    // ============================================================
+    // Subscription lifecycle (open while a picker is on screen)
+    // ============================================================
+    private var currentSubscription: CashuMintDirectoryQueryState? = null
+    private val openers = ConcurrentHashMap.newKeySet<Any>()
+    private val liveJobLock = Any()
+    private var liveJob: Job? = null
+
+    /**
+     * Begin observing new mint events. Idempotent — multiple openers can
+     * share one subscription, and the relay subscription is dropped when the
+     * last opener calls [close]. [opener] is any unique object the caller
+     * holds (typically the ViewModel instance) so we can ref-count cleanly.
+     */
+    fun open(
+        opener: Any,
+        relays: Set<NormalizedRelayUrl>,
+    ) {
+        if (openers.isEmpty()) {
+            // First opener — start the live indexer + relay subscription.
+            startLiveIndex()
+            backfillFromCacheAsync()
+        }
+        openers.add(opener)
+        syncSubscription(relays)
+    }
+
+    fun close(opener: Any) {
+        openers.remove(opener)
+        if (openers.isEmpty()) {
+            currentSubscription?.let { runCatching { assembler.unsubscribe(it) } }
+            currentSubscription = null
+            synchronized(liveJobLock) {
+                liveJob?.cancel()
+                liveJob = null
+            }
+        }
+    }
+
+    private fun syncSubscription(relays: Set<NormalizedRelayUrl>) {
+        val previous = currentSubscription
+        if (relays.isEmpty()) {
+            previous?.let { runCatching { assembler.unsubscribe(it) } }
+            currentSubscription = null
+            return
+        }
+        if (previous != null && previous.relays == relays) return
+
+        previous?.let { runCatching { assembler.unsubscribe(it) } }
+        val next = CashuMintDirectoryQueryState(relays)
+        currentSubscription = next
+        assembler.subscribe(next)
+    }
+
+    private fun startLiveIndex() {
+        synchronized(liveJobLock) {
+            if (liveJob != null) return
+            liveJob =
+                scope.launch(Dispatchers.Default) {
+                    cache.live.newEventBundles.collect { notes ->
+                        val touched =
+                            notes.mapNotNull { note ->
+                                when (val e = note.event) {
+                                    is CashuMintEvent -> announcements.put(e.id, e).let { true }
+                                    is MintRecommendationEvent -> {
+                                        if (e.isCashuRecommendation()) {
+                                            recommendations.put(e.id, e).let { true }
+                                        } else {
+                                            false
+                                        }
+                                    }
+                                    else -> false
+                                }
+                            }
+                        if (touched.isNotEmpty()) rebuildEntries()
+                    }
+                }
+        }
+    }
+
+    private fun backfillFromCacheAsync() {
+        scope.launch(Dispatchers.Default) {
+            cache.notes.forEach { _, note ->
+                when (val e = note.event) {
+                    is CashuMintEvent -> announcements[e.id] = e
+                    is MintRecommendationEvent -> if (e.isCashuRecommendation()) recommendations[e.id] = e
+                    else -> Unit
+                }
+            }
+            rebuildEntries()
+        }
+    }
+
+    // ============================================================
+    // Indexing
+    // ============================================================
+    private fun rebuildEntries() {
+        // 1. Group announcements by mint URL — most recent wins for display.
+        val byUrl: MutableMap<String, CashuMintEvent> = HashMap()
+        announcements.values.forEach { e ->
+            val url = e.mintUrl() ?: return@forEach
+            val existing = byUrl[url]
+            if (existing == null || e.createdAt > existing.createdAt) byUrl[url] = e
+        }
+
+        // 2. Build a per-URL set of announcement event ids so a recommendation
+        //    aTag → that mint's bucket. We use the d-tag (mint pubkey) per
+        //    NIP-87 to match recommendations to announcements — but many
+        //    clients also store the mint URL in the `u` tag of the
+        //    recommendation, so we accept both.
+        val urlByDTag: MutableMap<String, String> = HashMap()
+        announcements.values.forEach { e ->
+            val d = e.dTag()
+            val url = e.mintUrl()
+            if (d != null && url != null) urlByDTag[d] = url
+        }
+
+        // 3. Count recommendations per URL, deduplicating by (recommender, mint URL).
+        val perUrlAll: MutableMap<String, MutableSet<HexKey>> = HashMap()
+        val perUrlFollows: MutableMap<String, MutableSet<HexKey>> = HashMap()
+        val followSet = currentFollowSnapshot()
+
+        recommendations.values.forEach { rec ->
+            // Mints recommended via `u` tag(s) — directly carry the URL.
+            val urlsFromU = rec.mintUrls()
+            // Mints recommended via `a` tag(s) — look up the URL by mint d-tag.
+            val urlsFromA =
+                rec
+                    .mintEventAddresses()
+                    .mapNotNull { aTag ->
+                        // a-tag is "kind:pubkey:dTag" — we want the dTag.
+                        aTag.split(":").getOrNull(2)?.let(urlByDTag::get)
+                    }
+            (urlsFromU + urlsFromA).distinct().forEach { url ->
+                perUrlAll.getOrPut(url) { mutableSetOf() }.add(rec.pubKey)
+                if (rec.pubKey in followSet) {
+                    perUrlFollows.getOrPut(url) { mutableSetOf() }.add(rec.pubKey)
+                }
+            }
+        }
+
+        // 4. Build the final entries list — every URL with either an
+        //    announcement or a recommendation gets surfaced.
+        val allUrls = byUrl.keys + perUrlAll.keys
+        _entries.value =
+            allUrls.map { url ->
+                val followsRecs = perUrlFollows[url].orEmpty()
+                CashuMintDirectoryEntry(
+                    url = url,
+                    announcement = byUrl[url],
+                    recommendationCount = perUrlAll[url]?.size ?: 0,
+                    followsRecommendationCount = followsRecs.size,
+                    // Cap the per-row pubkey list — the row only renders
+                    // a small avatar gallery; the full count is preserved
+                    // in followsRecommendationCount for the "+N more" suffix.
+                    followsRecommenderPubkeys =
+                        followsRecs.take(CashuMintDirectoryEntry.MAX_FOLLOWS_RECOMMENDER_AVATARS).toList(),
+                )
+            }
+    }
+
+    private fun currentFollowSnapshot(): Set<HexKey> = followsFlow.value
+
+    private fun rank(
+        all: List<CashuMintDirectoryEntry>,
+        @Suppress("UNUSED_PARAMETER") follows: Set<HexKey>,
+    ): List<CashuMintDirectoryEntry> =
+        all.sortedWith(
+            compareByDescending<CashuMintDirectoryEntry> { it.followsRecommendationCount }
+                .thenByDescending { it.recommendationCount }
+                .thenBy { it.url },
+        )
+
+    // ============================================================
+    // Convenience accessors
+    // ============================================================
+
+    /** Find a directory entry by exact URL match (used to surface metadata for an already-known mint). */
+    fun lookup(url: String): CashuMintDirectoryEntry? = entries.value.firstOrNull { it.url == url }
+
+    /**
+     * Substring search ranked by the same comparator as [entries] —
+     * follows recommendations first, then total recommendations, then
+     * URL. Empty [query] returns the top mints overall, which is what
+     * the autocomplete dropdown shows before the user starts typing.
+     *
+     * Backs both the add-cashu-wallet autocomplete and the wallet
+     * settings "Add recommendation" flow; merging them onto one row
+     * composable lets both surfaces show the recommender avatar
+     * gallery and the +N suffix without each rolling their own join.
+     */
+    fun search(
+        query: String,
+        limit: Int = 6,
+    ): List<CashuMintDirectoryEntry> {
+        val needle = query.trim().lowercase()
+        val all = entries.value
+        val filtered =
+            if (needle.isEmpty()) {
+                all
+            } else {
+                all.filter {
+                    it.url.lowercase().contains(needle) ||
+                        (it.announcement?.content ?: "").lowercase().contains(needle) ||
+                        (it.announcement?.dTag() ?: "").lowercase().contains(needle)
+                }
+            }
+        return filtered.take(limit)
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip60Cashu/CashuPreferences.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.model.nip60Cashu
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.SharedPreferences
+import androidx.core.content.edit
+import com.vitorpamplona.amethyst.Amethyst
+
+/**
+ * Per-account Cashu state that needs durable, synchronous persistence —
+ * separate from [com.vitorpamplona.amethyst.model.AccountSettings] which
+ * batches writes through a 1-second debounced StateFlow.
+ *
+ * # Why a separate store
+ *
+ * The NUT-13 keyset counter is the critical bit. Every mint / swap /
+ * melt reserves counter slots, derives deterministic blinded outputs at
+ * those slots, sends them to the mint, and the mint signs them. The
+ * mint persists which (keyset, blind_message) pairs it has ever signed;
+ * a second request to sign the same blind_message returns HTTP 400
+ * "outputs already signed". So once the wallet hands a counter to the
+ * mint, the local counter advance MUST survive a crash — otherwise the
+ * next reservation pulls the same slot and the mint rejects it.
+ *
+ * The default settings save path debounces writes by 1000 ms, which is
+ * exactly the race window between "we asked the mint to sign" and "the
+ * mint replied". A crash inside that window (OOM, signer dialog dismiss,
+ * unexpected process death) loses the counter advance and makes the
+ * wallet unusable. This store writes via `commit = true` so each
+ * reservation is durable before the function returns.
+ *
+ * # Layout
+ *
+ * One SharedPreferences file per account, named
+ * `cashu_prefs_<npub>.xml`. Keys are flat:
+ *   - `counter_<keysetId>` → Long, the next free NUT-13 counter
+ *
+ * Plain (non-encrypted) prefs because keyset counters aren't secret —
+ * they're not the seed, they don't carry value, and a leak would only
+ * tell an attacker how many proofs the wallet has minted at each
+ * keyset (a privacy signal at most).
+ *
+ * # Migration
+ *
+ * Older builds stored counters inside `AccountSettings.cashuKeysetCounters`.
+ * On first read of a given keyset, callers should pre-seed the store
+ * from the legacy map (one-time copy) so an upgrade doesn't reset the
+ * counter to zero. See `AccountSettings.migrateCashuCountersTo` for
+ * the helper.
+ */
+class CashuPreferences(
+    private val prefs: SharedPreferences,
+) {
+    /** Inspect the next free counter for [keysetId] without advancing it. */
+    @Synchronized
+    fun peekCounter(keysetId: String): Long = prefs.getLong(counterKey(keysetId), 0L)
+
+    /**
+     * Atomically reserve [count] consecutive NUT-13 counters for
+     * [keysetId] and return the first reserved index. The write is
+     * forced to disk with `commit = true` BEFORE returning — see the
+     * class header for why this isn't optional.
+     */
+    @Synchronized
+    @SuppressLint("ApplySharedPref")
+    fun reserveCounters(
+        keysetId: String,
+        count: Int,
+    ): Long {
+        require(count > 0) { "Counter reservation must be positive" }
+        val current = peekCounter(keysetId)
+        val next = current + count.toLong()
+        prefs.edit(commit = true) { putLong(counterKey(keysetId), next) }
+        return current
+    }
+
+    /**
+     * Seed [keysetId]'s counter from a legacy value found in
+     * [AccountSettings.cashuKeysetCounters]. No-op when the store
+     * already has a value at or above [legacyValue] — never moves the
+     * counter backwards. Called once at wallet load to carry forward
+     * pre-migration state.
+     */
+    @Synchronized
+    @SuppressLint("ApplySharedPref")
+    fun seedCounterIfMissing(
+        keysetId: String,
+        legacyValue: Long,
+    ) {
+        if (legacyValue <= 0L) return
+        val current = peekCounter(keysetId)
+        if (current >= legacyValue) return
+        prefs.edit(commit = true) { putLong(counterKey(keysetId), legacyValue) }
+    }
+
+    companion object {
+        private const val FILE_PREFIX = "cashu_prefs_"
+
+        private fun counterKey(keysetId: String) = "counter_$keysetId"
+
+        /** Per-account instance. [npub] keys the on-disk file so each account is isolated. */
+        fun forAccount(npub: String): CashuPreferences {
+            val context = Amethyst.instance.appContext
+            val prefs = context.getSharedPreferences("$FILE_PREFIX$npub", Context.MODE_PRIVATE)
+            return CashuPreferences(prefs)
+        }
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/model/nip72Communities/CommunityListState.kt

@@ -20,6 +20,7 @@
  */
 package com.vitorpamplona.amethyst.model.nip72Communities
 
+import com.vitorpamplona.amethyst.commons.model.nip72Communities.CommunityListDecryptionCache
 import com.vitorpamplona.amethyst.model.AccountSettings
 import com.vitorpamplona.amethyst.model.AddressableNote
 import com.vitorpamplona.amethyst.model.LocalCache