fix: push remaining files with correct content (batch 3a)

https://claude.ai/code/session_01VminH5nD1jbzncbgTaqXEK

.claude/CLAUDE.md

@@ -3,38 +3,12 @@
 ## Project Overview
 
 Amethyst is a Nostr Client for Android that was made for Android-only and has been slowly switching
-over to a Kotlin Multiplatform project. The main modules are: `quartz`, `commons`, `amethyst`,
-`desktopApp`, `cli`, plus the audio-rooms transport stack `quic` + `nestsClient`. Quartz should
-contain implementations of Nostr specifications and utilities to help implement them. Commons stores
-shared code between Amethyst Android (`amethyst`) and Amethyst Desktop (`desktopApp`). The Desktop
-App is designed to be mouse first and so uses a completely different screen and navigation
-architecture while sharing the back end components with the android counterpart. `cli` ships `amy`,
-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. `geode` is a standalone JVM Nostr relay (Ktor) built on quartz's
-relay-server code; smaller modules are `benchmark` (Android macrobenchmarks),
-`relayBench` (head-to-head relay benchmark — boots geode, strfry and other
-relay binaries, replays a shared deterministic corpus, measures ingest/query/
-NIP-77 sync; `./relayBench/run.sh`, see `relayBench/README.md`) and
-`quic-interop` (QUIC interop runner, lives at `quic/interop`). `nestsClient` runs
-the audio-room protocol on top of `:quic` for the NIP-53 audio-rooms feature. It implements both IETF `draft-ietf-moq-transport-17` (under
-`moq/`) and **moq-lite Lite-03** (kixelated's variant, under `moq/lite/`); the
-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.
+over to a Kotlin Multiplatform project. This project has 4 main modules: `quartz`, `commons`,
+`amethyst` and `desktopApp`. Quartz should contain implementations of Nostr specifications and
+utilities to help implement them. Commons stores shared code between Amethyst Android (`amethyst`)
+and Amethyst Desktop (`desktopApp`). The Desktop App is designed to be mouse first and so uses a
+completely different screen and navigation architecture while sharing the back end components with
+the android counterpart.
 
 ## Architecture
 
@@ -51,141 +25,173 @@ amethyst/
 │       ├── commonMain/    # Shared composables, icons, state
 │       ├── androidMain/   # Android-specific UI utilities
 │       └── jvmMain/       # Desktop-specific UI utilities
-├── quic/           # Pure-Kotlin QUIC v1 + HTTP/3 + WebTransport (audio-rooms transport)
-│   └── src/
-│       ├── commonMain/    # Protocol, frame/packet codecs, TLS state machine
-│       ├── jvmAndroid/    # JCA-backed AEAD + UDP socket actuals
-│       └── commonTest/    # RFC vector + adversarial tests
-├── 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)
+└── ammolite/       # Support module (unused)
 ```
 
 **Sharing Philosophy:**
 - `quartz/` = Nostr business logic, protocol, data (no UI)
-- `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,
-  Quartz for crypto, `MediaCodec` / `AudioRecord` / `AudioTrack` for audio.
+- `commons/` = Shared UI components, icons, composables, flows and ViewModels
 - `amethyst/` & `desktopApp/` = Platform-native layouts and navigation
-- `cli/` = Thin assembly layer over `quartz/` + `commons/` (no new logic
-  allowed). May also depend on `:geode` (for `amy serve`, which embeds the
-  standalone relay); never on `:amethyst` or `:desktopApp`.
-
-**Plans per module:** design docs for new subsystems live in the owning
-module's `plans/YYYY-MM-DD-<slug>.md` (e.g. `cli/plans/`, `commons/plans/`).
-The global `docs/plans/` folder is frozen — don't add new plans there.
-
-## Android Runtime Processes (IMPORTANT — the app runs in TWO processes)
-
-The Android app is **not single-process**. Android instantiates the one `Amethyst`
-Application class (there is no per-process Application in the manifest) in **both**:
-
-- **main** — the normal app: UI, account, signer, `LocalCache`, relay client.
-  `Amethyst.instance` (`AppModules`) is built here.
-- **`:napplet`** — the sandboxed WebView host for NIP-5D napplets / NIP-5A nSites
-  (`NappletHostActivity`, declared `android:process=":napplet"`). It holds **no**
-  account or keys; `Amethyst.onCreate()` early-returns here so `Amethyst.instance`
-  is **left unset** (touching it throws `UninitializedPropertyAccessException`).
-  The sandbox runtime lives in its own module **`:nappletHost`** (depends only on
-  `:commons` + `:quartz`, **never** `:amethyst`) so it *cannot* import
-  `Amethyst`/`LocalCache`/`Account` — the broker-side (signer, gateways, registry)
-  stays in `:amethyst` and the two halves talk over Messenger IPC.
-
-Consequences — don't get caught assuming one process:
-
-- **Processes don't share memory.** Every `object`/companion/`static` is a
-  *separate copy per process*: `LocalCache` (an `object`), `NappletLaunchRegistry`,
-  etc. The populated `LocalCache` lives only in **main**; the sandbox neither
-  builds nor should reference it (a stray reference would lazily create a second,
-  empty cache there).
-- **Don't assume `Amethyst.instance` exists.** Any code reachable from `:napplet`
-  (the host activity, content server, or an Application lifecycle callback like
-  `onTrimMemory`) must guard on the process and never reach for `instance`.
-- **Cross-process state goes over Messenger IPC**, never a shared singleton — this
-  is why the broker (main) owns `NappletLaunchRegistry` and the sandbox only relays
-  an opaque token. See `amethyst/plans/2026-06-22-napplet-nsite-security.md`.
 
 ## Tech Stack
 
-Exact versions live in `gradle/libs.versions.toml` (the source of truth — check
-there rather than trusting a number copied here).
-
 | Layer | Technology |
 |-------|------------|
 | **Core** | Quartz (Nostr KMP) |
-| **UI** | Compose Multiplatform |
+| **UI** | Compose Multiplatform 1.7.x |
 | **Async** | kotlinx.coroutines + Flow |
 | **Network** | OkHttp (JVM) |
 | **Serialization** | Jackson |
 | **DI** | Manual / Koin |
-| **Build** | Gradle + Kotlin Multiplatform |
+| **Build** | Gradle 8.x, Kotlin 2.1.0 |
 
 ## Skills
 
-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:
+Specialized skills provide domain expertise with bundled resources and patterns:
 
-- **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.
+| Skill | Expertise | When to Use |
+|-------|-----------|-------------|
+| `nostr-expert` | Nostr protocol (Quartz library) | Event types, NIPs, tags, signing, Bech32 |
+| `kotlin-expert` | Advanced Kotlin patterns | StateFlow, sealed classes, @Immutable, DSLs |
+| `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 |
+| `android-expert` | Android platform | Navigation, permissions, lifecycle, Material3 |
+| `desktop-expert` | Desktop platform | Window, MenuBar, Tray, keyboard shortcuts |
+| `gradle-expert` | Build system | Dependencies, versioning, packaging, optimization |
+
+## 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
 
 ## Feature Workflow
 
-**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.
+**CRITICAL: Always check existing implementations first before creating new code!**
 
-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.
+When picking up a new task or feature, follow this process:
 
-**Relay client ops already exist — don't hand-roll subscribe/REQ/publish loops.**
-One-shot and high-level relay operations (fetch a set, fetch one, page past the
-relay cap, publish-and-confirm, NIP-45 count, NIP-77 sync/reconcile) are
-`INostrClient` **extension functions** in
-`quartz/…/nip01Core/relay/client/accessories/` (+ `…/reqs/` for the flow/subscribe
-helpers). Because they're extensions, they don't surface under "usages of
-`NostrClient`" or in completion — grep that package (or read its `README.md`, which
-catalogs them) before writing a new subscription/collect loop. Reuse `fetchAll`,
-`fetchFirst`, `fetchAllPages`, `publishAndConfirm`, `count`, `negentropyReconcile`,
-etc. instead of re-implementing them.
+### 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/
 
-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.
+   # 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.
 
 ## Build Commands
 
@@ -206,65 +212,41 @@ version. `quartz/` is protocol-only — no composables.
 ./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
 
-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.
+The Quartz library uses expect/actual for platform-specific implementations:
 
-## Icons
+```kotlin
+// commonMain - shared protocol logic
+expect class CryptoProvider {
+    fun sign(message: ByteArray, privateKey: ByteArray): ByteArray
+    fun verify(message: ByteArray, signature: ByteArray, publicKey: ByteArray): Boolean
+}
 
-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`.
+// androidMain - uses secp256k1-kmp-jni-android
+actual class CryptoProvider { /* Android 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
+// jvmMain - uses secp256k1-kmp-jni-jvm
+actual class CryptoProvider { /* JVM implementation */ }
 ```
 
-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.
+## Key Patterns
 
-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`).
+### 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))
+}
+```
 
 ## Code Formatting
 After completing any task that modifies Kotlin files, always run:
@@ -273,65 +255,18 @@ After completing any task that modifies Kotlin files, always run:
 ```
 Do this before considering the task complete.
 
-### Kotlin Style
-
-- **Never write fully-qualified class names inline in function bodies.** Add an
-  `import` for the class and reference it by its simple name. Write
-  `Event` (with `import com.vitorpamplona.quartz...Event`), not
-  `com.vitorpamplona.quartz...Event` in the middle of code.
-- The only acceptable inline fully-qualified names are: a genuine name
-  collision (prefer `import ... as Alias` instead), or where the language
-  requires it. Comments, KDoc, and string literals are exempt.
-- **Prefer the `androidx.core` KTX extension over the raw platform Java call**
-  when one exists — this is what Android Lint's `UseKtx` flags. Common swaps:
-  `Bitmap.createBitmap(w, h, cfg)` → `createBitmap(w, h)`,
-  `Bitmap.createScaledBitmap(src, w, h, f)` → `src.scale(w, h, f)`,
-  `Uri.parse(s)` → `s.toUri()`, and `prefs.edit()…apply()` → `prefs.edit { }`.
-  Only adopt the KTX form when it's behaviour-preserving: keep any explicit
-  argument that differs from the extension's default (a non-`ARGB_8888`
-  `Bitmap.Config`, `scale(filter = false)`), and leave calls the KTX has no
-  equivalent for (e.g. the `createBitmap` pixels/matrix overloads, or a
-  conditional-`apply()` editor loop) untouched.
-- **This "prefer the KTX sugar" rule does NOT extend to collection operators.**
-  The KTX preference is about platform wrappers (`Bitmap`/`Uri`/`SharedPreferences`),
-  which compile to the identical call. Collections are the opposite: in hot
-  event/parse paths Quartz deliberately uses raw JVM arrays (`TagArray =
-  Array<Array<String>>`) and the inline `fast*` operators (`fastForEach`,
-  `fastAny`, `fastFirstOrNull`, `fastFirstNotNullOfOrNull`, … in
-  `nip01Core/core/TagArray.kt`) instead of Kotlin `List` + stdlib
-  `forEach`/`map`/`filter`/`any` — the `fast*` variants allocate no iterator,
-  no intermediate list, and no lambda object. Don't "modernize" those into
-  stdlib collection calls; match the surrounding hot-path style.
-- **Never put raw invisible/bidirectional Unicode characters in source files**
-  — write them as `\uXXXX` escapes instead (`'\u202E'`, `Regex("[\u200B-\u200D\uFEFF]")`).
-  This covers the bidi family Sonar's Trojan-Source rule (CVE-2021-42574)
-  flags — U+202A–U+202E, the isolates U+2066–U+2069, U+200E/U+200F, U+061C —
-  plus zero-width characters (U+200B–U+200D, U+FEFF, U+2060). The escape
-  compiles to the identical codepoint, so behaviour is unchanged; the point is
-  that the file on disk stays visually unambiguous. Applies even when the
-  character is *intentional* (sanitizer strip-lists, adversarial test
-  payloads) — that's data, and escapes express it just as well. Exceptions:
-  U+200D as part of a real emoji ZWJ sequence in test data (👩‍👧 — functional,
-  not a bidi control), and LRM/RLM inside Crowdin-managed `strings.xml`
-  translations (legitimate RTL typography; don't touch those files by hand
-  anyway). Note the tooling trap: the Edit tool may normalise a typed
-  `\uXXXX` back into the raw character — if that happens, do the replacement
-  at byte level (`perl -CSD -pe 's/\x{202E}/\\u202E/g'`).
-
 ### Navigation Shell
 - **Desktop**: Sidebar + main content area
 - **Android**: Bottom navigation
 
 ## Git Workflow
 
+- Branch: `feat/desktop-<feature>` or `fix/desktop-<issue>`
 - Commits: Conventional commits (`feat:`, `fix:`, etc.)
 - Never use `--no-verify`
 
-### Remotes & pull requests
+## Resources
 
-A PR can be published two ways, via two **kinds** of remote — identify them by **URL** (`git remote -v`), because the names vary per clone and **a collaborator may have only one**:
-
-- a **GitHub** remote (`github.com/vitorpamplona/amethyst`) — the **canonical** `main`; moves constantly. Standard `gh` PR flow.
-- a **git-over-nostr** remote (`nostr://…/relay.ngit.dev/amethyst`, via `ngit`) — pushing fans out to GitHub **and** the GRASP git servers; **PRs here are nostr proposals** (the `pr/feat/*` branches), reviewed on **gitworkshop.dev** — *not* GitHub PRs. (In the maintainer's checkout these happen to be named `upstream` and `origin` respectively, but don't rely on that.)
-
-Before opening, revising, or merging a PR by **either** path, use the **`ngit-pr`** skill. It covers when to use which, identifying your remotes by URL, the `gh` and `ngit` commands, and — critically for the nostr path — the three-mains alignment gate (GitHub main vs the lagging nostr `main` vs local `main`) that its create/revise/merge flows depend on. Skipping it leads to rejected pushes and PRs that don't show up as revisions.
+- [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 21+ (`jvmToolchain(21)` in `desktopApp/build.gradle.kts`)
+1. **JDK Version**: Requires JDK 17+
    ```bash
    java -version
    ```
@@ -39,7 +39,7 @@ If the build fails, check:
 ./gradlew :desktopApp:packageMsi
 
 # Linux
-./gradlew :desktopApp:packageDeb   # or :desktopApp:packageRpm
+./gradlew :desktopApp:packageDeb
 ```
 
-Outputs will be in `desktopApp/build/compose/binaries/main/`
+Outputs will be in `desktopApp/build/compose/binaries/`

.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*"
+   find amethyst/src -name "*$ARGUMENTS*" -o -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 → `commons/commonMain/`
+   - Pure Composable functions → `shared-ui/commonMain/`
    - Business logic → `quartz/commonMain/`
    - Platform-specific → create expect/actual
 

.claude/core-skills-plan.md

@@ -1,87 +1,322 @@
-# Amethyst Skill Library — History & Changelog
+# AmethystMultiplatform Skills Creation Plan
 
-> 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`.
+## Overview
+Create 8 hybrid domain skills combining general expertise with AmethystMultiplatform-specific patterns.
 
-## Phase 1 (2025): Core skills created
+**Approach:** Each skill provides domain knowledge + project-specific implementation patterns from codebase.
 
-Eight hybrid domain skills (general expertise + Amethyst-specific patterns),
-each with a SKILL.md plus bundled `references/` and `scripts/`:
+## Skills to Implement
 
-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)
+### 1. kotlin-multiplatform ✅ COMPLETED
+**Focus:** KMP architecture, jvmAndroid source set pattern, expect/actual
 
-## Phase 2 (2026-04): Audit & Expansion
+**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
 
-After a full audit of the skill library, the following changes were made:
+**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
 
-### Stale references fixed
-- `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.
+**Differentiation:** Existing kotlin-multiplatform agent = general KMP. This skill = Amethyst's unique jvmAndroid pattern, concrete examples.
 
-### Redundant files removed
-- `.claude/skills/compose-desktop.md` deleted (superseded by `desktop-expert/`).
+**Status:** ✅ Skill created and packaged at `.claude/skills/kotlin-multiplatform/`
 
-### New references added to existing skills
-- `nostr-expert/references/nip19-bech32.md` — `Nip19Parser`, `Bech32Util`, `TlvBuilder`, entities.
-- `nostr-expert/references/event-factory.md` — `EventFactory` dispatch + registering a new kind.
-- `nostr-expert/references/crypto-and-encryption.md` — `EventHasher`, `Secp256k1Instance`, NIP-44, `SharedKeyCache`.
-- `nostr-expert/references/large-cache.md` — `LargeCache<K,V>` + `ICacheOperations`.
-- `kotlin-expert/references/common-utilities.md` — `NumberFormatters`, `TimeUtils`, `Hex`, `PubKeyFormatter`, `CoroutinesExt.launchIO`, etc.
-- `compose-expert/references/rich-text-parsing.md` — `RichTextParser`, `UrlParser`, `GalleryParser`, NIP-92 imeta.
-- `android-expert/references/image-loading.md` — Coil 3.x setup, custom fetchers, `MyAsyncImage`, `RobohashAsyncImage`.
+---
 
-### New skills created
-- **`account-state/`** — `Account.kt` (50+ StateFlow properties) and `LocalCache.kt` event store.
-- **`relay-client/`** — `ComposeSubscriptionManager`, filter assemblers, preloaders.
-- **`feed-patterns/`** — `FeedFilter`, `AdditiveComplexFeedFilter`, `FeedViewModel` hierarchy in `commons/`.
-- **`auth-signers/`** — `NostrSigner` abstraction across internal, NIP-46 remote, and NIP-55 external signers.
+### 2. gradle-expert ✅ COMPLETED
+**Focus:** Build optimization, dependency resolution, multi-module KMP troubleshooting
 
-## Phase 3 (2026-06): Fable 5 config review
+**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
 
-Instructions written to coach older models were removed now that the model
-handles them natively; stale references fixed:
+**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
 
-- `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.
+**Differentiation:** Focus on 4-module structure, KMP + Android + Desktop combo, specific issues (compose conflicts).
 
-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):
+**Status:** ✅ SKILL.md (549 lines) + 4 references + 2 scripts created at `.claude/skills/gradle-expert/`
 
-- `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>`.
+---
+
+### 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/

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

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

.claude/hooks/session-start.sh

@@ -129,17 +129,17 @@ install_sdk_package() {
   echo "Installed to $dest_dir"
 }
 
-# Install Android platform 37
+# Install Android platform 36
 install_sdk_package \
-  "$SDK_REPO_BASE/platform-37.0_r01.zip" \
-  "$ANDROID_SDK_DIR/platforms/android-37" \
-  "android-37.0"
+  "$SDK_REPO_BASE/platform-36_r02.zip" \
+  "$ANDROID_SDK_DIR/platforms/android-36" \
+  "android-36"
 
-# Install build-tools 37.0.0 (zip uses "android-37.0" as inner dir name)
+# Install build-tools 36.0.0 (zip uses "android-16" as inner dir name)
 install_sdk_package \
-  "$SDK_REPO_BASE/build-tools_r37_linux.zip" \
-  "$ANDROID_SDK_DIR/build-tools/37.0.0" \
-  "android-37.0"
+  "$SDK_REPO_BASE/build-tools_r36_linux.zip" \
+  "$ANDROID_SDK_DIR/build-tools/36.0.0" \
+  "android-16"
 
 # Install platform-tools
 install_sdk_package \
@@ -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:-$PWD}")"
+REPO_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-/home/user/Amber}")"
 LOCAL_PROPS="$REPO_ROOT/local.properties"
 if [ ! -f "$LOCAL_PROPS" ]; then
   echo "sdk.dir=$ANDROID_SDK_DIR" > "$LOCAL_PROPS"
@@ -174,97 +174,6 @@ if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
   echo "export PATH=\$PATH:$ANDROID_SDK_DIR/platform-tools" >> "$CLAUDE_ENV_FILE"
 fi
 
-# --- Kotlin/Native: pre-install native dependencies (GCC sysroot, LLDB) ---
-# The K/N compiler downloads these on first use, but that fails through the proxy.
-# Pre-download them so K/N benchmarks and linuxX64 compilation work out of the box.
-KONAN_DIR="/root/.konan"
-KONAN_DEPS_URL="https://download.jetbrains.com/kotlin/native"
-KONAN_DEPS_DIR="$KONAN_DIR/dependencies"
-
-install_konan_dep() {
-  local dep_name="$1"
-  local url="$2"  # full download URL
-  # Already extracted?
-  if [ -d "$KONAN_DEPS_DIR/$dep_name" ]; then
-    return 0
-  fi
-  local archive="$dep_name.tar.gz"
-  local cache_dir="$KONAN_DEPS_DIR/cache"
-  mkdir -p "$cache_dir"
-  if [ ! -f "$cache_dir/$archive" ]; then
-    echo "Downloading K/N dependency $dep_name..."
-    curl -fsSL "$url" -o "$cache_dir/$archive" || {
-      echo "Failed to download $dep_name" >&2; return 1
-    }
-  fi
-  echo "Extracting $dep_name..."
-  tar -xzf "$cache_dir/$archive" -C "$KONAN_DEPS_DIR"
-}
-
-# Dependencies for linuxX64 target (from konan.properties for Kotlin 2.3.20)
-install_konan_dep "x86_64-unknown-linux-gnu-gcc-8.3.0-glibc-2.19-kernel-4.9-2" \
-  "$KONAN_DEPS_URL/x86_64-unknown-linux-gnu-gcc-8.3.0-glibc-2.19-kernel-4.9-2.tar.gz"
-install_konan_dep "lldb-4-linux" \
-  "$KONAN_DEPS_URL/lldb-4-linux.tar.gz"
-install_konan_dep "llvm-19-x86_64-linux-essentials-109" \
-  "$KONAN_DEPS_URL/resources/llvm/19-x86_64-linux/llvm-19-x86_64-linux-essentials-109.tar.gz"
-install_konan_dep "libffi-3.2.1-2-linux-x86-64" \
-  "$KONAN_DEPS_URL/libffi-3.2.1-2-linux-x86-64.tar.gz"
-
-# --- Gradle distribution: pre-seed the wrapper distribution ---
-# The wrapper's distributionUrl (services.gradle.org) 307-redirects to
-# github.com release assets, which the web sandbox's git-only GitHub proxy
-# blocks (403) even at Full network access — so `./gradlew` can't bootstrap.
-# Download the pinned distribution from a mirror instead, but verify it against
-# Gradle's OFFICIAL sha256 (served from services.gradle.org, reachable here)
-# so a tampered/wrong mirror file is rejected and never executed. Idempotent:
-# skips entirely if the distribution is already installed.
-seed_gradle_distribution() {
-  local props="$CLAUDE_PROJECT_DIR/gradle/wrapper/gradle-wrapper.properties"
-  [ -f "$props" ] || return 0
-  local url zip name hash dir ver official mirror ok=""
-  url=$(sed -n 's/^distributionUrl=//p' "$props" | sed 's/\\//g')
-  [ -n "$url" ] || return 0
-  zip=${url##*/}; name=${zip%.zip}
-  # Gradle stores the dist under base36(md5(distributionUrl)) — derive it so this
-  # keeps working across version bumps instead of hardcoding the hash dir.
-  hash=$(python3 - "$url" <<'PY'
-import hashlib, sys
-n = int.from_bytes(hashlib.md5(sys.argv[1].encode()).digest(), 'big')
-d = "0123456789abcdefghijklmnopqrstuvwxyz"; s = ""
-while n:
-    s = d[n % 36] + s; n //= 36
-print(s or "0")
-PY
-)
-  dir="${GRADLE_USER_HOME:-$HOME/.gradle}/wrapper/dists/$name/$hash"
-  ver=${name%-bin}; ver=${ver%-all}
-  if [ -x "$dir/$ver/bin/gradle" ]; then return 0; fi   # already installed
-  echo "Seeding Gradle distribution $ver (github release blocked; using verified mirror)..." >&2
-  mkdir -p "$dir"
-  official=$(curl -fsSL "https://services.gradle.org/distributions/${zip}.sha256") || {
-    echo "Could not fetch official Gradle checksum; leaving gradlew to fail as before." >&2
-    return 0
-  }
-  for mirror in \
-      "https://mirrors.cloud.tencent.com/gradle" \
-      "https://mirrors.huaweicloud.com/gradle"; do
-    if curl -fsSL -o "$dir/$zip" "$mirror/$zip" \
-       && echo "${official}  $dir/$zip" | sha256sum -c - >/dev/null 2>&1; then
-      ok=1; break
-    fi
-    echo "Mirror $mirror failed download/verify; trying next." >&2
-    rm -f "$dir/$zip"
-  done
-  if [ -z "$ok" ]; then
-    echo "Gradle seed failed against all mirrors; leaving gradlew to fail as before." >&2
-    return 0
-  fi
-  unzip -q "$dir/$zip" -d "$dir" && touch "$dir/$zip.ok"
-  echo "Gradle $ver seeded and verified against official sha256." >&2
-}
-seed_gradle_distribution
-
 cd "$CLAUDE_PROJECT_DIR"
 ./gradlew --version > /dev/null 2>&1
 

.claude/hooks/stop-spotless.sh

@@ -1,12 +0,0 @@
-#!/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

@@ -1,17 +1,5 @@
 {
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|mcp__github__create_pull_request",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-push-spotless.sh",
-            "timeout": 180
-          }
-        ]
-      }
-    ],
     "SessionStart": [
       {
         "hooks": [
@@ -28,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-spotless.sh",
+            "command": "./gradlew spotlessApply 2>/dev/null || spotless-apply",
             "timeout": 120
           }
         ]

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

@@ -1,100 +0,0 @@
----
-name: account-state
-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
-
-The backbone of Amethyst's client state: one `Account` per signed-in user, plus the singleton `LocalCache` that holds every `Note` and `User` the client has seen.
-
-## When to Use This Skill
-
-- Working on `amethyst/src/main/java/com/vitorpamplona/amethyst/model/Account.kt`
-- Working on `amethyst/src/main/java/com/vitorpamplona/amethyst/model/LocalCache.kt`
-- Adding a new account-scoped setting (mutes, bookmarks, custom relay lists, private lists)
-- Reading/writing user metadata (`User`) or note state (`Note`)
-- Deciding whether to query `LocalCache` vs subscribe to an `Account` StateFlow
-
-## Mental Model
-
-```
-Relay frame ──► LocalCache.insertOrUpdateNote() ──► LocalCacheFlow emits change
-                                                            │
-                                                            ▼
-                                Account state objects pin the relevant addressable notes
-                                                            │
-                                                            ▼
-                            State-object `.flow` updates (kind3FollowList, nip65RelayList, muteList, …)
-                                                            │
-                                                            ▼
-                                                    ViewModels collect
-                                                            │
-                                                            ▼
-                                                 Composables render
-```
-
-`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+ **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`
-
-- `object LocalCache : ILocalCache, ICacheProvider` — the singleton event store.
-- Primary structures (all `LargeCache` — see `nostr-expert/references/large-cache.md`):
-  - `notes: LargeCache<HexKey, Note>` — every seen event (regular + addressable + replaceable) keyed by id or d-address.
-  - `users: LargeCache<HexKey, User>` — every seen pubkey, lazily populated.
-  - `addressables: LargeCache<Address, Note>` — secondary index for `kind:pubkey:d-tag` lookups.
-  - `channels`, `deletionIndex`, `hashtagIndex`, …
-- `LocalCacheFlow` emits coarse-grained "something changed, recheck" signals. Fine-grained reactivity lives in `Account`'s per-kind StateFlows.
-- Eviction is driven by `MemoryTrimmingService` (android service) under pressure.
-
-### Model classes
-
-- `User.kt` — mutable profile holder. Contains metadata, follow/follower counts, relay lists, liveset of notes authored.
-- `Note.kt` — mutable note holder. Contains the underlying `Event`, replies, reactions, zaps. Mutation via `addReply`, `addReaction`, `addZap`, emitted on `Note.flowSet` flows.
-- `Constants.kt` — DEFAULT_RELAYS, magic kinds/limits not covered by quartz.
-
-## Adding a New Account-Scoped Setting
-
-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 `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.<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.
-- **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` 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,94 +0,0 @@
-# Account State-Object Catalog
-
-`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`.
-
-(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
-
-| 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/` |
-
-## Relay Lists
-
-| 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
-
-| 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/` |
-
-## Other Feature State
-
-| 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 | — |
-
-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
-
-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.
-
-## When a State Object Doesn't Exist Yet
-
-If you're adding a new NIP that's user-scoped, follow the pattern (full recipe
-in `SKILL.md`):
-
-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/account-state/references/local-cache.md

@@ -1,101 +0,0 @@
-# LocalCache: The Singleton Event Store
-
-`amethyst/src/main/java/com/vitorpamplona/amethyst/model/LocalCache.kt` is the singleton (`object LocalCache`) that holds every event the client has received during the session. All rendering, all feed building, all search goes through it.
-
-## Shape
-
-```kotlin
-object LocalCache : ILocalCache, ICacheProvider {
-    val notes:        LargeCache<HexKey, Note>
-    val users:        LargeCache<HexKey, User>
-    val addressables: LargeCache<Address, Note>
-    val channels, deletionIndex, hashtagIndex, …
-}
-```
-
-All `LargeCache<K,V>` — see `nostr-expert/references/large-cache.md`. Thread-safe `getOrCreate`, functional scan with `forEach` / `filter` / `map`.
-
-## Insertion Path
-
-```
-Relay frame (EVENT "sub-id" {...})
-   │
-   ▼
-RelayPool / subscription manager calls parseNostrEvent(json)
-   │
-   ▼
-EventFactory.create(kind, ...) → typed Event subclass
-   │
-   ▼
-LocalCache.consume(event) / insertOrUpdateNote(event)
-   │
-   ├─ notes.getOrCreate(id) { Note(id) } — finds/creates the Note wrapper
-   ├─ updates note.event if this is a newer replaceable / first time for regular
-   ├─ reindex: hashtag tags → hashtagIndex, addressable → addressables, deletions → deletionIndex
-   ├─ for metadata: user.latestMetadata = event; user.liveMetadata.tryEmit(user)
-   └─ LocalCacheFlow signals listeners that something changed
-```
-
-`Note` and `User` are mutable wrappers — `getOrCreate` returns the same object across subsequent inserts for the same id/pubkey, which is why other code can `remember(noteId)` a `Note` reference and have it stay fresh.
-
-## Lookup
-
-```kotlin
-// By id (regular or replaceable)
-val note: Note = LocalCache.getOrCreateNote(id)
-
-// By `kind:pubkey:d-tag`
-val addressable: Note? = LocalCache.getAddressableNoteIfExists(address)
-
-// By pubkey
-val user: User = LocalCache.getOrCreateUser(pubKey)
-
-// By hashtag
-LocalCache.hashtagIndex.filter { _, notes -> ... }
-```
-
-All `getOrCreate*` functions are safe to call from any thread. They return immediately; they do NOT trigger network I/O.
-
-## Eviction
-
-Android-only. `amethyst/.../service/eventCache/MemoryTrimmingService.kt` listens for `ComponentCallbacks2.onTrimMemory` levels and drops least-recently-used entries from `notes` and `users`. On aggressive eviction, previously-returned `Note` / `User` references remain usable (they're just detached from the cache) but any new ids will produce new objects.
-
-## Reactive Consumption
-
-### Note-level
-
-```kotlin
-val note = LocalCache.getOrCreateNote(id)
-val metadata by note.flowSet.metadata.collectAsState()
-// `flowSet` has flows for: metadata, replies, reactions, zaps, reports, …
-```
-
-### Global
-
-```kotlin
-LocalCacheFlow.live.collectLatest {
-    // coarse "something changed" ping — used by feeds to re-run filters
-}
-```
-
-For per-feature reactivity (follow list changed, relays changed), prefer `Account.<featureFlow>` over `LocalCacheFlow`.
-
-## Deletion / Replacement
-
-- **Regular events**: once inserted, the first event wins unless explicitly deleted via a kind-5 deletion. `deletionIndex` tracks ids to hide.
-- **Replaceable** (kinds 0, 3, 10000-19999): a newer `created_at` replaces the older event in-place on the same `Note` wrapper.
-- **Addressable** (kinds 30000-39999): same as replaceable but keyed by `kind:pubkey:d-tag` in the `addressables` index.
-
-## Gotchas
-
-- **Don't hold a direct `Event` reference** — hold the `Note` wrapper. The `Note.event` field can be replaced by newer replaceable/addressable events behind your back.
-- **`LocalCache` is process-global**. Tests must either use a dedicated test fixture or reset it between cases.
-- **No TTL beyond memory pressure.** A long-running session accumulates. If you need bounded retention, do it at the feed / filter layer.
-- **Scanning the full cache is expensive** in hot paths. Always prefer an index (hashtag, addressable) or a pre-built feed filter.
-- **Eviction is not atomic with in-flight coroutines**. If you `forEach` during low-memory, you may see concurrent removals — that's fine, the snapshot semantics in `LargeCache` keep it safe, but your result set shrinks.
-
-## Related
-
-- `nostr-expert/references/large-cache.md` — the underlying cache primitive.
-- `nostr-expert/references/event-factory.md` — how raw JSON becomes the typed `Event` that `LocalCache` stores.
-- `feed-patterns` skill — how feeds scan and observe `LocalCache` efficiently.

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

@@ -1,258 +0,0 @@
----
-name: amy-expert
-description: Patterns for extending `amy`, the Amethyst CLI in `cli/`. Use when adding an `amy <verb>` command, touching files under `cli/src/main/kotlin/…/cli/`, wiring a new subcommand into `Main.kt`, writing an interop test script that drives Amy, or extracting logic out of `amethyst/` into `commons/` so a CLI command can call it. Enforces the thin-assembly-layer rule (no Nostr protocol or business logic inside `cli/`), the dual-output contract (text by default, single-line JSON object on stdout under `--json`, exit codes 0/1/2/124), and the extract-from-Android recipe. Complements `nostr-expert` (protocol in Quartz), `kotlin-multiplatform` (expect/actual for extraction), and `feed-patterns` / `account-state` / `relay-client` (where the business logic should end up). NOT for general Nostr or Kotlin work — those have their own skills.
----
-
-# Amy CLI Expert
-
-Practical patterns for touching the `cli/` module without breaking
-its public contract.
-
-## When to use this skill
-
-- Adding a new `amy <verb>` subcommand.
-- Editing anything under `cli/src/main/kotlin/…/cli/`.
-- Writing a shell script or test harness that drives Amy.
-- Extracting code out of `amethyst/` so the CLI can call it (this is
-  the single most common reason an Amy feature request stalls).
-- Deciding whether a piece of logic belongs in `cli/` vs `commons/`
-  vs `quartz/` (answer: almost never `cli/`).
-
-**Not for:** general Nostr protocol work (`nostr-expert`), general
-Kotlin (`kotlin-expert`), Compose UI (`compose-expert`), Android-only
-flows (`android-expert`), gradle/build (`gradle-expert`).
-
-## The rules that matter
-
-Amy has a small number of hard rules. Any change that breaks them is
-a breaking change to the CLI's public API, and breaks the interop-
-test harnesses that depend on it.
-
-### Rule 1 — `cli/` is a thin assembly layer
-
-No new Nostr protocol, filter assembly, state machines, or encryption
-lives in `cli/`. Ever. If you need logic that doesn't exist yet:
-
-- Protocol piece (event kind, tags, signing)? Add it to `quartz/`.
-- Business logic (state, defaults, ordering, filter assembly)?
-  Add it to `commons/` — extract from `amethyst/` first if needed
-  (see Rule 5).
-
-A `commands/*.kt` file longer than ~200 lines is a code smell.
-Either the command is doing too many things, or the logic has
-leaked in from where it should have lived.
-
-### Rule 2 — text by default, `--json` is the machine contract
-
-amy ships a dual-output contract:
-
-- **Default stdout is human-readable text.** A YAML-ish render of the
-  result map. No shape promise — the renderer can change between
-  releases.
-- **`--json` switches stdout to one JSON object, one line.** Stable
-  snake_case keys; this shape is the public API.
-- **stderr is for humans.** Progress logs, warnings, per-relay ACK
-  traces. Errors go here too — `error: <code>: <detail>` by default,
-  JSON `{"error":"…","detail":"…"}` under `--json`.
-- **Exit codes:** `0` success · `1` runtime · `2` bad args · `124`
-  await timeout.
-- Adding a `--json` key is safe; renaming or removing one is a
-  breaking change and needs the commit message to say so.
-
-Commands emit results via `Output.emit(mapOf(...))` and errors via
-`Output.error("code", "detail")`. The `Output` object (in
-`cli/src/main/kotlin/…/cli/Output.kt`) handles the text-vs-JSON
-branching automatically. Never `println(...)` user-facing output
-directly — `System.err.println(...)` is fine for progress logs only.
-
-See `references/output-conventions.md`.
-
-### Rule 3 — Non-interactive, ever
-
-No `readLine()`, no TTY prompts, no hidden interactive behaviour.
-Passwords, names, keys, anything — all flags. Any network wait is
-an explicit `await` verb with `--timeout`.
-
-### Rule 4 — `~/.amy/` is the whole world
-
-State is reloaded from `~/.amy/` on every invocation. No singletons,
-no in-process caches that survive across runs. This is what lets 100
-parallel interop scenarios share a harness safely.
-
-The layout:
-
-- `~/.amy/shared/events-store/` — one file-backed Nostr event store
-  per machine, shared across every account.
-- `~/.amy/<account>/` — per-account dir: `identity.json`,
-  `state.json`, `aliases.json`, `marmot/`.
-- `~/.amy/current` — marker file written by `amy use NAME` to pin
-  the active account.
-
-Account selection is via the global `--account NAME` flag (required
-when more than one account exists; auto-picked when exactly one
-does). `--account` cannot collide with subcommand flags, so commands
-like `marmot group create --name "Group"` or `profile edit --name "Alice"`
-keep their own `--name` parameter.
-
-Tests isolate by overriding `$HOME` for the amy subprocess
-(`HOME=$(mktemp -d) amy --account alice init`). amy reads `$HOME`
-directly (not `user.home`, which JDK 21 derives from `getpwuid` and
-ignores `$HOME`), so the same convention `git`/`gpg`/`npm`/`ssh`
-follow Just Works.
-
-If you need new persisted state, add it to `Config.kt`,
-`stores/FileStores.kt`, or a new helper (e.g. `Aliases.kt`) with a
-named JSON schema. Don't smuggle state into `~/.amy/` outside the
-documented files.
-
-### Rule 5 — Extract before adding
-
-If the command you're about to add needs logic from `amethyst/`,
-land the extraction first, in its own commit:
-
-1. Identify the class in `amethyst/src/main/java/…/`.
-2. List its Android-only dependencies (`Context`, `SharedPreferences`,
-   `WorkManager`, `Log`, `Bitmap`, `Uri`, …).
-3. For each, choose: inline, platform-abstract via expect/actual, or
-   take-as-constructor-arg.
-4. Move the file to `commons/commonMain/…`.
-5. Update the Android caller to use the new location. Add a JVM test.
-6. **Then** add the `cli/commands/…` file.
-
-Full checklist: `references/extraction-recipe.md`.
-
-## Standard command shape
-
-Every new command follows the same shape — parse args, open Context,
-prepare, call into commons/quartz, publish or drain, emit one result
-via `Output.emit`. The template is in `references/command-template.md`;
-copy it rather than re-deriving it.
-
-Wire-up checklist:
-1. New file in `cli/commands/` with the `object` pattern. Sub-verb
-   `dispatch` functions use the shared `route(...)` helper in
-   `Router.kt` rather than a hand-rolled `when (tail[0])`.
-2. Add a branch in `Main.kt`'s `dispatch` (top-level verbs call the
-   command object directly, e.g. `"relay" -> RelayCommands.dispatch(…)`;
-   `marmot` sub-verbs go through `marmotDispatch`'s `route` map).
-4. Extend `printUsage()` in `Main.kt`.
-5. Add the row to `cli/README.md`'s command table.
-6. Update `cli/ROADMAP.md` — move the row from 🆕 / 📦 to ✅.
-7. If the verb changes observable wire behaviour (a new event kind,
-   a new relay-routing rule, a new JSON discriminator), add a case
-   in the appropriate harness under `cli/tests/` — `cli/tests/marmot/`
-   for MLS flows, `cli/tests/dm/` for NIP-17, `cli/tests/cache/` for
-   event-store behaviour, or a new sibling suite if it's none.
-
-If you change `--json` output shape: note it in the commit message,
-bump the example in `cli/README.md`, update any interop fixtures
-under `cli/tests/`.
-
-## Where things live
-
-```
-cli/
-├── README.md              # user-facing tour: install, examples, command tables
-├── DEVELOPMENT.md         # public contract, architecture, design rules,
-│                          #   event-store, relay-routing, full on-disk layout
-├── ROADMAP.md             # parity matrix + ordered milestones
-├── plans/                 # dated design docs (use for new subsystems)
-├── tests/                 # end-to-end shell harnesses against a local relay
-│   ├── lib.sh             # shared logging + result tracking
-│   ├── headless/          # shared amy wrappers + assertions
-│   ├── marmot/            # MLS group-messaging interop (vs whitenoise-rs)
-│   ├── dm/                # NIP-17 DM interop (two amy clients)
-│   └── cache/             # FsEventStore behaviour vs the cache helpers
-└── src/main/kotlin/…/cli/
-    ├── Main.kt            # argv dispatch, global flags
-    ├── Args.kt            # flag parser
-    ├── Output.kt          # text/json mode emitter + colour
-    ├── Aliases.kt         # per-account aliases.json read/write
-    ├── Config.kt          # Identity, RunState, DataDir (~/.amy layout)
-    ├── Context.kt         # per-run wiring — the backbone
-    ├── SecureFileIO.kt    # 0600/0700 atomic writes, perm tighten
-    ├── stores/            # file-backed MLS / KP / message stores
-    ├── secrets/           # SecretStore backends (keychain / ncryptsec / plaintext)
-    └── commands/          # one file (or group) per top-level verb
-        ├── UseCommand.kt          # `amy use NAME`
-        ├── Router.kt              # `route(...)` shared sub-verb dispatcher
-        ├── InitCommands.kt        # init, whoami
-        ├── CreateCommand.kt + LoginCommand.kt
-        ├── RelayCommands.kt
-        ├── ProfileCommands.kt
-        ├── NotesCommands.kt + PostCommand.kt + FeedCommand.kt
-        ├── DmCommands.kt
-        ├── KeyPackageCommands.kt
-        ├── GroupCommands.kt + GroupCreateCommand.kt + GroupReadCommands.kt
-        │   GroupAddMemberCommand.kt + GroupMembershipCommands.kt
-        │   GroupMetadataCommands.kt
-        ├── MessageCommands.kt
-        ├── MarmotResetCommand.kt
-        ├── AwaitCommands.kt
-        ├── StoreCommands.kt
-        ├── AdminCommand.kt        # `amy admin RELAY METHOD` (NIP-86)
-        ├── ServeCommand.kt        # `amy serve` (embeds :geode)
-        └── cashu/                 # `amy cashu …` (NIP-60/61) — thin wrappers
-            ├── CashuCommands.kt   #   over commons CashuWalletOps / CashuWalletReader
-            ├── CashuWalletCommands.kt + CashuBalanceCommand.kt + CashuMintCommands.kt
-            └── CashuReceiveCommands.kt + CashuSendCommands.kt
-                + CashuMaintenanceCommands.kt + CashuMintRecCommands.kt
-```
-
-Shared logic consumed by Amy lives in `commons/`:
-- `commons/account/` — account bootstrap
-- `commons/marmot/` — MLS / group state
-- `commons/cashu/` — `ops/CashuWalletOps` (jvmAndroid) + `CashuWalletReader`
-  + `CashuKeysetCounterStore`; the NIP-60/61 wallet, shared with Android.
-- `commons/relayManagement/Nip86Retriever` — NIP-86 HTTP client, shared with
-  the Android relay-management screen.
-- `commons/defaults/` — default relays, kinds
-- Consult `commons/plans/` for cross-cutting design work in flight.
-
-A few amy verbs lean on modules beyond `quartz`/`commons`: `amy serve`
-depends on `:geode` (the standalone relay) — the one allowed extra module
-dependency. `:amethyst` / `:desktopApp` remain forbidden (Rule 5).
-
-## Common mistakes to refuse
-
-- **Adding protocol logic to `cli/`.** Push back, offer to extract.
-- **Silently changing a `--json` key.** Flag as breaking.
-- **Using `println` or `print` for command output.** Use
-  `Output.emit(...)` / `Output.error(...)`. Plain
-  `System.err.println` is fine for progress logs but never for
-  user-consumable output.
-- **`runBlocking` inside a command** — the top-level `main` already
-  does that. Commands are `suspend fun`.
-- **Depending on `:amethyst` or `:desktopApp`.** Never. If you need
-  something from there, Rule 5.
-- **Re-inventing identifier parsing.** Use `Context.requireUserHex`
-  or `resolveUserHexOrNull` in `quartz/nip05DnsIdentifiers/`.
-- **Re-inventing publish-and-confirm.** Use `Context.publish`.
-- **Re-inventing one-shot subscription.** Use `Context.drain`.
-- **Reading `user.home` directly.** Use `DataDir.DEFAULT_ROOT`, which
-  reads `$HOME` (the convention `git`/`gpg`/`npm` follow); JDK 21's
-  `user.home` is derived from `getpwuid` and ignores `$HOME`, which
-  silently breaks the test-isolation pattern.
-- **Adding a global flag that collides with subcommand flags.**
-  `--name` is reserved for subcommand use (group/profile names).
-  Account selection is `--account`.
-
-## Plans & design docs
-
-Cross-cutting design work goes in dated plan docs, in the module
-that owns the code being created — not in `docs/plans/`, which is
-frozen.
-
-- `cli/plans/` — Amy-specific subsystems.
-- `commons/plans/` — shared code Amy consumes (e.g.
-  `2026-04-21-event-renderer.md`).
-
-## Cross-references
-
-- [`cli/README.md`](../../../cli/README.md) — user-facing tour
-- [`cli/DEVELOPMENT.md`](../../../cli/DEVELOPMENT.md) — public
-  contract, architecture, on-disk layout
-- [`cli/ROADMAP.md`](../../../cli/ROADMAP.md) — parity matrix
-- `references/command-template.md`
-- `references/extraction-recipe.md`
-- `references/output-conventions.md`

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

@@ -1,102 +0,0 @@
-# Command-file template
-
-Copy this shape for every new Amy verb. Resist the urge to deviate —
-the uniform shape is what makes commands easy to audit and test.
-
-## Single-verb command
-
-```kotlin
-package com.vitorpamplona.amethyst.cli.commands
-
-import com.vitorpamplona.amethyst.cli.Args
-import com.vitorpamplona.amethyst.cli.Context
-import com.vitorpamplona.amethyst.cli.DataDir
-import com.vitorpamplona.amethyst.cli.Output
-
-object NotePublishCommand {
-    suspend fun run(dataDir: DataDir, rest: Array<String>): Int {
-        val args = Args(rest)
-        val text = args.positional(0, "text")
-
-        Context.open(dataDir).use { ctx ->
-            ctx.prepare()
-
-            val event = com.vitorpamplona.amethyst.commons.note
-                .buildTextNote(ctx.signer, text)
-            val ack = ctx.publish(event, ctx.outboxRelays())
-
-            Output.emit(mapOf(
-                "event_id"      to event.id,
-                "kind"          to event.kind,
-                "published_to"  to ack.filterValues { it }.keys.map { it.url },
-                "rejected_by"   to ack.filterValues { !it }.keys.map { it.url },
-            ))
-            return 0
-        }
-    }
-}
-```
-
-`Context` is `AutoCloseable`; wrap it in `use { }` so it's closed
-(RunState flushed, relays disconnected) on every exit path — never a
-hand-rolled `try { } finally { ctx.close() }`.
-
-`Output.emit(...)` handles the text-vs-JSON mode automatically. The
-result map IS the `--json` shape; the human-readable text default is
-derived from the same map by `Output.kt`'s renderer.
-
-## Multi-verb group
-
-When a feature has several verbs (`note publish`, `note show`,
-`note react`), group them:
-
-```kotlin
-object NoteCommands {
-    suspend fun dispatch(dataDir: DataDir, tail: Array<String>): Int =
-        route("note", tail, "note <publish|show|react>", mapOf(
-            "publish" to { rest -> NotePublishCommand.run(dataDir, rest) },
-            "show"    to { rest -> NoteShowCommand.run(dataDir, rest) },
-            "react"   to { rest -> NoteReactCommand.run(dataDir, rest) },
-        ))
-}
-```
-
-The shared `route(name, tail, usage, routes)` helper (`Router.kt`)
-handles the empty-input and unknown-verb `bad_args` branches, so the
-`dispatch` body is just the verb→handler map. Each verb gets its own
-file. Once a single file crosses ~200 lines, split it — see
-`GroupCommands.kt` and its siblings as the reference.
-
-## Wire-up checklist
-
-For every new command:
-
-1. File under `cli/commands/`.
-2. Branch in `Main.kt`'s top-level `dispatch`, calling the command
-   object directly:
-   ```kotlin
-   "note" -> NoteCommands.dispatch(dataDir, tail)
-   ```
-3. Line in `printUsage()` explaining the verb.
-4. Row in `cli/README.md`'s command table.
-5. Status flip in `cli/ROADMAP.md` (🆕 / 📦 → ✅).
-
-## What not to do
-
-- No `runBlocking` in a command body — `main()` already does it.
-- No `println` / `print` for command output — use
-  `Output.emit(...)` / `Output.error(...)`. `System.err.println(...)`
-  is fine for progress logs (they're already disposable).
-- No swallowing errors — let exceptions bubble; `main()` translates
-  them to `error: …` (text mode) / `{"error":…}` (JSON mode) plus the
-  right exit code.
-- No holding a connection open across invocations — every run opens
-  a fresh `Context` inside `use { }` so it closes on every exit path.
-- No blocking reads for user input — take a flag.
-- No global flags that collide with subcommand flags. `--name` is
-  reserved for subcommand use (group/profile name); the global
-  account selector is `--account`.
-
-## Output-shape rules
-
-See `output-conventions.md`.

.claude/skills/amy-expert/references/extraction-recipe.md

@@ -1,137 +0,0 @@
-# Extract-from-Android recipe
-
-The single most common reason an Amy feature request stalls: the
-logic it needs lives in `amethyst/` with Android-only imports. You
-cannot call it from `cli/`. You have to move it first.
-
-This recipe is how.
-
-## When to extract
-
-Before writing a new command, ask:
-
-1. Does the piece of logic I need exist in `quartz/` or `commons/`?
-   - **Yes** → use it.
-   - **No, but it's in `amethyst/`** → extract. This file.
-   - **No, it doesn't exist anywhere** → design it in `commons/`
-     directly. Write a plan doc under `commons/plans/` if it's a
-     new subsystem.
-
-2. Never duplicate `amethyst/` logic into `cli/`. That's a debt you
-   will pay later when the Android caller drifts.
-
-## Recipe
-
-Land this as its own commit, **before** the commit that adds the
-CLI command.
-
-### Step 1 — Find the class
-
-```bash
-grep -rn "fun followUser\|class FollowListManager" amethyst/src/main/java/
-```
-
-Identify the minimum unit to move. Sometimes it's a whole file,
-sometimes one function. Prefer the smallest unit that makes the
-command possible.
-
-### Step 2 — List Android-only dependencies
-
-Walk the imports. The usual offenders:
-
-| Dependency | Treatment |
-|---|---|
-| `android.content.Context` | Often accidental — inline if only used for logging or preferences. Otherwise, invert as constructor arg. |
-| `android.content.SharedPreferences` | Abstract behind an interface in `commons/`; Android actual uses SharedPreferences, JVM actual uses a JSON file. |
-| `androidx.work.WorkManager` | Rarely shareable — if the CLI needs it, simplify the flow to not require background scheduling. |
-| `android.util.Log` | Replace with `quartz` `PlatformLog` (already multiplatform). |
-| `android.graphics.Bitmap` | Almost never needed by Amy. Keep in Android and split the function. |
-| `android.net.Uri` | Replace with `kotlinx.io` path types or a plain `String`. |
-| `androidx.compose.*` | Must stay out of `commons/commonMain` unless you're in a Compose-Multiplatform module. Amy doesn't depend on Compose. |
-
-### Step 3 — Pick a migration strategy per dependency
-
-- **Inline-able.** One call, trivial. Delete it.
-- **Platform-abstractable.** Add `expect` in `commons/commonMain/` +
-  `actual` in `commons/androidMain/` + `actual` in `commons/jvmMain/`.
-  See `kotlin-multiplatform` skill for the mechanics and for the
-  `jvmAndroid` source-set pattern used throughout this repo.
-- **Inversion-of-control.** Take the Android dependency as a
-  constructor arg with an interface type. Amy supplies a JVM flavour;
-  Android supplies the Context-backed one.
-
-### Step 4 — Move the code
-
-```bash
-# Target location depends on what it is:
-# - Protocol → quartz/src/commonMain/kotlin/…
-# - Business logic → commons/src/commonMain/kotlin/…
-# - UI → commons/src/commonMain/… (needs Compose Multiplatform)
-git mv amethyst/src/main/java/com/.../FollowListManager.kt \
-       commons/src/commonMain/kotlin/com/.../FollowListManager.kt
-```
-
-Update package declarations. Run `./gradlew spotlessApply`.
-
-### Step 5 — Update the Android caller
-
-The amethyst/ caller now imports from the new location. Often this
-is the only code change visible in the Android app.
-
-If the Android caller was using a concrete Android-backed
-dependency, it now supplies that concrete dependency explicitly.
-
-### Step 6 — Add a JVM test
-
-In `commons/src/commonTest/kotlin/…` or `commons/src/jvmTest/kotlin/…`
-(depending on what the code exercises), add a test that runs on JVM.
-This guards against Android-only imports sneaking back in, and it's
-the only way to be sure Amy can now call the code.
-
-### Step 7 — Commit
-
-Single commit, descriptive:
-
-> refactor(follow): extract FollowListManager to commons for CLI reuse
->
-> Move FollowListManager from amethyst/model/nip02FollowLists/ to
-> commons/commonMain/.../followLists/. Android's SharedPreferences
-> dependency is inverted behind FollowListStore (interface); Android
-> keeps the SharedPreferences-backed actual, new JvmFollowListStore
-> writes JSON to disk. No behaviour change on Android.
-
-### Step 8 — Now add the CLI command
-
-Separate commit. Follows the pattern in `command-template.md`.
-
-## Cautionary notes
-
-- **Don't extract speculatively.** Only extract what the current
-  command needs. A feature-complete port can happen later; right now
-  the goal is to unblock one command without adding surface area you
-  don't have a second caller for.
-- **Android is allowed to keep side-effects.** Notifications,
-  background services, Intents, camera, permissions dialogs — those
-  stay in `amethyst/`. Amy's job isn't to replicate UX, it's to
-  exercise the protocol underneath.
-- **Check the consumers.** Sometimes the "logic" you want is already
-  partially in `commons/`, and the `amethyst/` class is just a thin
-  wrapper. In that case, re-use the `commons/` class directly and
-  delete the wrapper or keep it if Android genuinely needs it.
-- **Tests first if you're nervous.** Copy the existing
-  `amethyst/`-side test (if any), make it JVM-only by removing
-  Android imports, and watch it pass after the move.
-
-## Red flags during extraction
-
-Stop and reconsider if:
-
-- The Android class is 1000+ lines. Extract only the piece the CLI
-  needs; leave the rest for a follow-up.
-- You need `Context` in 30 places. It's probably being used as a
-  grab-bag; sort by actual use (strings, preferences, services, …)
-  and abstract those individually.
-- You find yourself writing `expect class` with a dozen methods. A
-  fine-grained interface is usually clearer than a monolithic
-  expect-actual.
-- You're about to add a Compose import to `cli/`. Stop.

.claude/skills/amy-expert/references/output-conventions.md

@@ -1,142 +0,0 @@
-# Output conventions
-
-amy ships a dual-output contract. Default stdout is human-readable
-text (a YAML-ish render of the underlying result map); `--json` flips
-stdout to a single JSON object per success. The text shape can drift;
-the `--json` shape is the public API.
-
-Commands always emit via `Output.emit(mapOf(...))`. The map IS the
-JSON shape — the renderer in `Output.kt` derives the text from the
-same map. Don't write two render paths; write one map and let
-`Output` pick.
-
-## Channels
-
-| Stream | Default mode | `--json` mode |
-|---|---|---|
-| **stdout** | YAML-ish text from `Output.emit(...)` | Exactly one JSON object per successful invocation |
-| **stderr** | Human progress logs, warnings, per-relay ACK traces, stack traces, `printUsage()` output, errors as `error: <code>: <detail>` | Same logs, plus errors as `{"error":...,"detail":...}` |
-
-If a command needs to emit structured data for machines, it goes on
-stdout and is automatically JSON under `--json`. If it needs to
-explain what it's doing to a human watching, stderr.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | Success. |
-| `1` | Runtime error. |
-| `2` | Bad arguments. |
-| `124` | `await` timed out. |
-
-Throw the right exception type in commands:
-
-- `IllegalArgumentException` → exit 2 automatically.
-- `AwaitTimeout` → exit 124 automatically.
-- Anything else → exit 1.
-
-The top-level `main()` in `Main.kt` handles the translation. Don't
-try-catch at the command level unless you're converting a third-party
-exception into one of the above.
-
-## `--json` object shape
-
-### Top-level
-
-Always an object. Never an array, never a primitive, never a
-newline-delimited stream.
-
-```json
-{ "event_id": "...", "kind": 1, "published_to": [...] }
-```
-
-### Keys
-
-- Stable snake_case.
-- Additive evolution is safe; renaming or removing a key is a
-  breaking change.
-- Don't nest unnecessarily. `{"data":{...}}` is noise.
-
-### Identifiers
-
-| Thing | Form |
-|---|---|
-| Event ID | 64-char lowercase hex string. Key name: `event_id`. |
-| Pubkey (primary subject) | hex **and** bech32. Keys: `pubkey` + `npub`. |
-| Pubkey (secondary reference) | hex only. Key: `pubkey`. |
-| Relay URL | Normalized string (`wss://…`). Never an object. |
-| Timestamps | Unix seconds, integer. Key names end in `_at`. The text renderer auto-formats these as `2026-04-25 13:42:11Z (8m ago)`. |
-| Group ID (Marmot) | Hex string. Key: `group_id`. |
-| Byte counts | Integer. Key names end in `_bytes`. The text renderer auto-formats these as `8.7 KiB`. |
-
-### Collections
-
-- Pluralise: `messages`, `members`, `admins`, `events`.
-- Always an array (possibly empty), never `null`.
-- Order: oldest-first unless there's a good reason otherwise — state
-  it in the key name (`messages_newest_first`) if you flip it.
-
-### Booleans
-
-- Use `true`/`false` in the result map. The text renderer prints them
-  as `yes`/`no` (green/red); `--json` keeps the literal booleans.
-- Name keys so `true` is the expected/successful state:
-  `is_member`, `published`, `accepted`.
-
-### Publish results
-
-When a command publishes an event, the canonical output shape is:
-
-```json
-{
-  "event_id": "<hex>",
-  "kind": 1,
-  "published_to": ["wss://relay.a/", "wss://relay.b/"],
-  "rejected_by": ["wss://relay.c/"]
-}
-```
-
-`published_to` is relays that ACK'd `true`. `rejected_by` is relays
-that ACK'd `false`. Relays that didn't answer before the timeout
-appear in neither — add `timed_out_on` if you need to surface them.
-
-### Error shape
-
-Default mode (text):
-
-```text
-error: not_member: <gid>
-```
-
-Under `--json`:
-
-```json
-{ "error": "not_member", "detail": "<gid>" }
-```
-
-- `error` is a short, stable, lower_snake code. Agents can branch on
-  it.
-- `detail` is free text — OK to change between versions.
-- Common codes today: `bad_args`, `no_identity`, `no_account`,
-  `exists`, `bad_key`, `not_member`, `no_dm_relays`, `timeout`,
-  `runtime`. Reuse before inventing.
-
-Use `Output.error("code", "detail")` from commands; it picks the
-right channel and format based on the active mode.
-
-## Never
-
-- `println(...)` of anything except `Output.emit(...)`.
-- `Json.writeLine` / `Json.error` — that helper is gone; use the
-  `Output` object instead.
-- Multi-line JSON (pretty-printed) under `--json`. One line, always.
-- Mixing stdout lines — one command invocation emits one stdout line
-  in `--json` mode. If you need progress updates, they go on stderr.
-- Machine output to stderr. The whole point is clean separation.
-- Silent fallbacks — if a relay rejects your publish, say so in the
-  result map.
-- Building text rendering by hand. Trust the `Output.kt` renderer:
-  it handles alignment, colour, byte/timestamp formatting, nested
-  maps and lists. If you need a bespoke render for one command,
-  pass a custom render lambda — don't go around `Output`.

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

@@ -1,8 +1,3 @@
----
-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.
@@ -738,29 +733,125 @@ fun SignerIntegration(accountViewModel: AccountViewModel) {
 
 ## 6. Build Configuration
 
-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:
+### Android Block
 
+**build.gradle (Amethyst pattern):**
 ```gradle
-flavorDimensions = ["channel"]
-productFlavors {
-    create("play")   { dimension = "channel" } // Firebase, Google services
-    create("fdroid") { dimension = "channel" } // UnifiedPush, open-source only
+android {
+    namespace = 'com.vitorpamplona.amethyst'
+    compileSdk = 36
+
+    defaultConfig {
+        applicationId = "com.vitorpamplona.amethyst"
+        minSdk = 26          // Android 8.0 (Oreo)
+        targetSdk = 36       // Android 15
+        versionCode = 435
+        versionName = "1.06.3"
+
+        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
+    }
 }
 ```
 
-`play` carries Firebase/Google services; `fdroid` swaps them for UnifiedPush and
-open-source alternatives so the F-Droid build stays proprietary-free.
+### Dependencies
 
-Proguard/R8 rules: see `references/proguard-rules.md`. APK size analysis:
-`scripts/analyze-apk-size.sh`.
+**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.
 
 ## 7. KMP Android Source Sets
 
@@ -964,7 +1055,6 @@ fun testPermissionRequest() {
 - `references/android-navigation.md` - Complete navigation patterns and examples
 - `references/android-permissions.md` - Permission handling patterns
 - `references/proguard-rules.md` - Proguard configuration
-- `references/image-loading.md` - Coil 3.x setup, custom fetchers (Blossom/Base64/BlurHash/ThumbHash), `MyAsyncImage`, `RobohashAsyncImage`
 - `scripts/analyze-apk-size.sh` - APK size optimization script
 
 ## When NOT to Use

.claude/skills/android-expert/references/image-loading.md

@@ -1,60 +0,0 @@
-# Image Loading
-
-Amethyst uses **Coil 3.x (KMP)** for async image loading on both Android and Desktop. Coil is configured once at app startup with custom fetchers, decoders, and an OkHttp/Ktor network layer wired to Tor/proxy settings.
-
-## Android Setup
-
-Under `amethyst/src/main/java/com/vitorpamplona/amethyst/service/images/`:
-
-- **`ImageLoaderSetup.kt`** — `class ImageLoaderSetup` is the entry point. Called from `Amethyst.onCreate()`. Installs a global Coil `ImageLoader` with custom fetchers/decoders and a shared `OkHttpClient` (via `OkHttpFactory`).
-- **`ImageCacheFactory.kt`** — builds the disk + memory cache backing the loader. Size-bounded; cleared on memory pressure.
-- **`ThumbnailDiskCache.kt`** — separate on-disk cache for generated thumbnails.
-- **`Base64Fetcher.kt`** — resolves `data:image/...;base64,...` URLs into bitmaps inline.
-- **`BlossomFetcher.kt`** — fetches blossom-hosted media using authenticated requests (NIP-96 / blossom auth event).
-- **`BlurHashFetcher.kt`** / **`ThumbHashFetcher.kt`** — synthesize placeholders from `blurhash` / `thumbhash` in NIP-92 `imeta` tags while the real image loads.
-- **`ProfilePictureFetcher.kt`** — special-case fetcher that falls back to a robohash when a profile has no `picture`.
-- **`MyDebugLogger`** (inside `ImageLoaderSetup.kt`) — surfaces loader errors to logcat in debug builds.
-
-## Desktop Setup
-
-Mirror under `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/service/images/`:
-
-- **`DesktopImageLoaderSetup.kt`** — same shape as Android, but uses Skia decoders and a JVM-native OkHttp client.
-- **`DesktopBase64Fetcher.kt`**, **`DesktopBlurHashFetcher.kt`**, **`DesktopThumbHashFetcher.kt`**, **`SkiaGifDecoder.kt`** — Skia / JVM equivalents of the Android fetchers.
-- Called from `desktopApp/.../desktop/Main.kt` (`fun main()` at L172) via `DesktopImageLoaderSetup.setup()` before `application { }`.
-
-## Composable Entry Points (Android)
-
-- **`amethyst/.../ui/components/MyAsyncImage.kt`** — `@Composable fun MyAsyncImage(...)`. Wraps Coil's `AsyncImage` with the project's error fallbacks, blurhash placeholders, and content-description defaults.
-- **`amethyst/.../ui/components/RobohashAsyncImage.kt`** — auto-generates a deterministic robohash avatar from a pubkey when no profile picture is set.
-- **`amethyst/.../ui/components/ImageGallery.kt`** — paged/zoomable gallery for notes with multiple images.
-
-Desktop has parallel composables under `desktopApp/.../ui/` — they consume the shared Coil `ImageLoader` configured by `DesktopImageLoaderSetup`.
-
-## Typical Reuse
-
-```kotlin
-MyAsyncImage(
-    model = url,
-    contentDescription = description,
-    modifier = Modifier.size(48.dp).clip(CircleShape),
-    placeholderBlurHash = imeta?.blurhash,    // NIP-92 placeholder
-    loading = { /* shimmer */ },
-    error = { /* broken image */ },
-)
-```
-
-For profile pictures, prefer `RobohashAsyncImage` so users without a `picture` field still get a stable avatar.
-
-## Gotchas
-
-- **Never call `ImageLoader.Builder` in a composable** — build once in `ImageLoaderSetup` and rely on `SingletonImageLoader`. Otherwise you shred the cache and blow up memory.
-- **Blossom/encrypted media must go through `BlossomFetcher`** — using the default HTTP fetcher returns ciphertext that decoders reject.
-- **Debug logcat noise**: `MyDebugLogger` is on in debug builds only; do not enable in release.
-- **`OkHttpFactory` feeds the loader** — if you replace the HTTP client (e.g. to route through Tor), update the factory, not the loader setup, or Tor routing silently bypasses images.
-- **NIP-92 `imeta` metadata flows in from the event, not the URL.** See `compose-expert/references/rich-text-parsing.md` for how `MediaUrlImage`/`MediaUrlVideo` carry the blurhash and dimensions into the composable.
-
-## Related
-
-- `compose-expert/references/rich-text-parsing.md` — how `MediaContentModels` feed composables.
-- `gradle-expert/references/version-catalog-guide.md` — Coil version alignment (`coil = 3.4.0` in `libs.versions.toml`).

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

@@ -1,104 +0,0 @@
----
-name: auth-signers
-description: Signer abstraction patterns in Amethyst. Use when working with event signing, choosing between a local keypair (`NostrSignerInternal`), a remote NIP-46 bunker signer (`NostrSignerRemote`), or a NIP-55 Android external-app signer (`NostrSignerExternal`). Covers the abstract `NostrSigner` base class, `SignerResult` contract, how to wire a new flow that needs to sign events, and the security/UX trade-offs between signer kinds.
----
-
-# Auth & Signers
-
-Any time Amethyst produces a signed Nostr event, it goes through a `NostrSigner`. There are three kinds; all three implement the same abstract contract so feature code doesn't care which one the user has configured.
-
-## When to Use This Skill
-
-- Adding a new flow that publishes an event (follow, post, react, zap, profile edit).
-- Reviewing whether a feature works when the user has a remote bunker signer or an external Android signer.
-- Debugging "Sign request approved but nothing happens" / timeouts on sign operations.
-- Onboarding a new signer kind (hardware signer, browser extension, etc.).
-- Understanding the NIP-46 bunker request/response taxonomy.
-
-## The Abstract Contract
-
-`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/signers/NostrSigner.kt`:
-
-```kotlin
-abstract class NostrSigner(val pubKey: HexKey) {
-    abstract fun <T : Event> sign(
-        template: EventTemplate<T>,
-        onReady: (T) -> Unit,
-    )
-    abstract fun nip04Encrypt(plaintext: String, toPubKey: HexKey, onReady: (String) -> Unit)
-    abstract fun nip04Decrypt(ciphertext: String, fromPubKey: HexKey, onReady: (String) -> Unit)
-    abstract fun nip44Encrypt(...)
-    abstract fun nip44Decrypt(...)
-    abstract fun decryptZapEvent(event: LnZapRequestEvent, onReady: (LnZapRequestEvent) -> Unit)
-}
-```
-
-Sibling files in the same folder:
-
-- **`NostrSignerInternal.kt`** — in-process signer with the user's seckey in memory. Fastest; used for locally-stored accounts.
-- **`NostrSignerSync.kt`** — blocking wrapper for scripts / migrations / tests where callbacks are inconvenient.
-- **`EventTemplate.kt`** — the unsigned holder passed to `sign()`.
-- **`SignerExceptions.kt`** — the error taxonomy (user denied, timeout, unsupported method, etc.).
-- **`caches/`** — request cache so duplicate sign/encrypt requests coalesce.
-
-### Concrete implementations
-
-- **Local (in-process)**: `NostrSignerInternal` — direct `Secp256k1Instance.signSchnorr` + NIP-44 inline. Used by accounts created/imported into Amethyst.
-- **Remote (NIP-46 bunker)**: `quartz/.../nip46RemoteSigner/signer/NostrSignerRemote.kt`. Talks to a bunker service over Nostr DMs using the `BunkerRequest*` / `BunkerResponse*` event taxonomy (`BunkerRequestConnect`, `BunkerRequestSign`, `BunkerRequestNip44Encrypt`, …).
-- **Android external (NIP-55)**: `quartz/src/androidMain/.../nip55AndroidSigner/client/NostrSignerExternal.kt`. Uses Android intents + content provider to delegate to another app on the same device. Launcher: `ExternalSignerLogin.kt`, `IActivityLauncher.kt`. Install-check: `IsExternalSignerInstalled.kt`.
-
-## The `SignerResult` Contract
-
-Signers return via callback (and internally track via `SignerResult` sealed types in `nip46RemoteSigner/signer/SignerResult.kt` and `nip55AndroidSigner/api/SignerResult.kt`). Result variants cover success, user-denied, timeout, remote-disconnected, unsupported. Feature code should:
-
-1. Pass a callback that handles success.
-2. Trust the cache/timeout behavior — don't roll your own retry.
-3. Surface `SignerExceptions` to the user with actionable messaging (e.g. "Bunker disconnected — reconnect?").
-
-## Typical Flow (Feature Code)
-
-```kotlin
-// High-level: Account methods already do this internally.
-val signer: NostrSigner = account.signer     // whichever kind the user configured
-
-val template = reactionEventTemplate(noteId, authorPubKey, "+")
-
-signer.sign(template) { signed ->
-    account.sendToRelays(signed)             // or similar pipeline
-}
-```
-
-Most feature code should go through `Account`'s mutation methods (`account.sendReaction`, `account.follow`) rather than touching the signer directly — the account layer handles signing + publishing + local state update atomically. Reach for the signer directly only when `Account` doesn't have a helper.
-
-## Choosing a Signer at Sign-Up
-
-Entry points:
-
-- **Existing private key** (`nsec`, 32-byte hex, file) → `NostrSignerInternal`.
-- **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.
-
-## Trade-offs
-
-| Signer | Latency | Offline OK? | Security | UX |
-|--------|---------|-------------|----------|-----|
-| Internal | µs | Yes | Key in app memory | No confirmation prompts |
-| Remote (NIP-46) | 100ms–seconds | No (needs bunker reachable) | Key never touches Amethyst | Occasional approval prompts |
-| External (NIP-55) | 100–500ms | Yes | Key in separate app | Prompt on every sign by default (configurable) |
-
-## Gotchas
-
-- **Callbacks may never fire.** External signers can be dismissed without result; remote signers can time out. Use `SignerExceptions` / timeout handling at every call site or rely on the `Account` layer's wrapping.
-- **`nip04Encrypt` is legacy** for NIP-04 DMs. New DM code should use NIP-17 gift-wrap → `nip44Encrypt` path.
-- **Don't cache signer output** beyond the `caches/` that quartz already maintains. Stale cache entries lead to duplicate publishes.
-- **Remote signer disconnects** need explicit reconnection UX — `RemoteSignerManager` exposes state; hook into it for an account-switching warning.
-- **External signer launch requires an Activity context** — it can't happen from a background service. Structure flows so signing is on the main dispatcher through an activity-scoped launcher.
-- **`NostrSignerSync`** is rare. If you reach for it, you're probably in a test or migration — production code uses the async API.
-
-## References
-
-- `references/nip46-remote-signer.md` — the NIP-46 bunker message taxonomy and connection lifecycle.
-- `references/nip55-android-signer.md` — Android intent-based external signer flow.
-- Complements: `nostr-expert/references/crypto-and-encryption.md` (the crypto under all signers), `account-state` (which wraps signer calls), `android-expert` (intent launcher patterns).

.claude/skills/auth-signers/references/nip46-remote-signer.md

@@ -1,109 +0,0 @@
-# NIP-46 Remote Signer (Bunker)
-
-Remote signers are a different Nostr client (the "bunker") that holds the private key and signs on request over Nostr DMs. Amethyst connects to a bunker via a `bunker://` URL and proxies every signing / encryption operation as a request/response over kind 24133 events.
-
-## Layout
-
-`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip46RemoteSigner/`:
-
-```
-nip46RemoteSigner/
-├── BunkerMessage.kt            ── common wrapper
-├── BunkerRequest.kt            ── sealed base for requests
-├── BunkerRequestConnect.kt
-├── BunkerRequestGetPublicKey.kt
-├── BunkerRequestGetRelays.kt
-├── BunkerRequestNip04Decrypt.kt
-├── BunkerRequestNip04Encrypt.kt
-├── BunkerRequestNip44Decrypt.kt
-├── BunkerRequestNip44Encrypt.kt
-├── BunkerRequestPing.kt
-├── BunkerRequestSign.kt
-├── BunkerResponse.kt           ── sealed base for responses
-├── BunkerResponseAck.kt
-├── BunkerResponseDecrypt.kt
-├── BunkerResponseEncrypt.kt
-├── BunkerResponseError.kt
-├── BunkerResponseEvent.kt
-├── BunkerResponseGetRelays.kt
-├── BunkerResponsePong.kt
-├── BunkerResponsePublicKey.kt
-├── NostrConnectEvent.kt        ── kind 24133 payload
-├── kotlinSerialization/        ── JSON codecs for each request/response
-└── signer/
-    ├── NostrSignerRemote.kt       ── the NostrSigner impl
-    ├── RemoteSignerManager.kt     ── connection lifecycle
-    ├── ConnectResponse.kt
-    ├── Nip04DecryptResponse.kt
-    ├── Nip04EncryptResponse.kt
-    ├── Nip44DecryptResponse.kt
-    ├── Nip44EncryptResponse.kt
-    ├── PingResponse.kt
-    ├── PubKeyResponse.kt
-    ├── SignerResult.kt
-    └── SignResponse.kt
-```
-
-## Connection Flow
-
-```
-User pastes bunker://<bunker-pubkey>?relay=wss://…&secret=…
-              │
-              ▼
-RemoteSignerManager.connect(url) generates a client keypair
-              │
-              ▼
-Publish BunkerRequestConnect (kind 24133, encrypted) to relay
-              │
-              ▼
-Wait for BunkerResponseAck or BunkerResponseError
-              │
-              ▼ on ack
-Return a NostrSignerRemote(clientKeys, bunkerPubKey, relays)
-```
-
-The client keypair is **not** the user's Nostr identity — it's a session key used to correspond with the bunker. The bunker controls the real signing key. `RemoteSignerManager` persists session state so reconnecting skips the handshake.
-
-## Request / Response Pattern
-
-Every signing or encryption call is an async round-trip:
-
-```
-Amethyst                              Bunker
-   │                                   │
-   │── BunkerRequestSign(template) ──►│
-   │                                   │  user approves (sometimes)
-   │◄── BunkerResponseEvent(signed) ──│
-   │                                   │
-```
-
-`NostrSignerRemote.sign(template, onReady)` serializes the `BunkerRequestSign`, encrypts it to the bunker's pubkey, publishes it, and waits (with a timeout) for a `BunkerResponseEvent` carrying the signed event. The response goes through a request-id correlation map so concurrent signs don't interleave.
-
-## Supported Requests
-
-- `BunkerRequestConnect` / `BunkerRequestPing` — lifecycle.
-- `BunkerRequestGetPublicKey` — verify what pubkey this session controls.
-- `BunkerRequestGetRelays` — discover the bunker's preferred inbox relays.
-- `BunkerRequestSign` — the main path.
-- `BunkerRequestNip04Encrypt`/`Decrypt` — legacy DMs.
-- `BunkerRequestNip44Encrypt`/`Decrypt` — NIP-44 payloads (gift-wrap, modern DMs).
-
-Each has a matching response with the same correlation id.
-
-## Timeouts & Disconnects
-
-- **Timeout**: default in `NostrSignerRemote`. Expired requests surface as `SignerExceptions.TimedOut` (or equivalent). Treat as "maybe the user will approve later but UI has given up" — don't auto-retry.
-- **Relay disconnect**: `RemoteSignerManager` reconnects transparently when the bunker's relay reappears; in-flight requests may still time out.
-- **Bunker revoke**: if the bunker closes the session, next sign attempt returns `BunkerResponseError`; prompt the user to reconnect.
-
-## Gotchas
-
-- **The session key is not the user key.** Logs and UI should never surface the session pubkey as "your pubkey".
-- **Don't assume a sign is fast** — UX should show a spinner and allow cancellation for 10+ seconds.
-- **Relay hints from `BunkerRequestGetRelays`** can change the relay list mid-session; the session manager handles it, but re-reads of `relays` in feature code may be stale.
-- **NIP-46 over Nostr is the only transport here** — there's no HTTP/WS shortcut. Any feature gating on "can this sign" must check relay reachability.
-
-## Related
-
-- `nip55-android-signer.md` — the other remote-ish signer (but local to the device).
-- `nostr-expert/references/crypto-and-encryption.md` — NIP-44 details (used by request/response encryption).

.claude/skills/auth-signers/references/nip55-android-signer.md

@@ -1,87 +0,0 @@
-# NIP-55 Android External Signer
-
-NIP-55 lets the user delegate signing to another Android app (Amber, nos2x-fox, etc.) that holds the private key. Communication is via `Intent`s and a `ContentProvider`, not Nostr itself.
-
-## Layout
-
-Android-only, under `quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip55AndroidSigner/`:
-
-```
-nip55AndroidSigner/
-├── JsonMapperNip55.kt     ── JSON layer for intent extras
-├── SignString.kt           ── canonical string to sign for login challenges
-├── api/
-│   ├── CommandType.kt      ── sign_event / nip04_encrypt / nip44_encrypt / …
-│   ├── SignerResult.kt     ── sealed result sent back by launcher callback
-│   ├── background/         ── "background" signer path via ContentProvider (no UI)
-│   ├── foreground/         ── "foreground" signer path via Activity + Intent
-│   └── permission/         ── permission grant / revoke helpers
-└── client/
-    ├── ExternalSignerLogin.kt       ── one-shot login / bootstrap intent
-    ├── IActivityLauncher.kt         ── abstraction over Activity + ActivityResultLauncher
-    ├── IsExternalSignerInstalled.kt ── query PM for compatible signers
-    ├── NostrSignerExternal.kt       ── the NostrSigner impl
-    └── handlers/                    ── per-command result handlers
-```
-
-Amethyst's Android app uses `ExternalSignerButton` (`amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedOff/login/ExternalSignerButton.kt`) as the sign-up entry point.
-
-## Two Transport Modes
-
-### Foreground (Activity + Intent)
-
-- Launches an `Intent` with `ACTION_VIEW` and data URI `nostrsigner:<payload>`.
-- The signer app opens, shows a UI prompt, returns via `onActivityResult`.
-- **Always works**, but requires user interaction each call unless the user has "always allow" granted.
-- Lives in `api/foreground/` and `client/handlers/`.
-
-### Background (ContentProvider)
-
-- Queries the signer's `ContentProvider` with `content://<signer-auth>/sign_event?...`.
-- No UI interaction — signer either silently approves (if pre-authorized) or denies.
-- Requires the user to have granted "always allow" permission beforehand via the foreground flow.
-- Lives in `api/background/` and `api/permission/`.
-- Falls back to foreground when background denies.
-
-`NostrSignerExternal` picks the path automatically: try background if pre-authorized, else foreground. See `client/handlers/` for the per-command dispatch.
-
-## Command Types
-
-`api/CommandType.kt` enumerates what the external signer supports:
-
-- `sign_event` — sign a Nostr event.
-- `nip04_encrypt` / `nip04_decrypt` — legacy DMs.
-- `nip44_encrypt` / `nip44_decrypt` — NIP-44 payloads (gift-wrap).
-- `get_public_key` — identity check.
-- `decrypt_zap_event` — LN zap request decoding.
-- `connect` — bootstrap / permissions.
-
-Commands map 1:1 to `NostrSigner` abstract methods.
-
-## Installation Check
-
-Before showing the "Use external signer" button, `IsExternalSignerInstalled.kt` queries the Android PackageManager for intent filters matching `nostrsigner:` URIs. If no compatible app is installed, hide the button (the UI already does this).
-
-## Permission Flow
-
-1. User taps "Use external signer" → `ExternalSignerLogin.launch(activityLauncher)`.
-2. Amethyst fires an intent asking the signer for the user's pubkey.
-3. Signer app opens, user approves, returns via `onActivityResult`.
-4. `NostrSignerExternal` is created with that pubkey and the package name of the approved signer.
-5. On subsequent sign requests, Amethyst tries background (via `ContentProvider`); if not granted, falls back to foreground intent.
-
-`api/permission/` has helpers to pre-grant / revoke permissions through the signer's dedicated permission URI.
-
-## Gotchas
-
-- **Activity context required.** All launch paths need an `Activity`, not just a `Context`. Design flows so the launcher is available when sign is called — if a background service needs to sign, it must defer until the app is foregrounded, or show a notification.
-- **Foreground loop.** Without "always allow", every single event sign = one Activity round-trip. That's bad UX for reactions / zaps. Push users toward granting always-allow.
-- **Multiple signer apps installed.** `IActivityLauncher` honors the one the user first approved, persisted in `AccountSyncedSettings`. Changing signers requires explicit re-login.
-- **KMP boundary.** `NostrSignerExternal` is strictly Android; Desktop uses `NostrSignerInternal` or `NostrSignerRemote` (NIP-46 bunker). Don't pretend there's a portable external-signer layer.
-- **Test coverage.** Signer Android flows have instrumented tests in `quartz/src/androidDeviceTest/kotlin/.../nip55AndroidSigner/` — device or emulator only.
-
-## Related
-
-- `nip46-remote-signer.md` — the other delegated-signing path (works on all platforms).
-- `android-expert/references/android-permissions.md` — Android permission mechanics.
-- `android-expert/SKILL.md` — intent / activity-result launcher patterns.

.claude/skills/compose-desktop.md

@@ -0,0 +1,339 @@
+# Compose Desktop Skill
+
+## Desktop Application Entry Point
+
+```kotlin
+// desktopApp/src/jvmMain/kotlin/Main.kt
+package com.vitorpamplona.amethyst.desktop
+
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.res.painterResource
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.*
+
+fun main() = application {
+    val windowState = rememberWindowState(
+        width = 1200.dp,
+        height = 800.dp,
+        position = WindowPosition.Aligned(Alignment.Center)
+    )
+
+    // System tray
+    Tray(
+        icon = painterResource("icon.png"),
+        tooltip = "Amethyst",
+        menu = {
+            Item("Show", onClick = { windowState.isMinimized = false })
+            Separator()
+            Item("Exit", onClick = ::exitApplication)
+        }
+    )
+
+    Window(
+        onCloseRequest = ::exitApplication,
+        state = windowState,
+        title = "Amethyst",
+        icon = painterResource("icon.png")
+    ) {
+        MenuBar {
+            Menu("File") {
+                Item("New Note", shortcut = KeyShortcut(Key.N, ctrl = true)) { }
+                Separator()
+                Item("Settings", shortcut = KeyShortcut(Key.Comma, ctrl = true)) { }
+                Separator()
+                Item("Quit", shortcut = KeyShortcut(Key.Q, ctrl = true), onClick = ::exitApplication)
+            }
+            Menu("Edit") {
+                Item("Copy", shortcut = KeyShortcut(Key.C, ctrl = true)) { }
+                Item("Paste", shortcut = KeyShortcut(Key.V, ctrl = true)) { }
+            }
+            Menu("View") {
+                Item("Feed") { }
+                Item("Messages") { }
+                Item("Notifications") { }
+            }
+            Menu("Help") {
+                Item("About Amethyst") { }
+            }
+        }
+
+        App()
+    }
+}
+```
+
+## Desktop-Specific Components
+
+### File Dialog
+```kotlin
+@Composable
+fun rememberFileDialog(): FileDialogState {
+    return remember { FileDialogState() }
+}
+
+class FileDialogState {
+    var isOpen by mutableStateOf(false)
+    var result by mutableStateOf<File?>(null)
+
+    fun open() { isOpen = true }
+
+    @Composable
+    fun Dialog(
+        title: String = "Select File",
+        allowedExtensions: List<String> = emptyList()
+    ) {
+        if (isOpen) {
+            DisposableEffect(Unit) {
+                val dialog = java.awt.FileDialog(null as java.awt.Frame?, title)
+                if (allowedExtensions.isNotEmpty()) {
+                    dialog.setFilenameFilter { _, name ->
+                        allowedExtensions.any { name.endsWith(it) }
+                    }
+                }
+                dialog.isVisible = true
+                result = dialog.file?.let { File(dialog.directory, it) }
+                isOpen = false
+                onDispose { }
+            }
+        }
+    }
+}
+```
+
+### Scroll Behavior
+```kotlin
+@Composable
+fun DesktopScrollableColumn(
+    modifier: Modifier = Modifier,
+    content: @Composable ColumnScope.() -> Unit
+) {
+    val scrollState = rememberScrollState()
+
+    Box(modifier) {
+        Column(
+            modifier = Modifier
+                .verticalScroll(scrollState)
+                .fillMaxSize()
+        ) {
+            content()
+        }
+
+        VerticalScrollbar(
+            modifier = Modifier.align(Alignment.CenterEnd),
+            adapter = rememberScrollbarAdapter(scrollState)
+        )
+    }
+}
+```
+
+### Keyboard Navigation
+```kotlin
+@Composable
+fun KeyboardNavigableList(
+    items: List<Note>,
+    selectedIndex: Int,
+    onSelect: (Int) -> Unit,
+    onActivate: (Note) -> Unit
+) {
+    val focusRequester = remember { FocusRequester() }
+
+    LaunchedEffect(Unit) {
+        focusRequester.requestFocus()
+    }
+
+    LazyColumn(
+        modifier = Modifier
+            .focusRequester(focusRequester)
+            .focusable()
+            .onKeyEvent { event ->
+                when {
+                    event.key == Key.DirectionDown && event.type == KeyEventType.KeyDown -> {
+                        onSelect((selectedIndex + 1).coerceAtMost(items.lastIndex))
+                        true
+                    }
+                    event.key == Key.DirectionUp && event.type == KeyEventType.KeyDown -> {
+                        onSelect((selectedIndex - 1).coerceAtLeast(0))
+                        true
+                    }
+                    event.key == Key.Enter && event.type == KeyEventType.KeyDown -> {
+                        items.getOrNull(selectedIndex)?.let { onActivate(it) }
+                        true
+                    }
+                    else -> false
+                }
+            }
+    ) {
+        itemsIndexed(items) { index, note ->
+            NoteCard(
+                note = note,
+                isSelected = index == selectedIndex,
+                modifier = Modifier.clickable { onSelect(index) }
+            )
+        }
+    }
+}
+```
+
+### Multi-Window Support
+```kotlin
+@Composable
+fun ApplicationScope.NoteDetailWindow(
+    note: Note,
+    onClose: () -> Unit
+) {
+    Window(
+        onCloseRequest = onClose,
+        title = "Note by ${note.author.name}",
+        state = rememberWindowState(width = 600.dp, height = 400.dp)
+    ) {
+        NoteDetailScreen(note)
+    }
+}
+
+// Usage in main application
+var openNotes by remember { mutableStateOf<List<Note>>(emptyList()) }
+
+openNotes.forEach { note ->
+    key(note.id) {
+        NoteDetailWindow(
+            note = note,
+            onClose = { openNotes = openNotes - note }
+        )
+    }
+}
+```
+
+### Tooltips
+```kotlin
+@Composable
+fun TooltipButton(
+    tooltip: String,
+    onClick: () -> Unit,
+    content: @Composable () -> Unit
+) {
+    TooltipArea(
+        tooltip = {
+            Surface(
+                shape = RoundedCornerShape(4.dp),
+                color = MaterialTheme.colorScheme.inverseSurface
+            ) {
+                Text(
+                    text = tooltip,
+                    modifier = Modifier.padding(8.dp),
+                    color = MaterialTheme.colorScheme.inverseOnSurface
+                )
+            }
+        }
+    ) {
+        IconButton(onClick = onClick) {
+            content()
+        }
+    }
+}
+```
+
+## Desktop Layout Pattern
+
+```kotlin
+@Composable
+fun DesktopAppLayout(
+    currentScreen: Screen,
+    onNavigate: (Screen) -> Unit,
+    content: @Composable () -> Unit
+) {
+    Row(Modifier.fillMaxSize()) {
+        // Sidebar navigation
+        NavigationRail(
+            modifier = Modifier.width(72.dp),
+            containerColor = MaterialTheme.colorScheme.surfaceVariant
+        ) {
+            Spacer(Modifier.height(16.dp))
+
+            NavigationRailItem(
+                icon = { Icon(Icons.Default.Home, "Feed") },
+                label = { Text("Feed") },
+                selected = currentScreen == Screen.Feed,
+                onClick = { onNavigate(Screen.Feed) }
+            )
+
+            NavigationRailItem(
+                icon = { Icon(Icons.Default.Email, "Messages") },
+                label = { Text("DMs") },
+                selected = currentScreen == Screen.Messages,
+                onClick = { onNavigate(Screen.Messages) }
+            )
+
+            NavigationRailItem(
+                icon = { Icon(Icons.Default.Notifications, "Notifications") },
+                label = { Text("Alerts") },
+                selected = currentScreen == Screen.Notifications,
+                onClick = { onNavigate(Screen.Notifications) }
+            )
+
+            Spacer(Modifier.weight(1f))
+
+            NavigationRailItem(
+                icon = { Icon(Icons.Default.Settings, "Settings") },
+                label = { Text("Settings") },
+                selected = currentScreen == Screen.Settings,
+                onClick = { onNavigate(Screen.Settings) }
+            )
+        }
+
+        // Divider
+        VerticalDivider()
+
+        // Main content
+        Box(Modifier.weight(1f).fillMaxHeight()) {
+            content()
+        }
+    }
+}
+```
+
+## Build Configuration
+
+```kotlin
+// desktopApp/build.gradle.kts
+plugins {
+    kotlin("jvm")
+    id("org.jetbrains.compose")
+}
+
+dependencies {
+    implementation(compose.desktop.currentOs)
+    implementation(compose.material3)
+    implementation(project(":quartz"))
+}
+
+compose.desktop {
+    application {
+        mainClass = "com.vitorpamplona.amethyst.desktop.MainKt"
+
+        nativeDistributions {
+            targetFormats(
+                org.jetbrains.compose.desktop.application.dsl.TargetFormat.Dmg,
+                org.jetbrains.compose.desktop.application.dsl.TargetFormat.Msi,
+                org.jetbrains.compose.desktop.application.dsl.TargetFormat.Deb
+            )
+
+            packageName = "Amethyst"
+            packageVersion = "1.0.0"
+
+            macOS {
+                bundleID = "com.vitorpamplona.amethyst.desktop"
+                iconFile.set(project.file("icons/icon.icns"))
+            }
+
+            windows {
+                iconFile.set(project.file("icons/icon.ico"))
+                menuGroup = "Amethyst"
+            }
+
+            linux {
+                iconFile.set(project.file("icons/icon.png"))
+            }
+        }
+    }
+}
+```

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

@@ -520,7 +520,6 @@ fun FeedList(items: List<Item>) {
 - **references/shared-composables-catalog.md** - Complete catalog of shared UI components
 - **references/state-patterns.md** - State management patterns with visual examples
 - **references/icon-assets.md** - Custom ImageVector icon patterns
-- **references/rich-text-parsing.md** - `RichTextParser`, `UrlParser`, `GalleryParser`, `Patterns`, `MediaContentModels`; NIP-92 imeta enrichment
 - **scripts/find-composables.sh** - Find all @Composable functions in codebase
 
 ## Quick Reference

.claude/skills/compose-expert/references/rich-text-parsing.md

@@ -1,64 +0,0 @@
-# Rich Text Parsing
-
-Amethyst converts raw event content (plain text with URLs, mentions, hashtags, media links, nostr references, markdown) into structured segments that Compose can render. Everything lives under `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/richtext/`.
-
-## Files
-
-- **`RichTextParser.kt`** — the main entry point. A `class RichTextParser` that takes a note's content, the URL preview cache, and NIP-92 `imeta` tags and returns a `RichTextViewState`.
-- **`RichTextParserSegments.kt`** — segment data classes (hashtag, url, mention, invoice, etc.) that the parser emits.
-- **`Patterns.kt`** — the regex bank. Single source of truth for URL, hashtag, mention, email, invoice, cashu, nostr-URI patterns. Prefer adding a case here to writing a one-off regex at a call site.
-- **`UrlParser.kt`** — URL extraction + validation; used to pull URLs out of free-form text before the parser classifies them.
-- **`GalleryParser.kt`** — builds `MediaGallery` groupings from consecutive media URLs in a note.
-- **`MediaContentModels.kt`** — the rendering contracts:
-  - `MediaUrlImage`, `MediaUrlVideo` — plain HTTP(S) media with optional NIP-92 metadata.
-  - `EncryptedMediaUrlImage`, `EncryptedMediaUrlVideo` — for encrypted/blossom-gated media.
-  - `MediaLocalImage`, `MediaLocalVideo` — for drafts / not-yet-uploaded media.
-- **`Base64Image.kt`** — inline base64 data URI support.
-- **`ExpandableTextCutOffCalculator.kt`** — decides where to truncate long content for "Show more" fold points.
-
-## How a Note Becomes Rendered UI
-
-1. Raw `content: String` arrives (from an `Event`).
-2. `RichTextParser` scans with patterns, extracts URLs, nostr IDs, hashtags, mentions, invoices, cashu tokens.
-3. URLs are classified against `imeta` tags (NIP-92) so media gets correct dimensions, mime type, blurhash.
-4. `GalleryParser` groups adjacent media into a single `MediaGallery` segment.
-5. The composable layer (elsewhere in `commons/compose/` and amethyst/desktop UI) walks the segment list and renders each with the appropriate composable (`RenderMarkdown`, `NoteQuoteBody`, `ClickableUrl`, etc.).
-
-## Typical Reuse
-
-```kotlin
-// inside a composable
-val state = remember(note, imetaTags) {
-    CachedRichTextParser.parseReturningNullable(content, imetaTags, callbackUri)
-}
-state?.paragraphs?.forEach { paragraph ->
-    paragraph.words.forEach { segment ->
-        when (segment) {
-            is UrlSegment       -> ClickableUrl(segment)
-            is HashtagSegment   -> HashtagChip(segment)
-            is NostrRefSegment  -> NoteCompose(segment.entity)
-            is ImageSegment     -> ZoomableMedia(segment.media)
-            // ...
-        }
-    }
-}
-```
-
-On Android there's `amethyst/.../service/CachedRichTextParser.kt` which caches parser output per content — re-parsing the same note on every recomposition is expensive, so **always parse behind a cache**.
-
-## NIP-92 imeta Enrichment
-
-`imeta` tags attached to an event carry structured metadata for each media URL: `url`, `m` (mime), `dim`, `blurhash`, `x` (sha256), `size`. `RichTextParser` maps these into `MediaUrlImage` / `MediaUrlVideo` so the renderer can reserve correct aspect ratio and show a blurhash placeholder before the image loads. Reference: `nip-catalog.md`.
-
-## Gotchas
-
-- **Don't parse on every recomposition.** Use `CachedRichTextParser` (Android) or `remember(content, imeta) { … }` for commonMain.
-- **Regexes live in `Patterns.kt`.** If you're writing a new regex for URLs/mentions/hashtags in a UI file, move it to `Patterns.kt` instead.
-- **Segments are `@Immutable`** data classes — safe to pass to Compose without triggering recomposition spam.
-- **Encrypted media is a separate class** (`EncryptedMediaUrl*`). If you handle `MediaUrlImage` but not its encrypted sibling, blossom/NIP-17 gated media silently falls through.
-- **`GalleryParser` groups** across whitespace-only-lines between URLs. Changing its grouping rules breaks layout in many note screens.
-
-## Related
-
-- `nostr-expert/references/nip-catalog.md` — NIP-92 (imeta) spec location
-- `compose-expert/references/shared-composables-catalog.md` — which composables consume which segment types

.claude/skills/compose-modifier-and-layout-style/SKILL.md

@@ -1,333 +0,0 @@
----
-name: compose-modifier-and-layout-style
-description: Use when writing or reviewing Jetpack Compose layout APIs, modifier parameters, modifier chain construction, hardcoded root layout decisions, or layout wrappers around a single conditional. Technique-layer skill — complements the codebase-specific compose-expert.
----
-
-# Compose modifier and layout style
-
-## Core principle
-
-A composable that emits layout is a leaf the *parent* places — the parent decides position, size, alignment, padding. The composable's job is structure (what's inside), not placement (where it goes). Three rules follow:
-
-- **Declare a `modifier` parameter and apply it to the root**, so the parent can actually do its job. Hardcoding `.fillMaxWidth()` on a composable's root takes that decision away from every future caller.
-- **Construct modifier chains as one fluent expression**, not stepwise reassignments. Both compile to the same thing, but the chain *reads* as intent in one pass.
-- **Conditional rendering belongs where the condition applies.** A layout call whose only content is one `if` exists solely to hold the condition — push the `if` outside instead.
-
-These travel together because the same composable usually triggers all three: you declare its parameters (rule 1), the caller constructs a chain to position it (rules 2), and the body has a conditional you might be tempted to wrap (rule 3).
-
-## When to use this skill
-
-- You're writing a `@Composable fun` that calls a layout (`Box`, `Column`, `Row`, `LazyColumn`, `Text`, `Image`, `Surface`, `Card`, `Layout { … }`, anything from `compose.foundation.layout` or `compose.material*`) and its signature has no `modifier` parameter, or has one that isn't applied to the root, or has a hardcoded `.fillMaxWidth()`/`.padding(...)` on the root.
-- You see `var m = Modifier` followed by `m = m.padding(…)`, `m = m.background(…)`, etc.
-- A `modifier = …` argument has three or more chained calls on a single line.
-- A composable's body is `Layout { if (cond) Content() }` — one conditional, nothing else.
-
-## 1. Declare a `modifier` parameter
-
-For composables that emit layout, prefer a `modifier` parameter after required parameters and before content/lambda parameters, with a default of `Modifier`. The name is exactly `modifier` — not `mod`, not `m`, not `wrapperModifier`.
-
-```kotlin
-// ❌ BAD — no modifier param; caller can't position, size, or constrain this
-@Composable
-fun HomeScreenHeader(title: String, subtitle: String) {
-    Column(
-        modifier = Modifier
-            .fillMaxWidth()
-            .padding(horizontal = 16.dp),
-        verticalArrangement = Arrangement.spacedBy(4.dp),
-    ) {
-        Text(title, style = MaterialTheme.typography.headlineLarge)
-        Text(subtitle, style = MaterialTheme.typography.bodyMedium)
-    }
-}
-```
-
-```kotlin
-// ✅ GOOD — parent decides width and padding; the composable describes structure only
-@Composable
-fun HomeScreenHeader(
-    title: String,
-    subtitle: String,
-    modifier: Modifier = Modifier,
-) {
-    Column(
-        modifier = modifier,
-        verticalArrangement = Arrangement.spacedBy(4.dp),
-    ) {
-        Text(title, style = MaterialTheme.typography.headlineLarge)
-        Text(subtitle, style = MaterialTheme.typography.bodyMedium)
-    }
-}
-```
-
-The caller now writes `HomeScreenHeader(title, subtitle, Modifier.fillMaxWidth().padding(horizontal = 16.dp))` once, at the home screen — the only place that knows the layout actually wants those.
-
-## 2. Apply the caller's modifier to the root, and apply it first
-
-When the root layout already takes other arguments (alignment, arrangement, padding *that's intrinsic to the composable*), the caller-provided modifier still goes on the root layout's `modifier` parameter — and the composable's local chain is appended after.
-
-```kotlin
-// ❌ BAD — modifier accepted but never applied
-@Composable
-fun Avatar(url: String, modifier: Modifier = Modifier) {
-    Image(painter = rememberAsyncImagePainter(url), contentDescription = null)
-}
-
-// ❌ BAD — applied to a child, not the root; caller's size/position changes don't take
-@Composable
-fun Avatar(url: String, modifier: Modifier = Modifier) {
-    Box {
-        Image(
-            painter = rememberAsyncImagePainter(url),
-            contentDescription = null,
-            modifier = modifier,
-        )
-    }
-}
-
-// ❌ BAD — caller's modifier ends up last, so the composable's own size wins
-@Composable
-fun Avatar(url: String, modifier: Modifier = Modifier) {
-    Image(
-        painter = rememberAsyncImagePainter(url),
-        contentDescription = null,
-        modifier = Modifier
-            .clip(CircleShape)
-            .size(48.dp)
-            .then(modifier),
-    )
-}
-```
-
-```kotlin
-// ✅ GOOD — caller's modifier first, then the composable's intrinsic chain
-@Composable
-fun Avatar(url: String, modifier: Modifier = Modifier) {
-    Image(
-        painter = rememberAsyncImagePainter(url),
-        contentDescription = null,
-        modifier = modifier
-            .clip(CircleShape)
-            .size(48.dp),
-    )
-}
-```
-
-Order matters: in a modifier chain, the *earlier* segment is the outer wrapper. The caller's modifier should be the outermost so caller-provided `.size(...)` or `.padding(...)` can override the composable's defaults rather than being overridden by them.
-
-## 3. Don't hardcode layout decisions on the root
-
-If the composable's root has `.fillMaxWidth()`, `.padding(horizontal = 16.dp)`, `.height(56.dp)`, etc., the caller can't *not* have them. Those are layout choices the parent should own.
-
-```kotlin
-// ❌ BAD — every caller now fills max width whether they want to or not
-@Composable
-fun PrimaryButton(text: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
-    Button(
-        onClick = onClick,
-        modifier = modifier.fillMaxWidth(),   // ← hardcoded
-    ) { Text(text) }
-}
-
-// ✅ GOOD — caller adds .fillMaxWidth() if (and only if) they want it
-@Composable
-fun PrimaryButton(text: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
-    Button(onClick = onClick, modifier = modifier) { Text(text) }
-}
-```
-
-The carve-out is for modifiers that are part of the **identity** of the composable — what makes an `Avatar` an avatar (the `.clip(CircleShape)` and a default `.size(48.dp)`), not where it sits on the screen. Test: can you imagine a caller wanting a version of this composable *without* that modifier? If yes, push it out. If no (an avatar without `clip(CircleShape)` isn't an avatar), keep it — but put it *after* the caller's modifier in the chain (see §2).
-
-## 4. Construct modifier chains as one fluent expression
-
-Recomposition re-runs the composable body — every modifier expression is re-evaluated. Reassigning `var modifier =` step-by-step looks plausible but breaks the visual flow, invites further mutation, and produces nothing a chain doesn't.
-
-```kotlin
-// ❌ BAD — visual flow broken into reassignments; `var` invites more mutation
-@Composable
-fun Demo() {
-    var m = Modifier
-    m = m.padding(16.dp)
-    m = m.fillMaxSize()
-    Box(m) { }
-}
-
-// ❌ ALSO BAD — same shape, dressed up with .then()
-@Composable
-fun Demo() {
-    var m = Modifier
-    m = m.padding(16.dp)
-    m = m.then(Modifier.fillMaxSize())
-    Box(m) { }
-}
-```
-
-```kotlin
-// ✅ GOOD
-@Composable
-fun Demo() {
-    val m = Modifier
-        .padding(16.dp)
-        .fillMaxSize()
-    Box(m) { }
-}
-```
-
-`val`, not `var`: once the chain is built, nothing should re-bind it. The reassignment shape is what makes `var` look necessary; the chain shape doesn't need it.
-
-### Inline at the call site is fine for short chains
-
-For one or two calls, build the modifier inline. The "extract to a `val`" rule only earns its keep when the chain is long enough to be worth naming, or when the same chain repeats.
-
-```kotlin
-// ✅ GOOD — short chain inline
-Box(modifier = Modifier.fillMaxWidth()) { … }
-Box(modifier = Modifier.padding(8.dp).background(Color.Red)) { … }
-```
-
-### Conditional segments stay on the chain
-
-A common reason to reach for `var` is "the modifier depends on a condition." It doesn't — splice the condition inline:
-
-```kotlin
-// ✅ GOOD — conditional inside the chain, still one expression
-Box(
-    modifier = Modifier
-        .fillMaxWidth()
-        .then(if (selected) Modifier.background(Color.Red) else Modifier),
-)
-```
-
-`Modifier` (the empty modifier) is the identity element for `.then` — it lets you keep the chain shape when one branch contributes nothing.
-
-## 5. Multiline formatting at the call site
-
-When a `modifier` argument's chain has **three or more** calls, format multiline with one call per line. Indent the chain so the dotted calls align beneath the value.
-
-```kotlin
-// ❌ BAD — three+ calls on one line; hard to scan
-Box(
-    modifier = modifier.fillMaxSize().padding(16.dp).weight(1f),
-)
-
-// ✅ GOOD
-Box(
-    modifier = modifier
-        .fillMaxSize()
-        .padding(16.dp)
-        .weight(1f),
-)
-```
-
-One or two calls stay on a single line — the threshold is the call count, not the character count. If a single call has very long arguments, that's a different problem (extract a `val`, or shorten the arguments).
-
-This applies *only* to a parameter named `modifier`. Other fluent-style arguments aren't covered here.
-
-## 6. Hoist single conditionals out of the layout
-
-When a layout's *only* content is one `if`, the layout exists solely to "hold" the conditional. Move the `if` outside — the layout will only exist when it has something to show.
-
-```kotlin
-// ❌ BAD — Column always emitted; only its inner content is conditional
-@Composable
-fun A() {
-    Column {
-        if (showHeader) {
-            Text("Title")
-            Text("Subtitle")
-        }
-    }
-}
-
-// ✅ GOOD — Column only exists when it has content
-@Composable
-fun A() {
-    if (showHeader) {
-        Column {
-            Text("Title")
-            Text("Subtitle")
-        }
-    }
-}
-```
-
-The benefit isn't a performance win — the runtime handles both fine — it's that the second form *reads* as "header section, conditionally." The first reads as "always-on column that may or may not have content."
-
-### The carve-outs (and why)
-
-- **Layout carries visual semantics that aren't conditional.** When the layout call passes `modifier`, `contentAlignment`, `horizontalArrangement`, or `verticalAlignment`, those arguments describe the *container*, not the content. Hoisting the conditional either loses those (the container collapses with the content) or duplicates them into both branches. Leave it.
-
-  ```kotlin
-  // ✅ KEEP AS-IS — modifier on the container is doing visible work
-  @Composable
-  fun A(modifier: Modifier = Modifier) {
-      Box(modifier = modifier) {
-          if (something) {
-              Text("Bleh1")
-              Text("Bleh2")
-          }
-      }
-  }
-  ```
-
-- **There are siblings to the `if`.** The layout has other content; the `if` is just one piece. Hoisting either pulls the siblings out (changing the layout) or leaves a different shape behind. Leave it.
-
-- **`if … else …` with both branches contributing composables.** Both branches do work; nothing to hoist; the layout *is* the shared container.
-
-  ```kotlin
-  // ✅ KEEP AS-IS — both branches contribute to the layout
-  Box {
-      if (something) Text("Hint") else innerTextField()
-  }
-  ```
-
-## Quick reference
-
-| Symptom | Diagnosis | Fix |
-|---|---|---|
-| `@Composable fun Foo(text: String)` with `Column`/`Box`/`Text` in body | No `modifier` param (§1) | Add `modifier: Modifier = Modifier`; pass to root |
-| `modifier: Modifier = Modifier` declared but never referenced | Param ignored (§2) | Apply to root layout's `modifier` arg |
-| `modifier` passed to a child, not the root | Wrong target (§2) | Move to the outermost layout's `modifier` |
-| `modifier = Modifier.x().y().then(modifier)` | Caller's modifier last (§2) | Reorder: `modifier = modifier.x().y()` |
-| `modifier = modifier.fillMaxWidth().padding(...)` on a general-purpose component | Layout hardcoded (§3) | Remove the hardcoded calls; let callers add them |
-| Sibling composables in the file don't have `modifier` either | Spreading anti-pattern | Fix this one; fix siblings opportunistically |
-| `mod: Modifier = Modifier` or `wrapperModifier: Modifier = Modifier` | Wrong name (§1) | Rename to exactly `modifier` |
-| `var m = Modifier` followed by `m = m.xxx()` reassignments | Stepwise modifier construction (§4) | One fluent chain on a `val`, or build inline |
-| `var m = Modifier; m = m.then(Modifier.xxx())` | Same shape via `.then` (§4) | Collapse `.then(Modifier.x())` to `.x()` in the chain |
-| Modifier branch needs a condition | Reaching for `var` (§4) | `.then(if (c) Modifier.x() else Modifier)` inside the chain |
-| `modifier = modifier.a().b().c()` on one line | Long chain not formatted (§5) | One call per line, indented under the value |
-| `Layout { if (cond) X() }` with no other content and no layout-tuning args | Hoist (§6) | Move the `if` outside the layout |
-| `Box(modifier = …) { if (cond) X() }` | Layout carries semantics — leave (§6 carve-out) | Keep as-is |
-| `Box { if (cond) X() else Y() }` | Both branches contribute — leave (§6 carve-out) | Keep as-is |
-
-## When NOT to apply
-
-- **Composables that don't emit layout.** A `@Composable fun computeColor(): Color` or a `@Composable @ReadOnlyComposable` accessor doesn't emit a layout node. No `modifier` parameter needed (and a `@ReadOnlyComposable` couldn't accept one anyway).
-- **`@Preview` functions.** Previews are throwaway entry points; the framework calls them with no caller. A `modifier` parameter would be unused dead weight.
-- **Test-only composables** inside `*Test` sources whose only caller is `composeTestRule.setContent { … }`. Same reasoning as previews.
-- **Internal layout primitives that take a `modifier` as their *first required* parameter** (very rare; framework-level). The rule is "first *optional* param"; some private utilities legitimately have `modifier` upfront as required.
-- **Modifier assembled imperatively from animation state.** A modifier built by appending values from `Animatable` or other procedural sources may legitimately need intermediate variables. The chain isn't the goal; readability is. If the chain becomes a worse expression, write the imperative form.
-- **Slot APIs that store modifiers** in a data class or builder (rare; usually framework-level code). The fluent-chain idea is about user-site construction.
-- **Test composables** pinning specific recomposition shapes — usually fine either way; don't refactor test composables purely for style.
-
-The declaration-side rules (§1–§3) should not be skipped merely because "this composable is internal", "only used in one place", "I'd rather not have the extra parameter on the signature", or "we know all the callers already". Those are exactly the rationalisations that produce composables that become single-use the day someone wants to call them twice.
-
-## Red flags during review
-
-| Thought | Reality |
-|---|---|
-| "This composable is internal-only — adding `modifier` is over-engineering" | The parameter is eight characters and a default. It's not over-engineering; it's the convention. Skipping it is the over-engineering — it's a custom decision against the grain of every Compose API. |
-| "It's only used in one place, so I know the layout requirements" | "Only used in one place" describes today. The cost of the parameter is paid once; the cost of refactoring callers when the second use site appears is paid per caller. |
-| "The sibling composables in this file don't have `modifier` either, so I'm matching style" | Spreading an anti-pattern isn't matching style. Fix this one. Fix the siblings opportunistically. |
-| "The parent always wants `.fillMaxWidth()` here" | Then the parent passes `.fillMaxWidth()`. The composable doesn't decide that for callers it hasn't met yet. |
-| "I'll add it when someone needs it" | You're someone. You need it now (for the convention). The next caller won't add it either — they'll work around its absence. |
-| "It's a tiny composable — the modifier param is noise" | The param is eight characters at the declaration and zero characters at any call site that doesn't need it. The "noise" is imagined. |
-| "I added `modifier` but kept `.fillMaxWidth()` on the root so the home screen doesn't have to" | Then the *not*-home-screen caller can't unset it. Move the `.fillMaxWidth()` to the caller. |
-| "I need `var` for the modifier because the chain depends on a condition" | A conditional segment is `.then(if (c) Modifier.x() else Modifier)`, still on one chain. No `var` needed. |
-| "Three lines is too few to make multiline" | Three chained calls *is* the threshold. Below three, one line. At or above three, multiline. |
-| "The Column adds nothing but I'll keep it for symmetry" | Then hoist the conditional and keep the Column inside the consequent — symmetry preserved, no always-on container. |
-| "I'll put the `if` inside because the layout already exists" | "Already exists" is the bug. The layout shouldn't exist when the condition is false. |
-
-## Related
-
-- [`compose-slot-api-pattern`](../compose-slot-api-pattern/SKILL.md) — the other half of declaring a reusable composable's public API: take `@Composable () -> Unit` slots for variable content. A reusable component takes both a `modifier` parameter *and* slots — caller owns placement *and* what to place.

.claude/skills/compose-recomposition-performance/SKILL.md

@@ -1,34 +0,0 @@
----
-name: compose-recomposition-performance
-description: Use when investigating Jetpack Compose recomposition performance, skippable/restartable composables, composables.txt or compiler reports, Layout Inspector recomposition counts, or frame-rate State reads in composition vs layout/draw, and it is not yet clear whether the cause is parameter stability or deferred reads. Technique-layer skill — complements the codebase-specific compose-expert.
----
-
-# Compose recomposition performance
-
-Router only — deep fixes live in [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) and [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md).
-
-## Two axes
-
-1. **Parameter stability / skipping** — can Compose skip this restartable composable; are arguments stable and comparable?
-2. **Where `State` is read** — is frame-rate `State` read during composition vs layout/draw?
-
-Either axis can dominate; they combine independently.
-
-## Route here → focused skill
-
-| Primary suspicion | Next skill |
-|---|---|
-| Skipping, unstable params, compiler/`composables.txt` churn | [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) |
-| Frame-rate `State` read phase (composition vs layout/draw) | [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) |
-| Evidence for both | Apply both skills in parallel |
-
-## Review order
-
-1. Decide which axis fits the evidence; open the matching skill.
-2. If unclear, sample both — stability churn vs composition-phase reads of fast `State`.
-3. Re-measure after changes.
-
-## When NOT to apply
-
-- Recomposition tracks real data changes, or the bug is correctness not cost.
-- No profiler / compiler signal suggests a problem.

.claude/skills/compose-side-effects/SKILL.md

@@ -1,173 +0,0 @@
----
-name: compose-side-effects
-description: Use when writing or reviewing Jetpack Compose code with LaunchedEffect, DisposableEffect, SideEffect, rememberCoroutineScope, rememberUpdatedState, snapshotFlow, snackbar, navigation, focus requests, analytics, or event Flow collection. Technique-layer skill — complements the codebase-specific compose-expert.
----
-
-# Compose: side effects
-
-## Core principle
-
-Composable bodies describe UI. They can be recomposed, skipped, or abandoned. Work that changes the outside world belongs in an effect API whose lifecycle matches the work.
-
-## Pick the smallest effect
-
-| Need | API |
-|---|---|
-| Publish Compose state to non-Compose code after every successful recomposition | `SideEffect` |
-| Register/unregister a listener, callback, observer, or resource | `DisposableEffect(keys...)` |
-| Run suspending, deferred, or keyed one-shot work | `LaunchedEffect(keys...)` |
-| Launch suspending work from a user event callback | `rememberCoroutineScope()` |
-| Convert Compose snapshot reads into a Flow inside a coroutine | `snapshotFlow { ... }` inside `LaunchedEffect` |
-
-## Effect keys
-
-Keys define restart identity. When any key changes, the old effect is cancelled/disposed and a new one starts.
-
-```kotlin
-// ✅ Restart collection when userId changes
-LaunchedEffect(userId) {
-    repository.events(userId).collect { event -> handle(event) }
-}
-
-// ❌ Unit hides a changing input; collection keeps using the first userId
-LaunchedEffect(Unit) {
-    repository.events(userId).collect { event -> handle(event) }
-}
-```
-
-Use stable, semantic keys:
-
-- Use the thing whose lifecycle the effect follows: `userId`, `screenId`, `lifecycleOwner`, `focusRequester`.
-- Do not use broad objects (`state`, `viewModel`) when only one property matters.
-- Do not add changing lambdas as keys unless you really want restarts on every lambda change.
-
-## Avoid stale captures
-
-For long-running effects that should not restart but need the latest callback or value, use `rememberUpdatedState`.
-
-```kotlin
-@Composable
-fun Timeout(onTimeout: () -> Unit) {
-    val latestOnTimeout by rememberUpdatedState(onTimeout)
-
-    LaunchedEffect(Unit) {
-        delay(1_000)
-        latestOnTimeout()
-    }
-}
-```
-
-Use this when the lifecycle is "start once" but the invoked lambda should stay fresh. Common cases:
-
-- A timeout or splash effect should not restart when `onTimeout` changes, but it should call the latest callback.
-- A lifecycle observer should stay registered to the same owner, but invoke the latest `onStart` / `onStop` lambdas.
-- A long-running collector should keep its collection lifecycle, but call the latest event handler.
-
-Do not use `rememberUpdatedState` to avoid choosing proper keys. If the changed value should restart the work, make it a key instead:
-
-```kotlin
-// BAD: userId changes should restart the collection, not update a captured value.
-val latestUserId by rememberUpdatedState(userId)
-LaunchedEffect(Unit) {
-    repository.events(latestUserId).collect { event -> handle(event) }
-}
-
-// GOOD: the collection lifecycle follows userId.
-LaunchedEffect(userId) {
-    repository.events(userId).collect { event -> handle(event) }
-}
-```
-
-`rememberUpdatedState` also does not make render state "non-recomposing." If the UI needs to display a changing value, read normal `State` in composition or use the deferred-read patterns in [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) for frame-rate values.
-
-## Collecting Flow
-
-Use `LaunchedEffect` for **side-effect/event flows**: snackbars, navigation events, analytics events, focus commands, or other streams where each emission triggers imperative work.
-
-```kotlin
-LaunchedEffect(events) {
-    events.collect { event ->
-        snackbarHostState.showSnackbar(event.message)
-    }
-}
-```
-
-Do not collect render state imperatively just to mutate local state. For UI state, collect near the state holder and pass plain values into the UI composable—the **state-holder vs UI split**, `collectAsStateWithLifecycle()` / `collectAsState()`, and preview-friendly wiring are covered in [`compose-state-holder-ui-split`](../compose-state-holder-ui-split/SKILL.md). Do not duplicate that architecture here.
-
-On Android, prefer lifecycle-aware collection where available; use `collectAsState()` on targets without lifecycle-aware APIs.
-
-For Compose state reads, use `snapshotFlow`:
-
-```kotlin
-LaunchedEffect(listState) {
-    snapshotFlow { listState.firstVisibleItemIndex }
-        .distinctUntilChanged()
-        .collect { index -> analytics.visibleIndex(index) }
-}
-```
-
-`snapshotFlow { ... }.map { ... }` without a terminal `collect` does nothing.
-
-## User events
-
-Use `rememberCoroutineScope()` when a click or gesture starts suspending work:
-
-```kotlin
-@Composable
-fun SaveButton(snackbarHostState: SnackbarHostState) {
-    val scope = rememberCoroutineScope()
-
-    Button(
-        onClick = {
-            scope.launch {
-                snackbarHostState.showSnackbar("Saved")
-            }
-        },
-    ) {
-        Text("Save")
-    }
-}
-```
-
-Avoid "event flag" state just to trigger a `LaunchedEffect`. The click already is the event.
-
-## Registration and cleanup
-
-Use `DisposableEffect` for paired setup/teardown:
-
-```kotlin
-@Composable
-fun ObserveLifecycle(owner: LifecycleOwner, observer: LifecycleObserver) {
-    DisposableEffect(owner, observer) {
-        owner.lifecycle.addObserver(observer)
-        onDispose {
-            owner.lifecycle.removeObserver(observer)
-        }
-    }
-}
-```
-
-Every registration path should have a matching `onDispose` cleanup path.
-
-## Common mistakes
-
-| Mistake | Fix |
-|---|---|
-| Network request directly in the composable body | Usually move to a ViewModel/state holder; use `LaunchedEffect` only for UI-owned keyed work |
-| Analytics property written from the composable body | Use `SideEffect` when it should publish after every successful recomposition |
-| Impression/event logged from the composable body | Use `LaunchedEffect(key)` when it should run once for that key |
-| `LaunchedEffect(Unit)` captures changing `id` | Key by `id`, or use `rememberUpdatedState` if it must not restart |
-| `rememberUpdatedState(id)` used so `LaunchedEffect(Unit)` keeps running after `id` changes | Hidden lifecycle bug | Key the effect by `id` |
-| Long-lived effect invokes an old callback after recomposition | Stale capture | Wrap the callback with `rememberUpdatedState` and call the wrapper inside the effect |
-| `LaunchedEffect(state) { ... }` restarts too often | Key by the specific property |
-| `LaunchedEffect(...) { nonSuspendSetter() }` | Usually `SideEffect`; keep `LaunchedEffect` only for keyed one-shot/deferred work |
-| Listener added in `LaunchedEffect` with no cleanup | Use `DisposableEffect` |
-| Launching from click by setting `shouldShowSnackbar = true` | Use `rememberCoroutineScope()` in the click callback |
-
-## Red flags during review
-
-- "This only runs once" about code in a composable body.
-- `LaunchedEffect(Unit)` in a function with changing parameters.
-- A flow chain inside an effect with no terminal collection.
-- Effects whose keys are chosen to silence lint instead of model lifecycle.
-- Callback lambdas used from long-lived effects without either a key or `rememberUpdatedState`.

.claude/skills/compose-slot-api-pattern/SKILL.md

@@ -1,198 +0,0 @@
----
-name: compose-slot-api-pattern
-description: Use when designing or reviewing a reusable Jetpack Compose component whose visual regions vary by caller, or when primitive content parameters and boolean shape flags are accumulating. Technique-layer skill — complements the codebase-specific compose-expert.
----
-
-# Compose: slot API pattern
-
-## Core principle
-
-A reusable Compose component's job is to lay things out, not to enumerate what it lays out. The moment you write `title: String, subtitle: String?, leadingIcon: ImageVector?, trailingIcon: ImageVector?, trailingText: String?, showSwitch: Boolean, switchValue: Boolean, onSwitchChange: (Boolean) -> Unit?, badge: String?, …`, the component has stopped describing a layout and started enumerating call sites — and the next call site will need a parameter the component doesn't have.
-
-The fix is to **delegate content to the caller** via `@Composable` lambda parameters. The component contributes structure (where the leading bit, headline, supporting bit, trailing bit go). The caller contributes everything that goes *in* those slots.
-
-Material 3's `ListItem` is the canonical example: every visual piece is a slot (`headlineContent`, `supportingContent`, `leadingContent`, `trailingContent`, `overlineContent`), not a primitive. That's not over-engineering — it's the design that scales to every list-item shape the design system needs without ever editing `ListItem` again.
-
-## When to use this skill
-
-You're designing or reviewing a Compose component intended for reuse (more than one call site, now or planned), its visual content varies by caller, and any of these is true:
-
-- Its signature has `title: String`, `icon: ImageVector`, `actionText: String?`, etc. — primitive types describing *content*.
-- It has multiple optional-content parameters that vary by call site (`subtitle: String?`, `leadingIcon: ImageVector?`, `trailingText: String?`).
-- It has boolean flags whose only purpose is to switch between content shapes (`showChevron: Boolean`, `showSwitch: Boolean`, `mode: Mode.Text | Mode.Switch | …`).
-- It accepts a `String` parameter where one caller would want a `Text` with custom style, a second caller a `Text` with a `Badge`, a third caller a row of icons.
-- It already has *one* slot (often `trailing` or `content`) and the rest of the parameters are still primitives.
-
-## 1. Replace primitive content with `@Composable` slots
-
-Where the component asks for caller-controlled *content*, prefer a `@Composable () -> Unit` slot. Where the slot is structurally required, leave it non-nullable with no default. Where it's optional, make it nullable with a `null` default.
-
-```kotlin
-// ❌ BAD — primitive parameters; trailing area is the only slot; everything else is locked
-@Composable
-fun SettingsRow(
-    title: String,
-    onClick: () -> Unit,
-    modifier: Modifier = Modifier,
-    subtitle: String? = null,
-    leadingIcon: ImageVector? = null,
-    trailing: (@Composable () -> Unit)? = null,
-) { … }
-```
-
-This shape *seems* fine because the call sites today fit (`title` is always single-line text, `leadingIcon` is always an `ImageVector`). The problem is the *next* call site: a row with a `Badge` next to the title, a leading slot that's a circular avatar (not an `ImageVector`), a subtitle that's a row of chips. Each forces either a new parameter, a new flag, or a workaround.
-
-```kotlin
-// ✅ GOOD — every visual region is a slot; the row describes structure, not content
-@Composable
-fun SettingsRow(
-    headlineContent: @Composable () -> Unit,
-    onClick: () -> Unit,
-    modifier: Modifier = Modifier,
-    supportingContent: (@Composable () -> Unit)? = null,
-    leadingContent: (@Composable () -> Unit)? = null,
-    trailingContent: (@Composable () -> Unit)? = null,
-) { … }
-```
-
-Call sites stay short because the typical content is a one-liner:
-
-```kotlin
-SettingsRow(
-    headlineContent = { Text("Account") },
-    leadingContent = { Icon(Icons.Default.Person, contentDescription = null) },
-    trailingContent = { SettingsRowDefaults.Chevron() },
-    onClick = { … },
-)
-```
-
-And the awkward cases that *would* have required new primitive parameters now don't:
-
-```kotlin
-SettingsRow(
-    headlineContent = {
-        Row(verticalAlignment = Alignment.CenterVertically) {
-            Text("Inbox")
-            Spacer(Modifier.width(8.dp))
-            Badge { Text("3") }
-        }
-    },
-    onClick = { … },
-)
-```
-
-### Slot naming
-
-- Use `xxxContent` for free-form `@Composable () -> Unit` slots (`headlineContent`, `supportingContent`, `trailingContent`) — matches Material 3.
-- Use a singular noun (`title`, `icon`, `actions`) when the slot is semantically constrained and the component name disambiguates (`Scaffold(topBar = { … }, bottomBar = { … }, floatingActionButton = { … })`).
-- Don't use `content` *and* other `xxxContent` slots together — pick one convention per component.
-
-## 2. Scope receivers when the slot emits into a layout
-
-If the slot's content will sit inside a `Row`/`Column`/`Box` whose layout features (`Modifier.weight`, `BoxScope.matchParentSize`, alignment) should be available to the caller, declare the slot as a receiver lambda: `@Composable RowScope.() -> Unit`.
-
-```kotlin
-// ❌ BAD — actions render inside a Row, but callers can't use RowScope.weight()
-@Composable
-fun MyTopBar(
-    title: @Composable () -> Unit,
-    actions: @Composable () -> Unit = {},   // ← caller has no Row scope
-)
-```
-
-```kotlin
-// ✅ GOOD — caller gets RowScope; .weight() and alignment-by works inside
-@Composable
-fun MyTopBar(
-    title: @Composable () -> Unit,
-    actions: @Composable RowScope.() -> Unit = {},
-)
-```
-
-This is what makes `TopAppBar(actions = { IconButton(…); IconButton(…) })` work — the caller is implicitly inside a `RowScope`.
-
-Don't bolt a scope receiver onto every slot reflexively. The receiver should match the actual parent layout the slot emits into. If the slot is rendered inside a `Box`, use `BoxScope`. If it's inside a `Column`, use `ColumnScope`. If the parent is not a standard layout (or none of its scope APIs are useful in slot content), no receiver.
-
-## 3. Optional slots — nullable with `null` default
-
-For slots that may be absent, prefer `(@Composable () -> Unit)? = null` over `@Composable () -> Unit = {}`:
-
-```kotlin
-// ❌ BAD — empty default; "no leading content" is the empty lambda
-leadingContent: @Composable () -> Unit = {}
-
-// ✅ GOOD — null means "no slot"; the component can omit space/padding when absent
-leadingContent: (@Composable () -> Unit)? = null
-```
-
-Why: with a nullable slot, the *component* can branch on `leadingContent != null` and skip the slot's container, spacing, padding entirely. With an empty default, the layout still allocates the slot — sometimes you see a stray padding or spacer around content that turned out to be nothing. The nullable form makes the "absent" case structurally distinct, which is almost always what you want.
-
-The trade-off: callers who pass an explicit empty `{}` to silence a slot now have to pass `null` or omit the argument. That's the right answer either way — they shouldn't be passing `{}`.
-
-## 4. Defaults live in `XxxDefaults`
-
-When you find yourself documenting "the trailing slot should usually be a chevron" or "pass `MaterialTheme.colorScheme.surface` for the default background", co-locate the helpers in a `XxxDefaults` object next to the component:
-
-```kotlin
-object SettingsRowDefaults {
-    @Composable
-    fun Chevron() = Icon(
-        imageVector = Icons.AutoMirrored.Filled.KeyboardArrowRight,
-        contentDescription = null,
-    )
-
-    @Composable
-    fun TrailingValue(text: String) = Text(
-        text = text,
-        style = MaterialTheme.typography.bodyMedium,
-        color = MaterialTheme.colorScheme.onSurfaceVariant,
-    )
-}
-```
-
-Call sites stay declarative for the common cases and the slot is still fully open for one-offs:
-
-```kotlin
-SettingsRow(
-    headlineContent = { Text("Notifications") },
-    trailingContent = { SettingsRowDefaults.Chevron() },
-    onClick = { … },
-)
-```
-
-This matches Material 3's `ButtonDefaults`, `TopAppBarDefaults`, etc. — defaults that are themselves composable belong here, not as new component parameters with `MaterialTheme.x.y` defaults expanded inline.
-
-## Quick reference
-
-| Symptom | Diagnosis | Fix |
-|---|---|---|
-| `title: String, subtitle: String?, leadingIcon: ImageVector?` on a reusable component | Primitive content params (§1) | Convert to `xxxContent: (@Composable () -> Unit)?` slots |
-| Multiple boolean flags (`showChevron`, `showSwitch`) selecting trailing shapes | Enumerating shapes (§1) | One `trailingContent: (@Composable () -> Unit)?` slot |
-| A `mode: Mode.Sealed` parameter listing variants | Same as flag soup (§1) | Slot it |
-| `actions: @Composable () -> Unit = {}` inside a `Row` body | Missing scope receiver (§2) | `actions: @Composable RowScope.() -> Unit = {}` |
-| `slot: @Composable () -> Unit = {}` for an optional area | Empty-lambda default (§3) | `slot: (@Composable () -> Unit)? = null` and branch on it |
-| Component param `defaultColor: Color = MaterialTheme.colorScheme.surface` | Defaults inlined (§4) | Move to `XxxDefaults.color` and reference it |
-| Common trailing content repeats at every call site | Missing default helper (§4) | Add `XxxDefaults.Chevron()` etc. |
-
-## When NOT to apply
-
-- **Single-use components.** A composable used in exactly one place, with no plan to reuse, doesn't benefit from slot flexibility — and the slot indirection makes the code harder to read for the one reader. Primitive params + inline content is fine. (As soon as a second call site appears, slot it.)
-- **Design-system primitives where every caller must look identical.** A `Heading2(text: String)` exists *because* you want every H2 to look the same; making it `headlineContent: @Composable () -> Unit` invites callers to break the rule. Keep it primitive. (Conversely: if `Heading2` ever needs a badge inline, slot it.)
-- **Semantic parameters the component intentionally owns.** If the component owns typography, iconography, accessibility wording, or product consistency, a primitive parameter may be the constraint you want.
-- **Constrained-type parameters that genuinely are constrained.** A `Switch(checked: Boolean, onCheckedChange: ...)` doesn't need its checked indicator to be a slot. Booleans-with-callbacks are not "content."
-- **Performance-critical fast paths** (rare in app code; common in framework primitives). A slot is an allocated lambda. In the deepest LazyList item layer, sometimes primitives win. If you're not writing the framework, this doesn't apply.
-
-## Red flags during review
-
-| Thought | Reality |
-|---|---|
-| "Title is *always* a String — making it a slot is over-engineering" | "Always today" is the trap. Material's `ListItem.headlineContent` exists because tomorrow someone wants a `Text + Badge`. The slot is `8` characters of extra wrapping at every call site (`{ Text(…) }`); the refactor to add a slot later edits every existing call site. |
-| "Lambdas are heavier than strings" | At the scale of typical Compose UI, this isn't measurable — and the framework's own components (`Button`, `ListItem`, `TopAppBar`, `Scaffold`) all slot. If your component is in the hottest of hot paths, see "When NOT to apply." |
-| "I'll add a slot later if someone asks" | The slot turns one parameter into two parameters (the slot itself + maybe an internal flag) and edits every call site. The shape change isn't a "later" change. |
-| "I'll model the variants with a sealed `Trailing` type instead" | Sealed enumeration is bounded; slots are unbounded. A sealed type works *until* the day someone needs a variant you didn't anticipate — at which point you're back to editing the component. The slot avoids the cycle. |
-| "The leading area is *always* an icon, the trailing area varies — I'll slot only the trailing" | This is the partial-slot trap. The "always-an-icon" assumption breaks the first time a row needs an avatar or a flag emoji or a coloured shape. Slot leading too. |
-| "There's only one call site today" | If there's only one call site, you're probably not designing a reusable component yet. See "When NOT to apply" — primitives are fine for a true single-use. The moment you copy-paste it, slot it. |
-
-## Related
-
-- [`compose-modifier-and-layout-style`](../compose-modifier-and-layout-style/SKILL.md) — the modifier-parameter rule (§1–§3 there) travels with slot APIs. A reusable component takes a `modifier` parameter *and* slots its content; the caller owns both placement and what to place.

.claude/skills/compose-stability-diagnostics/SKILL.md

@@ -1,140 +0,0 @@
----
-name: compose-stability-diagnostics
-description: Use when writing or reviewing Jetpack Compose parameter stability, compiler reports, skippability, unstable UI state classes, collection parameters, or Kotlin 2.0+ strong skipping behavior. Technique-layer skill — complements the codebase-specific compose-expert and kotlin-expert.
----
-
-# Compose stability diagnostics
-
-## Core principle
-
-Compose performance problems from parameters are about **whether inputs compare cheaply and predictably across recompositions**. With Kotlin 2.0.20+ strong skipping is enabled by default, so unstable parameters no longer automatically make restartable composables non-skippable. That does not make stability irrelevant: unstable parameters are compared by instance identity (`===`), stable parameters by equality (`equals`), and churny instances can still defeat skipping.
-
-First identify the compiler mode you are on, then read reports in that context.
-
-## When to use this skill
-
-- A composable or screen recomposes more than expected and parameter churn is suspected.
-- A UI-state/model class is passed to composables and contains `List`, `Set`, `Map`, ranges, Java time/money types, or third-party types.
-- `composables.txt` / `classes.txt` shows unstable parameters or non-skippable composables.
-- A project uses Kotlin < 2.0.20, disables strong skipping, or has old Compose compiler report guidance.
-
-## 1. Start with strong skipping
-
-On Kotlin 2.0.20+, strong skipping is enabled by default. In that mode:
-
-- Restartable composables are skippable even when parameters are unstable, unless explicitly opted out.
-- Stable parameters compare with `equals`.
-- Unstable parameters compare with instance equality (`===`).
-- Lambdas inside composables are automatically remembered based on captures.
-
-That means the question changes from "is this composable skippable at all?" to "will these parameters compare the way I expect, and are callers creating new unstable instances every frame?"
-
-For older compiler setups or strong skipping disabled, the legacy rule still matters: a restartable composable with unstable parameters may be restartable but not skippable.
-
-## 2. Generate compiler reports
-
-With Kotlin 2.0+ the Compose Compiler is configured through the Kotlin Gradle plugin:
-
-```kotlin
-plugins {
-    alias(libs.plugins.android.application) // or android.library / jvm
-    alias(libs.plugins.kotlin.android)      // or kotlin.multiplatform / kotlin.jvm
-    alias(libs.plugins.compose.compiler)
-}
-
-if (providers.gradleProperty("composeReports").orNull == "true") {
-    composeCompiler {
-        reportsDestination = layout.buildDirectory.dir("compose_compiler")
-        metricsDestination = layout.buildDirectory.dir("compose_compiler")
-    }
-}
-```
-
-Then build the variant whose compiler configuration you care about, for example:
-
-```bash
-./gradlew :app:assembleRelease -PcomposeReports=true
-```
-
-Use release/non-debuggable builds for runtime profiling. Compiler reports are build-time outputs, so the important thing is matching the variant and compiler flags you ship.
-
-Key files:
-
-| File | What it tells you |
-|---|---|
-| `<module>-classes.txt` | Stability of classes and properties |
-| `<module>-composables.txt` | Restartable/skippable status and parameter stability |
-| `<module>-composables.csv` | Same data in sortable form |
-| `<module>-module.json` | Aggregate metrics |
-
-## 3. Fix stability where semantics need it
-
-Pick the lightest fix that makes the type's immutability or equality semantics true.
-
-### Immutable collections
-
-`kotlin.collections.List` is an interface; Compose cannot know the runtime implementation is immutable. Prefer `kotlinx.collections.immutable` at UI-state boundaries:
-
-```kotlin
-// Before: unstable collection interfaces
-data class UiState(val items: List<Item>, val tags: Set<String>)
-
-// After: immutable collection contracts
-import kotlinx.collections.immutable.ImmutableList
-import kotlinx.collections.immutable.ImmutableSet
-
-data class UiState(val items: ImmutableList<Item>, val tags: ImmutableSet<String>)
-```
-
-Producers convert once at the boundary with `.toImmutableList()` / `.toImmutableSet()`.
-
-### `@Immutable` / `@Stable`
-
-- Use `@Immutable` when every property is effectively immutable and equality describes all observable state.
-- Use `@Stable` for types whose mutable state is observable by Compose, typically via `MutableState`.
-
-Do not annotate to silence a report. A false stability promise can produce stale UI.
-
-### Third-party immutable types
-
-For types you cannot annotate, use `stabilityConfigurationFiles`:
-
-```kotlin
-composeCompiler {
-    stabilityConfigurationFiles.add(
-        rootProject.layout.projectDirectory.file("compose_stability.conf"),
-    )
-}
-```
-
-```text
-java.math.BigDecimal
-java.math.BigInteger
-java.time.*
-kotlinx.datetime.*
-```
-
-Only list types you are willing to promise are immutable. Do not list mutable types such as `java.util.Date`.
-
-## Quick reference
-
-| Symptom | Diagnosis | Fix |
-|---|---|---|
-| Kotlin 2.0.20+ but old docs say unstable means non-skippable | Strong skipping changed the default | Check comparison semantics and instance churn instead |
-| `unstable val items: List<Item>` | Interface collection | Use `ImmutableList<Item>` or another true immutable wrapper |
-| `unstable val price: BigDecimal` | External immutable type | Add to stability config |
-| `@Immutable` on a type with mutable internals | False promise | Fix the model or remove the annotation |
-| Composable skips poorly despite strong skipping | New unstable instance each recomposition | Remember, hoist, or make the type stable/equality-based |
-| Reports not generated | Compose compiler plugin missing or flag not set | Apply `org.jetbrains.kotlin.plugin.compose` and enable destinations |
-
-## When NOT to apply
-
-- The issue is a fast-changing `State` read in composition, such as scroll or animation. Use `compose-state-deferred-reads`.
-- The recomposition count matches real data changes.
-- The bug is wrong data or stale state, not excess work.
-- The code is test-only and readability is more important than report cleanliness.
-
-## Related
-
-- [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) - frame-rate state should often be read in layout/draw rather than composition.
-- [`compose-recomposition-performance`](../compose-recomposition-performance/SKILL.md) - entry point when you are not sure which recomposition axis is involved.

.claude/skills/compose-state-deferred-reads/SKILL.md

@@ -1,141 +0,0 @@
----
-name: compose-state-deferred-reads
-description: Use when Jetpack Compose code reads scroll, animation, gesture, or other frame-rate State in composition, passes changing values across composable boundaries, or uses value-form layout/draw modifiers. Technique-layer skill — complements the codebase-specific compose-expert.
----
-
-# Compose state deferred reads
-
-## Core principle
-
-State reads invalidate the phase that reads them. If a `State<T>` is read in a composable body, changes invalidate composition. If it is read in layout or draw, changes can invalidate only layout or draw. Frame-rate state such as scroll offsets, animations, and drag positions usually belongs in layout/draw, not composition.
-
-The fix is structural: keep the `State<T>` or a provider lambda, and read the value inside a layout/draw callback.
-
-## When to use this skill
-
-- `val x by animate*AsState(...)` is passed to `Modifier.offset(x = ...)`, `Modifier.size(...)`, `Modifier.graphicsLayer(...)`, or another value-form modifier.
-- `LazyListState.firstVisibleItemScrollOffset`, `ScrollState.value`, `Animatable.value`, or gesture state is read in a composable body.
-- A composable takes `scrollOffset: Int`, `progress: Float`, `dragOffset: Offset`, or similar frame-rate values.
-- Recomposition counters climb during scroll, animation, or gestures even when data is stable.
-
-## 1. Prefer block-form modifiers
-
-Several modifiers have value forms and block forms. The value form receives values already read in composition; the block form can read during layout or draw.
-
-```kotlin
-// Before: animated value read in composition by the `by` delegate
-@Composable
-fun SelectionPill(selectedIndex: Int) {
-    val offsetX by animateDpAsState(120.dp * selectedIndex)
-    Box(Modifier.offset(x = offsetX))
-}
-
-// After: State is kept, value is read in the layout-phase offset block
-@Composable
-fun SelectionPill(selectedIndex: Int) {
-    val offsetX = animateDpAsState(120.dp * selectedIndex)
-    Box(
-        Modifier.offset {
-            IntOffset(offsetX.value.roundToPx(), 0)
-        },
-    )
-}
-```
-
-Common replacements:
-
-| Composition read | Deferred read |
-|---|---|
-| `Modifier.offset(x = animatedX)` | `Modifier.offset { IntOffset(animatedX.value.roundToPx(), 0) }` |
-| `Modifier.graphicsLayer(translationY = y)` | `Modifier.graphicsLayer { translationY = yProvider() }` |
-| `val radius by animateFloatAsState(...); drawBehind { drawCircle(radius = radius) }` | `val radius = animateFloatAsState(...); drawBehind { drawCircle(radius = radius.value) }` |
-
-The `drawBehind` block is already draw-phase; the important part is that the `State.value` read also happens inside that block.
-
-## 2. Pass providers across composable boundaries
-
-If the fast-changing value would cross a composable boundary, pass a provider lambda instead of a snapshot value:
-
-```kotlin
-// Before: HomeScreen reads scroll offset in composition and passes the value down
-@Composable
-fun HomeScreen() {
-    val listState = rememberLazyListState()
-    LazyColumn(state = listState) {
-        item { HeroImage(scrollOffset = listState.firstVisibleItemScrollOffset) }
-    }
-}
-
-@Composable
-fun HeroImage(scrollOffset: Int, modifier: Modifier = Modifier) {
-    AsyncImage(
-        model = "...",
-        modifier = modifier.graphicsLayer(translationY = -scrollOffset / 2f),
-    )
-}
-
-// After: the only read happens inside graphicsLayer
-@Composable
-fun HomeScreen() {
-    val listState = rememberLazyListState()
-    LazyColumn(state = listState) {
-        item {
-            HeroImage(
-                scrollOffsetProvider = {
-                    if (listState.firstVisibleItemIndex == 0) {
-                        listState.firstVisibleItemScrollOffset
-                    } else {
-                        0
-                    }
-                },
-            )
-        }
-    }
-}
-
-@Composable
-fun HeroImage(scrollOffsetProvider: () -> Int, modifier: Modifier = Modifier) {
-    AsyncImage(
-        model = "...",
-        modifier = modifier.graphicsLayer {
-            translationY = -scrollOffsetProvider() / 2f
-        },
-    )
-}
-```
-
-Suffix provider parameters with `Provider` when that clarifies the deferred-read contract.
-
-## 3. Other layout/draw read sites
-
-State reads can also be deferred inside:
-
-- `Modifier.layout { measurable, constraints -> ... }`
-- Custom `Alignment.align(...)`
-- `drawWithContent`, `drawBehind`, and other draw modifiers
-- Block-form layer/layout modifiers such as `graphicsLayer { ... }` and `offset { ... }`
-
-Use these when the state changes where something is placed or painted. If the state decides *which composables exist*, it belongs in composition.
-
-## Quick reference
-
-| Symptom | Diagnosis | Fix |
-|---|---|---|
-| `val x by animateFloatAsState(...)` then `Modifier.offset(...)` | `by` reads in composition | Keep `State<Float>` and read `.value` in `offset {}` |
-| `Modifier.graphicsLayer(translationY = animatedY)` | Property-argument form uses composition values | Use `graphicsLayer { translationY = ... }` |
-| `Child(scrollOffset = listState.firstVisibleItemScrollOffset)` | Fast-changing value crosses boundary | `Child(scrollOffsetProvider = { ... })` |
-| Draw block still recomposes every frame | Value was read before draw block | Move the `State.value` read inside the draw block |
-| State chooses between different UI branches | Composition decision | Keep the read in composition |
-
-## When NOT to apply
-
-- The state controls which composables are emitted.
-- The animation is one-shot, cheap, and clarity wins.
-- You are writing tests where direct value assertions are simpler.
-- Runtime evidence shows recomposition is not the bottleneck.
-
-## Related
-
-- [`compose-state-holder-ui-split`](../compose-state-holder-ui-split/SKILL.md) - where state-holder vs plain UI split applies when passing providers/lambdas across boundaries.
-- [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) - parameter stability and compiler reports.
-- [`compose-modifier-and-layout-style`](../compose-modifier-and-layout-style/SKILL.md) - child composables need a normal `modifier` parameter before callers can move visual reads into modifiers.

.claude/skills/compose-state-holder-ui-split/SKILL.md

@@ -1,157 +0,0 @@
----
-name: compose-state-holder-ui-split
-description: Use when a Jetpack Compose screen-level composable takes a ViewModel/component/controller, collects state or effects, handles navigation/snackbars, or wires callbacks while also rendering layout. Technique-layer skill — complements the codebase-specific compose-expert and feed-patterns.
----
-
-# Compose: state holder/UI split
-
-## Core principle
-
-Separate state-holder wiring from UI rendering. The state-holder composable talks to ViewModels, components, flows, navigation, and side effects. The UI composable takes plain immutable UI state plus callbacks and describes layout.
-
-This keeps screens previewable, testable, and easier to reuse across Android, Desktop, TV, and KMP/CMP targets.
-
-## When to use this skill
-
-Use this when a Compose screen:
-
-- Takes a ViewModel, component, controller, navigator, repository, or service directly.
-- Collects app/business state or side effects in the same function that lays out most UI.
-- Passes a whole state holder into child composables instead of explicit state and callbacks.
-- Is hard to preview because it needs dependency injection, navigation, lifecycle, or fake services.
-- Has UI tests that must construct a full app stack to verify a simple layout branch.
-
-## The pattern
-
-Use a small public state-holder composable:
-
-```kotlin
-@Composable
-fun ProfileScreen(component: ProfileComponent, modifier: Modifier = Modifier) {
-    val state by component.state.collectAsStateWithLifecycle()
-
-    ProfileScreen(
-        state = state,
-        onNameChange = component::onNameChange,
-        onSaveClick = component::save,
-        onBackClick = component::back,
-        modifier = modifier,
-    )
-}
-```
-
-Then put UI in a plain composable that knows nothing about the state holder:
-
-```kotlin
-@Composable
-fun ProfileScreen(
-    state: ProfileUiState,
-    onNameChange: (String) -> Unit,
-    onSaveClick: () -> Unit,
-    onBackClick: () -> Unit,
-    modifier: Modifier = Modifier,
-) {
-    ProfileContent(
-        name = state.name,
-        isSaving = state.isSaving,
-        canSave = state.canSave,
-        onNameChange = onNameChange,
-        onSaveClick = onSaveClick,
-        onBackClick = onBackClick,
-        modifier = modifier,
-    )
-}
-```
-
-Private content functions can break up layout:
-
-```kotlin
-@Composable
-private fun ProfileContent(
-    name: String,
-    isSaving: Boolean,
-    canSave: Boolean,
-    onNameChange: (String) -> Unit,
-    onSaveClick: () -> Unit,
-    onBackClick: () -> Unit,
-    modifier: Modifier = Modifier,
-) {
-    // Layout only.
-}
-```
-
-## Rules of thumb
-
-| Concern | State-holder composable | UI composable |
-|---|---|---|
-| Collect ViewModel/component state | Yes | No |
-| Collect one-shot effects | Yes, or a tiny sibling effect handler | Usually no |
-| Hold dependency-injected objects | Yes | No |
-| Accept immutable UI state | Usually passes it through | Yes |
-| Accept lambdas for user events | Wires them | Calls them |
-| Own layout, modifiers, semantics, test tags | No/minimal | Yes |
-| Own UI-local state like scroll, focus, text input, animation, interaction | Sometimes seeds it | Yes |
-| Preview/screenshot friendly | Not necessarily | Yes |
-
-The "no collection in UI composables" rule is about app/business state and side-effect streams. Plain UI composables can still own UI-local framework state: `rememberScrollState`, `rememberLazyListState`, `FocusRequester`, focus state, animation state, `TextFieldState`, `MutableInteractionSource.collectIsPressedAsState()`, and similar behavior that belongs to the rendered widget.
-
-If that UI-local state grows into coordinated behavior with multiple related fields and operations, consult `compose-expert` (state hoisting section) to decide whether it should become a plain state holder class remembered in composition.
-
-## What to pass
-
-Pass the smallest useful UI contract:
-
-- Prefer a dedicated `UiState`/`State` object over many unrelated primitives when the screen has real state.
-- Prefer explicit lambdas (`onRetryClick`, `onItemSelected`) over passing a whole component.
-- Keep domain models out of the UI composable if they force business rules into UI. Map to UI models when the UI needs a different shape.
-- Keep navigation as callbacks. The UI composable says "user clicked back", not "navigate to route X".
-- Frame-rate or UI-local values that should not force whole-tree recomposition when they change: prefer provider lambdas and deferred reads per [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md).
-
-## Side effects
-
-[`compose-side-effects`](../compose-side-effects/SKILL.md) covers effect APIs (`LaunchedEffect`, `DisposableEffect`, `SideEffect`), keys, cleanup, and `rememberUpdatedState`.
-
-Handle effects near the state holder, where the effect source and imperative target are both available:
-
-```kotlin
-@Composable
-fun ProfileScreen(component: ProfileComponent, snackbarHostState: SnackbarHostState) {
-    val state by component.state.collectAsStateWithLifecycle()
-
-    LaunchedEffect(component) {
-        component.effects.collect { effect ->
-            when (effect) {
-                ProfileEffect.Saved -> snackbarHostState.showSnackbar("Saved")
-            }
-        }
-    }
-
-    ProfileScreen(state = state, onSaveClick = component::save)
-}
-```
-
-If effect handling grows, extract `ProfileEffects(component, snackbarHostState)` rather than pushing the component into the UI composable.
-
-## Common mistakes
-
-| Mistake | Why it hurts | Fix |
-|---|---|---|
-| `fun Screen(viewModel: MyViewModel)` contains all layout | Hard to preview/test without Android lifecycle and DI | Add a plain UI overload that takes `state` and callbacks |
-| Child composables take `component` | Dependencies leak through the tree | Pass only the state/callbacks that child needs |
-| UI composable launches navigation | UI becomes coupled to app routing | Expose `onBackClick`, `onItemClick`, etc. |
-| UI composable collects app/business flows | Collection lifecycle is hidden in layout | Collect near the state holder and pass values down |
-| UI-local state is hoisted into the state holder for no reason | State holder starts owning layout mechanics | Keep scroll/focus/animation/text-field interaction state in the UI composable when it is only UI behavior |
-| Every tiny composable gets a state-holder overload | Too much ceremony | Split at screen/section boundaries, not every `Row` |
-
-## When NOT to apply
-
-- Tiny one-off composables that already take plain values and callbacks.
-- Design-system primitives such as `Button`, `Card`, or `ListItem`; those should expose slots and modifiers, not state holders.
-- Cases where the state-holder composable would only forward one primitive and add no isolation.
-
-## Related
-
-- [`compose-expert`](../compose-expert/SKILL.md) — Amethyst's shared-UI patterns, including state hoisting for UI element state and plain state holder classes.
-- [`compose-side-effects`](../compose-side-effects/SKILL.md) — effect keys and cleanup in Compose.
-- [`compose-state-deferred-reads`](../compose-state-deferred-reads/SKILL.md) — deferred reads for frame-rate / UI-local values passed across boundaries.
-- [`kotlin-multiplatform`](../kotlin-multiplatform/SKILL.md) — platform services, native views, and expect/interface boundaries when shared UI meets platform-specific leaves.

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

@@ -1,8 +1,3 @@
----
-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.
@@ -74,7 +69,7 @@ fun main() = application {
 - `rememberWindowState()` manages size/position
 - `onCloseRequest` handles window close
 
-**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).
+**See:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt:87-138`
 
 ---
 
@@ -149,7 +144,7 @@ Window(onCloseRequest = ::exitApplication, title = "App") {
 
 ### Keyboard Shortcuts (OS-Aware)
 
-**Current state:** `Main.kt` already branches on `isMacOS` (declared at L120) for every menu shortcut — `if (isMacOS) { KeyShortcut(..., meta = true) } else { KeyShortcut(..., ctrl = true) }` (see L239, L249, L286, L313, L325, L335, L347, L358, L374, L384, L400, L416, L449). When adding a new shortcut, follow the same branching pattern rather than hardcoding `ctrl = true`.
+**Current issue:** Main.kt hardcodes `ctrl = true` (Main.kt:105, 111, 117, 122, 123).
 
 **OS-specific shortcuts:**
 
@@ -280,9 +275,9 @@ Row(Modifier.fillMaxSize()) {
 }
 ```
 
-**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.
+**See:** Main.kt:191-264
 
-**Why a left sidebar?**
+**Why NavigationRail?**
 - Desktop has horizontal space (1200+ dp width)
 - Vertical sidebar is standard desktop pattern
 - Always visible (no tabs hidden)
@@ -290,7 +285,7 @@ Row(Modifier.fillMaxSize()) {
 
 **Android comparison:**
 - Android: `BottomNavigationBar` (horizontal, bottom)
-- Desktop: left vertical sidebar (`MainSidebar`)
+- Desktop: `NavigationRail` (vertical, left)
 
 ### Multi-Pane Layouts
 
@@ -509,10 +504,9 @@ desktopApp/
 ```
 
 **Key files:**
-- `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt` — `fun main()` L172, `application {` L186, `Window` L229, `MenuBar` L234 (OS-aware shortcuts begin at L239)
-- `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/deck/SinglePaneLayout.kt` — NavigationRail at L97
-- `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/deck/` — DeckLayout, WorkspaceManager, DeckState (multi-pane)
-- `desktopApp/build.gradle.kts` — desktop packaging config (DMG/MSI/DEB)
+- `Main.kt:87-138` - `application {}`, `Window`, `MenuBar`
+- `Main.kt:183-264` - NavigationRail pattern
+- `build.gradle.kts:45-73` - Desktop packaging config
 
 ---
 
@@ -656,11 +650,10 @@ fun FeedScreen() {
 - `references/os-detection.md` - Platform detection patterns
 
 ### Codebase Examples
-- `Main.kt` — Window + MenuBar entry point (`application` L186, `Window` L229, `MenuBar` L234)
-- `ui/deck/SinglePaneLayout.kt` — NavigationRail at L97
-- `ui/deck/DeckLayout.kt` / `WorkspaceManager.kt` — multi-pane workspace
-- `ui/feed/` — Desktop feed screens
-- `ui/login/` — Centered desktop login
+- Main.kt:87-138 - Window, MenuBar entry point
+- Main.kt:183-264 - NavigationRail pattern
+- FeedScreen.kt:49-136 - Desktop screen layout
+- LoginScreen.kt:44-97 - Centered desktop login
 
 ---
 
@@ -692,17 +685,13 @@ When working on desktop features:
 
 ❌ **Hardcoding Ctrl everywhere**
 ```kotlin
-// Do NOT do this in a new shortcut:
+// Main.kt:105 - Current issue
 shortcut = KeyShortcut(Key.N, ctrl = true)  // Wrong on macOS
 ```
 
-✅ **OS-aware shortcuts (the pattern `Main.kt` already uses)**
+✅ **OS-aware shortcuts**
 ```kotlin
-shortcut = if (isMacOS) {
-    KeyShortcut(Key.N, meta = true)    // Cmd+N on macOS
-} else {
-    KeyShortcut(Key.N, ctrl = true)    // Ctrl+N on Win/Linux
-}
+shortcut = DesktopShortcuts.primary(Key.N)
 ```
 
 ---
@@ -747,7 +736,7 @@ When implementing desktop features:
 
 1. **Read** `references/desktop-compose-apis.md` for API catalog
 2. **Check** `references/keyboard-shortcuts.md` for standard shortcuts
-3. **Reference** `Main.kt` (entry point L172-L450+) and `ui/deck/SinglePaneLayout.kt` (NavigationRail) for current patterns
+3. **Reference** Main.kt:87-264 for current patterns
 4. **Test** on all 3 platforms (macOS, Windows, Linux) if possible
 5. **Delegate** build issues to gradle-expert
 6. **Share** UI components via compose-expert, not desktop-expert

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

@@ -11,11 +11,11 @@ Comparison of mobile vs desktop navigation patterns in AmethystMultiplatform.
 
 ---
 
-## Desktop: Left Sidebar
+## Desktop: NavigationRail
 
 ### Current Implementation
 
-**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.
+**File:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt:191-264`
 
 ```kotlin
 @Composable
@@ -459,6 +459,6 @@ fun FeedScreen() {
 
 ## References
 
-- **Current Desktop:** `ui/deck/SinglePaneLayout.kt` (NavigationRail L97) and `ui/deck/DeckLayout.kt` (multi-pane)
+- **Current Desktop:** Main.kt:191-264
 - **Material3 NavigationRail:** [Material Design Docs](https://m3.material.io/components/navigation-rail)
 - **Material3 NavigationBar:** [Material Design Docs](https://m3.material.io/components/navigation-bar)

.claude/skills/desktop-expert/references/keyboard-shortcuts.md

@@ -365,9 +365,9 @@ fun testOsDetection() {
 
 ---
 
-## Current Pattern in Amethyst
+## Current Issues in Amethyst
 
-`Main.kt` (MenuBar starting at L234) already branches on `isMacOS` (L120) for every shortcut. When adding a new menu item, follow the same pattern — **do not** hardcode `ctrl = true`:
+**Main.kt:105-123** hardcodes `ctrl = true`:
 
 ```kotlin
 // ❌ WRONG: Hardcoded Ctrl (doesn't work on macOS)
@@ -378,7 +378,7 @@ Item(
 )
 ```
 
-**Current pattern (what Main.kt does):**
+**Fix:**
 
 ```kotlin
 // ✅ CORRECT: OS-aware

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

@@ -1,119 +0,0 @@
----
-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 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
-
-Amethyst's "feed" abstraction is: a `FeedFilter` that decides which notes belong in a list, plus a `FeedViewModel` that exposes the current state reactively to the UI. Every scrollable list — home, profile, hashtag, bookmarks, notifications, DMs — is a variant of this.
-
-## When to Use This Skill
-
-- Adding a new screen that shows a list of notes.
-- Modifying an existing feed's filtering / ordering / inclusion rules.
-- Investigating why a feed doesn't update after a mute/follow/bookmark change.
-- Deciding whether to extend a ViewModel or write a new filter.
-- Understanding the Android ⇄ Desktop sharing boundary for feeds.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ commons/.../viewmodels/  (shared, KMP)                      │
-│   FeedViewModel  ◄── ListChangeFeedViewModel                │
-│                 ◄── ChatroomFeedViewModel                   │
-│                 ◄── MarmotGroupFeedViewModel                │
-│                                                             │
-│                                                             │
-│ 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-only additions)              │
-│   AdditiveComplexFeedFilter<T, U>                           │
-│   FilterByListParams                                        │
-│   DefaultFeedOrder (Note/Event/Card comparators)            │
-│   (FeedFilters.kt & ChangesFlowFilter.kt here are just      │
-│    back-compat typealiases re-exporting commons)            │
-│                                                             │
-│   Concrete feeds: HomeNewThreadFeedFilter,                  │
-│   HashtagFeedFilter, NotificationFeedFilter, … live in      │
-│   feature folders under ui/screen/loggedIn/*/dal/           │
-└─────────────────────────────────────────────────────────────┘
-              ▲
-              │ reads
-              │
-┌─────────────────────────────────────────────────────────────┐
-│ model/LocalCache.kt + account.<feature>.flow                │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Key Files
-
-### Shared (commons)
-
-`commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/viewmodels/`:
-
-- **`FeedViewModel.kt`** — `abstract class FeedViewModel(localFilter, cacheProvider)`. Holds a `FeedContentState`, subscribes to invalidation signals (from `Account` flows and `LocalCacheFlow`), re-runs the filter, and emits a new `FeedState` for the UI.
-- **`ListChangeFeedViewModel.kt`** — specialization for feeds whose membership changes frequently (e.g. bookmarks).
-- **`ChatroomFeedViewModel.kt`** — DM thread feed.
-- **`MarmotGroupFeedViewModel.kt`** — NIP-29 / marmot group feed.
-- **`LiveStreamTopZappersViewModel.kt`, `SearchBarState.kt`, `ChatNewMessageState.kt`** — narrower, non-feed states that share the plumbing.
-
-### 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/`:
-
-- **`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 `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 `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 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) } }`.
-5. **Subscribe to relays.** Most feeds also need a `Subscribable` to fetch historical events. See the `relay-client` skill.
-
-## Filter Sharing (Android vs Desktop)
-
-- 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
-
-- **Never scan `LocalCache` from a composable.** Always go through a `FeedFilter` + `FeedViewModel`, which does it on a background dispatcher and debounces invalidation.
-- **`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 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
-
-- `references/feed-filter-composition.md` — step-by-step for adding a feed.
-- `references/viewmodel-base-classes.md` — inheritance graph for the `FeedViewModel` family.
-- Complements: `account-state` (where the data lives), `relay-client` (how to subscribe), `compose-expert` (how to render).

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

@@ -1,129 +0,0 @@
-# Adding a New Feed
-
-Step-by-step recipe for composing a new feed. Assume the feed shows `Note`s filtered by some criterion and should update reactively when the underlying state changes.
-
-## 1. Choose a Filter Base
-
-| 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 | `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) |
-
-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
-
-```kotlin
-class HashtagFeedFilter(
-    private val accountViewModel: AccountViewModel,
-    private val hashtag: String,
-) : AdditiveFeedFilter<Note>() {
-
-    override fun feedKey(): String = "Hashtag-$hashtag"
-
-    override fun showHiddenKey(): Boolean = false
-
-    override fun feed(): List<Note> {
-        val params = FilterByListParams.create(
-            excludeMuted = true,
-            hiddenUsers  = account.hiddenUsers.flow.value,
-        )
-        return LocalCache.hashtagIndex[hashtag]
-            .orEmpty()
-            .filter { params.match(it) }
-            .sortedWith(DefaultFeedOrder)
-            .take(limit())
-    }
-
-    override fun applyFilter(collection: Set<Note>): Set<Note> =
-        collection.filter { it.event?.isTaggedHash(hashtag) == true }.toSet()
-
-    override fun sort(collection: Set<Note>): List<Note> =
-        collection.sortedWith(DefaultFeedOrder)
-
-    override fun limit(): Int = 1000
-}
-```
-
-Key points:
-
-- `feedKey()` must uniquely identify this filter *instance*. The parameter (hashtag in this case) is part of the key so two hashtag feeds don't share state.
-- `feed()` is the full recompute — synchronous, runs on a background dispatcher.
-- `applyFilter()` is the per-event membership check used by the additive path.
-- Always use `FilterByListParams` rather than re-implementing mute / hidden-user logic.
-- `DefaultFeedOrder` is the canonical sort; deviating breaks paging assumptions.
-
-## 3. Pick a ViewModel
-
-If an existing ViewModel already matches the flow pattern, reuse it with your new filter:
-
-```kotlin
-class HashtagFeedViewModel(
-    val hashtag: String,
-    accountViewModel: AccountViewModel,
-) : FeedViewModel(
-    localFilter = HashtagFeedFilter(accountViewModel, hashtag),
-    cacheProvider = LocalCache,
-)
-```
-
-If membership changes aggressively (e.g. the user toggles a mute), use `ListChangeFeedViewModel` instead and hook into `account.muteList.flow`.
-
-## 4. Wire Invalidation
-
-`FeedViewModel` already re-queries on `LocalCacheFlow` ticks. For changes that come from `Account` state (mutes, follows, bookmarks, relay list updates) add them in the ViewModel:
-
-```kotlin
-init {
-    viewModelScope.launch {
-        account.muteList.flow.collect { invalidateAll() }
-    }
-}
-```
-
-`invalidateAll()` triggers a full `feed()` re-run; `invalidateInsertData(addedNotes)` is the additive path.
-
-## 5. Subscribe to Relays
-
-Unless the feed only shows already-cached data, write a `Subscribable` that fetches history. See `relay-client` skill. Typically:
-
-```kotlin
-val subscribable = rememberSubscribable(hashtag) {
-    HashtagFilterAssembler(hashtag).toSubscribable()
-}
-DisposableEffect(hashtag) {
-    subscribable.subscribe()
-    onDispose { subscribable.unsubscribe() }
-}
-```
-
-## 6. Render
-
-```kotlin
-val feedState by viewModel.feedState.feedContent.collectAsStateWithLifecycle()
-
-LazyColumn {
-    items(
-        items = feedState.feed.value,
-        key = { it.idHex },
-    ) { note ->
-        NoteCompose(note)
-    }
-}
-```
-
-Use `key = { it.idHex }` so Compose can diff efficiently across additive updates.
-
-## 7. Test
-
-Unit-test the filter in isolation: feed it a known `LocalCache` snapshot and assert the output order. Filters are side-effect-free once `LocalCache` is fixed, so they're straightforward to pin.
-
-## Common Mistakes
-
-- **Inline filtering in composables.** If you call `LocalCache.notes.filter { … }` in a composable, the filter recomputes every recomposition and never invalidates correctly. Always go through a `FeedFilter`.
-- **Forgetting `showHiddenKey()`.** If you want a "show hidden" toggle, override it; otherwise hidden content is silently dropped.
-- **Non-stable `feedKey()`.** Using a hash that depends on current time or mutable state causes the ViewModel to lose its cached state on every invalidation.
-- **Skipping `FilterByListParams`.** Muted users, reported users, spam filter — all of it lives there. Reimplementing is a source of bugs.

.claude/skills/feed-patterns/references/viewmodel-base-classes.md

@@ -1,90 +0,0 @@
-# ViewModel Base Classes
-
-Inheritance tree for the shared feed ViewModels in `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/viewmodels/`.
-
-## Tree
-
-```
-androidx.lifecycle.ViewModel
-    │
-    ▼
-InvalidatableContent  (interface)
-    │
-    ▼
-FeedViewModel(localFilter: FeedFilter<Note>, cacheProvider: ICacheProvider)
-    │
-    ├── ListChangeFeedViewModel   (list membership changes often)
-    │       │
-    │       └── (concrete bookmark / list feeds)
-    │
-    ├── ChatroomFeedViewModel     (DM thread)
-    │
-    └── MarmotGroupFeedViewModel  (NIP-29 group chat)
-```
-
-Tangentially related (same folder, not in the tree):
-- `LiveStreamTopZappersViewModel.kt` — sidebar state for live streams.
-- `SearchBarState.kt` — search input + suggestions.
-- `ChatNewMessageState.kt` — composer state for a new DM.
-- `thread/*` — thread ViewModels (not technically feeds but share wiring).
-
-## `FeedViewModel`
-
-```kotlin
-abstract class FeedViewModel(
-    localFilter: FeedFilter<Note>,
-    val cacheProvider: ICacheProvider,
-) : ViewModel(), InvalidatableContent {
-
-    val feedState = FeedContentState(localFilter, viewModelScope, cacheProvider)
-
-    fun invalidateAll()                      // full recompute
-    fun invalidateInsertData(newNotes: Set<Note>)   // additive path
-    fun invalidateReplace(replaced: Set<Note>)      // replaceable/addressable update
-}
-```
-
-`FeedContentState` is the thing the UI collects:
-
-- `feedContent: StateFlow<FeedState>` — the actual list, loading flag, paging state.
-- Runs the `localFilter.feed()` on a background dispatcher.
-- Debounces consecutive invalidations so bursts of relay frames don't thrash the filter.
-
-## `ListChangeFeedViewModel`
-
-Extends `FeedViewModel`. Override point:
-
-```kotlin
-abstract class ListChangeFeedViewModel(...) : FeedViewModel(...) {
-    // Automatically re-invalidates on Account list-flow changes
-    abstract fun dependencyList(): List<Flow<*>>
-}
-```
-
-Used for bookmarks, mutes, and custom `NIP-51` lists — anything whose membership is decided by an `Account` StateFlow.
-
-## `ChatroomFeedViewModel`
-
-Wraps filter + relay subscription + typing-indicator state for a single DM thread. Use directly for chat screens; don't reimplement per-thread.
-
-## `MarmotGroupFeedViewModel`
-
-NIP-29 (marmot variant) group feed. Adds group membership / moderator state on top of the base feed.
-
-## When to Extend vs Reuse
-
-- **Just a new filter** → instantiate `FeedViewModel` with your filter; no new class needed.
-- **New invalidation signal** → subclass and override `init` to add collectors.
-- **Entirely new paging model** (infinite scroll, server-assisted paging) → subclass with a custom `FeedContentState`.
-- **Non-feed state** (search, composer) → don't use `FeedViewModel` at all; see `SearchBarState.kt` / `ChatNewMessageState.kt` for narrow-state patterns.
-
-## Platform Wrapping
-
-On Android, feed ViewModels are created via `viewModel { HashtagFeedViewModel(...) }` in the composable. On Desktop, they're instantiated directly and stored in a `WorkspaceManager` column (see `desktopApp/.../ui/deck/WorkspaceManager.kt`). The ViewModel class itself is KMP-friendly.
-
-## Gotchas
-
-- **Multiple subscribers to `feedContent`** are fine — it's a `StateFlow`.
-- **ViewModels survive configuration changes on Android** but not on Desktop `key {}` rebuilds — re-instantiate in Desktop's workspace lifecycle.
-- **`cacheProvider` is almost always `LocalCache`** but the parameter exists so tests can inject a fixture.
-- **Don't call `invalidateAll()` from UI** — it's triggered by the ViewModel's own collectors. Calling it from the composable just causes extra filter runs.

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

@@ -7,9 +7,7 @@ description: Use when comparing Android strings.xml locale files to find untrans
 
 ## Overview
 
-Extract string resource keys from a default `values/strings.xml` that are absent in a target locale's `strings.xml`, excluding non-translatable entries. Outputs missing keys and offers to translate them.
-
-The repo now has **two independent Crowdin-managed resource trees** — you must scan **both** (see "Resource trees" below).
+Extract string resource keys from the default `values/strings.xml` that are absent in a target locale's `strings.xml`, excluding non-translatable entries. Outputs missing keys and offers to translate them.
 
 ## When to Use
 
@@ -17,296 +15,59 @@ The repo now has **two independent Crowdin-managed resource trees** — you must
 - Preparing a batch of strings for a translator
 - Checking translation coverage after adding new features
 
-## Resource trees (scan BOTH)
-
-There are two separate `strings.xml` trees, each with its own default `values/` and per-locale `values-<locale>/` files, each wired into `crowdin.yml` independently:
-
-| Tree | Default file | Per-locale file |
-|------|--------------|-----------------|
-| **amethyst** (Android app) | `amethyst/src/main/res/values/strings.xml` | `amethyst/src/main/res/values-<locale>/strings.xml` |
-| **commons** (KMP Compose resources, shared by Android + Desktop) | `commons/src/commonMain/composeResources/values/strings.xml` | `commons/src/commonMain/composeResources/values-<locale>/strings.xml` |
-
-The `commons` tree appeared when shared event-renderer composables were extracted out of `amethyst/` into `commons/` (Compose Multiplatform `stringResource`). It is **not** a copy of the amethyst tree — the vast majority of its keys are commons-only; only a small handful overlap. Every diff/count/translate command below works on either tree by swapping the base path — **run the whole technique once per tree** and report them separately (each maps to its own Crowdin file, so the counts should reconcile against two different Crowdin UI numbers).
-
-**Locale-qualifier caveat:** `commons` uses the same region-qualified locale dirs as amethyst for our four targets (`values-cs`, `values-de-rDE`, `values-sv-rSE`, `values-pt-rBR`), but the *full* set of locale dirs differs between trees. Enumerate `values-*` under each tree's own base rather than assuming they match.
-
-**Overlap (copy — but only after checking the English matches):** a few `commons` keys share a *name* with a key in the amethyst tree. For such a key already translated in the amethyst locale file you may **copy the existing approved translation verbatim** — but **only if the two English source values are byte-identical.** A shared key name does **not** guarantee a shared meaning.
-
-> ⚠️ **Mistake we actually made (2026-07-18):** `napplet_card_permissions` exists in *both* trees with the *same key name* but *different English* — commons = `"What it can access"`, amethyst = `"Permissions:"`. Copying the amethyst translation by key name produced the wrong string in commons (it said "Permissions:" where the UI reads "What it can access"). **Always diff the English values, not just the key names.** When the English differs, translate the commons value fresh — or, better, find the amethyst key whose *value* matches (here `favorite_app_access_show` = "What it can access") and copy *that* approved translation.
-
-Detect name-overlap **and flag value mismatches** in one pass:
-
-```bash
-cdef=commons/src/commonMain/composeResources/values/strings.xml
-adef=amethyst/src/main/res/values/strings.xml
-comm -12 \
-  <(grep '<string name=' "$cdef" | sed 's/.*name="\([^"]*\)".*/\1/' | sort -u) \
-  <(grep '<string name=' "$adef" | grep -v 'translatable="false"' | sed 's/.*name="\([^"]*\)".*/\1/' | sort -u) \
-| while read -r k; do
-    cv=$(grep -m1 "name=\"$k\"" "$cdef" | sed 's/.*>\(.*\)<\/string>/\1/')
-    av=$(grep -m1 "name=\"$k\"" "$adef" | sed 's/.*>\(.*\)<\/string>/\1/')
-    [ "$cv" = "$av" ] && echo "SAFE-COPY   $k" || echo "VALUE-DIFFERS $k  commons=\"$cv\"  amethyst=\"$av\""
-  done
-```
-
-Only `SAFE-COPY` keys may be copied verbatim. For `VALUE-DIFFERS`, translate the commons English fresh (or copy from the amethyst key that has the *matching value*).
-
-**Whitespace-quote convention differs between trees.** Android string resources use surrounding double-quotes to preserve leading/trailing whitespace (`"replying to "`). The **commons Compose-resources tree does NOT use this convention** — it authors trailing/leading spaces raw and unquoted (`replying to `). So when copying/translating a commons string with edge whitespace, **match the commons source: raw spaces, no wrapping quotes.** (Mistake we made: we copied amethyst's quoted `"replying to "` into commons, where the quotes would render literally.) A quick check for stray quote-wrapping you introduced:
-
-```bash
-grep -nE '<string name="[^"]*">"' commons/src/commonMain/composeResources/values-*/strings.xml
-# The commons English tree has zero quote-wrapped values — any hit in a locale file is almost certainly a bad copy from amethyst.
-```
-
-**Why two catalogs exist — the duplication is NOT a bug to "fix" (don't ask again).** You will see the same English text (`Cancel`, `Save`, `Delete`, `Open`, …) defined *many* times across the amethyst tree under per-feature keys **and** once more in commons under generic keys (`action_cancel`, `action_save`, …). This is **required architecture, not an error:**
-
-- The two trees are **different resource systems**: amethyst uses Android `R.string`; commons uses Compose-Multiplatform `Res.string` (`com.vitorpamplona.amethyst.commons.resources.Res`).
-- **`commons` cannot depend on `amethyst`** (amethyst depends on commons — the reverse would be circular). So a composable extracted *into* commons physically cannot reference `R.string.cancel`; it needs its own string, hence the generic `action_*` keys. That is the only way an extracted shared composable can render "Cancel."
-- The scattered amethyst per-feature duplicates (`nip46_signer_cancel`, `nest_create_cancel`, …) are **pre-existing tech debt**; the commons keys did not create them.
-- Both catalogs are Crowdin-managed **independently**, and Crowdin's translation memory pre-fills repeats, so translating the same word in both trees is **not** wasted effort.
-
-**Do not** treat the value-overlap as something to deduplicate during a translation pass. Migrating amethyst's own screens onto the shared `action_*` strings is a *separate, optional* refactor and a maintainer call — out of scope for this skill. Just translate each tree correctly and independently.
-
-## Background: Crowdin strip-identical behavior
-
-This repo syncs translations via Crowdin (branch `l10n_crowdin_translations`). Crowdin's default export behavior **omits any translation that exactly equals the source**, so a key that the translator deliberately kept as English (common for brand terms like `"Nowhere Drop"`, single-word loanwords like `"Apps"` / `"Feed"` / `"Issues"`, or version prefixes like `"v%1$s"`) will not appear in the locale's `strings.xml` even though the Crowdin UI shows it as 100% translated.
-
-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):
 
 | Locale | Language | Directory |
 |--------|----------|-----------|
-| `cs` | Czech | `values-cs` |
+| `cs-rCZ` | Czech | `values-cs-rCZ` |
 | `pt-rBR` | Brazilian Portuguese | `values-pt-rBR` |
 | `sv-rSE` | Swedish | `values-sv-rSE` |
 | `de-rDE` | German | `values-de-rDE` |
 
-> Czech was consolidated onto the base qualifier (PR #3461, 2026-07-03): a
-> `cs: cs` `languages_mapping` entry in `crowdin.yml` makes Crowdin export to
-> `values-cs`, and `values-cs-rCZ` no longer exists. The other locales still
-> use Crowdin's default region-qualified `androidCode` until they are
-> consolidated the same way — update this table as each one moves.
-
 ## Technique
 
 ### 1. Identify files
 
-Do this for **each** resource tree (see "Resource trees" above). The examples below use the amethyst base path; repeat every step with the commons base path swapped in.
-
 ```
-# amethyst tree
 Default:  amethyst/src/main/res/values/strings.xml
 Target:   amethyst/src/main/res/values-<locale>/strings.xml
-
-# commons tree
-Default:  commons/src/commonMain/composeResources/values/strings.xml
-Target:   commons/src/commonMain/composeResources/values-<locale>/strings.xml
 ```
 
-A convenient way to run the whole technique twice is to loop over the two base dirs:
+### 2. Find missing keys using cs-rCZ as reference
+
+Always diff against `cs-rCZ` first — it is the most complete locale and serves as the reference. Any keys missing in `cs-rCZ` will also be missing in the other target locales.
 
 ```bash
-for base in amethyst/src/main/res commons/src/commonMain/composeResources; do
-  echo "########## tree: $base ##########"
-  # ... run the diff/count/value-extraction commands with $base/values[...] ...
-done
-```
-
-### 2. Find missing keys using cs as reference
-
-Always diff against `cs` first — it is the most complete locale and serves as the reference. Any keys missing in `cs` will also be missing in the other target locales.
-
-You MUST diff **both** `<string name=` AND `<plurals name=` — these are independent resource types and a key that is a `<plurals>` in the source will never appear in a `<string>` diff. Forgetting `<plurals>` is the most common silent failure of this skill (it misses things like `music_playlist_track_count`, `notification_count_more`, etc.).
-
-```bash
-# Strings: extract translatable keys from default (exclude translatable="false")
-echo "=== missing <string> ==="
+# Extract translatable keys from default (exclude translatable="false")
 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/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/strings.xml \
+  <(grep '<string name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort)
 ```
 
-This gives two lists of missing key names — keep them separate; `<plurals>` translations need the per-locale CLDR category set (see Step 5 → "Plurals: handle with care").
-
-Crowdin can asymmetrically strip keys across locales (each translator independently chose source-identical for different keys), so **cs is not a reliable upper bound**. Diff **every** target locale and union the results — don't assume the cs set covers the others. A quick per-locale count is a useful sanity check against the Crowdin UI's "N untranslated":
-
-```bash
-for locale in cs 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).
+This gives the list of missing key names. Do NOT diff each locale separately — assume the same keys are missing in all target locales.
 
 ### 3. Get English values for missing keys
 
-For each missing key, extract its English value. `<string>` is a single line; `<plurals>` is a multi-line block — handle each appropriately.
+For each missing key, extract its English value:
 
 ```bash
-# Missing <string>: full line from default strings.xml
+# For each missing key, extract the 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 \
   <(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/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/strings.xml \
+  <(grep '<string name=' amethyst/src/main/res/values-cs-rCZ/strings.xml \
     | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
 ```
 
-### 4. Audit missing strings for plural-shaped patterns
-
-Before presenting results, **scan the missing English strings** for two red-flag patterns and warn the user about each match:
-
-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 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`)**, **Latvian (`lv`)** and **Welsh (`cy`)**. ICU/CLDR maps `count=0` to `other` for English and most of 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"`.
-
-> ⚠️ **Latvian is the trap here — do NOT strip its `zero` items** (we nearly did, 2026-07-22). `lv` has an integer-bearing `zero` category that covers far more than 0: `select(0)`, `select(10)` and `select(11)` all return `zero` (the rule is `n % 10 = 0` or `n % 100 = 11..19`). So a Latvian `<item quantity="zero">` is *live code on the majority of counts*, and it must read as a normal plural form ("%1$d minūšu"), **not** as "no items" wording. An earlier version of this skill claimed only `ar` and `cy` had `zero`, which flagged all ~40 correct Latvian entries as dead and would have deleted working translations.
-
-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. (This is why `zero` is the wrong tool even where it exists: in `lv` it does not mean "zero".)
-
-**Verify, don't recall.** Before asserting any locale's category set, check it against CLDR rather than memory:
-
-```bash
-python3 -m venv /tmp/cldr && /tmp/cldr/bin/pip -q install babel
-/tmp/cldr/bin/python -c "
-from babel import Locale
-for c in ['en','lv','ar','cy','cs','de','sv','pt_BR','ru','pl']:
-    r = Locale.parse(c).plural_form
-    print(c, sorted({r(n) for n in range(0,10001)}), 'select(0)=', r(0), 'select(10)=', r(10))
-"
-```
-
-Across the 56 locale dirs this repo ships, **only `ar-rSA` and `lv-rLV`** have an integer-bearing `zero`.
-
-Flag and offer to fix:
-
-```bash
-# Scan every locale's strings.xml for <item quantity="one"> entries that
-# hardcode "1" (or other literal digits) instead of using a placeholder.
-# Looks at default + all values-* locales, in BOTH resource trees.
-for f in amethyst/src/main/res/values/strings.xml amethyst/src/main/res/values-*/strings.xml \
-         commons/src/commonMain/composeResources/values/strings.xml \
-         commons/src/commonMain/composeResources/values-*/strings.xml; do
-  awk -v file="$f" '
-    /<plurals/ { in_plurals = 1; name = $0; sub(/.*name="/, "", name); sub(/".*/, "", name) }
-    in_plurals && /quantity="one"/ {
-      # Extract item text (between > and <)
-      text = $0; sub(/^[^>]*>/, "", text); sub(/<.*$/, "", text)
-      # Flag if it contains a digit AND no %d / %1$d placeholder
-      if (text ~ /[0-9]/ && text !~ /%[0-9]*\$?d/) {
-        print file ":  <plurals name=\"" name "\">  one=\"" text "\""
-      }
-    }
-    /<\/plurals>/ { in_plurals = 0 }
-  ' "$f"
-done
-```
-
-Then scan for dead `quantity="zero"` entries. CLDR's `zero` category is integer-bearing only in **Arabic (`ar`)**, **Latvian (`lv`)** and **Welsh (`cy`)** — those three are skipped below, so a hit is a genuine bug. 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 \
-         commons/src/commonMain/composeResources/values/strings.xml \
-         commons/src/commonMain/composeResources/values-*/strings.xml; do
-  # Skip Arabic, Latvian and Welsh — they natively use the zero category.
-  # (Latvian's zero covers 0, 10, 11-19, 20, 30, … — stripping it breaks most counts.)
-  case "$f" in
-    *values-ar*|*values-cy*|*values-lv*) 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
-# Flag missing English values that look like they should be <plurals>
-while IFS= read -r key; do
-  line=$(grep "name=\"$key\"" amethyst/src/main/res/values/strings.xml)
-  # Hardcoded standalone "1" (word-boundary), or a count placeholder followed by a likely-countable noun
-  if echo "$line" | grep -qE '>([^<]*\b1\b[^<]*|[^<]*%[0-9]*\$?d[^<]*)<'; then
-    echo "PLURAL CANDIDATE: $line"
-  fi
-done < <(comm -23 \
-  <(grep '<string name=' amethyst/src/main/res/values/strings.xml \
-    | grep -v 'translatable="false"' \
-    | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-  <(grep '<string name=' amethyst/src/main/res/values-cs/strings.xml \
-    | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
-```
-
-The regex is intentionally noisy — review each hit by hand. Many `%d` strings (e.g. `"Limits for kind %1$d"`, `"Max event size (bytes)"`) are *not* plural-bearing. Only flag the ones whose surrounding noun changes form with the count.
-
-For each genuine match, **stop and warn the user before translating**, e.g.:
-
-> ⚠️ `notification_count` is `"1 new reply"` — this hardcodes `"1"` and should likely be a `<plurals>` resource (e.g. `quantity="one"` → `"%d new reply"`, `quantity="other"` → `"%d new replies"`). Convert before translating?
-
-Do not silently translate plural-shaped `<string>` entries; the wrong shape will then need to be fixed in every locale.
-
-### 5. Present results and ask to translate
+### 4. Present results and ask to translate
 
 Output the missing entries as raw XML resource lines (copy-paste ready):
 
@@ -318,82 +79,18 @@ Output the missing entries as raw XML resource lines (copy-paste ready):
 
 Also check `<string-array>` and `<plurals>` tags using the same approach if the project uses them.
 
-#### Plurals: handle with care
-
-When adding or proposing **`<plurals>`** entries, follow these rules:
-
-- **Never hardcode `"1"`** in the English text of a `quantity="one"` item. Use the format placeholder (e.g. `%1$d` / `%d`) so the runtime substitutes the actual count. Hardcoding `"1"` breaks every language whose `one` category covers numbers other than 1 (e.g. some Slavic languages).
-- **Don't assume `one` + `other` is enough.** CLDR plural categories vary by language: `zero`, `one`, `two`, `few`, `many`, `other`. Always include **every category the target language uses**, not just the categories present in English. Examples:
-  - English (`en`): `one`, `other`
-  - Czech (`cs`): `one`, `few`, `many`, `other`
-  - Polish (`pl`): `one`, `few`, `many`, `other`
-  - Russian (`ru`): `one`, `few`, `many`, `other`
-  - Arabic (`ar`): `zero`, `one`, `two`, `few`, `many`, `other`
-  - Latvian (`lv`): `zero`, `one`, `other` — its `zero` is **not** "no items"; it covers 0, 10, 11–19, 20, 30, …
-  - 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`), Latvian (`lv`) and Welsh (`cy`).** CLDR's `zero` category is integer-bearing only in those three 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. Conversely, **never delete an existing `zero` item from `ar`/`lv`/`cy`** — there it is live. 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]?"
 
-### 6. Adding translations (if approved)
+### 5. Adding translations (if approved)
 
 When adding translated strings to locale files:
 
 - **Append new strings at the bottom** of the file, just before the closing `</resources>` tag.
 - Do NOT try to insert them in alphabetical or matching order — a separate process handles ordering.
-- **Insert into each locale ONLY the keys missing from *that* locale — never a shared "union" block.** Because Crowdin strips keys asymmetrically (Step 2), a key you translate may already exist in some target locales. If you compute one union set of missing keys, translate it, and paste the *same* block into every locale, you will create **duplicate keys** in whichever locales already had them. Drive the insertion off the **per-locale** diff, not the union:
-
-  ```bash
-  # For each locale, insert only the keys comm -23 reports missing FOR THAT LOCALE.
-  for l in cs de-rDE sv-rSE pt-rBR; do
-    missing=$(comm -23 \
-      <(grep '<string name=' $base/values/strings.xml | grep -v 'translatable="false"' \
-        | sed 's/.*name="\([^"]*\)".*/\1/' | sort) \
-      <(grep '<string name=' $base/values-$l/strings.xml \
-        | sed 's/.*name="\([^"]*\)".*/\1/' | sort))
-    # ... append ONLY the $missing keys' translations to values-$l/strings.xml ...
-  done
-  ```
-
-  (This bit us on 2026-07-21: `ps1_save_block`, `podcast_value_for_value`, and `chats_history_relays` were each missing in only *some* commons locales, but the same 3-key block was pasted into all four — producing duplicates in the locales that already had them.)
-
-- **After inserting, verify each edited file has no duplicate keys AND is well-formed XML — before you call the task done.** A duplicate key is not a warning: the `commons` tree's Compose-resources build task fails hard on it (`convertXmlValueResourcesForCommonMain: … Duplicated key '…'`), which breaks the build for everyone. Quick post-insertion gate over every file you touched:
-
-  ```bash
-  for f in <every edited strings.xml>; do
-    dups=$(grep -oE '<(string|plurals) name="[^"]*"' "$f" \
-      | sed 's/.*name="\([^"]*\)"/\1/' | sort | uniq -d)
-    [ -n "$dups" ] && echo "DUP in $f: $dups"
-    python3 -c "import xml.dom.minidom; xml.dom.minidom.parse('$f')" \
-      || echo "MALFORMED $f"
-  done
-  # For a commons change, also run the build task that enforces this:
-  #   ./gradlew :commons:convertXmlValueResourcesForCommonMain
-  ```
 
 ## Common Mistakes
 
-- **Scanning only the amethyst tree** — there are now **two** Crowdin-managed `strings.xml` trees (`amethyst/src/main/res` and `commons/src/commonMain/composeResources`). A key extracted into `commons/` will never show up in the amethyst diff. Run the whole technique once per tree (see "Resource trees") and report each separately.
-- **Copying an overlapping `commons` translation by key name alone** — a shared key name does NOT mean shared English. `napplet_card_permissions` is "What it can access" in commons but "Permissions:" in amethyst; copying by name produced the wrong string. Diff the English *values* first; copy verbatim only when they're byte-identical, else translate fresh (see "Overlap" in Resource trees).
-- **Applying amethyst's `"…"` whitespace-quote convention to a commons string** — the commons Compose-resources tree authors edge whitespace raw and unquoted; wrapping quotes copied from amethyst render literally there. Match the commons source format.
-- **Trying to "dedupe" the amethyst↔commons value-overlap** — it's required architecture (commons can't depend on amethyst, so shared composables need their own `Res.string` catalog), not an error. Don't fold consolidation into a translation pass.
 - **Forgetting `translatable="false"`** — these should never appear in locale files
-- **Diffing only `<string name=`** — `<plurals>` is a separate resource type; a source `<plurals>` missing from a locale will never show up in a `<string>` diff. Always run the diff twice (once per resource type) as shown in Step 2. The same goes for `<string-array>` if the project uses it.
-- **Trusting a git "sync-timestamp" heuristic to pre-filter the list** — this skill used to skip keys added before the last `New Crowdin translations` commit, on the theory that Crowdin had already "decided" them. It was dropped: a key added shortly before an export that translators hadn't reached yet is genuinely missing, so the heuristic silently dropped real work. Use the raw on-disk diff and reconcile against the Crowdin web UI's untranslated count instead.
-- **Adding source-identical fallbacks locally** — they get overwritten on the next Crowdin sync. Android falls back to `values/strings.xml` at runtime anyway, so a key intentionally kept as English already renders correctly. Skip these by inspection (brand terms, loanwords, `v%1$s`-style strings); don't translate them to an identical value.
-- **Skipping per-locale diffs when only diffing cs** — Crowdin can strip different keys in different locales (each translator's choice), so cs is not a reliable upper bound. Diff each target locale and union the results.
-- **Pasting the union set of missing keys into every locale → duplicate keys** — the union is the right set to *translate*, but the wrong set to *insert*. A key missing in only some locales, inserted into all of them, duplicates in the ones that already had it. Drive each file's insertion off its own per-locale diff (see Step 6). In `commons`, a duplicate key is build-breaking: `convertXmlValueResourcesForCommonMain` fails with `Duplicated key '…'`. **Always run the post-insertion duplicate + XML-wellformedness gate in Step 6 before declaring done.** (Happened 2026-07-21 with `ps1_save_block` / `podcast_value_for_value` / `chats_history_relays`.)
-- **Inserting strings in a specific position** — always append at the bottom; ordering is handled separately
-- **Hardcoding `"1"` in a `<plurals>` `quantity="one"` item** — always use the count placeholder; otherwise non-English `one` categories produce wrong text
-- **Copying English's `one`/`other` set into every locale** — each language must include all CLDR plural categories it uses (e.g. Czech needs `one`, `few`, `many`, `other`)
-- **Using `<item quantity="zero">` to special-case count=0** — outside Arabic, Latvian 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.
-- **Reporting Latvian `quantity="zero"` entries as dead code** — `lv` has a real, integer-bearing `zero` category covering 0, 10, 11–19, 20, 30, … so those entries fire on *most* counts. An earlier version of this skill excluded only `ar`/`cy` from the zero audit and flagged all ~40 correct `values-lv-rLV` entries; acting on that would have deleted working translations. Confirm any locale's category set against CLDR (the babel snippet in Step 4) before calling a `zero` item dead.
+- **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
+- **Inserting strings in a specific position** — always append at the bottom; ordering is handled separately

.claude/skills/find-non-lambda-logs/SKILL.md

@@ -1,125 +0,0 @@
----
-name: find-non-lambda-logs
-description: Use when auditing or migrating Log calls — flags both interpolated Log.d/i/w/e that should use the lambda overload (allocation hygiene) and catch-block Log.w/e that interpolate ${e.message} but drop the throwable (lost stack traces)
----
-
-# Find Non-Lambda Log Calls
-
-## Overview
-
-Two related logging hygiene issues:
-
-1. **Lambda overload missing.** `Log.d/i/w/e` calls that use string interpolation without the lambda overload waste string allocation when the log level is filtered out in release builds.
-2. **Throwable dropped in catch blocks.** `Log.w/e` calls inside `catch (e: ...)` blocks that interpolate `${e.message}` but don't pass `e` lose the stack trace, and log nothing useful when `e.message` is null (NPE, IOException with no message, etc.).
-
-## When to Use
-
-- After merging branches that add new logging
-- Periodic audit of logging hygiene
-- After migrating `android.util.Log` usages to the shared `Log` wrapper
-
-## What to Flag
-
-Calls with **string interpolation** (`$` in message) that do **not** pass a throwable:
-
-```kotlin
-// FLAG - interpolation without lambda, no throwable
-Log.d("Tag", "Processing ${event.id}")
-Log.w("Tag", "Failed for $url")
-
-// IGNORE - passes throwable (lambda overload doesn't accept throwable)
-Log.w("Tag", "Error: ${e.message}", e)
-Log.e("Tag", "Failed for $url", throwable)
-
-// IGNORE - no interpolation (no allocation benefit from lambda)
-Log.d("Tag", "Initialization complete")
-```
-
-## Search Commands
-
-**Important:** Tags can be string literals (`"Tag"`) or variables (`tag`, `LOG_TAG`). Run both patterns for each step.
-
-### Step 1: Find interpolated Log.d/Log.i (highest priority — filtered in release)
-
-```
-pattern: Log\.(d|i)\("[^"]+",\s*"[^"]*\$
-type: kotlin
-```
-```
-pattern: Log\.(d|i)\(\w+,\s*"[^"]*\$
-type: kotlin
-```
-
-### Step 2: Find interpolated Log.w/Log.e without throwable
-
-```
-pattern: Log\.(w|e)\("[^"]+",\s*"[^"]*\$
-type: kotlin
-```
-```
-pattern: Log\.(w|e)\(\w+,\s*"[^"]*\$
-type: kotlin
-```
-
-Then **manually exclude** lines where a throwable is passed as third argument (ending with `, e)`, `, throwable)`, etc.). Check the actual line — a catch block catching `e` doesn't mean `e` is passed to the Log call.
-
-### Step 3: Find catch-block Log.w/e that drop the throwable
-
-Among the Step 2 hits, the calls that interpolate `${e.message}` (or `${t.message}`, `${throwable.message}`) but do not pass the exception itself are a separate bug — they lose the stack trace AND log a useless empty-ish line whenever the exception's message is null.
-
-Quick filter:
-
-```
-pattern: Log\.(w|e)\([^)]*\$\{(e|t|throwable|cause)\.message\}[^)]*\)$
-type: kotlin
-```
-
-Then for each hit, open the file and confirm the line is **inside a `catch (e: ...)` block** and **does not pass `e` (or the matching name) as a third argument**. False positives: extension functions / helpers that accept an `e: SomeError` parameter and forward it elsewhere.
-
-Both Step 2 and Step 3 may flag the same line — handle Step 3 first (different fix), then apply Step 2 to whatever remains.
-
-### Step 4: Verify no android.util.Log leakage
-
-```
-pattern: android\.util\.Log\.(d|i|w|e|v)\(
-type: kotlin
-```
-
-These bypass the `Log.minLevel` filter entirely. Exclude `PlatformLog.android.kt` which is the wrapper implementation.
-
-## Fix Patterns
-
-### Lambda overload (Step 1 + Step 2)
-
-```kotlin
-// Before
-Log.d("Tag", "Processing event ${event.id} from ${relay.url}")
-
-// After
-Log.d("Tag") { "Processing event ${event.id} from ${relay.url}" }
-```
-
-### Throwable overload (Step 3)
-
-Switch to `(tag, msg, throwable)` — the lambda overload does **not** accept a throwable, so this case must use the eager-string form. Drop the redundant `${e.message}` from the message text since the throwable already carries it.
-
-```kotlin
-// Before — stack trace lost, prints "...failed: null" if e.message is null
-try { groupManager.clearAllState() } catch (e: Exception) {
-    Log.w("MarmotManager") { "clearAllState failed: ${e.message}" }
-}
-
-// After — full stack trace logged
-try { groupManager.clearAllState() } catch (e: Exception) {
-    Log.w("MarmotManager", "clearAllState failed", e)
-}
-```
-
-Trade-off: the message string is allocated eagerly even when warn is filtered, but warn-level catch logs are rare-event paths so this cost is negligible compared to losing diagnostic detail.
-
-## Do NOT Convert
-
-- **To lambda:** calls passing a `Throwable` parameter — the lambda overload `(tag) { message }` has no throwable parameter.
-- Static string calls with no `$` interpolation — no allocation benefit.
-- Commented-out log calls.
-- Informational/intentional log of `e.message` *outside* a catch block (rare; usually means the exception was already handled and only the message is meaningful).

.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 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 system expertise for AmethystMultiplatform's 4-module KMP architecture. Focus: practical troubleshooting, dependency resolution, and project-specific optimizations.
 
 ## Build Architecture Mental Model
 
-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):
+Think of this project as **4 layers**:
 
 ```
 ┌─────────────┬─────────────┐
@@ -165,11 +165,11 @@ implementation(libs.jna)
 
 **The problem:** Two Compose ecosystems (Multiplatform + AndroidX) must align, or duplicate classes.
 
-**Current project config** (always re-check `gradle/libs.versions.toml` — these drift):
+**Current project config:**
 ```toml
-composeMultiplatform = "1.11.1"  # Plugin + runtime
-composeBom = "2026.05.01"        # AndroidX Compose BOM
-kotlin = "2.3.21"
+composeMultiplatform = "1.9.3"  # Plugin + runtime
+composeBom = "2025.12.01"       # AndroidX Compose BOM
+kotlin = "2.3.0"
 ```
 
 **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,50 +3,46 @@
 ## Visual Hierarchy
 
 ```
-   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)        │
-        └──────────────────────────────┘
+┌─────────────────────────────────────────────────────────┐
+│                    Root Project                          │
+│                     (Amethyst)                           │
+└─────────────────────────────────────────────────────────┘
+                          │
+         ┌────────────────┼────────────────┬────────────┐
+         │                │                │            │
+         ▼                ▼                ▼            ▼
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────┐
+│  :amethyst  │  │ :desktopApp │  │ :benchmark  │  │:ammolite │
+│  (Android)  │  │   (JVM)     │  │  (Android)  │  │ (Support)│
+└─────────────┘  └─────────────┘  └─────────────┘  └──────────┘
+       │                │                │
+       │                │                │
+       └────────────────┼────────────────┘
+                        │
+                        ▼
+                ┌─────────────┐
+                │  :commons   │
+                │  (KMP UI)   │
+                │             │
+                │ jvmAndroid  │
+                │  /      \   │
+                │ jvm   android│
+                └─────────────┘
+                        │
+                        │
+                        ▼
+                ┌─────────────┐
+                │  :quartz    │
+                │(KMP Library)│
+                │             │
+                │ commonMain  │
+                │     │       │
+                │ jvmAndroid  │
+                │  /  |  \    │
+                │jvm and ios  │
+                └─────────────┘
 ```
 
-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)
@@ -81,7 +77,7 @@ Verified edges (from each module's `build.gradle.kts`):
 **Type:** Android Application
 **Targets:** Android
 **Dependencies:**
-- Modules: `:commons`, `:quartz`, `:nestsClient`
+- Modules: `:commons`, `:quartz`, `:ammolite`
 - External: Android SDK, AndroidX, Firebase, Tor
 
 **Role:** Android-specific navigation, layouts, and entry point
@@ -90,40 +86,17 @@ Verified edges (from each module's `build.gradle.kts`):
 **Type:** Android Library
 **Targets:** Android
 **Dependencies:**
-- Modules: `:commons`, `:quartz` (androidTest only)
+- Modules: `:commons`, `:quartz`
 - External: AndroidX Benchmark
 
 **Role:** Performance benchmarking for Android builds
 
-### :cli (Amy CLI)
-**Type:** JVM Application (no Compose)
-**Dependencies:** `:quartz`, `:commons`
+### :ammolite (Support Module)
+**Type:** Android Library
+**Targets:** Android
+**Dependencies:** Android-specific utilities
 
-**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
+**Role:** Android support utilities for amethyst
 
 ## Dependency Flow Patterns
 
@@ -139,10 +112,10 @@ Verified edges (from each module's `build.gradle.kts`):
 ### Android Build Chain
 ```
 :amethyst → :commons (androidMain) → :quartz (androidMain)
-                                           ↓
-                                     jvmAndroid
-                                           ↓
-                                     commonMain
+    ↓                                      ↓
+:ammolite                            jvmAndroid
+                                         ↓
+                                   commonMain
 ```
 
 ## Source Set Dependencies
@@ -211,9 +184,9 @@ implementation(libs.jna)  // JAR variant
 implementation(compose.ui)              // Compose Multiplatform BOM
 implementation(compose.material3)
 
-// Version catalog alignment (re-check libs.versions.toml — these drift)
-composeMultiplatform = "1.11.1"
-composeBom = "2026.05.01"  // AndroidX Compose
+// Version catalog alignment
+composeMultiplatform = "1.9.3"
+composeBom = "2025.12.01"  // AndroidX Compose
 ```
 **Why:** Two Compose ecosystems (Multiplatform + AndroidX) must align
 

.claude/skills/kotlin-coroutines-structured-concurrency/SKILL.md

@@ -1,441 +0,0 @@
----
-name: kotlin-coroutines-structured-concurrency
-description: Use when writing or reviewing Kotlin code that stores CoroutineScope, launches from init/non-suspending APIs, calls runBlocking, or catches broad exceptions around suspend calls. Technique-layer skill — complements the codebase-specific kotlin-coroutines.
----
-
-# Kotlin coroutines: structured concurrency
-
-## Core principle
-
-A well-structured coroutine is a self-contained unit of asynchronous work — single entry, single exit, scoped to a lifecycle known at the call site.
-
-**Scopes should usually be tied to the caller's lifecycle, not stored as a property on the callee.** A stored `CoroutineScope` is a strong review signal: the class must prove it owns cancellation, error reporting, restart behavior, and lifecycle. Most repositories, managers, use cases, and data sources cannot prove that, so they should expose `suspend` APIs instead.
-
-The fix is almost always the same: **make the API `suspend` and let the caller own the scope.**
-
-## When to use this skill
-
-You're writing or reviewing Kotlin code and you see any of these:
-
-- A class with `private val scope: CoroutineScope` (constructor param stored as a property)
-- An `init { scope.launch { ... } }` block
-- A non-suspending public function whose body is `scope.launch { ... }`
-- `runBlocking { ... }` in suspend-capable application code, or in tests where `runTest` should apply
-- `runCatching { suspendCall() }` or a `catch` on `Exception` / `Throwable` around a `suspend` call without rethrowing `CancellationException`
-- A `catch (e: CancellationException)` (or equivalent) around suspension that does not rethrow
-
-## The silent-cancellation bug
-
-The reason an unowned `CoroutineScope` property is so dangerous: "once a scope is cancelled, every future `launch` on it silently completes as cancelled — no exception, no log, nothing." The work just doesn't happen. This is one of the hardest coroutine bugs to diagnose, and it appears when a class holds a long-lived reference to a lifecycle it does not own.
-
-If APIs are `suspend`, this can't happen: the caller's scope is either alive (work runs) or the call site cancels (the caller knows).
-
-## Anti-patterns and fixes
-
-### 1. CoroutineScope stored as a property
-
-```kotlin
-// ❌ BAD
-@Inject
-class UserRepository(
-    private val scope: CoroutineScope,
-    private val api: UserApi,
-) {
-    fun refresh() {
-        scope.launch { _state.value = api.fetchUser() }
-    }
-}
-
-// ✅ GOOD
-@Inject
-class UserRepository(
-    private val api: UserApi,
-) {
-    suspend fun refresh(): User = api.fetchUser()
-}
-```
-
-The repository no longer needs to know about coroutines at all. The caller (a ViewModel, a use case) decides on what scope, with what error handling, with what cancellation semantics.
-
-### 2. init-block launches
-
-```kotlin
-// ❌ BAD: construction-time side effect, unbounded work
-class UserSession(private val scope: CoroutineScope, private val api: Api) {
-    init { scope.launch { _user.value = api.load() } }
-}
-```
-
-The constructor returns immediately. The caller can't `await` the load, can't see errors, can't cancel. The class is "alive" but its state is undefined.
-
-```kotlin
-// ✅ GOOD: explicit bootstrap, caller owns the suspension
-class UserSession(private val api: Api) {
-    private var _user: User? = null
-    val user: User get() = checkNotNull(_user) { "Call init() first" }
-
-    suspend fun init() { _user = api.load() }
-}
-```
-
-### 3. Fire-and-forget from non-UI classes
-
-A non-suspending public function on a **non-UI class** (repository, manager, use case, data source) that launches into a class-owned scope. The caller gets no result, no error, no cancellation, and no guarantee the work ever ran.
-
-```kotlin
-// ❌ BAD — repository with stored scope and fire-and-forget public API
-class AnalyticsClient(private val scope: CoroutineScope, private val api: Api) {
-    fun track(event: Event) {
-        scope.launch { api.send(event) }      // caller has no idea what happens
-    }
-    fun signOut() {
-        scope.launch { api.signOut() }        // silent failure if scope cancelled
-    }
-}
-```
-
-```kotlin
-// ✅ GOOD
-class AnalyticsClient(private val api: Api) {
-    suspend fun track(event: Event) = api.send(event)
-    suspend fun signOut() = api.signOut()
-}
-```
-
-#### Carve-out: the UI ↔ state-holder boundary
-
-UI frameworks are non-suspending. A Composable's `onClick`, a Fragment's `onKeyEvent`, an Activity's `onNewIntent` — none can `suspend`. The state holder (ViewModel, Decompose Component, feature model, etc. — anything whose role is to absorb UI events and hold UI state) **is** the boundary that translates one-shot UI events into asynchronous work bound to the UI lifecycle. That's its job.
-
-```kotlin
-// ✅ GOOD — state holder absorbs a non-suspending UI event onto its scope
-class FavouritesViewModel(private val repo: FavouritesRepository) : ViewModel() {
-    fun onToggleFavourite(item: Item) {
-        viewModelScope.launch { repo.toggleFavourite(item) }
-    }
-}
-
-// in Compose:
-ListItem(onClick = { viewModel.onToggleFavourite(item) })
-```
-
-This is **not** the fire-and-forget anti-pattern. All three conditions must hold:
-
-1. **State holder for a UI surface** — a ViewModel, Decompose Component, feature model, or equivalent UI state holder. Not a repository, manager, use case, or data source.
-2. **Lifecycle-bound scope** — `viewModelScope`, a Component's `coroutineScope` that's cancelled on destroy, a Composable's `rememberCoroutineScope()`. Not `AppScope`, not an injected long-lived scope, not an ad-hoc `CoroutineScope(...)`.
-3. **Caller really is a UI event** — Composable callback, key handler, lifecycle hook. Not another business-logic class calling through the state holder.
-
-The repository / use case / data source layers underneath still expose `suspend` APIs. The state holder is the *only* layer where the non-suspending → suspending translation belongs.
-
-"It feels like a state holder" isn't enough. The question is "does the UI directly bind to this?" If no, the carve-out doesn't apply.
-
-### 4. Stored scopes that aren't injected
-
-The same anti-pattern, without an injected scope:
-
-```kotlin
-// ❌ BAD — same problem, scope is constructed in-class instead of injected
-class FooManager {
-    private val scope = MainScope()
-    private val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
-}
-```
-
-Lifecycle is now owned by nothing and lives forever. Replace with `suspend` APIs.
-
-The same is true if the instantiation is nested inside a function body — `fun foo() { CoroutineScope(...).launch { … } }` is just a stored scope with extra steps. Each call leaks a new uncancellable scope; bundling it into a `by lazy` property doesn't fix the underlying issue (the scope shouldn't exist at all).
-
-### 5. DI-bound singletons / initializers that launch
-
-A specific pattern that is hard to spot: a DI-bound class (`@SingleIn(AppScope)`, `@Singleton`, an `Initializer.initialize()`) launches a coroutine from its constructor / `init` block / `initialize()`. The launched work then has:
-
-- **A non-deterministic start time** — whenever the graph realizes the binding. Cold-start ordering is invisible.
-- **No observable lifecycle.** Nothing else in the codebase can see whether it's running or has crashed.
-- **No `stop()` / restart path.** If upstream enters a bad state, the loop is uncancellable.
-- **No calling code to grep for.** Readers can't find "who starts this and when".
-
-§1 says scopes should be tied to the caller's lifecycle. The DI-bound variant violates this indirectly: the *scope* may be injected, but the *launch* is hidden inside construction — same effect, harder to see.
-
-```kotlin
-// ❌ BAD — singleton boots work as a side effect of being constructed
-@SingleIn(AppScope::class)
-@Inject
-class TokenRefresher(
-    @ForScope(AppScope::class) private val scope: CoroutineScope,
-    private val auth: AuthService,
-) {
-    init {
-        scope.launch {
-            while (isActive) {
-                delay(5.minutes)
-                auth.refreshIfNeeded()
-            }
-        }
-    }
-}
-
-// ❌ ALSO BAD — Initializer.initialize() that *launches*, not just registers
-class TokenInvalidatorInitializer @Inject constructor(
-    @ForScope(AppScope::class) private val scope: CoroutineScope,
-    private val store: AuthStore,
-    private val invalidator: TokenInvalidator,
-) : Initializer {
-    override fun initialize() {
-        scope.launch { store.tokenChanges.collect { invalidator.invalidate() } }
-    }
-}
-```
-
-Both look like "application-scoped singletons", but the **When NOT to apply** carve-out is *not* permission to launch from `init` / `initialize()`. It's permission for a singleton to own a scope when its API is suspending.
-
-#### First ask: does this background-loop class need to exist at all?
-
-Most background-loop classes exist only because no one inverted the observation. Three answers, in order of preference:
-
-**Pattern 1 — invert into the consumer.** The class observes state forever to react when it changes. But *someone* mutates the state — sign-out flow, profile switch, flag-update handler. That mutation site is already in a coroutine context and is the natural place to do the work directly.
-
-```kotlin
-// ✅ GOOD — no background loop, no scope, no class. The mutation site does the work.
-class Authenticator(
-    private val authStore: AuthStore,
-    private val tokenInvalidator: TokenInvalidator,
-) {
-    suspend fun signOut() {
-        authStore.clearTokens()
-        tokenInvalidator.invalidate()   // direct call at the mutation site
-    }
-}
-```
-
-The background-loop class is **deleted**. The work happens where the state changes.
-
-When this applies: the consumer of the state has a clear lifecycle (a use case, an Authenticator, a service handler) and can perform the reaction inline.
-
-**Pattern 2 — scheduled work.** Genuinely periodic or deferred. Use WorkManager / BGTaskScheduler. The enqueue is one-shot; make it suspending and call it once from an orchestrator that already runs at startup.
-
-**Pattern 3 — explicit named launch site.** Sometimes the consumer is a synchronous API with no observable lifecycle (e.g., OpenTelemetry's `Sampler.shouldSample(...)`, an AIDL stub fanout, a broadcast receiver bridge). The observation has to live somewhere coroutine-aware, but it must live at an *explicit named call site* — not in the class's own `init`.
-
-```kotlin
-// ✅ GOOD — work is named; an explicit call site owns the launch
-@SingleIn(AppScope::class)
-class OtelConfigurableSampler(...) : Sampler {
-    @Volatile private var delegate: Sampler = ...
-
-    suspend fun observeRate(featureFlags: FeatureFlags) {
-        featureFlags.observe(OTEL_SAMPLING_RATE).collect { rate ->
-            delegate = Sampler.traceIdRatioBased(rate.coerceIn(0.0, 1.0))
-        }
-    }
-
-    override fun shouldSample(...) = delegate.shouldSample(...)
-}
-
-// wired explicitly at the OTel SDK init module:
-applicationScope.launch { otelSampler.observeRate(featureFlags) }
-```
-
-When this applies: the consumer is a synchronous API that calls *into* you with no observable lifecycle. The launch can't be invertible, but it must still be visible at a named call site.
-
-#### Test for which pattern fits
-
-"Is the consumer's lifecycle observable to me?"
-
-- **Yes, and they're already in a coroutine context** → Pattern 1. Push the subscription into them; delete the background-loop class.
-- **The work is periodic / deferred** → Pattern 2. Suspend enqueue called once.
-- **No, they're a synchronous API with no observable lifecycle** → Pattern 3. Explicit launch site, not `init`.
-
-If a fourth answer seems to fit — e.g., "I want a `Bootable` interface that launches everything for me" — that's the same anti-pattern with an extra layer of abstraction. The whole point is that launches be *visible*; auto-discovery by interface defeats it.
-
-#### Initializers are still fine — *if they only register*
-
-The `Initializer` pattern is correct when `initialize()` *registers* a listener or hook. The bug is when `initialize()` *launches* a coroutine.
-
-```kotlin
-// ✅ GOOD Initializer — registers a contributor, doesn't launch
-class FavouritesContributorInitializer @Inject constructor(
-    private val registry: ContributorRegistry,
-    private val favouritesContributor: FavouritesContributor,
-) : Initializer {
-    override fun initialize() {
-        registry.register(favouritesContributor)
-    }
-}
-```
-
-**`Initializer.initialize()` must not `launch` a coroutine.** If yours does, it's a Pattern 1/2/3 candidate.
-
-#### Diagnostic for review
-
-- Where is the start moment defined? If "wherever DI realizes me", bad.
-- Who can observe whether the work is running? If "no one", bad.
-- Who can stop or restart it? If "no one", bad.
-- Can a reader grep for the launch site? If no, bad.
-
-If the answers are "the consumer / the orchestrator / the named call site" — you're good.
-
-### 6. Swallowing `CancellationException`
-
-A `catch` clause around a `suspend` call that matches `CancellationException` — directly, or through `Exception` / `Throwable` — and doesn't rethrow usually turns cancellation into silent success. The parent coroutine thinks the child finished; the child keeps running (or its side effects do); the cancellation contract is broken.
-
-Same failure shape as §1's stored-scope bug, viewed from the other end: §1 hides the work *from* the caller's lifecycle; this hides cancellation *from* the work.
-
-```kotlin
-// ❌ BAD — catches CancellationException, never rethrows
-suspend fun fetch() {
-    try {
-        api.load()
-    } catch (e: Exception) {           // matches CancellationException too
-        logger.warn("load failed", e)
-    }
-}
-
-// ❌ ALSO BAD — runCatching has the same problem
-suspend fun fetch() {
-    runCatching { api.load() }
-        .onFailure { logger.warn("load failed", it) }
-}
-```
-
-The acceptable shapes:
-
-```kotlin
-// ✅ Separate catch first
-try { api.load() }
-catch (e: CancellationException) { throw e }
-catch (e: Exception) { logger.warn("load failed", e) }
-
-// ✅ Conditional rethrow inside the broad catch
-try { api.load() }
-catch (e: Exception) {
-    if (e is CancellationException) throw e
-    logger.warn("load failed", e)
-}
-
-// ✅ ensureActive() — good when the catch handles ordinary failures and you only need
-// to rethrow if the current coroutine is cancelled
-try { api.load() }
-catch (e: Exception) {
-    currentCoroutineContext().ensureActive()
-    logger.warn("load failed", e)
-}
-
-// ✅ runCatching with explicit guard
-runCatching { api.load() }
-    .onFailure {
-        if (it is CancellationException) throw it
-        logger.warn("load failed", it)
-    }
-
-// ✅ runCatching terminated with getOrThrow (cancellation flows back out)
-runCatching { api.load() }.getOrThrow()
-```
-
-The trigger is "a suspend call inside the `try`", not "the enclosing function is declared `suspend`". This applies inside any suspending body — `suspend fun`, a `launch { … }` lambda, a Flow `collect { … }`, etc.
-
-The common carve-out is an intentionally local timeout: catching `TimeoutCancellationException` from your own `withTimeout` and converting it to a domain result can be correct. Keep that catch narrow and close to the timeout. Do not use it as permission to swallow arbitrary cancellation.
-
-Catching a non-cancellation subtype (`IOException`, your own exception types) is fine — they don't extend `CancellationException`.
-
-### 7. `runBlocking`
-
-`runBlocking` parks the current thread until the lambda finishes. Inside suspend-capable or lifecycle-scoped application paths it is wrong: a thread that meant to be async is now blocked, structured concurrency is broken, and any cancellation upstream has no effect. It is the "callee makes a structural decision for the caller" anti-pattern at its most direct.
-
-```kotlin
-// ❌ BAD — bridging to suspend by blocking the calling thread
-fun saveUser(user: User) {
-    runBlocking { repository.save(user) }
-}
-```
-
-Three fixes, by context:
-
-**Suspend-capable application code** — make the function `suspend`:
-
-```kotlin
-// ✅ GOOD
-suspend fun saveUser(user: User) = repository.save(user)
-```
-
-If the immediate caller can't suspend either (a non-suspending UI callback, a `BroadcastReceiver` hook), use the existing lifecycle-bound scope at the boundary — see §3's UI ↔ state-holder carve-out. The fix is at the boundary, not inside `saveUser`.
-
-Legitimate blocking boundaries exist: `main` in a CLI tool, Java interop APIs that must return synchronously, framework callbacks with no suspending alternative, and migration shims. Keep `runBlocking` at that outer boundary, keep the body small, and call suspending code immediately.
-
-**Tests** — use `runTest`:
-
-```kotlin
-// ❌ BAD — real time, slow tests, no virtual delay
-@Test fun loadsUser() = runBlocking {
-    assertThat(repository.load().name).isEqualTo("Alice")
-}
-
-// ✅ GOOD
-@Test fun loadsUser() = runTest {
-    assertThat(repository.load().name).isEqualTo("Alice")
-}
-```
-
-`runTest` gives you virtual time (`delay()` returns immediately), `TestDispatcher` integration, and proper coroutine cleanup. Real-time `runBlocking` in tests makes them slow and flaky.
-
-**`ContentProvider` carve-out** — Android's `ContentProvider` methods (`query`, `insert`, `update`, `delete`, `onCreate`, `call`) are synchronous from outside the process. There is no way to suspend them. Inside *member functions* of a `ContentProvider` subclass (direct or indirect — not companion objects), `runBlocking` is the unavoidable bridge. Keep the body as short as possible and call into suspending code immediately:
-
-```kotlin
-// ✅ Acceptable in ContentProvider members only
-class MyProvider : ContentProvider() {
-    override fun query(...): Cursor? = runBlocking { dao.query(...) }
-}
-```
-
-This carve-out is for `android.content.ContentProvider` subclasses *only*. "It's like a `ContentProvider`" doesn't apply, and a `runBlocking` in a `ContentProvider`'s companion object is still a regular violation — the helper isn't part of the framework's synchronous surface.
-
-## Quick reference
-
-| Symptom | Anti-pattern | Fix |
-|---|---|---|
-| Class has `private val scope: CoroutineScope` | Stored scope on the callee | Remove. Make public APIs `suspend`. |
-| `init { scope.launch { ... } }` | Construction-time launch | Move to `suspend fun init()` / `login()` |
-| `fun foo() { scope.launch { ... } }` on a repository/manager/use case | Fire-and-forget from non-UI class | `suspend fun foo()`, let UI state holder pick the scope |
-| `fun onClick() { viewModelScope.launch { ... } }` on a state holder, called from UI | UI ↔ state-holder boundary — fine | Keep as-is (see §3 carve-out) |
-| `private val scope = MainScope()` | Internally-constructed stored scope | Same — remove, make APIs `suspend` |
-| `@SingleIn(AppScope) class X(scope) { init { scope.launch { … } } }` | DI-bound opaque launch (§5) | Expose `suspend fun run()`, launch from startup orchestrator |
-| `class Y : Initializer { override fun initialize() { scope.launch { … } } }` | Initializer that launches, not registers (§5) | Same — `suspend fun run()`, orchestrator owns lifecycle |
-| `try { suspendCall() } catch (e: Exception\|Throwable\|CancellationException) { … }` with no rethrow | Swallowed cancellation (§6) | Prefer `catch (e: CancellationException) { throw e }`; use `ensureActive()` only when that matches the intent |
-| `runCatching { suspendCall() }.onFailure { … }` with no cancellation guard | Same shape as above (§6) | Add `if (it is CancellationException) throw it`, or terminate with `.getOrThrow()` |
-| `runBlocking { … }` inside suspend-capable app code | Thread-blocking bridge (§7) | Make caller `suspend`; or use a lifecycle scope at the boundary |
-| `runBlocking { … }` in a test | Same — real-time bridging (§7) | Use `runTest { … }` |
-| `runBlocking { … }` inside a `ContentProvider.query`/`insert`/… member | Carve-out (§7) | Acceptable; keep the body minimal |
-
-## Refactoring guidance
-
-Removing an existing offender:
-
-1. **Start at the leaf.** Pick the class farthest from any UI — usually a repository or data source. Its public surface should be the easiest to convert.
-2. **Convert public functions to `suspend`** one at a time. The compiler will surface every caller.
-3. **At each caller, choose the scope deliberately:** `viewModelScope`, `lifecycleScope`, `coroutineScope { }`, or an explicit job. This is the choice that was missing before.
-4. **Delete the `CoroutineScope` constructor parameter** once nothing uses it. Remove the injection binding.
-
-Don't try to fix every class in one MR. Removing an anti-pattern is incremental work.
-
-## When NOT to apply
-
-- **UI state holders absorbing UI events.** A ViewModel/Component/feature model with `fun onClick(...) { viewModelScope.launch { ... } }` is correct — that's the boundary the framework needs. See §3 carve-out.
-- **Lifecycle owners with explicit cancellation and error policy.** Actors/services, app infrastructure, or application-scoped singletons may own a scope when they expose clear `close`/`cancel`/restart behavior or otherwise map directly to an application lifecycle. Inject `Application.applicationScope` explicitly rather than creating one ad-hoc. **This is not permission to launch from `init` / `initialize()`** — see §5.
-- **Already-suspending APIs** don't need any of this work.
-- **Tests** sometimes use `TestScope` as a deliberate ambient scope — that's a different pattern with explicit virtual-time control.
-
-## Red flags during review
-
-These thoughts mean the anti-pattern is back:
-
-| Thought | Reality |
-|---|---|
-| "I'll just add a `CoroutineExceptionHandler` to the scope" | The problem isn't error handling. The problem is the scope shouldn't exist. |
-| "I need to launch from `init` so the data's ready when consumers arrive" | Consumers reading state that isn't ready is the bug. Use phasing. |
-| "The caller doesn't want to deal with `suspend`" | Then the caller chooses fire-and-forget at their scope. Don't decide for them. |
-| "It's just a small fire-and-forget call" | Silent cancellation makes every fire-and-forget a potential silent failure. |
-| "We caught and logged the exception, so we're fine" | Did the catch rethrow `CancellationException`? If no, the coroutine is silently un-cancelled. (§6) |
-| "It's just one `runBlocking`, in a non-critical path" | Every `runBlocking` asserts the caller has no async option. If they do, it's the wrong primitive. (§7) |
-| "Tests are simpler with `runBlocking`" | They run in real time, can't fast-forward `delay`, and lose `TestDispatcher` semantics. Use `runTest`. (§7) |
-
-## Related
-
-- [`kotlin-flow-state-event-modeling`](../kotlin-flow-state-event-modeling/SKILL.md) — `StateFlow`, `SharedFlow`, `Channel`, `stateIn`, one-shot events, and related modeling.
-- [`kotlin-coroutines`](../kotlin-coroutines/SKILL.md) — Amethyst's relay-pool / callbackFlow / testing async patterns.

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

@@ -795,7 +795,6 @@ Passing lambda to function?
 - `references/sealed-class-catalog.md` - All sealed types in quartz
 - `references/dsl-builder-examples.md` - TagArrayBuilder, other DSL patterns
 - `references/immutability-patterns.md` - @Immutable usage, data classes, collections
-- `references/common-utilities.md` - Canonical helpers: `NumberFormatters`, `TimeUtils`, `Hex`, `PubKeyFormatter`, `CoroutinesExt.launchIO`, `OptimizedJsonMapper`, etc.
 
 ### Codebase Examples
 - AccountManager.kt:36-50 - sealed class AccountState, StateFlow pattern
@@ -807,5 +806,6 @@ Passing lambda to function?
 
 ---
 
-**Version:** 1.0.1
-**Last Updated:** 2026-06-10
+**Version:** 1.0.0
+**Last Updated:** 2025-12-30
+**Codebase Reference:** AmethystMultiplatform commit 258c4e011

.claude/skills/kotlin-expert/references/common-utilities.md

@@ -1,69 +0,0 @@
-# Common Utility Functions
-
-Canonical helpers that repeatedly come up when working in Amethyst. Prefer these to hand-rolling equivalents.
-
-## Formatting (commons)
-
-All under `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/util/`:
-
-- **`NumberFormatters.kt`**
-  - `countToHumanReadable(counter: Int, noun: String): String` — `1500 → "1K items"`, `2_500_000 → "2M items"`. Suffixes `K`, `M`, `G`.
-  - `countToHumanReadableBytes(bytes: Int): String` — `1024 → "1 KB"`, scales through KB/MB/GB/TB.
-- **`PubKeyFormatter.kt`** — condense an npub to `npub1abc…xyz` with a symmetric prefix/suffix truncation. Use in chips and small UI that show an author.
-- **`EmojiUtils.kt`** — parse custom emoji (`:name:`), render bridging to NIP-30 `emoji` tags.
-- **`IterableUtils.kt`** — small shortcuts like `firstNotNullOf` variants, chunking helpers.
-- **`PlatformNumberFormatter.kt`** — expect/actual locale-aware number formatting (delegates to `NumberFormat` on JVM/Android).
-
-## Time (quartz)
-
-`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/TimeUtils.kt` — the source of truth for "now in Nostr seconds" and common offsets:
-
-```kotlin
-TimeUtils.now()               // Long seconds since epoch (Nostr `created_at`)
-TimeUtils.oneMinuteAgo()
-TimeUtils.fiveMinutesAgo()
-TimeUtils.fifteenMinutesAgo()
-TimeUtils.oneHourAgo()
-TimeUtils.oneDayAgo()
-TimeUtils.oneWeekAgo()
-
-TimeUtils.withinTenMinutes(other)   // |now - other| < 10m
-```
-
-Constants (`TEN_SECONDS`, `ONE_MINUTE`, `FIVE_MINUTES`, `TEN_MINUTES`, `FIFTEEN_MINUTES`, `ONE_HOUR`, `EIGHT_HOURS`, `ONE_DAY`, `ONE_WEEK`) are in seconds and are what every subscription filter and staleness check uses — keep using them instead of magic numbers.
-
-## Hex / bytes / strings (quartz)
-
-Under `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/`:
-
-- **`Hex.kt`** — `ByteArray.toHex()`, `String.hexToByteArray()`. MPP-friendly, no java.util.
-- **`StringUtils.kt`** — generic helpers (normalization, truncation).
-- **`StringExt.kt`** — small extensions (e.g. safe substring).
-- **`UriParser.kt`** — NIP-19 / nostr URI friendly URL parsing without java.net.
-- **`UrlEncoder.kt`** / **`Rfc3986.kt`** — percent-encoding / decoding for URL-safe content.
-- **`UnicodeNormalizer.kt`** — NFC normalization for search/matching.
-
-## Threading & coroutines
-
-- **`commons/src/commonMain/.../threading/Threading.kt`** — shared dispatchers and `CoroutineScope` helpers for commonMain code.
-- **`amethyst/src/main/java/.../service/CoroutinesExt.kt`** — Android-only helpers: `launchIO(block)`, `launchMain(block)` built on top of `Dispatchers.IO` / `Dispatchers.Main`. Use these in ViewModels and services to stop re-spelling the dispatcher every time.
-- **`amethyst/src/main/java/.../service/MainThreadChecker.kt`** — debug assertion helper for catching main-thread misuse during dev.
-
-## Quartz iterables & JSON
-
-- **`quartz/.../utils/IterableExt.kt`** — mutation-free filter/map/group helpers used by the cache layer.
-- **`quartz/.../utils/JsonElementExt.kt`** — safe navigation for Jackson nodes when parsing unknown-shape JSON.
-- **`quartz/.../kotlinSerialization/OptimizedJsonMapper.kt`** — shared Jackson mapper with reified `fromJson<T>(...)` / `toJson(...)`; prefer this to spinning up a local `ObjectMapper`.
-
-## Number formatting for Android display
-
-`amethyst/src/main/java/.../service/CountFormatter.kt` and `ByteFormatter.kt` wrap the commons formatters with Android-specific pluralization / locale. Use them from Android UI; use the commons functions directly from commonMain.
-
-## When to Add vs Reuse
-
-Before introducing a new helper:
-
-1. `grep -r "fun count\|fun format\|fun toHuman" commons/ quartz/` — there is almost certainly something already.
-2. If you're about to write `System.currentTimeMillis() / 1000` — use `TimeUtils.now()`.
-3. If you're about to write `String.format("%.1f K", n / 1000.0)` — use `countToHumanReadable`.
-4. If you need locale-specific rendering on both Android and Desktop, reach for `PlatformNumberFormatter` (expect/actual) rather than hard-coding.

.claude/skills/kotlin-flow-state-event-modeling/SKILL.md

@@ -1,183 +0,0 @@
----
-name: kotlin-flow-state-event-modeling
-description: Use when writing or reviewing Kotlin StateFlow/SharedFlow/Channel choices, sentinel default values, stateIn placement, WhileSubscribed staleness, or MutableStateFlow update patterns. Technique-layer skill — complements the codebase-specific kotlin-expert.
----
-
-# Kotlin Flow: state and event modeling
-
-## Core principle
-
-**Pick the primitive that matches replay, fan-out, and synchronous-read requirements.** `StateFlow`, `SharedFlow`, `Channel`-backed flows, and cold `Flow` differ in buffering, who sees each emission, and whether `.value` exists. Wrong choices drop events, leak sharing coroutines, or force fake domain sentinels into state.
-
-## When to use this skill
-
-You're writing or reviewing Kotlin code involving:
-
-- `MutableStateFlow<T>(SomeSentinel)` — `NoUser`, `Empty`, `Loading`, etc. — because the real value is async
-- `.stateIn(...)` called inside a function rather than assigned to a property
-- `SharingStarted.WhileSubscribed(...)` on a flow whose `.value` is read synchronously and must stay fresh
-- `MutableSharedFlow` for navigation events, snackbars, or other one-shot emissions where loss would be a bug
-- `.map { }` on a `StateFlow` when consumers still need synchronous `.value`
-- `MutableStateFlow.value = _state.value.copy(...)` or update code that builds expensive objects inside `update { ... }`
-
-## SharedFlow for single-consumer fire-once events
-
-`SharedFlow` defaults have no replay buffer. If nothing is collecting at the exact instant of emission, the event is gone. For a **single UI consumer** handling exactly-once events such as navigation or snackbars, a buffered `Channel` exposed as a `Flow` often matches the semantics better:
-
-```kotlin
-// ❌ BAD
-private val _navEvents = MutableSharedFlow<NavigationEvent>()
-val navEvents: SharedFlow<NavigationEvent> = _navEvents.asSharedFlow()
-
-// ✅ GOOD
-private val _navEvents = Channel<NavigationEvent>(Channel.BUFFERED)
-val navEvents: Flow<NavigationEvent> = _navEvents.receiveAsFlow()
-```
-
-`Channel.receiveAsFlow()` is **fan-out, not broadcast**: with multiple collectors, each event is delivered to **one** collector. `Channel.BUFFERED` is bounded, so sends can suspend and `trySend` can fail. If multiple observers must all see the same event, use explicit state, durable storage, or a deliberately configured `SharedFlow` instead.
-
-## StateFlow polluted with invalid sentinel defaults
-
-`StateFlow` forces an initial value. When the real value is async, developers sometimes invent fake domain values — `NoUser`, `EmptyUser`, placeholder IDs — and every consumer is forced to treat that sentinel as real data.
-
-```kotlin
-// ❌ BAD — sentinel leaks into the type
-class UserSession(private val db: Db) {
-    private val _user = MutableStateFlow<User>(NoUser)
-    val user: StateFlow<User> = _user.asStateFlow()
-    init { scope.launch { _user.value = db.load() } }
-}
-```
-
-One fix is **phasing**: don't expose the `StateFlow` until the real value exists.
-
-```kotlin
-// ✅ GOOD — bootstrap suspends; observers only see real users
-class UserSession(private val db: Db) {
-    private var _user: MutableStateFlow<User>? = null
-    val user: StateFlow<User>
-        get() = checkNotNull(_user) { "Call login() first" }
-
-    suspend fun login() {
-        _user = MutableStateFlow(db.load())
-    }
-}
-```
-
-If absence, loading, or error is a real state, model it explicitly (`User?`, `sealed interface UserUiState`, `Result`, etc.). The bug is a fake domain value masquerading as real data, not every initial value.
-
-## Mutate MutableStateFlow with `update { ... }`
-
-Prefer `MutableStateFlow.update { current -> ... }` over reading `.value` and writing it back. `update` applies the transform atomically against the latest state, which avoids lost updates when multiple coroutines mutate the same state.
-
-```kotlin
-// BAD — read/modify/write can lose concurrent updates.
-_state.value = _state.value.copy(
-    selectedId = id,
-    details = details,
-)
-
-// GOOD — transform starts from the latest state.
-_state.update { current ->
-    current.copy(
-        selectedId = id,
-        details = details,
-    )
-}
-```
-
-Keep object creation outside the `update` block unless it needs the current state. The update lambda can be retried, so expensive work or side effects inside it may run more than once:
-
-```kotlin
-// GOOD — details does not depend on current state, so build it once.
-val details = Details.from(response)
-_state.update { current ->
-    current.copy(details = details)
-}
-
-// GOOD — derived value depends on current state, so compute it inside.
-_state.update { current ->
-    val nextItems = current.items.replaceById(updatedItem)
-    current.copy(items = nextItems)
-}
-```
-
-The block should be a pure, fast state transformation: no network calls, database writes, logging side effects, random IDs, or time reads unless those values were captured before the block.
-
-## `stateIn()` inside a function
-
-```kotlin
-// ❌ BAD — new sharing coroutine every call
-fun getPreferences(): StateFlow<Prefs> =
-    repo.prefsFlow.stateIn(scope, SharingStarted.Eagerly, Prefs.Default)
-```
-
-Every call to `getPreferences()` launches a fresh coroutine on `scope` that never completes. Performance dies fast under repeated reads.
-
-```kotlin
-// ✅ GOOD — one shared instance, computed once
-val preferences: StateFlow<Prefs> =
-    repo.prefsFlow.stateIn(viewModelScope, SharingStarted.Eagerly, Prefs.Default)
-```
-
-## `WhileSubscribed` with synchronous `.value`
-
-`SharingStarted.WhileSubscribed(timeout)` disconnects the upstream when there are no active collectors. While disconnected, `.value` returns the last cached value, which may be stale or still the initial value.
-
-**Rule:** if `.value` must be fresh or initialized without an active collector, use `SharingStarted.Eagerly` or explicit initialization. `WhileSubscribed` is fine when stale/cached values are acceptable and consumers primarily collect asynchronously.
-
-## `.map` on `StateFlow` loses `.value`
-
-```kotlin
-// ❌ BAD — `name.value` won't compile; it's now a plain Flow
-val name: Flow<String> = userState.map { it.name }
-```
-
-If you need synchronous `.value`, terminate the chain with `.stateIn(...)`:
-
-```kotlin
-// ✅ GOOD
-val name: StateFlow<String> = userState
-    .map { it.name }
-    .stateIn(viewModelScope, SharingStarted.Eagerly, userState.value.name)
-```
-
-Community "derived state flow" utilities run the transform on every `.value` read — only acceptable for fast, idempotent transforms. Default to `.stateIn(...)`.
-
-## Decision: which Flow type?
-
-| Need | Primitive |
-|------|-----------|
-| State that always has a value, read by both async collectors **and** synchronous code | `StateFlow`, often with `SharingStarted.Eagerly` when `.value` matters |
-| Hot stream, multiple subscribers, **no** requirement for synchronous `.value` | `SharedFlow` |
-| Discrete events for **one** consumer, exactly-once handoff | Consider `Channel(BUFFERED).receiveAsFlow()` |
-| Cold stream, one consumer per collection | Plain `Flow` |
-
-If you're tempted to reach for `SharedFlow`, ask: would dropping an emission be a bug, and how many consumers must see it? If one consumer must handle it exactly once, a `Channel` may fit. If every observer must see it, model durable state or configure a broadcast stream deliberately.
-
-## Quick reference
-
-| Symptom | Problem | Fix |
-|---------|---------|-----|
-| `MutableStateFlow<X>(FakeDomainValue)` | Invalid placeholder default | Model absence explicitly or use phase initialization |
-| `MutableSharedFlow<Event>` for single-consumer nav/snackbar | Lossy default event stream | Consider `Channel(BUFFERED).receiveAsFlow()` |
-| `fun foo() = flow.stateIn(...)` | Per-call sharing coroutine | Make it a `val` / shared instance |
-| `WhileSubscribed` + `.value` must be fresh/initialized | Stale or initial data | `SharingStarted.Eagerly` or explicit initialization |
-| `stateFlow.map { ... }` consumed as state | Lost `.value` | Terminate with `.stateIn(...)` |
-| `_state.value = _state.value.copy(...)` | Non-atomic read/modify/write | `_state.update { it.copy(...) }` |
-| Expensive object creation inside `update { ... }` that doesn't use current state | Work can repeat if update retries | Build before `update`; keep only current-state transforms inside |
-
-## Red flags during review
-
-| Thought | Reality |
-|---------|---------|
-| "We need `SharedFlow` because there are multiple subscribers" | Multiple subscribers change the semantics. `Channel.receiveAsFlow()` is not broadcast; choose the event model deliberately. |
-| "We'll use `WhileSubscribed` to save resources" | Only if stale/initial `.value` reads are acceptable. Verify before applying. |
-| "I'll use a sentinel until real data loads" | Consumers treat it as real domain; prefer explicit UI/state modeling or phasing. |
-| "I'll construct the new object inside `update` because it's convenient" | The lambda may retry. Construct outside unless it depends on the current state. |
-
-## Related
-
-- [`kotlin-coroutines-structured-concurrency`](../kotlin-coroutines-structured-concurrency/SKILL.md) — scope ownership, init launches, fire-and-forget boundaries, cancellation, `runBlocking`
-- [`compose-side-effects`](../compose-side-effects/SKILL.md) — collecting event flows and wiring side effects in Compose
-- [`compose-state-holder-ui-split`](../compose-state-holder-ui-split/SKILL.md) — where state holders expose flows to UI

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

@@ -3,7 +3,7 @@ name: kotlin-multiplatform
 description: |
   Platform abstraction decision-making for Amethyst KMP project. Guides when to abstract vs keep platform-specific,
   source set placement (commonMain, jvmAndroid, platform-specific), expect/actual patterns. Covers primary targets
-  (Android, JVM/Desktop, iOS — all mature) with web/wasm as possible future targets. Integrates with gradle-expert for dependency issues.
+  (Android, JVM/Desktop, iOS) with web/wasm future considerations. Integrates with gradle-expert for dependency issues.
   Triggers on: abstraction decisions ("should I share this?"), source set placement questions, expect/actual creation,
   build.gradle.kts work, incorrect placement detection, KMP dependency suggestions.
 ---
@@ -242,17 +242,17 @@ expect fun currentTimeSeconds(): Long
 
 **Android (androidMain):**
 - Uses Android framework (Activity, Context, etc.)
-- secp256k1-kmp-jni-android (`0.23.0` in `libs.versions.toml`) for crypto
+- secp256k1-kmp-jni-android for crypto
 - AndroidX libraries
 
 **Desktop JVM (jvmMain):**
 - Uses Compose Desktop (Window, MenuBar, etc.)
-- secp256k1-kmp-jni-jvm (same `0.23.0` line) for crypto
+- secp256k1-kmp-jni-jvm for crypto
 - Pure JVM libraries
 
 **iOS (iosMain):**
-- Mature target — actively built and tested
-- Architecture targets: iosArm64, iosSimulatorArm64, iosX64 (plus macosArm64 for host tooling)
+- Active development, framework configured
+- Architecture targets: macosArm64Main, iosArm64Main, iosSimulatorArm64Main
 - Platform APIs via platform.posix, Security framework
 
 ### Web, wasm - Future Targets

.claude/skills/kotlin-multiplatform/references/target-compatibility.md

@@ -14,7 +14,7 @@ Current targets (Android, JVM/Desktop, iOS) and future targets (web, wasm) with
 - Android framework (Activity, Context, Intent, etc.)
 - AndroidX libraries (ViewModel, Navigation, etc.)
 - JVM libraries via jvmAndroid (Jackson, OkHttp)
-- Platform-specific crypto: `secp256k1-kmp-jni-android` (0.23.0 in `libs.versions.toml`)
+- Platform-specific crypto: secp256k1-kmp-jni-android
 
 **Constraints:**
 - Mobile UX paradigms (bottom navigation, vertical scroll)
@@ -44,7 +44,7 @@ class MainActivity : AppCompatActivity() {
 - Pure JVM libraries
 - JVM libraries via jvmAndroid (Jackson, OkHttp)
 - Compose Desktop (Window, MenuBar, etc.)
-- Platform-specific crypto: `secp256k1-kmp-jni-jvm` (same 0.23.0 line)
+- Platform-specific crypto: secp256k1-kmp-jni-jvm
 
 **Constraints:**
 - Desktop UX paradigms (sidebar, menus, keyboard shortcuts)
@@ -70,7 +70,7 @@ fun main() = application {
 
 ### iOS (iosMain + architecture targets)
 
-**Status:** ✅ Mature — actively built and tested
+**Status:** ⚠️ In development, framework configured
 
 **Runtime:** Native iOS
 
@@ -78,8 +78,6 @@ fun main() = application {
 - iosMain (common iOS code)
 - iosArm64Main (device - iPhone/iPad)
 - iosSimulatorArm64Main (Apple Silicon simulator)
-- iosX64Main (Intel simulator)
-- macosArm64Main (host tooling / XCFramework build)
 
 **Available:**
 - iOS platform APIs (platform.posix, Foundation, etc.)

.claude/skills/kotlin-types-value-class/SKILL.md

@@ -1,119 +0,0 @@
----
-name: kotlin-types-value-class
-description: Use when writing or reviewing Kotlin type declarations to choose @JvmInline value class over data class where appropriate, including Compose stability implications. Technique-layer skill — complements the codebase-specific kotlin-expert.
----
-
-# Kotlin value class vs data class
-
-## Core principle
-
-Prefer `@JvmInline value class` for single-field types that carry domain meaning. Data classes are for aggregating multiple fields. A value class gives you type safety (you can't mix up `UserId` and `String`) without the allocation overhead of a data class.
-
-## When to use this skill
-
-- Writing a new Kotlin type that wraps a single value
-- Reviewing a data class that has only one property
-- Seeing primitive types (`String`, `Long`, `Int`, etc.) used where a domain type would prevent misuse
-- Compose compiler reports showing unstable parameters that could be value classes
-
-## Decision flow
-
-| Situation | Prefer |
-|---|---|
-| Single field + domain-meaningful (`UserId`, `EmailAddress`, `Percentage`) | `@JvmInline value class` |
-| Single field + no domain meaning (just grouping) | Type alias or keep the primitive |
-| Multiple fields | Data class |
-| Needs custom `equals`/`hashCode`/`toString` beyond the wrapped value | Data class (value classes delegate to the underlying type) |
-| Used as a generic type argument or nullable in hot paths | Data class or primitive (autoboxing cost) |
-
-```kotlin
-// GOOD: domain-meaningful single field
-@JvmInline value class UserId(val value: String)
-@JvmInline value class EmailAddress(val value: String)
-@JvmInline value class Percentage(val value: Float)
-
-// BAD: data class wrapping a single field
-data class UserId(val value: String) // unnecessary allocation
-data class EmailAddress(val value: String) // type safety without the overhead is available
-
-// BAD: value class with no domain meaning
-@JvmInline value class Wrapper(val value: String) // just use the String, or a type alias
-
-// BAD: value class needing custom equality
-@JvmInline value class CaseInsensitiveString(val value: String)
-// value class equals delegates to String equals, which IS case-sensitive
-// Use a data class if you need different equality semantics
-```
-
-## Compose stability
-
-`@JvmInline value class` is treated as `Stable` by the Compose compiler when its underlying type is stable (primitives, `String`, and other stable types). This means:
-
-- Value classes passed as composable parameters avoid "unstable parameter" warnings
-- No need for `@Immutable` annotations at Compose boundaries when wrapping primitives or strings
-- Replacing single-field data classes with value classes at UI boundaries improves skippability
-
-```kotlin
-// Before: data class wrapping a single field
-data class UiState(val userId: String) // works, but allocates a wrapper object
-
-// After: value class is stable and zero-allocation at runtime
-@JvmInline value class UserId(val value: String)
-data class UiState(val userId: UserId)
-```
-
-## Gotchas
-
-- **Autoboxing**: Value classes are unboxed at compile time but boxed (allocated) when used as nullable (`UserId?`), generic type arguments (`List<UserId>`), or vararg parameters. In hot paths these allocations matter; in most code they don't.
-- **No backing fields**: You cannot use `init` blocks, `lateinit`, or delegated properties like `by lazy`. The class body is extremely constrained — only the single constructor parameter exists.
-- **No data-class conveniences**: No `copy()`, no `component1()` for destructuring, and no way to customize `toString()`. If you need any of these, use a data class.
-- **No custom equals/hashCode/toString**: These always delegate to the underlying type. Need custom equality → use a data class.
-- **when exhaustiveness**: Sealed hierarchies of value classes work differently than data class hierarchies. Test `when` branches carefully.
-- **Serialization semantics**: With kotlinx.serialization, a `@Serializable data class A(val value: String)` serializes as `{"value":"..."}`, but a `@Serializable value class A(val value: String)` serializes as the underlying value (`"..."`). Replacing a single-field data class with a value class is a breaking change for your API/JSON contract.
-- **Serialization**: Some serialization frameworks need explicit support for value classes (e.g., kotlinx.serialization's `@Serializable` works, but Jackson may need configuration).
-- **Interoperability**: From Java, value classes appear as their underlying type. Java callers bypass the type-safety wrapper.
-- **Reflection and runtime erasure**: When passed as `Any` or used in generic contexts, value classes box into a synthetic wrapper class. Java reflection sees mangled method signatures, and frameworks that rely on raw runtime types (some ORMs, DI containers, or serializers) may see the underlying type rather than the value class.
-
-## Packing multiple values
-
-A value class can only declare one field, but Compose provides `packFloats`, `packInts`, and matching `unpack*` functions in `androidx.compose.ui.util` to store multiple primitives in a single `Long`. This lets you represent composite values (e.g., a 2D point, size, or padding) as a zero-allocation value class instead of a multi-field data class.
-
-```kotlin
-@JvmInline value class Offset(val packedValue: Long)
-
-fun Offset(x: Float, y: Float): Offset = Offset(packFloats(x, y))
-val Offset.x: Float get() = unpackFloat1(packedValue)
-val Offset.y: Float get() = unpackFloat2(packedValue)
-```
-
-- **Only use this in performance-critical paths** — manual bit-packing is error-prone. A data class is simpler and safer for most UI types.
-- **Available in `androidx.compose.ui.util`** — `packFloats`, `packInts`, `unpackFloat1`, `unpackFloat2`, `unpackInt1`, `unpackInt2`.
-
-## Common mistakes
-
-| Mistake | Fix |
-|---|---|
-| Data class wrapping a single domain field | Replace with `@JvmInline value class` |
-| Value class with no domain meaning (just a wrapper) | Use a type alias or the primitive directly |
-| Value class needing custom equality | Use a data class instead |
-| Value class as generic type argument in hot path | Accept autoboxing cost or use the primitive |
-| `@Immutable` annotation on a type that could be a value class | Replace with value class — it's Stable by default |
-| Forgetting `@JvmInline` annotation | Always pair `value class` with `@JvmInline` for single-field classes |
-
-## Red flags during review
-
-- A data class with exactly one property
-- A `String`, `Long`, or `Int` used where different values should not be interchangeable (e.g., `fun transfer(from: String, to: String, amount: Long)`)
-- An `@Immutable` annotation on a single-field wrapper
-- A type alias used for domain distinction where value-class semantics are needed (type aliases are type-erased, no runtime protection)
-
-## When NOT to apply
-
-- The type needs multiple fields → data class
-- The type needs custom `equals`/`hashCode`/`toString` → data class
-- The type is used heavily as a nullable or generic in performance-critical code → measure autoboxing cost first
-- The project does not need the type-safety distinction → a type alias or primitive is sufficient
-
-## Related
-
-- [`compose-stability-diagnostics`](../compose-stability-diagnostics/SKILL.md) — diagnose unstable Compose parameters; value classes are one fix

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

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

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

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

.claude/skills/nostr-expert/references/crypto-and-encryption.md

@@ -1,80 +0,0 @@
-# Crypto & Encryption in Quartz
-
-Event signing, hashing, and NIP-44 payload encryption.
-
-## Layout
-
-### Core crypto (`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/crypto/`)
-
-- `EventHasher.kt` — canonical JSON serialization + SHA-256 → event id. NIP-01 §1.
-- `EventHasherSerializer.kt` — Jackson serializer that emits the exact byte layout NIP-01 hashing requires.
-- `KeyPair.kt` — holder for `privateKey: ByteArray` + derived `pubKey: ByteArray`. Generates fresh key pairs via `secureRandom`.
-- `Nip01Crypto.kt` — one-stop helper: sign an event, verify a signature, derive pubkey from seckey.
-- `EventAssembler.kt` — takes an unsigned template + signer and produces a fully populated `Event`.
-- `EventExt.kt` — `Event.verify()` / `Event.hasValidSignature()` extensions.
-
-### secp256k1 abstraction (`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/`)
-
-- `Secp256k1Instance.kt` — `expect object` with `signSchnorr`, `verifySchnorr`, `pubKey(seckey)`, `sharedSecret`.
-- `Secp256k1InstanceKotlin.kt` — pure-Kotlin actual (iOS via native, etc.).
-- Android actual: `secp256k1-kmp-jni-android` (0.23.0). JVM actual: `secp256k1-kmp-jni-jvm`.
-- Tests/benchmarks pull in `com.vitorpamplona:schnorr256k1-kmp` (libschnorr256k1) for the in-house C JNI baseline used in `Secp256k1CrossValidationTest` and the 3-way benchmarks; production never ships it.
-
-### NIP-44 encryption (`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip44Encryption/`)
-
-- `Nip44.kt` — dispatcher that handles both v1 (ChaCha20 w/o Poly1305, legacy) and v2 (XChaCha20-Poly1305).
-- `Nip44v2.kt` — current spec: HKDF key derivation → XChaCha20-Poly1305 → padded plaintext → Base64.
-- `Nip44v1.kt` — legacy path (decrypt-only for backward compat; do not encrypt with v1).
-- `crypto/` — `ChaCha20Poly1305`, `HKDF`, `Hmac`, etc. (pure Kotlin, MPP-friendly).
-- `SharedKeyCache.kt` — in-process LRU for ECDH shared secrets. Critical for performance in chat/list screens that decrypt many messages with the same counterparty.
-- `EncryptedInfoString.kt` — versioned payload envelope that the parser reads to pick v1 vs v2.
-
-## Typical Flows
-
-### Sign an event
-
-```kotlin
-// Direct (when you have the privkey in memory)
-val signed = Nip01Crypto.sign(unsignedEvent, keyPair.privateKey)
-
-// Via signer (preferred — honors external/remote signers)
-val signer: NostrSigner = ...     // NostrSignerInternal, Nip46RemoteSigner, NostrSignerExternal
-signer.sign(template) { signed -> /* emit signed event */ }
-```
-
-Use `NostrSigner` whenever the key might not live in the current process (NIP-46 bunker, NIP-55 Android external signer). See the `auth-signers` skill.
-
-### Verify an event
-
-```kotlin
-event.verify()               // throws on failure
-event.hasValidSignature()    // returns Boolean
-```
-
-Both recompute `sha256(canonicalJson(event))` and call Schnorr `verifySchnorr(sig, hash, pubKey)`.
-
-### NIP-44 encrypt / decrypt
-
-```kotlin
-// Always compute shared secret through the cache — direct ECDH is expensive
-val sharedSecret = SharedKeyCache.getOrComputeShared(mySeckey, theirPubkey)
-
-val cipherText = Nip44.encrypt(plaintext, sharedSecret)   // v2 by default
-val plain      = Nip44.decrypt(cipherText, sharedSecret)  // dispatches on version byte
-```
-
-Callers rarely touch `Nip44v2` directly; go through `Nip44`.
-
-## Gotchas
-
-- **Never log private keys, shared secrets, or raw plaintext.** `KeyPair.privateKey` is a `ByteArray` on purpose so it doesn't get interned as a String.
-- **Don't recompute ECDH per message.** `SharedKeyCache` exists because the same counterparty appears in many messages; bypassing the cache produces noticeable UI lag.
-- **`EventHasher` ordering is canonical.** Serialize tags / content exactly as `EventHasherSerializer` emits, or ids won't match relays.
-- **secp256k1 JNI is platform-specific**: if you add crypto that must run in `commonTest`, wrap it in `expect/actual` or you'll get `UnsatisfiedLinkError` in JVM unit tests.
-- **NIP-44 pads messages**. Don't assert exact ciphertext length; assert decrypt round-trips.
-
-## Tests
-
-- `quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip01Core/crypto/` — sign/verify/hash round-trips.
-- `quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip44Encryption/` — NIP-44 vectors (encryption parity with reference vectors).
-- JNI crypto is exercised in `androidUnitTest` / JVM integration tests.

.claude/skills/nostr-expert/references/event-factory.md

@@ -1,68 +0,0 @@
-# EventFactory: Parsing JSON into Typed Events
-
-`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/EventFactory.kt` is the single dispatch point that turns a parsed `(id, pubKey, createdAt, kind, tags, content, sig)` tuple into the correct `Event` subclass.
-
-## What It Does
-
-EventFactory is a giant `when` over `kind` that maps integer kind values to concrete event classes. If a kind isn't recognized, it falls back to the generic base `Event` (so unknown kinds still round-trip). Every NIP that defines a new kind registers its class here.
-
-Typical shape:
-
-```kotlin
-object EventFactory {
-    fun create(
-        id: HexKey,
-        pubKey: HexKey,
-        createdAt: Long,
-        kind: Int,
-        tags: TagArray,
-        content: String,
-        sig: HexKey,
-    ): Event = when (kind) {
-        MetadataEvent.KIND        -> MetadataEvent(id, pubKey, createdAt, tags, content, sig)
-        TextNoteEvent.KIND        -> TextNoteEvent(id, pubKey, createdAt, tags, content, sig)
-        ContactListEvent.KIND     -> ContactListEvent(id, pubKey, createdAt, tags, content, sig)
-        ReactionEvent.KIND        -> ReactionEvent(id, pubKey, createdAt, tags, content, sig)
-        // …hundreds more…
-        else                      -> Event(id, pubKey, createdAt, kind, tags, content, sig)
-    }
-}
-```
-
-Callers are normally upstream of this: `Event.fromJson(...)` / `EventMapper.fromJson(...)` / the relay client's message parser. You rarely call EventFactory directly — you consume typed events it produces.
-
-## Registering a New Event Kind
-
-Adding a NIP is roughly:
-
-1. Create the event class under `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nipXX…/` alongside the NIP package.
-2. Subclass the right base:
-   - `Event` — regular events (stored forever).
-   - `BaseReplaceableEvent` — kinds `10000-19999`, `0`, `3`.
-   - `BaseAddressableEvent` — kinds `30000-39999` (identified by `kind:pubkey:d-tag`).
-   - Ephemeral events extend `Event` but have kind `20000-29999`.
-3. Define `companion object { const val KIND = <n> }`.
-4. If the event has tag builders, define a `TagArrayBuilder<YourEvent>` DSL in a `TagArrayBuilder` extension — see `nostr-expert/references/tag-patterns.md`.
-5. Add a branch to `EventFactory.create(...)` so JSON parsing produces your typed class.
-6. If the event is addressable, ensure it exposes a stable `dTag()` and `address()`.
-7. Add tests under `quartz/src/commonTest/...`.
-
-## Why a Monolithic when?
-
-- **Zero overhead**: compiled to a dense lookup. No reflection, no registry map.
-- **Exhaustive browsing**: every known kind lives at one search location. `grep KIND = 1234 quartz/...` finds everything.
-- **Obvious migration path**: adding a kind means adding a case; removing a kind is a grep-and-delete.
-
-The tradeoff is the file is large and every new kind edits the same file — expect merge conflicts in PRs that touch it, and resolve by keeping both branches.
-
-## Supporting Utilities
-
-- `EventAssembler.kt` (crypto/) — higher-level helper that takes a signer and a `kind + tags + content` and produces a fully signed event (id + sig populated).
-- `EventTemplate.kt` (signers/) — unsigned-event holder, useful in signer flows.
-- `Event.fromJson(...)` / `Event.toJson()` — JSON round-trip using `OptimizedJsonMapper` (Jackson on jvmAndroid).
-
-## Related References
-
-- `event-hierarchy.md` — class hierarchy, Kind ranges
-- `nip-catalog.md` — which kind maps to which NIP
-- `tag-patterns.md` — `TagArrayBuilder` DSL for writing tags cleanly

.claude/skills/nostr-expert/references/large-cache.md

@@ -1,63 +0,0 @@
-# LargeCache: Platform-Aware In-Memory Store
-
-`quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/cache/LargeCache.kt` provides a thread-safe key-value cache with a functional iteration API. Used everywhere Amethyst needs to hold many events, users, or derived state in memory.
-
-## Files
-
-- `LargeCache.kt` — `expect class LargeCache<K, V>` and its factory `createLargeCache()`.
-- `ICacheOperations.kt` — interface the cache exposes: `forEach`, `filter`, `map`, `mapNotNull`, `groupBy`, `maxOrNullOf`, `sumOf`, `count`, `any`, `firstOrNull`, etc.
-- `CacheCollectors.kt` — functional collector helpers used by the cache API.
-
-### Actual implementations
-
-- **Android** (`androidMain`) — backed by a `ConcurrentHashMap` (and optionally `androidx.collection.LruCache` variants for size-bounded caches).
-- **JVM/Desktop** (`jvmMain`) — `ConcurrentHashMap` directly.
-- **iOS** (`iosMain`) — `NSMapTable`/Kotlin concurrent map wrapper.
-
-## Core API
-
-```kotlin
-val cache: LargeCache<HexKey, Note> = LargeCache()
-
-cache.put(id, note)
-cache.get(id)                         // V?
-cache.getOrCreate(id) { Note(id) }    // atomic compute-if-absent
-cache.containsKey(id)
-cache.remove(id)
-cache.size()
-
-// Functional iteration — thread-safe snapshot semantics
-cache.forEach { key, value -> ... }
-cache.filter { key, value -> value.kind == 1 }
-cache.map { key, value -> value.pubKey }
-cache.count { _, v -> v.isUnread }
-cache.maxOrNullOf { _, v -> v.createdAt }
-cache.groupBy { _, v -> v.kind }
-```
-
-The important contract: **functional operations iterate a consistent snapshot**, so you can `filter` inside a coroutine without racing concurrent writers. This is why `LocalCache` (the Amethyst event store) can be scanned to build a feed while relays are still inserting.
-
-## When to Use
-
-- **Event / note stores** — `LocalCache.notes: LargeCache<HexKey, Note>`.
-- **User profiles** — `LocalCache.users: LargeCache<HexKey, User>`.
-- **Address → event** lookups for addressable (parameterized replaceable) events.
-- **Shared-secret caches** (see `SharedKeyCache.kt` — a similar pattern at smaller scale).
-
-## When Not to Use
-
-- Small maps (<100 entries) — regular `mutableMapOf` is fine.
-- Off-process state (DB, disk) — use the `store/` event DB, not LargeCache.
-- Hot one-shot lookups — if you're already inside a Flow pipeline, chain operators rather than maintaining a parallel cache.
-
-## Gotchas
-
-- **`getOrCreate` vs `put`** — `getOrCreate` is atomic and safe under contention; `get` then `put` is a race.
-- **Iteration during mutation is safe** but the snapshot may include or exclude a concurrent write. Don't rely on a just-put value being visible inside a currently-running `forEach`.
-- **Don't store `Flow`s inside LargeCache.** Cache values should be immutable / thread-safe objects. For reactive state, keep a `StateFlow` next to the cache and emit on writes.
-- **No TTL / eviction by default.** If you need bounded size, wrap with `LruCache` or build an explicit eviction loop keyed off a secondary structure.
-
-## Related
-
-- `amethyst/src/main/java/com/vitorpamplona/amethyst/model/LocalCache.kt` — the canonical user of `LargeCache<HexKey, Note>` and `LargeCache<HexKey, User>`.
-- `nip44Encryption/SharedKeyCache.kt` — smaller domain-specific cache using the same pattern.

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

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

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

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

.claude/skills/nostr-expert/references/nip19-bech32.md

@@ -1,83 +0,0 @@
-# NIP-19: Bech32 Encoding & Parsing
-
-Quartz implementation for `npub`, `nsec`, `note`, `nevent`, `nprofile`, `naddr`, `nrelay`, `nembed` — the user-facing encoded forms of Nostr identifiers.
-
-## Layout
-
-All under `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip19Bech32/`:
-
-- `Nip19Parser.kt` — the entry point. Parses any Bech32 or `nostr:` URI into a typed `Entity`.
-- `bech32/Bech32Util.kt` — raw Bech32 encode/decode (bits ↔ 5-bit groups).
-- `tlv/Tlv.kt` / `tlv/TlvBuilder.kt` — Type-Length-Value codec for composite entities (`nevent`, `nprofile`, `naddr`).
-- `TlvTypes.kt` — TLV type constants (0 = special payload, 1 = relay, 2 = author, 3 = kind).
-- `entities/` — one class per entity type (see below).
-- `ATagExt.kt`, `ByteArrayExt.kt`, `EventExt.kt`, `ListEntityExt.kt`, `TlvBuilderExt.kt` — convenience extensions for encoding domain objects directly.
-
-## Entity Types
-
-Each is a `sealed class Entity` subclass under `entities/`:
-
-| Class       | Prefix     | Payload                                           | Purpose |
-|-------------|------------|---------------------------------------------------|---------|
-| `NPub`      | `npub1...` | 32-byte pubkey                                    | Public key |
-| `NSec`      | `nsec1...` | 32-byte private key                               | Private key (never log/share) |
-| `NNote`     | `note1...` | 32-byte event id                                  | Bare note reference (no hints) |
-| `NEvent`    | `nevent1…` | TLV: event id + relays + author + kind            | Rich note reference |
-| `NProfile`  | `nprofile…`| TLV: pubkey + relays                              | User reference with relay hints |
-| `NAddress`  | `naddr1…`  | TLV: d-tag + relays + author + kind (addressable) | Parameterized replaceable event |
-| `NRelay`    | `nrelay1…` | TLV: relay URL                                    | Relay pointer |
-| `NEmbed`    | `nembed1…` | Compressed event JSON                             | Full event embedded inline |
-
-## Parsing
-
-```kotlin
-// From anywhere (URI, Bech32, nostr: prefix, "nostr:" + data):
-val entity: Entity? = Nip19Parser.uriToRoute(input)?.entity
-
-// More forgiving — strips scheme, whitespace, surrounding chars:
-val parsed = Nip19Parser.tryParseAndClean(dirtyInput)
-
-when (entity) {
-    is NPub      -> entity.hex           // 32-byte pubkey hex
-    is NEvent    -> entity.hex + entity.relay + entity.author + entity.kind
-    is NAddress  -> entity.atag          // kind:pubkey:d-tag
-    is NProfile  -> entity.hex + entity.relay
-    // …
-}
-```
-
-## Encoding
-
-The cleanest path is the entity's `toNostrUri()` / `toBech32()` methods (each entity class defines them). For composite entities (NEvent, NProfile, NAddress), internally the code builds a TLV buffer via `TlvBuilder`:
-
-```kotlin
-// TlvBuilder DSL (tlv/TlvBuilder.kt)
-val bytes = TlvBuilder().apply {
-    addHex(TlvTypes.SPECIAL, eventIdHex)
-    addString(TlvTypes.RELAY, relayUrl)
-    addHex(TlvTypes.AUTHOR, authorHex)
-    addInt(TlvTypes.KIND, kind)
-}.build()
-
-Bech32Util.encode("nevent", bytes)
-```
-
-Kotlin-idiomatic extension helpers live in `TlvBuilderExt.kt`, `EventExt.kt`, and `ATagExt.kt` — prefer those over hand-building TLV.
-
-## When to Use
-
-- **Pasted input from users** → `Nip19Parser.tryParseAndClean` (handles prefixes, whitespace, leftover `nostr:`)
-- **Internal routing / deep links** → `Nip19Parser.uriToRoute`
-- **Outbound share links** → call the entity's `toNostrUri()` / `toBech32()` directly
-- **Building a custom TLV entity** → `TlvBuilder` DSL + `Bech32Util.encode`
-
-## Gotchas
-
-- `NSec` should never be logged or propagated. Parse and discard the string buffer.
-- Relay hints in `NEvent`/`NProfile`/`NAddress` are hints, not guarantees. The Outbox model (NIP-65) overrides them.
-- TLV types are fixed (see `TlvTypes.kt`); do not reorder or invent new types without NIP-19 support.
-- `NEmbed` is an Amethyst-specific compressed-event extension, not part of NIP-19 proper.
-
-## Tests
-
-See `quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip19Bech32/` for round-trip tests covering every entity and `Nip19Parser` input cleaning.

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

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

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

@@ -3,7 +3,7 @@
 ## Current version
 
 ```
-com.vitorpamplona.quartz:quartz:1.13.1
+com.vitorpamplona.quartz:quartz:1.06.3
 ```
 
 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.13.1"
+quartz = "1.06.3"
 
 [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.13.1")
+    implementation("com.vitorpamplona.quartz:quartz:1.06.3")
 }
 ```
 
@@ -70,7 +70,7 @@ plugins {
 }
 
 dependencies {
-    implementation("com.vitorpamplona.quartz:quartz:1.13.1")
+    implementation("com.vitorpamplona.quartz:quartz:1.06.3")
     // JNA needed for libsodium (NIP-44) on JVM
     implementation("net.java.dev.jna:jna:5.18.1")
 }

.claude/skills/quartz-kmp.md

@@ -0,0 +1,23 @@
+# 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.06.3
+```
+
+See `.claude/skills/quartz-integration/SKILL.md` for full integration guide.

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

@@ -1,135 +0,0 @@
----
-name: relay-client
-description: Subscription and filter-assembly patterns for the Amethyst relay client layer in `commons/.../relayClient/`. Use when working with compose-scoped subscriptions (`ComposeSubscriptionManager`, `Subscribable`), filter assemblers (`MetadataFilterAssembler`, `ReactionsFilterAssembler`, `FeedMetadataCoordinator`), preloaders (`MetadataPreloader`, `MetadataRateLimiter`), EOSE managers, or any feature that needs to talk to relays lifecycle-aware from a composable. Complements `nostr-expert` (protocol filter syntax) and `kotlin-coroutines` (callbackFlow patterns).
----
-
-# Relay Client & Subscriptions
-
-The layer between `LocalCache`/`Account` and the raw relay connection. Ensures composables only subscribe to what is visible, deduplicates filters across screens, and rate-limits bulk queries like "fetch metadata for these 200 pubkeys".
-
-## When to Use This Skill
-
-- Adding a new screen that needs events it doesn't already have (write a `FilterAssembler`).
-- Wiring a composable to subscribe on enter / unsubscribe on leave (`ComposeSubscriptionManager`).
-- Preloading metadata / profile pictures for a set of pubkeys (`MetadataPreloader`).
-- Deduplicating identical filters across concurrent screens.
-- Handling EOSE → "we have historical data, stop showing loading" transitions.
-
-## Layout
-
-All under `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/relayClient/`:
-
-```
-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
-│   └── 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"
-    ├── LifecycleAwareKeyDataSourceSubscription.kt
-    └── PrioritizedSubscriptionQueue.kt / SubscriptionPriority.kt
-```
-
-## Core Concept: `Subscribable<T>`
-
-```kotlin
-// composeSubscriptionManagers/ComposeSubscriptionManager.kt
-interface Subscribable<T> {
-    val state: StateFlow<T>
-    fun subscribe()
-    fun unsubscribe()
-}
-```
-
-Every feature-level manager implements or embeds a `Subscribable`. The `MutableComposeSubscriptionManager` reference implementation uses reference-counting so that two screens asking for the same feed share one subscription, and only the last leaver actually closes it.
-
-`ComposeSubscriptionManagerControls.kt` provides `DisposableEffect`-style helpers so composables don't leak subscriptions when the user navigates away or the process backgrounds.
-
-## Typical Flow
-
-```kotlin
-@Composable
-fun ProfileHeader(pubKey: HexKey) {
-    val subscription = rememberSubscribable(pubKey) {
-        MetadataFilterAssembler(setOf(pubKey)).toSubscribable()
-    }
-    LaunchedEffect(pubKey) { subscription.subscribe() }
-    DisposableEffect(pubKey) { onDispose { subscription.unsubscribe() } }
-
-    val metadata by subscription.state.collectAsStateWithLifecycle()
-    // render metadata…
-}
-```
-
-The assembler produces a `Filter` (see `quartz/.../nip01Core/relay/RelayFilters.kt` in the quartz module). The `RelayPool` below dedups, opens subs, emits events to `LocalCache.consume`, and emits EOSE through the eose manager.
-
-## Assemblers
-
-An assembler is a plain class:
-
-```kotlin
-class MetadataFilterAssembler(
-    private val pubKeys: Set<HexKey>,
-) {
-    fun toFilter(): Filter = filter {
-        kinds(MetadataEvent.KIND)
-        authors(pubKeys)
-        limit(pubKeys.size)
-    }
-}
-```
-
-Assemblers stay pure — no state, no I/O. They're the composition seam: `FeedMetadataCoordinator` takes a list of visible notes and assembles a single metadata filter covering every referenced pubkey.
-
-## Preloaders
-
-`MetadataPreloader` is the "I need metadata for 200 pubkeys, but don't melt my CPU or the relay" path. It uses `MetadataRateLimiter` (token bucket) to throttle bulk fetches and group them into relay-friendly chunks.
-
-Related: `amethyst/.../service/images/ImageLoaderSetup.kt` also uses preloaders for blurhash hydration — they're a general pattern, not metadata-specific.
-
-## EOSE Handling
-
-Each subscription tracks "End of Stored Events" per relay. The eose manager in `eoseManagers/` aggregates per-relay EOSE into a single "loading done" boolean that the UI uses to hide spinners. Without aggregation, composables would flicker as individual relays ack.
-
-## Patterns
-
-### DO
-
-- Build one `Subscribable` per feature scope (screen / dialog / card).
-- Dedupe via reference counting — multiple identical subscriptions should share.
-- Use `DisposableEffect` / `LaunchedEffect` to tie sub/unsub to lifecycle.
-- Put the relay `Filter` building in an assembler so the test is trivial.
-- Route bulk metadata through `MetadataPreloader`; don't fire N subscriptions.
-
-### DON'T
-
-- Don't call `RelayPool` / `NostrClient` directly from composables — always through a `Subscribable`.
-- Don't hold a subscription past the composable's lifetime — memory & socket leaks.
-- Don't build ad-hoc filters inline in composables — assemblers only.
-- Don't preload metadata for everything — it's a rate-limited resource and competes with user-visible loads.
-
-## Related
-
-- **Headless / one-shot client ops** (CLI, geode, tests, non-compose code): don't go
-  through `Subscribable` — use the `INostrClient` extension functions in
-  `quartz/…/nip01Core/relay/client/accessories/` (`fetchAll`, `fetchFirst`,
-  `fetchAllPages`, `publishAndConfirm`, `count`, `negentropyReconcile`/`negentropySync`,
-  …). They're extensions, so they don't show up under "usages of `NostrClient`" — see
-  that package's `README.md` for the catalog before writing a raw subscribe/collect loop.
-- `nostr-expert/references/tag-patterns.md` — how tags inform what a filter needs to look for.
-- `kotlin-coroutines/references/relay-patterns.md` — relay pool internals (sibling layer beneath assemblers).
-- `feed-patterns` skill — feeds compose several Subscribables (content + metadata + reactions).
-- `account-state` skill — `Account`'s per-kind flows are themselves consumers of the relay-client layer.

.claude/skills/relay-client/references/filter-assemblers.md

@@ -1,56 +0,0 @@
-# Filter Assemblers
-
-An assembler takes a plain input (a set of pubkeys, a set of note ids, a hashtag, a time range) and produces a relay `Filter`. Assemblers are pure, test-friendly, and composable.
-
-## Concrete Assemblers
-
-Under `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/relayClient/assemblers/`:
-
-- **`MetadataFilterAssembler.kt`** — `class MetadataFilterAssembler(pubKeys: Set<HexKey>)`. Emits a `Filter` for kind 0 over those authors, respecting relay `limit` conventions.
-- **`ReactionsFilterAssembler.kt`** — builds a kind 7 filter with `#e` tag set to the note ids you want reactions for.
-- **`FeedMetadataCoordinator.kt`** — higher-order coordinator: given a list of currently-visible notes, figure out which pubkeys and note ids still need metadata and reactions, and produce one (or two) consolidated filters.
-
-## Subscription Helper
-
-`commons/.../relayClient/subscriptions/KeyDataSourceSubscription.kt` — wraps an assembler plus a "data source" that keeps the assembler's input set up to date. E.g. "the set of pubkeys visible in the current feed" is a data source; when the feed scrolls, the set changes, and the subscription re-emits a new filter.
-
-## RelayFilter DSL (quartz)
-
-The `Filter` type the assemblers produce is defined in `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/RelayFilters.kt`. The DSL roughly looks like:
-
-```kotlin
-filter {
-    kinds(MetadataEvent.KIND)
-    authors(pubKeys)
-    since(TimeUtils.oneHourAgo())
-    until(TimeUtils.now())
-    limit(200)
-    // tag filters
-    tag("e", noteIds)
-    tag("p", pubKeys)
-    tag("t", hashtags)
-}
-```
-
-Builders for individual tag types match the `TagArrayBuilder` conventions (see `nostr-expert/references/tag-patterns.md`).
-
-## Writing a New Assembler
-
-Recipe for `FooFilterAssembler`:
-
-1. Create the file under `assemblers/`.
-2. Define a small immutable `data class FooQuery(...)` holding the inputs — or take constructor parameters directly if simple.
-3. Expose one method: `fun toFilter(): Filter` (or `toFilters()` if you need multiple).
-4. Keep the class deterministic and side-effect-free. No cache reads, no coroutines.
-5. Add a unit test that asserts the `Filter`'s JSON serialization — `quartz`'s filter serialization is stable, so golden tests work.
-
-## Coordinator Pattern
-
-When a feature needs several related filters (content + reactions + zaps + metadata), write a **coordinator** (see `FeedMetadataCoordinator.kt`) that takes higher-level inputs and fans out to several single-purpose assemblers. Coordinators compose; they don't talk to relays themselves.
-
-## Gotchas
-
-- **`limit` matters** on large author sets. Without it, relays may rate-limit or truncate.
-- **Use `since` liberally** to avoid pulling years of history; a feed usually only needs `TimeUtils.oneHourAgo()` or similar.
-- **Don't put filter logic inline in composables** — it ends up duplicated and desynced across screens.
-- **`toFilter()` should be cheap** — assemblers may be called on every recomposition until you wrap them in a subscription.

.claude/skills/relay-client/references/preloaders.md

@@ -1,46 +0,0 @@
-# Preloaders & Rate Limiting
-
-Bulk-fetch patterns for data that needs to come in over relays but isn't directly user-requested (e.g. "hydrate metadata for 200 pubkeys the user might scroll past", "prefetch images before a gallery opens").
-
-## Files
-
-Under `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/relayClient/preload/`:
-
-- **`MetadataPreloader.kt`** — `class MetadataPreloader(rateLimiter: MetadataRateLimiter, ...)`. Accepts "I need metadata for pubkeys X, Y, Z" requests and batches them into relay-friendly subscriptions.
-- **`MetadataRateLimiter.kt`** — token-bucket-style limiter. Caps how many metadata fetches are in-flight simultaneously so relays don't rate-limit the client.
-
-Additional preloader seams worth knowing:
-- `MetadataPreloader` is itself called by `FeedMetadataCoordinator` (`assemblers/FeedMetadataCoordinator.kt`) — feeds generate the bulk request set.
-- Image prefetching uses an `ImagePrefetcher` interface (see `preload/MetadataPreloader.kt` for the contract). Implementations live in platform code: Android uses Coil's prefetch API, Desktop uses the Skia loader.
-
-## When to Use a Preloader
-
-- You have a **set** of pubkeys/note ids and you want them in `LocalCache` "soon" but the user isn't waiting on any single one.
-- You need to **coalesce** many small requests from different composables into one relay subscription.
-- You care about **backpressure** — a normal `Subscribable` fires immediately; a preloader defers and batches.
-
-If the user is looking at something right now, use a `Subscribable` instead (`MetadataFilterAssembler`). Preloaders are for "might need this".
-
-## Typical Flow
-
-```kotlin
-// Inside a coordinator, e.g. when a feed list emits the set of visible pubkeys
-metadataPreloader.request(pubKeys)
-// MetadataPreloader deduplicates against what it has already scheduled, clips
-// with the rate limiter, and eventually opens a relay sub through the normal
-// ComposeSubscriptionManager plumbing.
-```
-
-The preloader is process-wide (one instance, injected where needed). Don't instantiate per-screen — that defeats the deduplication.
-
-## Gotchas
-
-- **Rate limits are cooperative.** The limiter throttles the client; relays enforce their own limits. If you see `NOTICE: rate-limited` frames, the preloader's budget is too generous — lower the bucket size.
-- **Don't preload sensitive kinds** (encrypted DMs, gift-wrapped events) — they aren't speculatively useful and waste bandwidth.
-- **Preload scope should match visibility scope.** When a screen unmounts, cancel its preload requests, otherwise you keep fetching for off-screen data.
-- **`MetadataRateLimiter` is not a general rate limiter.** Reuse it only for metadata-like patterns. For publishing rate limits use relay-specific logic in the signer path.
-
-## Related
-
-- `filter-assemblers.md` — the atomic unit the preloader assembles.
-- `kotlin-coroutines/references/relay-patterns.md` — how the underlying relay pool handles concurrent subscriptions.

.dockerignore

@@ -1,17 +0,0 @@
-# Keep the Docker build context small + reproducible: exclude VCS metadata,
-# Gradle/build outputs, IDE files, and local caches. The build stage runs a
-# fresh `./gradlew :geode:installDist` inside the image, so nothing under any
-# build/ directory needs to travel with the context.
-.git
-.github
-**/build/
-.gradle/
-**/.gradle/
-.idea/
-*.iml
-.kotlin/
-**/.kotlin/
-local.properties
-# Docs + non-geode app modules aren't needed to build the relay, but the Gradle
-# settings reference every module, so we can't drop the module source trees;
-# only their build artifacts (covered above) are excluded.

.git-hooks/pre-push

@@ -12,24 +12,8 @@ echo "$JAVA_HOME"
 echo "$(java -version)"
 echo "Running test... "
 
-# Single-variant pre-push tests. `./gradlew test` would compile six Android
-# variants of :amethyst (play/fdroid × debug/release/benchmark) plus full
-# native-libs merging per variant — ~6× the work of one variant. CI runs the
-# multi-flavor matrix on push to main; pre-push only needs one happy path.
-TASKS=(
-    :quartz:jvmTest
-    :commons:jvmTest
-    :nestsClient:jvmTest
-    :quic:jvmTest
-    :amethyst:testPlayDebugUnitTest
-    :cli:test
-)
+./gradlew test --quiet
 
-if [ "${CLAUDE_CODE_REMOTE:-}" = "true" ]; then
-    ./gradlew "${TASKS[@]}" --quiet
-else
-    ./gradlew "${TASKS[@]}" :desktopApp:test --quiet
-fi
 status=$?
 
 if [ "$status" = 0 ] ; then

.gitattributes

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

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,68 +0,0 @@
-<!--
-Thanks for contributing to Amethyst! Before opening this PR, please skim
-CONTRIBUTING.md — especially the "Proof of testing" and "Interoperability
-tests" sections if you are not a regular contributor to this repo.
-
-Delete any section below that doesn't apply.
--->
-
-## Summary
-
-<!-- 1–3 sentences. What changed and why. Not "what files changed" — the
-diff already shows that. -->
-
-## Test plan
-
-<!-- Required. What did you actually run, on what platform, with what result?
-"CI is green" is necessary but not sufficient — show the new path firing.
-
-For UI changes, attach screenshots (light + dark) or a short recording.
-For Android: device model + Android version. For Desktop: OS + window size.
-For build/packaging changes: paste the `./gradlew` command + tail of output.
-
-If you are NOT a regular contributor to this repo, this section is required
-regardless of how small the change is — see CONTRIBUTING.md § Proof of
-testing. -->
-
-- [ ] Ran `./gradlew spotlessApply` — repo is formatted
-- [ ] Ran `./gradlew test` (or the relevant module's tests)
-- [ ] Manually exercised the change (see notes below)
-
-Notes / screenshots:
-
-<!-- paste here -->
-
-## Interop suites
-
-<!-- The interop suites listed in CONTRIBUTING.md § Interoperability tests
-are NOT run in CI. If your change touches the relevant code paths, run them
-locally and tick the box. If your change can't possibly affect them
-(docs-only, UI-only on unrelated screens, etc.), tick "N/A". -->
-
-- [ ] N/A — change can't affect wire bytes / decoded audio / MLS state / DM envelopes
-- [ ] Marmot / MLS — `cli/tests/marmot/marmot-interop-headless.sh` (NIP-EE / `whitenoise-rs`)
-- [ ] NIP-17 DM — `cli/tests/dm/dm-interop-headless.sh`
-- [ ] Audio rooms manual — `cli/tests/nests/nests-interop.sh` (Amethyst ↔ nostrnests.com)
-- [ ] MoQ-lite hang-tier — `:nestsClient:jvmTest -DnestsHangInterop=true`
-- [ ] MoQ-lite browser-tier — `:nestsClient:jvmTest -DnestsBrowserInterop=true`
-- [ ] QUIC interop-runner — `quic/interop/run-matrix.sh -s {aioquic,picoquic,quic-go,quinn}`
-
-## AI assistance
-
-<!-- Optional disclosure. We accept AI-assisted PRs (Claude Code, Copilot,
-Cursor, Codex, etc.) under the same rules as human PRs — see
-CONTRIBUTING.md § Human and AI contributions. A one-line note here is
-appreciated when an assistant did the bulk of the diff. -->
-
-- [ ] Drafted with AI assistance, manually reviewed and tested
-- [ ] Written by hand
-
-If "Drafted with AI assistance" is ticked, also read
-[`CONTRIBUTING-WITH-AI.md`](CONTRIBUTING-WITH-AI.md) for the additional
-gates that apply to AI-authored PRs.
-
-## License
-
-- [ ] By submitting this PR, I agree to license my contribution under the
-      MIT license. Any code I did not author personally carries its
-      original license header.

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

@@ -1,49 +0,0 @@
-name: Assert Stable Release
-description: >-
-  Defense-in-depth guard for package-manager bump workflows. Re-validates
-  tag format, prerelease flag, and draft status before invoking third-party
-  actions that hold write credentials to external package manager repos.
-
-inputs:
-  tag:
-    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)"
-    required: false
-    default: "false"
-  is_draft:
-    description: "Whether the release is a draft (empty string treated as false)"
-    required: false
-    default: "false"
-
-runs:
-  using: composite
-  steps:
-    - name: Assert release is stable
-      shell: bash
-      env:
-        TAG: ${{ inputs.tag }}
-        IS_PRERELEASE: ${{ inputs.is_prerelease }}
-        IS_DRAFT: ${{ inputs.is_draft }}
-      run: |
-        set -euo pipefail
-        echo "tag=$TAG prerelease=$IS_PRERELEASE draft=$IS_DRAFT"
-
-        # Stable = exactly vMAJOR.MINOR.PATCH; reject everything else.
-        if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-          echo "::error::Tag $TAG does not match stable vMAJOR.MINOR.PATCH format; refusing bump"
-          exit 1
-        fi
-
-        # Draft releases must never trigger bumps.
-        if [[ "$IS_DRAFT" == "true" ]]; then
-          echo "::error::Release is draft; refusing bump"
-          exit 1
-        fi
-
-        # Prerelease flag cross-check (belt-and-suspenders with workflow-level `if:`).
-        if [[ "$IS_PRERELEASE" == "true" ]]; then
-          echo "::error::Release is prerelease; refusing bump"
-          exit 1
-        fi

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

@@ -1,90 +0,0 @@
-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/actions/resolve-release/action.yml

@@ -1,73 +0,0 @@
-name: Resolve Release
-description: >-
-  Resolve a bump workflow's target tag and that release's real published state.
-  Companion to assert-stable-release: this one FETCHES the facts, that one
-  ENFORCES them. Split so the enforcement stays a pure function of its inputs.
-
-  Handles both entry points of the bump workflows:
-    - workflow_run  -> tag comes from the triggering run's head_branch
-    - workflow_dispatch (manual recovery) -> tag comes from the input
-  In both cases draft/prerelease are read back from the GitHub API rather than
-  inferred, so a draft or prerelease can never slip through to a third-party
-  package repo just because the trigger payload lacked the flags.
-
-inputs:
-  tag:
-    description: "Release tag to resolve (e.g. vX.Y.Z)"
-    required: true
-  github_token:
-    description: "Token used to read the release via the GH API"
-    required: true
-
-outputs:
-  tag:
-    description: "The resolved tag, verbatim (e.g. v1.13.1)"
-    value: ${{ steps.resolve.outputs.tag }}
-  ver:
-    description: "The tag with the leading 'v' stripped (e.g. 1.13.1)"
-    value: ${{ steps.resolve.outputs.ver }}
-  is_prerelease:
-    description: "'true' if the GH Release is flagged prerelease"
-    value: ${{ steps.resolve.outputs.is_prerelease }}
-  is_draft:
-    description: "'true' if the GH Release is still a draft"
-    value: ${{ steps.resolve.outputs.is_draft }}
-
-runs:
-  using: composite
-  steps:
-    - name: Resolve tag and release state
-      id: resolve
-      shell: bash
-      env:
-        TAG: ${{ inputs.tag }}
-        GH_TOKEN: ${{ inputs.github_token }}
-        REPO: ${{ github.repository }}
-      run: |
-        set -euo pipefail
-
-        if [[ -z "$TAG" ]]; then
-          echo "::error::No tag to resolve (neither workflow_run.head_branch nor the dispatch input was set)"
-          exit 1
-        fi
-
-        # A missing release here is a real fault, not something to paper over:
-        # every caller is about to publish this version to an external package
-        # manager. Fail loudly and let the caller's Report-failure step file it.
-        if ! META=$(gh release view "$TAG" --repo "$REPO" --json isDraft,isPrerelease 2>&1); then
-          echo "::error::No GH Release found for tag $TAG in $REPO -- refusing to bump"
-          echo "$META"
-          exit 1
-        fi
-
-        IS_DRAFT=$(echo "$META" | jq -r '.isDraft')
-        IS_PRERELEASE=$(echo "$META" | jq -r '.isPrerelease')
-
-        {
-          echo "tag=$TAG"
-          echo "ver=${TAG#v}"
-          echo "is_draft=$IS_DRAFT"
-          echo "is_prerelease=$IS_PRERELEASE"
-        } >> "$GITHUB_OUTPUT"
-
-        echo "resolved tag=$TAG ver=${TAG#v} draft=$IS_DRAFT prerelease=$IS_PRERELEASE"

.github/dependabot.yml

@@ -1,17 +0,0 @@
-version: 2
-updates:
-  # Auto-update SHA-pinned GitHub Actions across all workflows.
-  # Required for supply-chain safety — SHA pins only age well with active bumps.
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: monthly
-    labels:
-      - release-ops
-      - dependencies
-    commit-message:
-      prefix: chore(actions)
-    groups:
-      actions:
-        patterns:
-          - "*"

.github/workflows/build.yml

@@ -19,300 +19,180 @@ jobs:
     timeout-minutes: 15
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
+        uses: actions/setup-java@v5
         with:
-          distribution: 'temurin'
+          distribution: 'zulu'
           java-version: 21
 
-      # Remote Gradle build cache: writes on push to main, reads on PRs and
-      # other branches. Caches both `~/.gradle/caches/` and individual task
-      # outputs, so dependency-only changes hit the cache and skip recompiling
-      # downstream modules / re-merging native libs (~600MB of work on
-      # :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@v6
+      - name: Cache gradle
+        uses: actions/cache@v5
         with:
-          cache-read-only: ${{ github.ref != 'refs/heads/main' }}
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
 
       - name: Linter (gradle)
-        run: ./gradlew spotlessCheck :quartz:verifyKmpPurity :commons:verifyKmpPurity
+        run: ./gradlew spotlessCheck
 
-  build-desktop:
+  test:
     needs: lint
     strategy:
       fail-fast: false
       matrix:
-        include:
-          - os: ubuntu-latest
-            desktop-task: packageDeb
-            desktop-artifact-name: Desktop Linux DEB
-            desktop-artifact-path: desktopApp/build/compose/binaries/main/deb/*.deb
-          - os: macos-latest
-            desktop-task: packageDmg
-            desktop-artifact-name: Desktop macOS DMG
-            desktop-artifact-path: desktopApp/build/compose/binaries/main/dmg/*.dmg
-          - os: windows-latest
-            desktop-task: packageMsi
-            desktop-artifact-name: Desktop Windows MSI
-            desktop-artifact-path: desktopApp/build/compose/binaries/main/msi/*.msi
+        os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 60
+    timeout-minutes: 30
     defaults:
       run:
         shell: bash
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
+        uses: actions/setup-java@v5
         with:
-          distribution: 'temurin'
+          distribution: 'zulu'
           java-version: 21
 
-      - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v6
+      - name: Cache gradle
+        uses: actions/cache@v5
         with:
-          cache-read-only: ${{ github.ref != 'refs/heads/main' }}
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
 
-      # 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 (gradle)
+        run: ./gradlew test --no-daemon
 
-      - name: Test + Build Desktop (gradle)
-        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
-      # releases can install the uploaded artifact.
-      - name: Relax libicu dependency in .deb
-        if: matrix.desktop-task == 'packageDeb'
-        run: |
-          set -euo pipefail
-          chmod +x scripts/relax-deb-libicu.sh
-          scripts/relax-deb-libicu.sh desktopApp/build/compose/binaries/main/deb/*.deb
-
-      - name: Upload Desktop Distribution
-        uses: actions/upload-artifact@v7
-        with:
-          name: ${{ matrix.desktop-artifact-name }}
-          path: ${{ matrix.desktop-artifact-path }}
-
-  # geode (the standalone Nostr relay) is JVM-only, so it runs in its own job
-  # rather than the build-desktop matrix — one runner suffices (no reason to test
-  # a platform-independent module 3× across the desktop OS matrix). Isolating it
-  # also keeps its default suite's CPU-heavy throughput benchmarks (a 1M-event
-  # mirror sync, WireReqFloor, NegentropyServerReconcile) from contending with the
-  # timing-sensitive quartz relay-client tests under org.gradle.parallel — that
-  # contention flakes tests like NostrClientReqBypassingRelayLimitsTest.
-  test-geode:
-    needs: lint
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
-        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' }}
-
-      - name: Test geode (gradle)
-        run: ./gradlew :geode:test
-
-      - name: Upload geode Test Reports
-        uses: actions/upload-artifact@v7
-        if: failure()
-        with:
-          name: geode Test Reports
-          path: geode/build/reports
-
-  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@v7
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
-        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
-    timeout-minutes: 60
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
-        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' }}
-
-      # Lint + focused unit tests + benchmark assembly in one Gradle invocation.
-      # Previously: one invocation for lint, one for `test` (which compiled all
-      # six amethyst variants × all flavors), one for `assembleBenchmark`
-      # (re-walking the same task graph). Combining them keeps the daemon hot
-      # across phases and lets task-level dedup (e.g. compileKotlin) only
-      # happen once.
-      #
-      # `-PdisableAbiSplits=true` produces a single non-split APK per
-      # (flavor, buildType) instead of 5 (4 ABIs + universal). The CI only
-      # uploads the universal-equivalent benchmark APK; per-ABI splits were
-      # being built and discarded, costing ~600MB of stripped_native_libs
-      # intermediates and several minutes per run.
-      #
-      # Test scope: only Debug unit tests for amethyst. The release/benchmark
-      # variants are compile-equivalent for unit-test purposes; running all six
-      # adds ~5× the kotlinc work without catching new defects on PRs. Push to
-      # main still gets the full test matrix via the production-build path.
-      - name: Test + Build Android (gradle)
-        run: |
-          ./gradlew \
-            :amethyst:lintFdroidBenchmark \
-            :amethyst:lintPlayBenchmark \
-            :quartz:jvmTest \
-            :commons:jvmTest \
-            :nestsClient:jvmTest \
-            :amethyst:testFdroidDebugUnitTest \
-            :amethyst:testPlayDebugUnitTest \
-            :amethyst:assembleBenchmark \
-            -PdisableAbiSplits=true
-
-      - name: Upload Android Lint Reports
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: Android Lint Reports
-          path: amethyst/build/reports/lint-results-*.html
-
-      # Publishes the JUnit XML produced by the unit-test tasks above as inline
-      # annotations plus a job summary. Replaces asadmansr/android-test-report-action,
-      # which was abandoned (last release 2020) and rebuilt an EOL Ubuntu 18.04 +
-      # Python 2 Docker image on every run — bionic's apt archives have since gone
-      # unreliable and broke this job. Pinned to a commit SHA (not the movable
-      # v6.4.2 tag) to close the supply-chain hole. annotate_only avoids needing
-      # `checks: write`, so it keeps working on pull requests from forks (where the
-      # GITHUB_TOKEN is read-only). fail_on_failure preserves the old step's
-      # behavior of marking the job red when a test fails.
       - name: Android Test Report
-        uses: mikepenz/action-junit-report@d9f48fc87bc235f7e214acf696ca5abc0a986f16 # v6.4.2
-        if: always()
-        with:
-          report_paths: '**/build/test-results/**/TEST-*.xml'
-          annotate_only: true
-          detailed_summary: true
-          fail_on_failure: true
+        uses: asadmansr/android-test-report-action@v1.2.0
+        if: ${{ always() && matrix.os == 'ubuntu-latest' }}
 
       - name: Upload Test Results
-        uses: actions/upload-artifact@v7
-        if: failure()
+        uses: actions/upload-artifact@v6
+        if: ${{ always() && matrix.os == 'ubuntu-latest' }}
         with:
           name: Test Reports
           path: amethyst/build/reports
 
-      # With -PdisableAbiSplits=true the APK is named without the ABI/universal
-      # suffix: amethyst-<flavor>-benchmark.apk. Glob both forms so this still
-      # works if a contributor runs CI on a branch that doesn't pass the flag.
+  build-android:
+    needs: 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: 'zulu'
+          java-version: 21
+
+      - name: Cache gradle
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Build APK (gradle)
+        run: ./gradlew assembleDebug
+
+      - name: Upload Play APK
+        uses: actions/upload-artifact@v6
+        with:
+          name: Play Debug APK
+          path: amethyst/build/outputs/apk/play/debug/amethyst-play-universal-debug.apk
+
+      - name: Upload FDroid APK
+        uses: actions/upload-artifact@v6
+        with:
+          name: FDroid Debug APK
+          path: amethyst/build/outputs/apk/fdroid/debug/amethyst-fdroid-universal-debug.apk
+
+      - name: Build Benchmark APK (gradle)
+        run: ./gradlew assembleBenchmark
+
       - name: Upload Play APK Benchmark
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v6
         with:
           name: Play Benchmark APK
-          path: |
-            amethyst/build/outputs/apk/play/benchmark/amethyst-play-benchmark.apk
-            amethyst/build/outputs/apk/play/benchmark/amethyst-play-universal-benchmark.apk
+          path: amethyst/build/outputs/apk/play/benchmark/amethyst-play-universal-benchmark.apk
 
       - name: Upload FDroid APK Benchmark
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v6
         with:
           name: FDroid Benchmark APK
-          path: |
-            amethyst/build/outputs/apk/fdroid/benchmark/amethyst-fdroid-benchmark.apk
-            amethyst/build/outputs/apk/fdroid/benchmark/amethyst-fdroid-universal-benchmark.apk
+          path: amethyst/build/outputs/apk/fdroid/benchmark/amethyst-fdroid-universal-benchmark.apk
 
       - name: Upload Compose Reports
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v6
         with:
           name: Compose Reports
           path: amethyst/build/compose_compiler
+
+  build-desktop:
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            task: packageDeb
+            artifact-name: Desktop Linux DEB
+            artifact-path: desktopApp/build/compose/binaries/main/deb/*.deb
+          - os: macos-latest
+            task: packageDmg
+            artifact-name: Desktop macOS DMG
+            artifact-path: desktopApp/build/compose/binaries/main/dmg/*.dmg
+          - os: windows-latest
+            task: packageMsi
+            artifact-name: Desktop Windows MSI
+            artifact-path: desktopApp/build/compose/binaries/main/msi/*.msi
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'zulu'
+          java-version: 21
+
+      - name: Cache gradle
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Build Desktop Distribution
+        run: ./gradlew :desktopApp:${{ matrix.task }}
+
+      - name: Upload Desktop Distribution
+        uses: actions/upload-artifact@v6
+        with:
+          name: ${{ matrix.artifact-name }}
+          path: ${{ matrix.artifact-path }}

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

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

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

@@ -1,165 +0,0 @@
-name: Bump Homebrew Formula (geode relay)
-
-# Sibling of bump-homebrew-formula.yml (the amy CLI). Same mechanism, different
-# artifact:
-#   - bump-homebrew-formula.yml       -> Formula `amy`   (the headless CLI)
-#   - this workflow                   -> Formula `geode` (the standalone relay)
-#
-# After a stable release, download the published `geode-<version>-jvm.tar.gz`
-# bundle, compute its sha256, and open a PR that syncs
-# `geode/packaging/homebrew/geode.rb`'s url + sha256 to that release. Keeping the
-# in-repo reference formula accurate makes the eventual homebrew-core submission a
-# copy-paste.
-#
-# What it does NOT do yet: open a PR against Homebrew/homebrew-core. `brew
-# bump-formula-pr` can only bump a formula that already EXISTS in homebrew-core,
-# and `geode` has never been submitted there — that first submission is a manual,
-# human-reviewed new-formula PR (the one-time bootstrap). Once it lands, wire the
-# auto-bump here — see the "TODO(bootstrap)" note at the bottom of this file.
-
-# Trigger: after "Create Release Assets" succeeds for a tag push. NOT
-# `release: types: [released]` — that event never fires, because the release is
-# created by create-release.yml under GITHUB_TOKEN and GitHub suppresses
-# workflow-triggering events for it. See the full note in bump-homebrew.yml.
-on:
-  workflow_run:
-    workflows: ["Create Release Assets"]
-    types: [completed]
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag to sync (for manual recovery)'
-        required: true
-        type: string
-
-permissions:
-  contents: write
-  pull-requests: write
-  # The "Report failure" step opens a [release-ops] issue via
-  # github.rest.issues.create, which needs issues:write.
-  issues: write
-
-concurrency:
-  # Serialize per tag; do not cancel in-progress runs.
-  group: bump-homebrew-geode-formula-${{ github.event.workflow_run.head_branch || inputs.tag }}
-  cancel-in-progress: false
-
-jobs:
-  sync-formula:
-    # See bump-homebrew.yml for why these three conditions: successful, tag-push
-    # (not a dry-run dispatch), v-prefixed. Exact format enforced downstream.
-    if: >-
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.workflow_run.conclusion == 'success' &&
-       github.event.workflow_run.event == 'push' &&
-       startsWith(github.event.workflow_run.head_branch, 'v'))
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Resolve release
-        id: rel
-        uses: ./.github/actions/resolve-release
-        with:
-          tag: ${{ github.event.workflow_run.head_branch || inputs.tag }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Re-assert stable release
-        uses: ./.github/actions/assert-stable-release
-        with:
-          tag: ${{ steps.rel.outputs.tag }}
-          is_prerelease: ${{ steps.rel.outputs.is_prerelease }}
-          is_draft: ${{ steps.rel.outputs.is_draft }}
-
-      - name: Download jvm bundle and compute sha256
-        id: asset
-        run: |
-          set -euo pipefail
-          TAG="${{ steps.rel.outputs.tag }}"
-          VER="${{ steps.rel.outputs.ver }}"
-          URL="https://github.com/${{ github.repository }}/releases/download/${TAG}/geode-${VER}-jvm.tar.gz"
-          echo "Fetching $URL"
-          # workflow_run fires only after every upload leg has finished, so the
-          # asset should already be there. Retry anyway for release-CDN
-          # propagation (mirrors the repo's push/pull retry ethos).
-          ok=0
-          for i in 1 2 3 4 5; do
-            if curl -fsSL -o geode-jvm.tar.gz "$URL"; then ok=1; break; fi
-            wait=$(( 2 ** i ))
-            echo "attempt $i failed; retrying in ${wait}s"
-            sleep "$wait"
-          done
-          [[ "$ok" == 1 ]] || { echo "::error::could not download $URL"; exit 1; }
-          test -s geode-jvm.tar.gz
-          SHA=$(shasum -a 256 geode-jvm.tar.gz | awk '{print $1}')
-          echo "url=$URL" >> "$GITHUB_OUTPUT"
-          echo "sha256=$SHA" >> "$GITHUB_OUTPUT"
-          echo "geode-${VER}-jvm.tar.gz -> $SHA"
-
-      - name: Update reference formula
-        run: |
-          set -euo pipefail
-          FORMULA=geode/packaging/homebrew/geode.rb
-          URL="${{ steps.asset.outputs.url }}"
-          SHA="${{ steps.asset.outputs.sha256 }}"
-          # Rewrite the two indented lines in the formula block. Anchoring on the
-          # 2-space indent avoids touching the header comment's example curl url.
-          sed -i -E "s|^(  url ).*|\1\"${URL}\"|" "$FORMULA"
-          sed -i -E "s|^(  sha256 ).*|\1\"${SHA}\"|" "$FORMULA"
-          echo "----- $FORMULA -----"
-          grep -E "^  (url|sha256) " "$FORMULA"
-
-      - name: Open or update the formula-sync PR
-        # peter-evans/create-pull-request is MIT-licensed CI-only tooling (not
-        # linked into any shipped artifact). It no-ops when there is no diff.
-        uses: peter-evans/create-pull-request@v8
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          base: main
-          branch: chore/bump-geode-formula-${{ steps.rel.outputs.tag }}
-          add-paths: geode/packaging/homebrew/geode.rb
-          commit-message: 'chore: sync geode Homebrew formula to ${{ steps.rel.outputs.tag }}'
-          title: 'chore: sync geode Homebrew formula to ${{ steps.rel.outputs.tag }}'
-          body: |
-            Auto-synced `geode/packaging/homebrew/geode.rb` to the
-            `${{ steps.rel.outputs.tag }}` release:
-
-            - `url`    -> `${{ steps.asset.outputs.url }}`
-            - `sha256` -> `${{ steps.asset.outputs.sha256 }}`
-
-            Opened by `.github/workflows/bump-homebrew-geode-formula.yml`. Merge to
-            keep the reference formula ready for the homebrew-core submission/bump.
-
-      # TODO(bootstrap): once `geode` is accepted into Homebrew/homebrew-core,
-      # add a LOCAL script mirroring scripts/bump-homebrew-cask.sh that runs
-      # `brew bump-formula-pr geode --url=<url> --sha256=<sha>` from a
-      # maintainer's machine. Do NOT wire that into CI — it needs a classic
-      # `repo`-scoped PAT, which as a CI secret would hand write access to this
-      # repo to anyone with push access. See BUILDING.md § Homebrew cask.
-
-      - name: Report failure
-        if: failure()
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const tag = context.payload.workflow_run?.head_branch || context.payload.inputs?.tag || 'unknown';
-            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
-            await github.rest.issues.create({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              title: `[release-ops] bump-homebrew-geode-formula failed for ${tag}`,
-              body: [
-                `geode Homebrew formula sync failed for release \`${tag}\`.`,
-                ``,
-                `- Run: ${runUrl}`,
-                `- Channel: Homebrew Formula (\`geode\` relay)`,
-                ``,
-                `Recovery options:`,
-                `1. Re-run the workflow once the underlying issue is fixed`,
-                `2. Manually update \`geode/packaging/homebrew/geode.rb\` (url + sha256) from the release asset`,
-                `3. Check the release actually published \`geode-${tag.replace(/^v/, '')}-jvm.tar.gz\``
-              ].join('\n'),
-              labels: ['release-ops', 'bug']
-            });

.github/workflows/bump-homebrew.yml

@@ -1,181 +0,0 @@
-name: Sync Homebrew Cask Reference
-
-# Sibling of bump-homebrew-formula.yml (amy) and bump-homebrew-geode-formula.yml
-# (geode). Same mechanism, third artifact:
-#   - this workflow -> Cask `amethyst-nostr` (the desktop GUI app / DMG)
-#
-# What it does: after a stable release, download the published macOS DMG, assert
-# it is notarized + stapled, compute its sha256, and open a PR syncing
-# `desktopApp/packaging/homebrew/amethyst-nostr.rb` to that release.
-#
-# What it does NOT do: open a PR against Homebrew/homebrew-cask. That step is
-# deliberately MANUAL and runs on a maintainer's machine —
-# `scripts/bump-homebrew-cask.sh`. Reason: `brew bump-cask-pr` forks
-# homebrew-cask into the token owner's account, which requires a CLASSIC PAT
-# with the `repo` scope; that scope grants write to every repository the account
-# can reach, and stored as a CI secret it would be usable by anyone with push
-# access to this repo. Keeping it in a maintainer's shell instead of a CI secret
-# removes that blast radius entirely, at the cost of one command per release.
-# See BUILDING.md § Homebrew cask.
-#
-# Consequence: this workflow needs NO external token. GITHUB_TOKEN is enough,
-# exactly like the two formula workflows.
-#
-# Trigger: after "Create Release Assets" succeeds for a tag push. NOT
-# `release: types: [released]` — that event never fires, because the release is
-# created by create-release.yml under GITHUB_TOKEN and GitHub suppresses
-# workflow-triggering events for it. See the note in bump-homebrew-formula.yml.
-on:
-  workflow_run:
-    workflows: ["Create Release Assets"]
-    types: [completed]
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag to sync (for manual recovery)'
-        required: true
-        type: string
-
-permissions:
-  contents: write
-  pull-requests: write
-  # The "Report failure" step opens a [release-ops] issue via
-  # github.rest.issues.create, which needs issues:write.
-  issues: write
-
-concurrency:
-  # Serialize per tag; do not cancel in-progress runs.
-  group: bump-homebrew-${{ github.event.workflow_run.head_branch || inputs.tag }}
-  cancel-in-progress: false
-
-jobs:
-  sync-cask:
-    # See bump-homebrew-formula.yml for why these three conditions: successful,
-    # tag-push (not a dry-run dispatch), v-prefixed. Format enforced downstream.
-    if: >-
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.workflow_run.conclusion == 'success' &&
-       github.event.workflow_run.event == 'push' &&
-       startsWith(github.event.workflow_run.head_branch, 'v'))
-    # macOS runner: `xcrun stapler` is the only way to verify the notarization
-    # ticket, and shipping an unnotarized DMG to the cask is the failure mode
-    # this whole channel is most exposed to.
-    runs-on: macos-latest
-    timeout-minutes: 20
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Resolve release
-        id: rel
-        uses: ./.github/actions/resolve-release
-        with:
-          tag: ${{ github.event.workflow_run.head_branch || inputs.tag }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Re-assert stable release
-        uses: ./.github/actions/assert-stable-release
-        with:
-          tag: ${{ steps.rel.outputs.tag }}
-          is_prerelease: ${{ steps.rel.outputs.is_prerelease }}
-          is_draft: ${{ steps.rel.outputs.is_draft }}
-
-      - name: Download DMG, verify notarization, compute sha256
-        id: asset
-        run: |
-          set -euo pipefail
-          TAG="${{ steps.rel.outputs.tag }}"
-          VER="${{ steps.rel.outputs.ver }}"
-          URL="https://github.com/${{ github.repository }}/releases/download/${TAG}/amethyst-desktop-${VER}-macos-arm64.dmg"
-          echo "Fetching $URL"
-          # workflow_run fires only after every upload leg has finished, so the
-          # asset should already be there. Retry anyway for release-CDN
-          # propagation (mirrors the repo's push/pull retry ethos).
-          ok=0
-          for i in 1 2 3 4 5; do
-            if curl -fsSL -o amethyst.dmg "$URL"; then ok=1; break; fi
-            wait=$(( 2 ** i ))
-            echo "attempt $i failed; retrying in ${wait}s"
-            sleep "$wait"
-          done
-          [[ "$ok" == 1 ]] || { echo "::error::could not download $URL"; exit 1; }
-          test -s amethyst.dmg
-
-          # A cask must point at a notarized+stapled DMG or every user hits a
-          # Gatekeeper block. Refuse to advertise one that is not.
-          if ! xcrun stapler validate amethyst.dmg; then
-            echo "::error::${TAG} DMG has no stapled notarization ticket -- refusing to sync the cask. Check the notarizeReleaseDmg step in create-release.yml."
-            exit 1
-          fi
-
-          SHA=$(shasum -a 256 amethyst.dmg | awk '{print $1}')
-          echo "sha256=$SHA" >> "$GITHUB_OUTPUT"
-          echo "amethyst-desktop-${VER}-macos-arm64.dmg -> $SHA"
-
-      - name: Update reference cask
-        run: |
-          set -euo pipefail
-          CASK=desktopApp/packaging/homebrew/amethyst-nostr.rb
-          VER="${{ steps.rel.outputs.ver }}"
-          SHA="${{ steps.asset.outputs.sha256 }}"
-          # Anchor on the 2-space indent so the header comment's example lines
-          # are never touched.
-          sed -i '' -E "s|^(  version ).*|\1\"${VER}\"|" "$CASK"
-          sed -i '' -E "s|^(  sha256 ).*|\1\"${SHA}\"|" "$CASK"
-          echo "----- $CASK -----"
-          grep -E "^  (version|sha256) " "$CASK"
-
-      - name: Open or update the cask-sync PR
-        # peter-evans/create-pull-request is MIT-licensed CI-only tooling (not
-        # linked into any shipped artifact). It no-ops when there is no diff.
-        uses: peter-evans/create-pull-request@v8
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          base: main
-          branch: chore/bump-amethyst-cask-${{ steps.rel.outputs.tag }}
-          add-paths: desktopApp/packaging/homebrew/amethyst-nostr.rb
-          commit-message: 'chore: sync amethyst-nostr cask to ${{ steps.rel.outputs.tag }}'
-          title: 'chore: sync amethyst-nostr cask to ${{ steps.rel.outputs.tag }}'
-          body: |
-            Auto-synced `desktopApp/packaging/homebrew/amethyst-nostr.rb` to the
-            `${{ steps.rel.outputs.tag }}` release:
-
-            - `version` -> `${{ steps.rel.outputs.ver }}`
-            - `sha256`  -> `${{ steps.asset.outputs.sha256 }}`
-
-            The DMG was verified notarized + stapled before this PR was opened.
-
-            **Merge this, then push it upstream from a maintainer machine:**
-
-            ```bash
-            scripts/bump-homebrew-cask.sh ${{ steps.rel.outputs.tag }}
-            ```
-
-            That step is manual on purpose — it needs a classic PAT with the
-            `repo` scope, which is deliberately NOT stored as a CI secret. See
-            BUILDING.md § Homebrew cask.
-
-      - name: Report failure
-        if: failure()
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const tag = context.payload.workflow_run?.head_branch || context.payload.inputs?.tag || 'unknown';
-            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
-            await github.rest.issues.create({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              title: `[release-ops] sync-homebrew-cask failed for ${tag}`,
-              body: [
-                `amethyst-nostr cask sync failed for release \`${tag}\`.`,
-                ``,
-                `- Run: ${runUrl}`,
-                `- Channel: Homebrew Cask (\`amethyst-nostr\`)`,
-                ``,
-                `Recovery options:`,
-                `1. Re-run the workflow once the underlying issue is fixed`,
-                `2. Check the DMG is notarized: \`xcrun stapler validate\` on the release asset`,
-                `3. Manually update \`desktopApp/packaging/homebrew/amethyst-nostr.rb\` (version + sha256)`
-              ].join('\n'),
-              labels: ['release-ops', 'bug']
-            });

.github/workflows/bump-winget.yml

@@ -1,214 +0,0 @@
-name: Sync Winget Manifest Reference
-
-# Fourth sibling of the three Homebrew sync workflows, same shape:
-#   bump-homebrew-formula.yml       -> Formula `amy`
-#   bump-homebrew-geode-formula.yml -> Formula `geode`
-#   bump-homebrew.yml               -> Cask    `amethyst-nostr`
-#   this workflow                   -> Winget  `VitorPamplona.Amethyst`
-#
-# What it does: after a stable release, download the published Windows MSI,
-# compute its sha256, read its ProductCode, and open a PR syncing
-# desktopApp/packaging/winget/*.yaml to that release.
-#
-# What it does NOT do: open a PR against microsoft/winget-pkgs. That step is
-# deliberately MANUAL and runs on a maintainer's machine —
-# `scripts/bump-winget.sh`. Reason: submitting requires push access to a fork of
-# winget-pkgs. The previous design stored a classic `public_repo` PAT as
-# WINGET_TOKEN and handed it to a third-party action; that scope grants write to
-# every public repo the account can reach, and as an Actions secret it was
-# usable by anyone with push access to this repo. The local script uses the
-# maintainer's existing `gh` auth instead, so no PAT is created at all.
-# See BUILDING.md § Winget.
-#
-# Consequence: this workflow needs NO external token and no third-party action.
-#
-# Trigger: after "Create Release Assets" succeeds for a tag push. NOT
-# `release: types: [released]` — that event never fires, because the release is
-# created by create-release.yml under GITHUB_TOKEN and GitHub suppresses
-# workflow-triggering events for it. See the note in bump-homebrew-formula.yml.
-on:
-  workflow_run:
-    workflows: ["Create Release Assets"]
-    types: [completed]
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag to sync (for manual recovery)'
-        required: true
-        type: string
-
-permissions:
-  contents: write
-  pull-requests: write
-  # The "Report failure" step opens a [release-ops] issue via
-  # github.rest.issues.create, which needs issues:write.
-  issues: write
-
-concurrency:
-  group: bump-winget-${{ github.event.workflow_run.head_branch || inputs.tag }}
-  cancel-in-progress: false
-
-jobs:
-  sync-manifest:
-    # See bump-homebrew-formula.yml for why these three conditions: successful,
-    # tag-push (not a dry-run dispatch), v-prefixed. Format enforced downstream.
-    if: >-
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.workflow_run.conclusion == 'success' &&
-       github.event.workflow_run.event == 'push' &&
-       startsWith(github.event.workflow_run.head_branch, 'v'))
-    # Linux, not Windows: msitools reads the MSI Property table just as well, and
-    # this leg is billed 1x instead of 2x.
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Resolve release
-        id: rel
-        uses: ./.github/actions/resolve-release
-        with:
-          tag: ${{ github.event.workflow_run.head_branch || inputs.tag }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Re-assert stable release
-        uses: ./.github/actions/assert-stable-release
-        with:
-          tag: ${{ steps.rel.outputs.tag }}
-          is_prerelease: ${{ steps.rel.outputs.is_prerelease }}
-          is_draft: ${{ steps.rel.outputs.is_draft }}
-
-      - name: Install msitools
-        run: sudo apt-get update -qq && sudo apt-get install -y -qq msitools
-
-      - name: Download MSI, compute sha256 + ProductCode
-        id: asset
-        run: |
-          set -euo pipefail
-          TAG="${{ steps.rel.outputs.tag }}"
-          VER="${{ steps.rel.outputs.ver }}"
-          URL="https://github.com/${{ github.repository }}/releases/download/${TAG}/amethyst-desktop-${VER}-windows-x64.msi"
-          echo "Fetching $URL"
-          # workflow_run fires only after every upload leg has finished, so the
-          # asset should already be there. Retry anyway for release-CDN
-          # propagation (mirrors the repo's push/pull retry ethos).
-          ok=0
-          for i in 1 2 3 4 5; do
-            if curl -fsSL -o amethyst.msi "$URL"; then ok=1; break; fi
-            wait=$(( 2 ** i ))
-            echo "attempt $i failed; retrying in ${wait}s"
-            sleep "$wait"
-          done
-          [[ "$ok" == 1 ]] || { echo "::error::could not download $URL"; exit 1; }
-          test -s amethyst.msi
-
-          SHA=$(sha256sum amethyst.msi | awk '{print $1}' | tr '[:lower:]' '[:upper:]')
-
-          # ProductCode is the ARP key winget uses to detect an existing install.
-          # jpackage regenerates it per build, so read it rather than pin it.
-          PRODUCT_CODE=$(msiinfo export amethyst.msi Property \
-            | awk -F'\t' '$1 == "ProductCode" { print $2 }' | tr -d '\r')
-          if [[ ! "$PRODUCT_CODE" =~ ^\{[0-9A-Fa-f-]{36}\}$ ]]; then
-            echo "::error::could not read a valid ProductCode from the MSI (got: '${PRODUCT_CODE}')"
-            exit 1
-          fi
-
-          echo "url=$URL" >> "$GITHUB_OUTPUT"
-          echo "sha256=$SHA" >> "$GITHUB_OUTPUT"
-          echo "product_code=$PRODUCT_CODE" >> "$GITHUB_OUTPUT"
-          echo "sha256=$SHA"
-          echo "ProductCode=$PRODUCT_CODE"
-
-      - name: Update reference manifests
-        run: |
-          set -euo pipefail
-          DIR=desktopApp/packaging/winget
-          TAG="${{ steps.rel.outputs.tag }}"
-          VER="${{ steps.rel.outputs.ver }}"
-          SHA="${{ steps.asset.outputs.sha256 }}"
-          URL="${{ steps.asset.outputs.url }}"
-          PC="${{ steps.asset.outputs.product_code }}"
-
-          # Anchored substitutions so the header comments are never touched.
-          sed -i -E "s|^(PackageVersion: ).*|\1${VER}|" \
-            "$DIR/VitorPamplona.Amethyst.yaml" \
-            "$DIR/VitorPamplona.Amethyst.installer.yaml" \
-            "$DIR/VitorPamplona.Amethyst.locale.en-US.yaml"
-          sed -i -E "s|^(  InstallerUrl: ).*|\1${URL}|"    "$DIR/VitorPamplona.Amethyst.installer.yaml"
-          # Quoted: an all-digit 64-char digest would otherwise parse as a YAML
-          # integer and fail the schema's `string` type.
-          sed -i -E "s|^(  InstallerSha256: ).*|\1'${SHA}'|" "$DIR/VitorPamplona.Amethyst.installer.yaml"
-          sed -i -E "s|^(  ProductCode: ).*|\1'${PC}'|"    "$DIR/VitorPamplona.Amethyst.installer.yaml"
-          sed -i -E "s|^(ReleaseNotesUrl: ).*|\1https://github.com/${{ github.repository }}/releases/tag/${TAG}|" \
-            "$DIR/VitorPamplona.Amethyst.locale.en-US.yaml"
-
-          echo "----- synced -----"
-          grep -hE "^(PackageVersion|  InstallerUrl|  InstallerSha256|  ProductCode|ReleaseNotesUrl): " "$DIR"/*.yaml
-
-      - name: Sanity-check the manifests still parse
-        run: |
-          set -euo pipefail
-          python3 - <<'PY'
-          import glob, sys, yaml
-          for f in sorted(glob.glob('desktopApp/packaging/winget/*.yaml')):
-              d = yaml.safe_load(open(f))
-              assert d['PackageIdentifier'] == 'VitorPamplona.Amethyst', f
-              assert d['PackageVersion'], f
-              print('OK', f, d['ManifestType'])
-          PY
-
-      - name: Open or update the manifest-sync PR
-        # peter-evans/create-pull-request is MIT-licensed CI-only tooling (not
-        # linked into any shipped artifact). It no-ops when there is no diff.
-        uses: peter-evans/create-pull-request@v8
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          base: main
-          branch: chore/bump-winget-manifest-${{ steps.rel.outputs.tag }}
-          add-paths: desktopApp/packaging/winget
-          commit-message: 'chore: sync winget manifests to ${{ steps.rel.outputs.tag }}'
-          title: 'chore: sync winget manifests to ${{ steps.rel.outputs.tag }}'
-          body: |
-            Auto-synced `desktopApp/packaging/winget/` to the
-            `${{ steps.rel.outputs.tag }}` release:
-
-            - `PackageVersion`  -> `${{ steps.rel.outputs.ver }}`
-            - `InstallerSha256` -> `${{ steps.asset.outputs.sha256 }}`
-            - `ProductCode`     -> `${{ steps.asset.outputs.product_code }}`
-
-            **Merge this, then push it upstream from a maintainer machine:**
-
-            ```bash
-            scripts/bump-winget.sh ${{ steps.rel.outputs.tag }}
-            ```
-
-            That step is manual on purpose — it needs push access to a fork of
-            `microsoft/winget-pkgs`, which is deliberately NOT stored as a CI
-            secret. The script uses your existing `gh` auth. See
-            BUILDING.md § Winget.
-
-      - name: Report failure
-        if: failure()
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const tag = context.payload.workflow_run?.head_branch || context.payload.inputs?.tag || 'unknown';
-            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
-            await github.rest.issues.create({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              title: `[release-ops] sync-winget-manifest failed for ${tag}`,
-              body: [
-                `Winget manifest sync failed for release \`${tag}\`.`,
-                ``,
-                `- Run: ${runUrl}`,
-                `- Channel: Winget (\`VitorPamplona.Amethyst\`)`,
-                ``,
-                `Recovery options:`,
-                `1. Re-run the workflow once the underlying issue is fixed`,
-                `2. Check the release actually published \`amethyst-desktop-${tag.replace(/^v/, '')}-windows-x64.msi\``,
-                `3. Manually update \`desktopApp/packaging/winget/*.yaml\` (version, sha256, ProductCode)`
-              ].join('\n'),
-              labels: ['release-ops', 'bug']
-            });

.github/workflows/crowdin.yml

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

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

@@ -1,143 +0,0 @@
-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@v7
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
-        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@v7
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@v5.6.0
-        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

@@ -23,7 +23,6 @@
 /.idea/deviceManager.xml
 /.idea/inspectionProfiles/
 /.idea/migrations.xml
-/.idea/planningMode.xml
 /desktopApp/vlc-temp/
 /commons/.idea/gradle.xml
 /commons/.idea/misc.xml
@@ -159,39 +158,8 @@ TASKS.md
 
 # Claude Code local settings
 .claude/settings.local.json
-.claude/scheduled_tasks.lock
 
-# 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/appimagetool-x86_64.AppImage
-desktopApp/packaging/appimage/squashfs-root/
-
-# flatpak-builder state/cache from local builds (CI uses --state-dir under desktopApp/build/)
-.flatpak-builder/
-desktopApp/packaging/flatpak/**/build-dir/
-desktopApp/packaging/flatpak/**/repo/
-
-# Git worktrees
-.worktrees/
-.claude/worktrees/
-benchmark/src/main/jniLibs/
-
-/tools/marmot-interop/state
-
-# Cargo build artifacts for the cross-stack interop sidecars at
-# nestsClient/tests/hang-interop/. Cargo.lock is committed (binary workspace).
-/nestsClient/tests/hang-interop/target/
+# Downloaded VLC binaries (vlc-setup plugin)
+desktopApp/src/jvmMain/appResources/linux/
+desktopApp/src/jvmMain/appResources/macos/
+desktopApp/src/jvmMain/appResources/windows/

.idea/kotlinc.xml

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

BUILDING.md

@@ -1,843 +0,0 @@
-# Building Amethyst Desktop
-
-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)
-- [Incident response](#incident-response)
-- [Fallback plans](#fallback-plans)
-
----
-
-## Prerequisites
-
-All platforms:
-
-- **JDK 21** (Zulu or Temurin recommended)
-- **Git**
-
-Platform-specific:
-
-- **macOS**: Xcode Command Line Tools (`xcode-select --install`)
-- **Windows**: WiX Toolset 3.x on PATH (for MSI). `winget install WiXToolset.WiXToolset`
-- **Linux (all)**: nothing extra for `.deb`; `rpm` + `fakeroot` for `.rpm`;
-  `appimagetool` + `desktop-file-utils` for AppImage; `flatpak` +
-  `flatpak-builder` for the Flatpak bundle (see
-  [`desktopApp/packaging/flatpak/README.md`](desktopApp/packaging/flatpak/README.md))
-
-Install Linux RPM tooling:
-
-```bash
-# Debian/Ubuntu
-sudo apt-get install -y rpm fakeroot
-
-# Fedora
-sudo dnf install -y rpm-build
-```
-
-Install appimagetool locally (CI fetches its own — SHA-verified):
-
-```bash
-# 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
-```
-
----
-
-## Clone + first build
-
-```bash
-git clone https://github.com/vitorpamplona/amethyst.git
-cd amethyst
-
-# Dev loop (launches Amethyst Desktop)
-./gradlew :desktopApp:run
-
-# Package for current OS
-./gradlew :desktopApp:packageDistributionForCurrentOS
-```
-
----
-
-## 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 |
-|---|---|---|
-| macOS DMG (host arch) | `./gradlew :desktopApp:packageReleaseDmg` | `desktopApp/build/compose/binaries/main-release/dmg/Amethyst-*.dmg` |
-| Windows MSI | `./gradlew :desktopApp:packageReleaseMsi` | `desktopApp/build/compose/binaries/main-release/msi/Amethyst-*.msi` |
-| Linux `.deb` | `./gradlew :desktopApp:packageReleaseDeb` | `desktopApp/build/compose/binaries/main-release/deb/amethyst_*.deb` |
-| Linux `.rpm` | `./gradlew :desktopApp:packageReleaseRpm` | `desktopApp/build/compose/binaries/main-release/rpm/amethyst-*.rpm` |
-| Linux AppImage | `./gradlew :desktopApp:createReleaseAppImage` | `desktopApp/build/appimage/Amethyst-*-x86_64.AppImage` |
-| Linux Flatpak | `flatpak-builder` over `createReleaseDistributable` output — see [`desktopApp/packaging/flatpak/README.md`](desktopApp/packaging/flatpak/README.md) | `desktopApp/build/flatpak/Amethyst-*-x86_64.flatpak` (CI) |
-| Windows `.zip` portable | See below (inline `7z`) | — |
-| Linux `.tar.gz` portable | See below (inline `tar`) | — |
-
-**Inline portable archives** (run after `createReleaseDistributable`):
-
-```bash
-./gradlew :desktopApp:createReleaseDistributable
-
-# Linux tar.gz
-VER=$(grep -E '^app\s*=' gradle/libs.versions.toml | head -1 | cut -d'"' -f2)
-( cd desktopApp/build/compose/binaries/main-release/app \
-  && tar czf "../../../../portable/amethyst-desktop-${VER}-linux-x64.tar.gz" Amethyst/ )
-
-# Windows .zip (PowerShell)
-Compress-Archive -Path desktopApp\build\compose\binaries\main-release\app\Amethyst `
-  -DestinationPath "desktopApp\build\portable\amethyst-desktop-$env:VER-windows-x64.zip"
-```
-
-Cross-platform architecture note: **`jpackage` cannot cross-compile**. An Intel
-DMG must be built on `macos-13` (x64); an ARM DMG must be built on `macos-14`
-or later. CI runs both.
-
----
-
-## Asset naming contract
-
-All GH Release assets follow:
-
-```
-amethyst-desktop-<version>-<family>-<arch>.<ext>
-```
-
-Where:
-
-| Field | Values                                                |
-|---|-------------------------------------------------------|
-| `<version>` | Tag stripped of leading `vX.YY.ZZ`                    |
-| `<family>` | `macos`, `windows`, `linux`                           |
-| `<arch>` | `x64`, `arm64`                                        |
-| `<ext>` | `dmg`, `msi`, `zip`, `deb`, `rpm`, `AppImage`, `flatpak`, `tar.gz` |
-
-Single source of truth: [`scripts/asset-name.sh`](scripts/asset-name.sh).
-Package manager manifests (Homebrew cask, Winget) depend on this exact scheme —
-any change is a breaking contract.
-
-Examples:
-
-- `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`
-- `amethyst-desktop-1.12.1-linux-x64.flatpak`
-
----
-
-## Reproducible Android builds
-
-The release APKs are **bit-for-bit reproducible**: anyone can rebuild the exact
-bytes we ship (minus the signature) from the tagged source and confirm the
-artifact on F-Droid / Zapstore / GitHub was built from this code and nothing
-else. What makes that hold:
-
-- **Pinned toolchain.** AGP, Kotlin, R8, and the Compose compiler are pinned in
-  `gradle/libs.versions.toml`; the build targets **JDK 21**. R8 is deterministic
-  for a fixed version + inputs, so the minified output is stable. Build with the
-  same JDK 21 you see in `BUILDING.md` / CI.
-- **No build-time clock.** Nothing injects `System.currentTimeMillis()` /
-  build dates into `BuildConfig` (a Spotless rule bans the call in `quartz` and
-  `commons`), and AGP normalizes ZIP entry timestamps, so two builds an hour
-  apart are identical.
-- **Deterministic version name.** `generateVersionName` only appends a branch
-  suffix off feature branches; a release tag builds in detached-`HEAD` (or from a
-  source tarball with no `.git`) resolve to the bare `app` version.
-- **No dependency-metadata blob.** `dependenciesInfo { includeInApk = false;
-  includeInBundle = false }` in `amethyst/build.gradle.kts` stops AGP from
-  embedding the Google-encrypted dependency protobuf in the signing block — that
-  ciphertext is non-deterministic.
-- **Reproducible native library.** The bundled Tor (Arti) `.so` is the one
-  binary we compile ourselves; it is built reproducibly from source (pinned Rust
-  toolchain, locked deps, canonical build path). See
-  [`tools/arti-build/README.md`](tools/arti-build/README.md) → "Reproducible
-  builds". All other native libs (`secp256k1`, `webrtc`) are version-pinned Maven
-  prebuilts and so are byte-identical by download.
-
-### Verify a release APK reproduces
-
-```bash
-# 1. Check out the exact released tag and build the same variant unsigned.
-git checkout v1.12.1
-./gradlew clean :amethyst:assembleFdroidRelease
-
-# 2. Diff your unsigned build against the published APK, ignoring only the
-#    signature (META-INF/*). apksigner + a zip-aware diff is the simplest check;
-#    diffoscope gives a human-readable breakdown of any remaining delta.
-diffoscope \
-  amethyst/build/outputs/apk/fdroid/release/amethyst-fdroid-arm64-v8a-release-unsigned.apk \
-  amethyst-fdroid-arm64-v8a-1.12.1.apk
-```
-
-A clean run shows differences confined to `META-INF/` (the signing files). Any
-diff in `classes*.dex`, `resources.arsc`, or native libs means something in the
-toolchain drifted — file it before publishing.
-
----
-
-## Local SonarQube analysis (opt-in)
-
-The build supports running a [SonarQube](https://www.sonarsource.com/products/sonarqube/)
-analysis against a locally hosted server. It is **off by default**: unless you
-opt in, the scanner plugin is neither downloaded nor applied and the build is
-unaffected.
-
-### 1. Install and start a local SonarQube server
-
-Either run the official Docker image:
-
-```bash
-docker run -d --name sonarqube -p 9000:9000 sonarqube:community
-```
-
-or download the [Community Build zip](https://www.sonarsource.com/products/sonarqube/downloads/),
-unzip it, and start it (requires a JDK 17+ on `PATH`):
-
-```bash
-cd sonarqube-<version>
-bin/macosx-universal-64/sonar.sh console   # pick the folder matching your OS
-```
-
-Once it reports up, open <http://localhost:9000> (first login `admin`/`admin`,
-you'll be asked to change it), create a **local project** named `Amethyst` with
-project key `Amethyst`, and generate a **project analysis token** for it
-(*Project Settings → Analysis Method → With Gradle*, or
-*My Account → Security → Generate token*). The token looks like `sqp_…`.
-
-### 2. Point the build at your server
-
-Add the server and token to `local.properties` (gitignored — the token never
-lands in the repo):
-
-```properties
-sonar.host.url=http://localhost:9000
-sonar.token=sqp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-```
-
-### 3. Run the analysis
-
-```bash
-./gradlew sonar
-```
-
-When it finishes, browse the results at
-<http://localhost:9000/dashboard?id=Amethyst>.
-
-### 4. Optional: include Android Lint results
-
-The scanner auto-imports each Android module's lint report and shows the
-findings as external issues alongside Sonar's own. It only *imports* — it never
-runs lint itself — so without the reports on disk the analysis warns
-`Unable to import Android Lint report file(s)`. Generate them first, then run
-the scan as a **separate** invocation (chaining lint and `sonar` in one Gradle
-call does not guarantee lint finishes first):
-
-```bash
-./gradlew :amethyst:lintPlayDebug :benchmark:lintBenchmark :nappletHost:lintDebug
-./gradlew sonar
-```
-
-The reports persist under each module's `build/reports/`, so re-run lint only
-when you want fresh lint data in the next scan.
-
-Every `sonar.*` entry in `local.properties` is forwarded to the scanner, so any
-[analysis parameter](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/analysis-parameters/)
-can be set there. `sonar.projectKey` / `sonar.projectName` default to the root
-project name (`Amethyst`).
-
-Even when opted in, the scanner plugin only loads on invocations that actually
-request the `sonar` task — ordinary builds and IDE syncs are unaffected (which
-is also why `./gradlew tasks` doesn't list it).
-
-Note: the SonarQube Gradle scanner plugin is LGPL-3.0. It is a build-time-only
-tool fetched after explicit opt-in; it is never linked into shipped artifacts.
-
----
-
-## Release runbook
-
-The release flow is driven by a tag push. Every cut ships Android + Desktop +
-Quartz library in one pipeline.
-
-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
-   ```
-
-   `amethyst/build.gradle.kts` reads both from the catalog
-   (`versionCode = libs.versions.appCode.get().toInt()`), so there is nothing
-   else to edit.
-
-2. **Commit + tag + push**:
-
-   ```bash
-   git commit -am "chore(release): 1.12.1"
-   git tag -s v1.12.1 -m "Release 1.12.1"
-   git push && git push --tags
-   ```
-
-3. **Wait** for the `Create Release Assets` workflow to finish (~25–30 min).
-
-4. **Verify** — the GH Release should hold **31 assets**:
-   - **8 desktop** — `dmg` (macOS arm64), `msi` + `zip` (Windows), `deb`, `rpm`,
-     `AppImage`, `flatpak`, `tar.gz` (Linux). There is **no Intel/x64 macOS
-     DMG** — `jpackage` cannot cross-compile and no Intel runner leg is
-     configured, so macOS ships arm64-only.
-   - **13 Android** — 5 Google Play APKs + 5 F-Droid APKs + 2 AABs + the
-     F-Droid `.apks` set built for Accrescent.
-   - **5 amy** + **5 geode** bundles.
-   - Asset sizes look sane (see §Enforce asset size budget — CI auto-fails at 1 GB/asset)
-   - Android flow unchanged
-
-   Quick diff against the previous release, which catches a silently-dropped
-   matrix leg better than any count:
-
-   ```bash
-   diff <(gh release view v1.13.0 --json assets --jq '.assets[].name' | sed 's/1\.13\.0/VER/g' | sort) \
-        <(gh release view v1.13.1 --json assets --jq '.assets[].name' | sed 's/1\.13\.1/VER/g' | sort)
-   ```
-
-5. **Stable vs prerelease** — a tag containing `-rc`, `-beta`, `-alpha`, `-dev`,
-   or `-snapshot` is auto-classified as prerelease. Only stable tags run the
-   Homebrew + Winget bump workflows (and those are no-ops until the one-time
-   bootstrap PRs land — see § Bootstrap).
-
-### Dry-run (no tag push)
-
-Use `workflow_dispatch` to exercise the full matrix without publishing:
-
-```bash
-gh workflow run create-release.yml \
-  -f dry_run=true \
-  -f test_tag=v0.0.0-dryrun \
-  --ref feat/my-branch
-```
-
-Assets are built and size-checked, but not uploaded; bump workflows do not
-fire. Use for pre-merge validation of workflow changes.
-
-### Version constraint: tag must match `libs.versions.toml`
-
-The first step in each build-desktop matrix job asserts:
-
-```
-tag (stripped of 'v') == gradle/libs.versions.toml [versions] app
-```
-
-If they drift, the workflow fails fast. Always bump the TOML first, then tag.
-
-### NEVER change Windows `upgradeUuid`
-
-`desktopApp/build.gradle.kts:upgradeUuid` is the MSI product family GUID.
-Changing it breaks in-place upgrades for existing Windows users — they must
-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`~~ | *Not used.* The cask bump runs on a maintainer's machine — see § Homebrew cask | — |
-| ~~`WINGET_TOKEN`~~ | *Not used.* The winget bump runs on a maintainer's machine — see § Winget | — |
-| `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` — a *step* at the end of the `deploy-android` job, not a job of its own, so it does not appear in a job list | 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 — **currently no-ops**: neither package has been bootstrapped upstream yet (§ Bootstrap) | Automatic (CI), inactive |
-
-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)
-
-> **Status as of v1.13.1: neither Homebrew nor Winget has been bootstrapped.**
-> `https://formulae.brew.sh/api/cask/amethyst-nostr.json` and
-> `microsoft/winget-pkgs/manifests/v/VitorPamplona/Amethyst` both 404, so
-> **Amethyst does not currently ship through either channel.** The bump
-> workflows detect this and skip with a `::warning::` instead of failing, so a
-> green release run does *not* mean Homebrew/Winget shipped. The two subsections
-> below are the work that activates them; until then treat the desktop app as
-> GitHub-Releases-only on macOS and Windows.
-
-### Package-manager credentials (and why there are none)
-
-The full secret inventory is in [§ Secrets the CI needs](#secrets-the-ci-needs).
-Neither package-manager channel adds anything to it:
-
-**There are deliberately no package-manager PATs in CI.** Both the Homebrew
-cask and the Winget manifest bumps run on a maintainer's machine. The reasoning
-is worth keeping, because it is the reason this repo has no third secret to
-rotate:
-
-`brew bump-cask-pr` forks `Homebrew/homebrew-cask` **into the token owner's
-account** (`POST /repos/Homebrew/homebrew-cask/forks`), pushes a branch to that
-fork, then opens the PR upstream. That shape forces a **classic** PAT with the
-`repo` scope:
-
-- A fine-grained PAT cannot express it. Its "Repository access" selector only
-  lists repos owned by the resource owner, so `Homebrew/homebrew-cask` can never
-  be selected — and Homebrew's API layer authorises against classic OAuth scopes
-  (`x-oauth-scopes`), which fine-grained tokens do not emit.
-- Homebrew declares the requirement in source as
-  `CREATE_ISSUE_FORK_OR_PR_SCOPES = ["repo"]` (`utils/github.rb`).
-
-And `repo` cannot be narrowed: it grants write to *every* repository the owning
-account can reach — including `vitorpamplona/amethyst` itself. Stored as an
-Actions secret it would be usable by **anyone with push access to this repo**,
-since a pushed branch containing a workflow runs with repo secrets. That is a
-strict escalation for a channel that ships one DMG a month.
-
-So the split is:
-
-- **CI** (`bump-homebrew.yml`, `GITHUB_TOKEN` only) does the error-prone
-  bookkeeping: downloads the DMG, asserts it is notarized + stapled, computes
-  the sha256, and opens an in-repo PR syncing
-  `desktopApp/packaging/homebrew/amethyst-nostr.rb`.
-- **A maintainer** merges that PR and runs `scripts/bump-homebrew-cask.sh`,
-  which re-verifies the sha256 and the notarization ticket against the live
-  asset before calling `brew bump-cask-pr`.
-
-The token then lives only in that maintainer's shell:
-
-```bash
-export HOMEBREW_GITHUB_API_TOKEN=ghp_...   # classic PAT, `repo` scope
-scripts/bump-homebrew-cask.sh v1.13.2
-```
-
-Create one at
-<https://github.com/settings/tokens/new?scopes=repo&description=Homebrew%20cask%20bump>.
-Prefer a dedicated bot account whose only asset is a fork of `homebrew-cask`, so
-a leak reaches nothing else.
-
-### Winget
-
-Same split, and it needs **no token at all**. `scripts/bump-winget.sh` drives
-`gh`, which a maintainer is already authenticated with, and it does not need
-`wingetcreate` (Windows-only) because winget manifests are plain YAML — so it
-runs fine from macOS or Linux:
-
-```bash
-scripts/bump-winget.sh v1.13.2
-```
-
-CI (`bump-winget.yml`, `GITHUB_TOKEN` only) does the bookkeeping: downloads the
-MSI, computes the sha256, reads the `ProductCode` out of the MSI Property table
-with `msitools`, and opens an in-repo PR syncing
-`desktopApp/packaging/winget/*.yaml`. The script re-verifies the sha256 against
-the live asset, then forks `microsoft/winget-pkgs`, commits the three manifests
-to `manifests/v/VitorPamplona/Amethyst/<version>/`, and opens the PR.
-
-The previous design stored a classic `public_repo` PAT as `WINGET_TOKEN` and
-passed it to the third-party `vedantmgoyal9/winget-releaser` action — a token
-with write access to every public repo the account owns, handed to code we do
-not control, in a place any push-access collaborator could read it from. None of
-that is needed.
-
-### Homebrew cask (one-time initial PR)
-
-```bash
-brew bump-cask-pr amethyst-nostr \
-  --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.12.1/amethyst-desktop-1.12.1-windows-x64.msi
-```
-
-Set `PackageIdentifier = VitorPamplona.Amethyst`. After the first manifest is
-merged into `microsoft/winget-pkgs`, `bump-winget.yml` auto-submits new
-version manifests.
-
----
-
-## Troubleshooting installs
-
-### macOS — Gatekeeper "damaged and can't be opened"
-
-Amethyst Desktop is currently unsigned. First-time launch requires:
-
-1. **Right-click → Open** on the app (don't double-click) — then click **Open** on the Gatekeeper dialog
-2. Or: `xattr -cr /Applications/Amethyst.app` to strip quarantine
-3. Or: System Settings → Privacy & Security → "Open Anyway" after a blocked launch
-
-Recommended path: install via Homebrew (`brew install --cask amethyst-nostr`)
-— cask flow handles this seamlessly.
-
-### Windows — SmartScreen "Windows protected your PC"
-
-Amethyst Desktop is currently unsigned (no Authenticode). First-time launch:
-
-1. Click **More info** on the SmartScreen dialog
-2. Click **Run anyway**
-
-Alternatively use `winget install VitorPamplona.Amethyst` — winget install
-bypasses the UI dialog after accepting the installer's inherent trust.
-
-### Linux AppImage won't execute
-
-```bash
-chmod +x Amethyst-*.AppImage
-./Amethyst-*.AppImage
-```
-
-On Fedora Silverblue / very minimal distros, FUSE might be missing. Use
-`--appimage-extract-and-run`:
-
-```bash
-./Amethyst-*.AppImage --appimage-extract-and-run
-```
-
----
-
-## Uninstall + state paths
-
-State is shared across install channels (DMG, Homebrew, MSI, Winget, .deb,
-.rpm, AppImage, tar.gz). Switching channels does not duplicate data but may
-expose downgrade migration risks — **prefer a single install channel per
-machine**.
-
-**Exception: Flatpak.** The sandbox redirects XDG dirs into
-`~/.var/app/com.vitorpamplona.amethyst.Desktop/`, so a Flatpak install keeps
-its own separate state and does not see (or risk downgrading) state written
-by any other channel.
-
-| OS | App location | State directories |
-|---|---|---|
-| macOS | `/Applications/Amethyst.app` | `~/.amethyst` (accounts + keys)<br>`~/Library/Application Support/Amethyst` (Tor)<br>`~/Library/Caches/AmethystDesktop` (image cache)<br>`~/Library/Preferences/com.apple.java.util.prefs.plist` (**shared** — see below) |
-| Windows | `%LOCALAPPDATA%\Amethyst` or `C:\Program Files\Amethyst` | `%APPDATA%\Amethyst`<br>`%LOCALAPPDATA%\Amethyst` |
-| Linux (deb/rpm) | `/opt/amethyst` | `~/.config/amethyst`<br>`~/.local/share/amethyst`<br>`~/.cache/amethyst` |
-| Linux (AppImage/tar.gz) | user-chosen | Same as above |
-| Linux (Flatpak) | `/var/lib/flatpak` or `~/.local/share/flatpak` | `~/.var/app/com.vitorpamplona.amethyst.Desktop/` |
-
-**macOS preferences are in a SHARED file.** `DesktopPreferences` uses the Java
-Preferences API, which on macOS writes into
-`~/Library/Preferences/com.apple.java.util.prefs.plist` — one plist for *every*
-Java application on the machine, not a per-app file. Never delete it to "reset
-Amethyst": that wipes unrelated apps' settings. This is why the Homebrew cask's
-`zap` stanza deliberately omits it.
-
-Uninstall:
-
-- Homebrew: `brew uninstall --cask amethyst-nostr && brew zap amethyst-nostr`
-- Winget: `winget uninstall VitorPamplona.Amethyst`
-- .deb: `sudo apt remove amethyst`
-- .rpm: `sudo dnf remove amethyst`
-- AppImage / tar.gz: delete the file / extracted directory
-- Flatpak: `flatpak uninstall com.vitorpamplona.amethyst.Desktop` (add
-  `--delete-data` to also remove `~/.var/app/…`)
-- macOS `.dmg`: drag from `/Applications` to Trash, then delete state dirs manually
-
----
-
-## Incident response
-
-### Bad GH Release asset
-
-1. Immediately mark release as prerelease (pauses bump workflows):
-   ```bash
-   gh release edit v1.08.1 --prerelease
-   ```
-2. Delete the bad asset:
-   ```bash
-   gh release delete-asset v1.08.1 amethyst-desktop-1.08.1-macos-arm64.dmg --yes
-   ```
-3. Rebuild locally or rerun the failing matrix job:
-   ```bash
-   gh run rerun <run-id> --failed
-   ```
-4. Flip back to stable once verified (re-fires bump workflows — confirm fix first):
-   ```bash
-   gh release edit v1.08.1 --prerelease=false
-   ```
-
-### Bad build reached Homebrew
-
-**Preferred**: ship a point release (e.g. v1.08.2) — users on v1.08.1 get the
-fix via `brew upgrade`.
-
-**Alternative**: close the open PR in `Homebrew/homebrew-cask` before merge,
-or file a revert PR if already merged. Typical Homebrew turn-around: 1–2 days.
-
-### Bad build reached Winget
-
-Winget manifests are append-only — no hard unpublish. Options:
-
-1. Ship a point release (preferred — users upgrade via `winget upgrade`)
-2. File a manifest-removal PR against `microsoft/winget-pkgs`. Moderator
-   review: 24–72h.
-
-### User-facing communication
-
-On any incident:
-
-1. Edit the release body on GitHub with a warning banner + workaround
-2. Pin a GH Issue with downgrade instructions per channel
-3. Announce via Nostr relay + project social channels
-
----
-
-## Fallback plans
-
-### macOS Intel runner retirement
-
-GitHub's `macos-13` runner will eventually be deprecated. Monitor
-<https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners>
-for the deprecation date. When it hits:
-
-1. Drop the `macos-13` matrix entry from `.github/workflows/create-release.yml`
-2. Add a cross-arch build step on `macos-14` using a bundled x64 JDK + `jpackage --mac-signing-prefix` shenanigans, OR accept that only Apple Silicon DMGs ship and direct Intel users to `winget` on a Parallels VM or to rebuild from source.
-3. Update README install matrix to reflect the change.
-
-### Homebrew main-cask rejects unsigned app (post-Sept 1 2026)
-
-Homebrew has committed to disabling unsigned casks in `Homebrew/homebrew-cask`
-on 2026-09-01. Before that date:
-
-**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:
-
-```bash
-# Create repo: vitorpamplona/homebrew-amethyst
-# Update bump-homebrew.yml:
-#   tap: vitorpamplona/amethyst
-#   cask: amethyst-nostr
-# Users install: brew tap vitorpamplona/amethyst && brew install --cask amethyst-nostr
-```
-
-Note: a private tap does NOT bypass Gatekeeper itself (macOS OS-level) — users
-still see the "unsigned developer" dialog. Tap only sidesteps Homebrew's
-internal policy.
-
----
-
-## Follow-up channels (separate PRs)
-
-- **AUR** (`amethyst-desktop-bin`) — blocked on AUR account ownership decision
-- **Scoop** (Windows) — blocked on bucket strategy (own vs Extras)
-- **Flathub** — deferred (moderate ongoing maintenance)

CONTRIBUTING-WITH-AI.md

@@ -1,400 +0,0 @@
-# Contributing to Amethyst with AI Assistance
-
-This document is a companion to [`CONTRIBUTING.md`](CONTRIBUTING.md).
-Everything in `CONTRIBUTING.md` applies to every contribution. This doc
-adds gates specific to pull requests whose diff was substantially
-authored by an AI coding assistant (Claude Code, Copilot, Cursor,
-Codex, etc.). Where this doc and `CONTRIBUTING.md` differ, the
-stricter rule wins.
-
-If you are not using an AI assistant, you can stop reading here.
-
-- [Research before code](#research-before-code)
-- [Build and install both flavours](#build-and-install-both-flavours)
-- [Protocol-introducing changes](#protocol-introducing-changes)
-- [Performance and resource hygiene](#performance-and-resource-hygiene)
-- [Automated tests for new logic](#automated-tests-for-new-logic)
-- [Regression test plan](#regression-test-plan)
-- [Code review pass before opening the PR](#code-review-pass-before-opening-the-pr)
-- [Don't touch without an issue first](#dont-touch-without-an-issue-first)
-- [Everything else](#everything-else)
-
----
-
-## Research before code
-
-AI agents are good at writing plausible-looking code for issues that
-no longer make sense. Before you (or your assistant) write a line of
-code, confirm the issue still wants to be implemented.
-
-- **Issue still valid.** The issue is open, not superseded by a merged
-  PR, not blocked by a NIP change, and not declared out of scope. Old
-  bountied issues fail these checks routinely.
-- **Post a research summary on the issue first.** A one-paragraph
-  comment stating your read of the problem, the approach you intend
-  to take, and the modules you expect to touch. Give maintainers a
-  chance to flag it as stale before you invest in a diff.
-- **No duplicate PR.** Search open and recently-closed PRs for the
-  same feature. If a prior attempt exists, link to it and explain
-  what you do differently.
-- **Fits Amethyst's nature.** The feature must work in a decentralised
-  client: no central server, no maintainer-controlled state, no
-  required third-party account. If the proposal assumes any of these,
-  the feature doesn't belong in Amethyst, regardless of the bounty.
-- **NIPs still current.** If the issue references a specific NIP,
-  check it hasn't been deprecated or superseded.
-
-## Build and install both flavours
-
-Any change that could differ between flavours — UI, services,
-dependencies, `AndroidManifest.xml`, ProGuard rules — must build and
-install on both Play and F-Droid:
-
-```bash
-./gradlew installPlayDebug
-./gradlew installFdroidDebug
-```
-
-Paste the `BUILD SUCCESSFUL` tail of both into the PR description.
-
-**Why both.** F-Droid drops Google-proprietary dependencies (Play
-Services, Firebase, Cast SDK, etc.). Code that compiles only on Play
-is rejected. The canonical recent example is the Chromecast feature:
-the Google Cast SDK is a Play-only dependency, so F-Droid required a
-separate stub implementation under `amethyst/src/fdroid/`. Agents
-routinely add Play-only imports without realising the F-Droid build
-breaks.
-
-If a change is conclusively flavour-irrelevant (a pure `quartz/`
-protocol fix, a docs change, a translation), one flavour is enough —
-say which and why in the PR description.
-
-### Test the release-minified build, not just `*-debug`
-
-Reflection-touched code paths — `ViewModelProvider.Factory`,
-`expect`/`actual` boundaries, serialization, custom Compose runtime
-machinery — silently break under R8 / ProGuard while compiling fine
-in `*-debug` builds. The cheapest way to catch this on this codebase
-is the `benchmark` build type:
-
-```bash
-./gradlew :amethyst:installPlayBenchmark
-```
-
-That installs `com.vitorpamplona.amethyst.benchmark` ("Amy Benchmark"
-on the home screen) — R8-minified, release-flavoured, `profileable =
-true`, side-by-side with your normal Amethyst install via the
-`.benchmark` applicationId suffix. Sign in to a test npub and exercise
-the new flow there before opening the PR. A feature that crashes or
-silently no-ops in the benchmark build but works in `*-debug` is a
-missing keep rule — file it before reviewers find it.
-
-## Protocol-introducing changes
-
-If your PR publishes a new event kind, a new tag form, a new marker,
-or a new interpretation of an existing NIP clause, the diff must also
-include:
-
-- **Cross-client compatibility section in the PR description.** State
-  explicitly: which earlier Amethyst versions honour the new payload
-  (forward/backward compat), whether other major clients (Damus,
-  Primal, Iris, Coracle, etc.) implement the same NIP clause today,
-  and what user-visible behaviour differs for users still on older
-  builds or other clients. Don't paper over this with "syncs across
-  devices" — say which devices, which clients, and which versions.
-- **Wire-format verification.** Before opening the PR, fetch the
-  published event from a relay and confirm its tags, content, and
-  encryption envelope match what you intended. `nak req -i <event-id>
-  wss://<relay>` is the standard tool. Paste the relevant tag line
-  (redact private content) into the PR description. This catches bugs
-  that don't show locally — wrong markers, missing relay hints,
-  malformed private-tag JSON.
-- **NIP citation.** If you claim "NIP-X allows this", quote the exact
-  spec line in the PR. A reviewer should not have to re-derive the
-  authority for your tag form.
-
-## Performance and resource hygiene
-
-Code that looks fine in review can wreck the app at runtime. The
-following are common AI-agent footguns in this codebase. None of them
-trip CI — they only surface in careful manual review or on a real
-device. PRs that introduce any of them will be sent back.
-
-### UI thread and recomposition
-
-- **No main-thread blocking.** Network, JSON parsing, regex, crypto,
-  file I/O, and DB queries belong on `Dispatchers.IO` or
-  `Dispatchers.Default`. Never `runBlocking { ... }` from a Composable,
-  click handler, or `LaunchedEffect`.
-- **Hoist work out of `@Composable` bodies and `LazyColumn` item
-  content.** Parsing, list filtering, building maps, allocating data
-  classes all belong in `remember`, `derivedStateOf`, or the
-  ViewModel, not in the render path. New lambdas allocated per render
-  also defeat `@Stable` and cause unnecessary recomposition of
-  children.
-- **Use `collectAsStateWithLifecycle()`** for Flow → Compose, not
-  `collectAsState()`, so collection pauses when the screen is
-  off-screen.
-
-### Coroutines and scoping
-
-- **No `GlobalScope.launch` and no ad-hoc `CoroutineScope(Job())`.**
-  Use `viewModelScope`, a lifecycle scope, or a passed-in
-  `CoroutineScope`, so cancellation propagates on logout, navigation,
-  or process death.
-- **Don't put suspend work in `init {}`** of ViewModels. It runs on
-  whatever thread constructed the VM and can't be cancelled. Use a
-  `MutableStateFlow` + `viewModelScope.launch` pattern.
-
-### Memory and caching
-
-- **Don't build a parallel cache of Notes, Users, or Events.**
-  Amethyst stores them once in `LocalCache` (backed by `LargeCache`),
-  keyed by id or pubkey, mutable in place. A new
-  `mutableMapOf<HexKey, Note>()` in your feature doubles the working
-  set and gets stale.
-- **Don't roll your own image cache.** Coil is wired up with
-  size-aware loaders. Decoding a full-resolution image yourself will
-  OOM mid-scroll.
-- **Bound your collections.** Unbounded `mutableMapOf` or
-  `mutableListOf` that accrue per-event entries are memory leaks. If
-  you mean "the last N", use a size-bounded structure.
-
-### Relay traffic and mobile network
-
-- **Use the existing subscription layer.**
-  `ComposeSubscriptionManager`, `Subscribable`, and the filter
-  assemblers under `commons/.../relayClient/` are lifecycle-aware,
-  deduped, and EOSE-closed. Don't open ad-hoc WebSockets and don't
-  issue raw `REQ` filters from a Composable.
-- **Don't re-fetch what's already in `LocalCache`.** Check the cache
-  first; only subscribe for what's missing.
-- **Respect data-saver and connectivity context.** Auto-fetching
-  full-resolution video on cellular is a regression even if the code
-  technically works.
-
-### KMP source-set discipline
-
-- **Android-only imports don't belong in `commons/commonMain` or
-  `quartz/commonMain`.** Use `expect`/`actual` for platform-specific
-  bits, or move the Android-specific code to `androidMain`.
-
-### Logging
-
-- **Use the Quartz lambda Log.**
-  `com.vitorpamplona.quartz.utils.Log.d { "msg $x" }` — the lambda
-  body only runs when the log level is enabled. Plain
-  `Log.d("msg $x")` allocates the formatted string on every call,
-  including in feed and scroll hot paths.
-- **Strip diagnostic `Log.d` calls before commit.** Logs added
-  during on-device debugging — even lambda-form ones — must be
-  removed from the production diff. They survive R8 stripping only
-  in debug builds, so committed `Log.d` doesn't directly hurt
-  release performance, but it bloats the diff, scatters noise across
-  logcat for the next developer, and silently grows over time. If a
-  log line is genuinely load-bearing for future
-  incident-response, promote it to `Log.i`/`w` with explicit
-  justification in the commit message.
-
-Relevant skills under `.claude/skills/`: `account-state`,
-`relay-client`, `kotlin-coroutines`, `kotlin-multiplatform`,
-`find-non-lambda-logs`.
-
-## Automated tests for new logic
-
-For any change beyond pure UI tweaks or docs, add automated tests.
-"Tested manually" alone is not enough; it doesn't survive the next
-refactor, and reviewers can't re-verify it.
-
-Minimum bar:
-
-- **New logic in `quartz/`** (event types, NIPs, parsing, crypto,
-  Bech32) — must have unit tests in the matching
-  `commonTest` / `androidTest` / `jvmTest` source set. Quartz is the
-  protocol surface; everything new there gets coverage.
-- **New logic in `commons/`** (ViewModels, filters, formatters,
-  non-trivial state transitions) — unit tests for the paths a future
-  refactor could break.
-- **Bug fixes** — a regression test that fails before your fix and
-  passes after. No exception. If the bug is hard to reproduce in a
-  unit test, write the test that reproduces it first.
-- **UI-only changes** in `amethyst/` or `desktopApp/` — automated UI
-  tests are not required (per `CONTRIBUTING.md` § Tests). The manual
-  on-device test plan and screenshots stay required.
-
-If your change touches a domain covered by an interop suite (MLS /
-Marmot, NIP-17 DMs, audio rooms, MoQ-lite, QUIC), run the relevant
-suite locally and paste the result. CI does not run them. See
-[`CONTRIBUTING.md` § *Interoperability tests*](CONTRIBUTING.md#interoperability-tests)
-for the suite list and commands.
-
-Commands:
-
-```bash
-./gradlew test                  # unit + KMP common tests, all modules
-./gradlew :quartz:test          # one module
-./gradlew connectedAndroidTest  # Android instrumented (needs device)
-```
-
-Tests pass before you open the PR. "CI will catch it" is not a
-substitute — interop and instrumented suites don't run in CI.
-
-## Regression test plan
-
-The PR template has a **Test plan** section. For AI-authored PRs that
-aren't pure docs or translations, that section must contain *two*
-parts under these exact subheadings:
-
-- `### Feature test plan` — what you did to confirm the new thing works.
-- `### Regression test plan` — what you did to confirm the old things
-  still work, and that you actually thought about which ones could
-  break.
-
-Don't add a new top-level section to the PR description — put both
-subheadings inside the existing **Test plan** section.
-
-Worked example of the required structure (real shape from a recent
-feature PR; substitute your own touch points and verifications):
-
-````markdown
-## Test plan
-
-### Feature test plan
-
-- Long-press a reply note → quick-action sheet → "Mute thread" →
-  thread disappears from Home immediately.
-- Force-stop the app, relaunch → muted thread still hidden (relay
-  round-trip verified).
-- Settings → Security & Filters → Muted threads → tap "Unmute" →
-  thread reappears in Home.
-
-### Regression test plan
-
-Touch points and verification:
-
-- Existing user-mute — could regress through the shared
-  `Account.isAcceptable` chokepoint — verified: muted a different
-  user, posts hidden as before.
-- Hidden words — same chokepoint — verified: added a word, posts
-  filtered; removed it, posts back.
-- Multi-account switch — could leak mute list across accounts —
-  verified: switched between two npubs, each saw only its own mutes.
-- R8-minified build — could fail on new ViewModel factory — verified
-  on `installPlayBenchmark`.
-- Both flavours — built and installed `installPlayDebug`; F-Droid
-  build is flavour-irrelevant for this change (no Google-proprietary
-  touch points), built only.
-````
-
-For the regression test plan, list:
-
-1. **Touch points** — screens, flows, ViewModels, shared state, or
-   modules your change reads from or modifies. List the ones a
-   careful reader would expect to be affected, not the entire app.
-2. **Failure mode** — for each touch point, what would actually go
-   wrong if your change is buggy. "Feed wouldn't load." "Metadata
-   stale across account switch." "OOM on scroll."
-3. **Verification** — what you did to confirm it still works. Same
-   `action → observed result` format as the feature test plan.
-
-Worked example, for "add a new field to `Account`":
-
-- Account creation — could crash on first launch — verified: created
-  a fresh npub, app opened home feed.
-- Account switching — could leak state across users — verified:
-  switched twice between two npubs, feeds refreshed.
-- Settings export/import — could corrupt restore — verified:
-  exported, wiped data, re-imported, no errors.
-
-Common touch-point categories worth scanning every PR for:
-
-- Account / login / logout / multi-account switch.
-- **Multi-device sync when the feature publishes per-account state to
-  relays.** Sign in to the same npub on a second device and verify
-  the new state propagates and is honoured there. State explicitly
-  which Amethyst versions both sides need to be running for the sync
-  to work (current build only, or older builds too).
-- Both flavours (Play and F-Droid).
-- Feed types: home, profile, hashtag, bookmarks, notifications,
-  DMs, communities.
-- Orientation changes.
-- Cold start vs warm start.
-- Background → foreground transitions.
-- Release-minified build (`installPlayBenchmark`) for any code path
-  that touches reflection — ViewModel factories, expect/actual,
-  custom serialization.
-
-If a touch point can't reasonably be verified (it would require a
-relay matrix you don't have, or a device combination you can't
-access), state so and explain why you accept the risk. A reviewer
-can tell you to do it anyway, but silent omission is not an option.
-
-## Code review pass before opening the PR
-
-Before pushing, run a code-review pass with a *different* agent or
-model than the one that wrote the code. AI agents are bad at finding
-their own bugs; switching agent breaks the same-context blind spots
-that produced the initial diff.
-
-Options:
-
-- Use a dedicated review skill if your harness has one — `/simplify`,
-  `/kotlin-review`, `/security-review`, `/code-review`.
-- Spawn a fresh agent from a different model (Sonnet → Opus, Opus →
-  GPT-5, Claude → Codex) and have it review the diff.
-- Run any static-analysis pass available (`./gradlew lint`).
-
-After the review, **re-run the tests and the manual on-device test
-plan**. Review feedback routinely surfaces bugs the tests didn't
-catch; the fix introduces its own risk; verify the fix didn't
-regress.
-
-If the review flags issues, either address them or document in the
-PR description why you accept the risk. Don't silently discard
-review output.
-
-### When on-device QA finds bugs in your own diff
-
-On-device QA frequently surfaces defects after the initial
-implementation reads as "done". Don't fold those fixes silently
-into the feature commit and force-push — that erases the signal that
-the defect existed and what it was. Instead:
-
-- Land each fix as its own commit, or a final squashed
-  `"Manual testing fixes"` commit at the tip of the branch.
-- The commit message body names the root cause, not just the
-  symptom. Answer the question "why was this missing from the initial
-  diff?" — undocumented event-shape variant, collision with a
-  recently-merged upstream change, Compose recomposition assumption,
-  R8 keep-rule gap, lifecycle race.
-- A reviewer reading your branch sees: feature → code-review cleanup
-  → on-device manual-QA fixes. That's a healthy development arc, not
-  a liability.
-
-## Don't touch without an issue first
-
-Open an issue and get explicit maintainer alignment before opening a
-PR for:
-
-- **Signer and KeyStore surface** — `NostrSigner` and its
-  implementations (`NostrSignerInternal`, `NostrSignerRemote`,
-  `NostrSignerExternal`), anything touching key storage or the
-  signing flow.
-- **Release pipeline** — workflow files under `.github/workflows/`,
-  signing config, Gradle plugins, packaging.
-- **NIP direction calls** — anything that changes how Amethyst
-  interprets a NIP, or invents a new tag or kind, needs upstream NIP
-  discussion (and likely a NIP PR) first.
-
-These areas have a high cost when an unaligned PR lands — security
-risk, release breakage, protocol fragmentation. Open the issue first
-regardless of whether you call your change a bug fix, refactor, or
-feature; describe what you observed and what you propose. A maintainer
-will tell you to skip the issue gate if the change is genuinely
-trivial.
-
-## Everything else
-
-For commit format, dev setup, interop tests, PR structure, translation
-flow, and coding standards — see [`CONTRIBUTING.md`](CONTRIBUTING.md)
-and [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md).

CONTRIBUTING.md

@@ -1,321 +0,0 @@
-# Contributing to Amethyst
-
-Thanks for your interest in improving Amethyst. This document captures the
-expectations, conventions, and review rules for code, documentation, and
-translation contributions across all modules in this repository (`amethyst/`,
-`desktopApp/`, `quartz/`, `commons/`, `cli/`, `quic/`, `nestsClient/`).
-
-By contributing, you agree to license your work under the MIT license. Any
-work contributed where you are not the original author must contain its
-license header with the original author(s) and source.
-
-- [Ways to contribute](#ways-to-contribute)
-- [Proof of testing (new / occasional contributors)](#proof-of-testing-new--occasional-contributors)
-- [Reporting bugs and requesting features](#reporting-bugs-and-requesting-features)
-- [Security issues](#security-issues)
-- [Development setup](#development-setup)
-- [Where code belongs](#where-code-belongs)
-- [Workflow](#workflow)
-- [Coding standards](#coding-standards)
-- [Tests](#tests)
-- [Interoperability tests](#interoperability-tests)
-- [Commits](#commits)
-- [Pull requests](#pull-requests)
-- [Translations](#translations)
-- [Releases](#releases)
-
----
-
-## Ways to contribute
-
-- Fix bugs or implement features (see issues and the bounty notes in the
-  issue templates).
-- Improve documentation in `README.md`, `BUILDING.md`, `SECURITY.md`, the
-  per-module `plans/` folders, and the `.claude/` skill docs.
-- Add or improve translations on
-  [Crowdin](https://crowdin.com/project/amethyst-social).
-- Report bugs, suggest features, or open issues at
-  [github.com/vitorpamplona/amethyst/issues](https://github.com/vitorpamplona/amethyst/issues)
-  or the Nostr mirror at
-  [gitworkshop.dev/repo/amethyst](https://gitworkshop.dev/repo/amethyst).
-- Send patches over Nostr using
-  [GitStr](https://github.com/fiatjaf/gitstr) — see the address at the bottom
-  of the README.
-
-## Proof of testing (new / occasional contributors)
-
-We accept pull requests authored by humans and pull requests authored with
-help from AI coding assistants (Claude Code, Copilot, Cursor, Codex, etc.)
-under the same rules:
-
-- **You are the author of record.** You are responsible for understanding,
-  testing, and defending every line — including code an assistant wrote for
-  you. "The AI did it" is not a valid response to review feedback.
-- **No hallucinated APIs or imports.** Don't submit code that calls
-  functions, classes, or libraries that don't exist in this repo or its
-  declared dependencies. Build and run it before you push.
-- **No machine-translated locale files.** Translations go through Crowdin so
-  native speakers can review them.
-- **Disclose substantial AI involvement** with a one-line note in the PR
-  description. Courtesy, not a gate.
-
-If you are **not a regular contributor** to this repository — first PR, or
-sporadic enough that maintainers wouldn't recognize your handle — the PR
-description must include proof that you actually ran the change:
-
-- **Code/logic changes:** paste the test output, CLI command, or log lines
-  that show the new path executing. CI green is necessary but not
-  sufficient.
-- **UI changes** (`amethyst/`, `desktopApp/`, or `@Composable` code in
-  `commons/`): attach screenshots or a short recording from a real device or
-  emulator. See the PR template for the exact checklist (light + dark,
-  device / OS info, empty / loading / error states).
-- **Build / Gradle / packaging changes:** paste the `./gradlew` command and
-  the tail of its output.
-- **Translation-only PRs:** mention which locale and which strings you
-  touched; screenshots not required.
-
-Once you have an established track record, a short test plan is enough on
-subsequent PRs. Maintainers may still ask for screenshots on visual changes.
-
-If you can't run a particular target locally (e.g. no macOS, but your change
-affects the DMG build), say so explicitly. Honest "I couldn't test this on
-Windows" beats a silent guess.
-
-If you used an AI coding assistant for a substantial portion of the diff,
-also read [`CONTRIBUTING-WITH-AI.md`](CONTRIBUTING-WITH-AI.md) — it adds
-gates specific to AI-authored PRs (research before code, both-flavour
-build, performance footguns, automated tests, regression test plan,
-second-agent code review).
-
-## Reporting bugs and requesting features
-
-Use the GitHub issue templates at
-[`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) rather than opening a
-blank issue — they exist so triage can route the report without a follow-up
-round trip.
-
-**Bug report (`[BUG]` title prefix):** describe the bug, give numbered repro
-steps from a fresh app launch, state expected behavior, attach video /
-screenshots for anything visual or timing-sensitive, list device info (phone
-brand/model, Android version, app version, flavour, Amber version if
-applicable), and include a bounty.
-
-**Feature request (`[FEATURE]` title prefix):** describe the user-facing
-outcome and include a bounty. Skip implementation suggestions unless they're
-load-bearing.
-
-### Bounties
-
-Maintainer time is allocated by bounty size. From the templates: *"If no
-bounty is offered, not even a small one, this bug will not be worked on
-because it doesn't matter to you."* Issues are prioritized by bounty ÷
-effort, even a few hundred sats outrank a zero-bounty issue, and bounties
-aren't refunded. If you can fix it yourself, just open the PR — bounties
-exist to move issues nobody is currently working on. Security issues do not
-need a bounty and should not be filed publicly; see
-[SECURITY.md](SECURITY.md).
-
-## Security issues
-
-**Do not file security vulnerabilities as public GitHub issues.** Use
-[GitHub private vulnerability reporting](https://github.com/vitorpamplona/amethyst/security/advisories/new)
-instead. See [SECURITY.md](SECURITY.md) for scope, expected response times,
-and disclosure policy.
-
-## Development setup
-
-Prerequisites:
-
-1. **JDK 21+** (Zulu or Temurin recommended)
-2. **Android Studio** (for Android development)
-3. **Android 8.0+ phone or emulator** (for installing the Android app)
-4. **Xcode + iOS simulator** if you're touching `quartz/` iOS code
-5. **libsodium** for full local builds (`brew install libsodium` on macOS)
-
-Desktop packaging prerequisites (only if you're building installers) are
-listed in [BUILDING.md § Prerequisites](BUILDING.md#prerequisites).
-
-Clone and import:
-
-```bash
-git clone https://github.com/vitorpamplona/amethyst.git
-cd amethyst
-```
-
-Common Gradle entry points:
-
-```bash
-./gradlew :desktopApp:run         # Run desktop app
-./gradlew :amethyst:installDebug  # Install Android debug build
-./gradlew :quartz:build           # Build Quartz for all targets
-./gradlew build                   # Full build + tests
-```
-
-## Where code belongs
-
-Modules:
-
-- `quartz/` — Nostr KMP library (protocol, crypto, models). **No UI.**
-- `commons/` — Shared Compose Multiplatform UI, icons, ViewModels, flows.
-- `quic/` — Pure-Kotlin QUIC v1 + HTTP/3 + WebTransport.
-- `nestsClient/` — Audio-rooms client (NIP-53) built on `:quic` and
-  `:quartz`.
-- `amethyst/` — Android app: Activity, layouts, navigation.
-- `desktopApp/` — Desktop JVM app: Window, sidebar, keyboard shortcuts.
-- `cli/` — `amy`, a non-interactive JVM CLI over `quartz` + `commons`.
-
-Per-module design docs live in `<module>/plans/YYYY-MM-DD-<slug>.md`. The
-global `docs/plans/` folder is frozen.
-
-Before writing a new class or composable, check whether it already exists.
-Most logic is already implemented somewhere — duplicating it is the #1 cause
-of PR churn. Place new code by purpose:
-
-| What you're adding | Goes in |
-|---|---|
-| Nostr event types, NIPs, tags, signing, crypto, Bech32 | `quartz/commonMain/` |
-| Shared Composables, icons, ViewModels, StateFlows | `commons/commonMain/viewmodels/` or `commons/commonMain/` |
-| Android-only screen, navigation, system integration | `amethyst/` |
-| Desktop-only window, sidebar, menu bar, shortcut | `desktopApp/` |
-| `amy <verb>` subcommand (thin assembly only) | `cli/src/main/kotlin/.../cli/` |
-| QUIC / HTTP/3 / WebTransport protocol code | `quic/` |
-| MoQ session / audio-room logic | `nestsClient/` |
-
-Hard rules:
-
-- `quartz/` has **no UI**.
-- `cli/` has **no Nostr protocol or business logic** — it's a thin assembly
-  layer over `quartz` + `commons`. If your CLI command needs new behavior,
-  extract it into `commons/` first.
-- ViewModels belong in `commons/commonMain/`. Only screens (the Composable
-  that wires layout + navigation) stay in the platform module.
-- For platform-specific behavior in a shared file, use `expect`/`actual`.
-
-## Workflow
-
-1. **Survey first.** Search the codebase for existing implementations before
-   writing new code. The `.claude/CLAUDE.md` file has a recommended set of
-   `grep` queries; running them routinely turns up the exact class you were
-   about to re-invent.
-2. **Open a small PR.** One feature or one fix per PR. Refactors that
-   support the change are fine; unrelated refactors are not.
-3. **Branch off `main`.**
-4. **Run tests + spotless locally** before pushing.
-5. **Open the PR** with a description that explains *why*, not just *what*.
-
-## Coding standards
-
-- Kotlin, formatted with Spotless. Always run `./gradlew spotlessApply`
-  before considering a task complete. CI runs `spotlessCheck` and will fail
-  on unformatted code.
-- Never use `--no-verify` to bypass pre-commit hooks. If a hook fails, fix
-  the cause.
-- Default to writing no comments. Add one only when the *why* is non-obvious
-  (a workaround, a subtle invariant, behavior that would surprise a
-  reader). Don't restate what the code does, and don't reference the
-  current task or callers — that belongs in the PR description.
-
-## Tests
-
-```bash
-./gradlew test                 # Unit + KMP common tests, all modules
-./gradlew connectedAndroidTest # Android instrumented tests (needs device)
-./gradlew :quartz:test         # Single module
-```
-
-Add tests when:
-
-- You fix a bug — a regression test that fails before your fix and passes
-  after.
-- You add new protocol code in `quartz/` — Nostr event parsing, NIP
-  implementations, and crypto paths should have unit coverage.
-- You add anything to `commons/` with non-trivial state transitions.
-
-UI changes don't need automated UI tests, but they do need the screenshots
-described in the proof-of-testing section.
-
-## Interoperability tests
-
-Amethyst ships several cross-stack interop harnesses that drive our code
-against external reference implementations. They are **not run in CI** —
-they're slow, require Rust / bun / Docker / Chromium, and most PRs don't
-touch the code they cover. If your change *does* touch a covered area, you
-are expected to run the relevant suite locally and paste the result into
-the PR description. Reviewers may ask if you didn't.
-
-| Suite | Path | What it covers | When you must run it |
-|---|---|---|---|
-| **Marmot / MLS (Whitenoise)** | `cli/tests/marmot/` | NIP-EE MLS groups: KeyPackage publish, group create/invite/remove, admin promote/demote, leave, replay, KP rotation — Amethyst (or `amy`) ↔ `whitenoise-rs` Rust reference | Changes to MLS / Marmot code in `quartz/` or `commons/`, or to the Marmot UI / group-chat flow in `amethyst/` |
-| **NIP-17 DMs (amy ↔ amy)** | `cli/tests/dm/` | Text + file DM round-trip, strict kind:10050, `--allow-fallback` NIP-65 chain, `dm list --since` window slide | Changes to DM, gift-wrap (NIP-59), or NIP-17 code paths in `quartz/` or `commons/` |
-| **Audio rooms (manual)** | `cli/tests/nests/` | 47-test manual harness: Amethyst Android ↔ nostrnests.com reference web client. Host/listener flows, hand-raise, role promotion, kicks, schedule, reconnect, JWT refresh, PIP | Changes to NIP-53 audio rooms (`amethyst/` UI) or `nestsClient/` that affect host/listener UX |
-| **MoQ-lite hang-tier** | `nestsClient/tests/hang-interop/` | Rust `hang-listen` / `hang-publish` ↔ Amethyst Kotlin through a real `moq-relay` 0.10.x subprocess. Wire-byte capture, FFT-on-PCM, mute / hot-swap / packet-loss / late-join / 60s broadcast / multi-listener fan-out | Changes to `nestsClient/.../moq/lite/`, `nestsClient/.../audio/`, `MoqLite*Speaker.kt` / `*Listener.kt`, `ReconnectingNests*.kt`, or `quartz/.../nip53` |
-| **MoQ-lite browser-tier** | `nestsClient/tests/browser-interop/` | Headless Chromium with `@moq/lite` + `@moq/hang` via Playwright ↔ Amethyst Kotlin (forward + reverse). WebCodecs encode/decode, ALPN negotiation, browser-side reconnect | Same as hang-tier, plus any change to `:quic` (WebTransport, packet header protection, key updates, stream demux) |
-| **QUIC interop-runner** | `quic/interop/` | The standard `quic-interop-runner` matrix (ns-3 sim) against aioquic, picoquic, quic-go, quinn. Handshake, transfer, loss, corruption, IPv6, migration, key update, version negotiation | Any change in `:quic` that could affect wire bytes, congestion control, or the TLS state machine |
-
-### Running them
-
-Each suite has its own README; the non-obvious bits worth flagging up
-front:
-
-- **MoQ-lite tiers** are opt-in via `-DnestsHangInterop=true` and
-  `-DnestsBrowserInterop=true` on `:nestsClient:jvmTest`. Cold first run is
-  ~10–13 min per tier; cached runs ~3–7 min.
-- **`quic/interop/run-matrix.sh` is not concurrency-safe.** Run peers
-  sequentially: `for peer in aioquic picoquic quic-go quinn; do
-  quic/interop/run-matrix.sh -s $peer; done`. Plan at
-  `quic/interop/plans/2026-05-06-interop-runner.md`.
-- **CLI suites** ([`cli/tests/README.md`](cli/tests/README.md)): headless
-  variants need only `cargo` + a loopback `nostr-rs-relay`; the interactive
-  Marmot variant prompts a human to drive the Android UI.
-
-If a change is documentation-only, UI-only, build-script-only, or otherwise
-cannot affect wire bytes / decoded audio / MLS state / DM envelopes, skip
-the interop suites and say so in the PR description.
-
-## Commits
-
-- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`,
-  `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, etc.
-- One logical change per commit. Squashing during PR review is fine.
-- Keep subject lines under ~72 characters. Use the body to explain *why*
-  the change was made when it isn't obvious.
-- Branch names follow `feat/<scope>-<short-name>` or
-  `fix/<scope>-<short-name>` (e.g. `feat/desktop-sidebar-resize`,
-  `fix/android-notification-leak`).
-
-## Pull requests
-
-A good PR description has:
-
-1. **Summary** — 1–3 sentences on what changed and why.
-2. **Test plan** — exactly what you ran, on what platform, with what
-   result. Include screenshots / recordings for UI changes (mandatory for
-   non-regular contributors; expected for everyone on visual changes).
-
-We aim to give first-pass feedback within a few days. PRs may sit longer if
-they're large, touch security-sensitive code, or arrive during a release
-window.
-
-## Translations
-
-- Submit translations via
-  [Crowdin](https://crowdin.com/project/amethyst-social), not as direct PRs
-  to `strings.xml`. Crowdin pushes are integrated through the `crowdin.yml`
-  workflow.
-- The `/find-missing-translations` skill can help reviewers spot
-  untranslated keys for a target locale.
-
-## Releases
-
-Release runbooks (Android AAB upload, desktop packaging on macOS / Windows /
-Linux, Homebrew cask, Winget manifest, Apple Developer signing, asset
-naming) live in [BUILDING.md § Release runbook](BUILDING.md#release-runbook)
-and [BUILDING.md § Bootstrap runbook](BUILDING.md#bootstrap-runbook-one-time).
-
-If your PR needs to be cut into a particular release, mention it in the PR
-description and the maintainers will coordinate.
-
----
-
-Thanks again for contributing.

PLANS.md

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

PRIVACY.md

@@ -1,114 +1,54 @@
 # Amethyst Privacy Policy and Terms of Use
 
-**App:** Amethyst (Android Nostr client)<br>
-**Publisher:** Vitor Pamplona<br>
-**Contact:** amethyst@vitorpamplona.com<br>
-**Last updated:** 2026-05-24
+## Privacy Policy
 
-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.
+Effective as of Jun 12, 2023
 
-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 Amethyst app for Android does not collect or process any personal information from its users. 
 
-This document explains what data leaves your phone, who can see it, and the standards that apply to use of the app.
+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. 
 
-## Privacy
+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.
 
-### Data sent off-device
+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. 
 
-Using the app causes the following data to leave your phone:
+### Privacy with Relay services
 
-- **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).
+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.
 
-The developer does not run any server that aggregates or stores this data.
+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.
 
-### Data stored on your device
+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.
 
-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.
+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. 
 
-### What relays can see
+### Visibility & Permanence of Your Content on Nostr Relays
 
-A relay you connect to sees:
+#### Information Visibility
 
-- 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.
+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.
 
-A relay does **not** see the plaintext of:
+#### Information Permanence
 
-- Private Direct Messages (encrypted to the recipient under NIP-17 / NIP-44).
-- Private Zaps.
+Information shared on Nostr should be assumed permanent for privacy purposes. There is no way to guarantee deleting or editing any content once posted.
 
-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.
+## Child safety standards
 
-### 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.
+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.
 
 ## Terms of Use
 
-### Google Play build
+### For versions downloaded from Google's Play Store
 
-You agree not to use the Google Play build of Amethyst to submit Objectionable Content to relays. Objectionable Content includes:
+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.
 
-- 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.
+### For versions downloaded from F-Droid
 
-These Terms apply only to the Google Play distribution of Amethyst.
+We do not control the distribution of the application in F-Droid. Legal matters should be resolved between the user and F-Droid. 
 
-### F-Droid and other source-built distributions
+## Other Notes
 
-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.
+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.
 
-## Updates
-
-This document may change. The current version is published at https://github.com/vitorpamplona/amethyst/blob/main/PRIVACY.md.
+If you have any questions about Amethyst or this privacy policy, you can send a message to amethyst@vitorpamplona.com

PULL_NOTIFICATION.md

@@ -1,303 +0,0 @@
-# Always-On Notification Service
-
-Amethyst's always-on notification service maintains persistent WebSocket connections to the
-user's inbox relays and DM relays, ensuring real-time delivery of DMs, zaps, mentions, and
-other notifications without depending on an external push server.
-
-## Why
-
-The existing push notification system (`push.amethyst.social`) can only monitor relays it
-knows about. Private, paid, or obscure inbox relays get missed entirely. The only way to
-guarantee 100% notification coverage is for the device itself to maintain connections to
-the user's NIP-65 inbox relays and NIP-17 DM relays.
-
-## Architecture
-
-```
-NIP-65 notification inbox relays ──WebSocket──┐
-                                              ├──> [NotificationRelayService]
-NIP-17 DM inbox relays ───────────WebSocket──┘           |
-                                                         v
-                                                  EventNotificationConsumer
-                                                         |
-                                                         v
-                                                  Android Notification
-```
-
-The service shares the **same `NostrClient` instance** as the UI. This is the key design
-decision. When the app is in the foreground, both the UI and the service are collecting
-the `relayServices` flow. The `AccountFilterAssembler` subscription from the Compose UI
-tree stays active as long as the Activity exists (even when stopped/backgrounded),
-keeping notification and DM relay connections alive. When the app returns to the
-foreground, the UI piggybacks on the already-open connections. **Zero reconnection, zero
-dropped messages.**
-
-```
-BACKGROUND MODE (service running):
-  inbox-relay-1 ──WebSocket──> [AccountFilterAssembler: notifications, metadata, follows]
-  inbox-relay-2 ──WebSocket──> [AccountFilterAssembler: notifications, metadata, follows]
-  dm-relay-1 ────WebSocket──> [AccountFilterAssembler: gift wraps]
-  (outbox relays disconnected — no Home/Video/Discovery subscriptions)
-
-APP FOREGROUNDS:
-  inbox-relay-1 ──WebSocket──> [Same connection] <── Home/Discovery subs resume
-  inbox-relay-2 ──WebSocket──> [Same connection] <── Home/Discovery subs resume
-  dm-relay-1 ────WebSocket──> [Same connection]  <── ChatroomList subs resume
-  outbox-relay-3 ──WebSocket──> [New connection]  <── Home/Video feed relay
-```
-
-## Subscription Architecture
-
-### What the service does
-
-The service does NOT create its own relay subscriptions. It only keeps the
-`RelayProxyClientConnector` alive by collecting `relayServices`. The actual subscriptions
-come from the `AccountFilterAssembler` in the Compose tree (`LoggedInPage`), which
-stays active as long as the Activity exists and covers:
-
-- **Metadata** — user profile, relay lists, mute lists, follows (via `AccountMetadataEoseManager`)
-- **Follows** — follow list changes that affect notification filtering (via `AccountFollowsLoaderSubAssembler`)
-- **Notifications** — mentions, zaps, reactions on NIP-65 inbox relays (via `AccountNotificationsEoseFromInboxRelaysManager`)
-- **Gift wraps** — NIP-59 encrypted DMs on NIP-17 DM relays (via `AccountGiftWrapsEoseManager`)
-- **Drafts** — draft events (via `AccountDraftsEoseManager`)
-
-This is critical because notification filtering depends on follow lists, mute lists,
-and relay configurations. If the service maintained its own isolated subscriptions,
-it would miss follow list changes and display notifications from muted users.
-
-### What pauses on background
-
-Heavy feed subscriptions use `LifecycleAwareKeyDataSourceSubscription` which subscribes
-on `ON_START` and unsubscribes on `ON_STOP`. When the app backgrounds:
-
-| Subscription | Behavior | Why |
-|-------------|----------|-----|
-| `AccountFilterAssembler` | **Stays active** | Needed for notifications, DMs, follow/mute list changes |
-| `HomeFilterAssembler` | **Pauses** | Home feed data with nobody viewing wastes bandwidth |
-| `VideoFilterAssembler` | **Pauses** | Video feed data with nobody viewing wastes bandwidth |
-| `DiscoveryFilterAssembler` | **Pauses** | Discovery feed data with nobody viewing wastes bandwidth |
-| `ChatroomListFilterAssembler` | **Pauses** | Chatroom list updates with nobody viewing waste bandwidth |
-
-When the feed subscriptions pause, the relay pool automatically disconnects outbox relays
-that no longer have any active subscriptions. Only inbox and DM relays stay connected
-(because `AccountFilterAssembler` still has active subscriptions on them).
-
-## Foreground Service
-
-`NotificationRelayService` is a foreground service with `specialUse` type:
-
-- **No time limit**: Unlike `dataSync` (6-hour limit on Android 15), `specialUse` has no
-  timeout restriction. **Why it matters:** A notification service must run indefinitely.
-  The `dataSync` type would force the service to stop after 6 cumulative hours per 24-hour
-  period, making it useless for always-on notifications.
-- **BOOT_COMPLETED safe**: Can be started from boot receivers on Android 15+, unlike
-  `dataSync` which is restricted. **Why it matters:** Without this, the service couldn't
-  auto-restart after a reboot on modern Android.
-- **START_STICKY**: Android will restart the service if it's killed by the system.
-- **Persistent notification**: Shows "Connected to N inbox relays" with a Pause action.
-  Uses `IMPORTANCE_LOW` so it's silent and unobtrusive.
-
-### ForegroundServiceStartNotAllowedException
-
-On Android 12+, starting a foreground service from the background can throw
-`ForegroundServiceStartNotAllowedException`. The service catches this gracefully and stops
-itself rather than crashing the app.
-
-**Why it matters:** Without this catch, if the watchdog alarm or WorkManager tries to
-restart the service while the app lacks the background-start exemption (e.g., battery
-optimization is active), the app would crash with an unhandled exception.
-
-### Redundant startForeground()
-
-`startForeground()` is called from both `onCreate()` and `onStartCommand()` as a safety
-net. In rare edge cases, `onStartCommand()` can fire before `onCreate()` completes
-(observed in ntfy issue #1520). The `foregroundStarted` flag prevents double invocation.
-
-**Why it matters:** If `startForeground()` isn't called within 5 seconds of
-`startForegroundService()`, the app crashes with an ANR. The redundant call ensures the
-foreground notification is posted regardless of which lifecycle method runs first.
-
-## 8-Layer Auto-Restart Defense
-
-Android (and OEM battery optimizers) will aggressively try to kill background services.
-The notification service uses 8 independent mechanisms to stay alive. Each addresses a
-specific kill vector that the others don't cover:
-
-### Layer 1: START_STICKY
-
-**What:** When Android kills the service due to memory pressure, `START_STICKY` tells the
-system to recreate it with a null intent.
-
-**Why needed:** This is the baseline restart mechanism provided by Android. However, it's
-unreliable in practice — many OEMs (Xiaomi MIUI, Huawei EMUI, Samsung One UI, Oppo
-ColorOS) override this behavior and prevent sticky service restarts. That's why we need
-the remaining 7 layers.
-
-### Layer 2: onTaskRemoved() Alarm
-
-**What:** When the user swipes the app from recents, schedules a 1-second alarm to restart
-the service.
-
-**Why needed:** On stock Android, swiping from recents only removes the task but leaves
-the foreground service running. However, many OEMs treat swipe-from-recents as a force
-stop, killing the foreground service. `START_STICKY` won't help because some OEMs block
-sticky restarts after a task removal. The alarm bypasses this by scheduling the restart
-through `AlarmManager`, which is a separate system that OEM modifications rarely touch.
-
-### Layer 3: onDestroy() Broadcast
-
-**What:** When the service is destroyed for any reason, it broadcasts to
-`AutoRestartReceiver`, which enqueues a one-time WorkManager task with a network
-connectivity constraint.
-
-**Why needed:** This catches the gap between `START_STICKY` and `onTaskRemoved()`.
-If the system kills the service during normal operation (not from recents), `START_STICKY`
-should restart it — but if the OEM blocks that restart, the broadcast fires a WorkManager
-task as a backup. WorkManager is harder for OEMs to suppress because it's part of
-Google Play Services infrastructure.
-
-### Layer 4: AlarmManager Watchdog (5 minutes)
-
-**What:** `ServiceWatchdogManager` fires an `ELAPSED_REALTIME` alarm every 5
-minutes. The receiver checks if the service should be running and restarts it.
-
-**Why needed:** This is the "belt and suspenders" layer. If all of the above layers fail
-(sticky restart blocked, alarm from `onTaskRemoved` didn't fire, broadcast wasn't
-delivered), the watchdog will catch it within 5 minutes of the device being awake.
-The alarm deliberately does NOT use the `_WAKEUP` variant: pulling the CPU out of
-sleep every 5 minutes is a battery cost with no payoff, because a service restarted
-on a sleeping device can't do useful network work until the device wakes anyway.
-While the device sleeps, Layer 5 (WorkManager) and Layer 8 (FCM/UnifiedPush) cover
-delivery; the moment the device wakes, the pending watchdog alarm fires.
-
-### Layer 5: WorkManager Periodic Catch-Up (15 minutes)
-
-**What:** Runs every 15 minutes with a network connectivity constraint. Ensures relay
-connections are active and restarts the foreground service if needed.
-
-**Why needed:** WorkManager survives process death and device reboots — it's the most
-persistent scheduling mechanism on Android. Even if the app process is completely dead,
-WorkManager (backed by JobScheduler) will eventually wake it. The 15-minute interval is
-WorkManager's minimum, ensuring regular catch-up even if the foreground service has been
-dead for a while.
-
-### Layer 6: Network-Available One-Time Worker
-
-**What:** When `AutoRestartReceiver` fires, it enqueues a one-time WorkManager task that
-runs as soon as network connectivity is available.
-
-**Why needed:** If the service dies during a network outage, there's no point restarting it
-immediately (the relays won't connect). This worker waits for connectivity and restarts
-then, rather than waiting up to 15 minutes for the next periodic worker. This is especially
-important after airplane mode, tunnel/elevator scenarios, or switching between WiFi and
-cellular.
-
-### Layer 7: Boot and Package Receivers
-
-**What:** `BootCompletedReceiver` restarts the service after device reboot
-(`BOOT_COMPLETED`, `QUICKBOOT_POWERON`) and app update (`MY_PACKAGE_REPLACED`).
-
-**Why needed:** After a reboot, no services are running — `START_STICKY` doesn't apply
-across reboots. The boot receiver is the only way to restart. After an app update, the
-old process is killed and the new version's services don't auto-start. Without
-`MY_PACKAGE_REPLACED`, users would need to manually open the app after every Play Store
-update to restore notifications.
-
-### Layer 8: FCM / UnifiedPush (existing)
-
-**What:** The existing push notification system continues to work alongside the always-on
-service.
-
-**Why needed:** FCM is the only mechanism that survives a force stop (because Google Play
-Services handles delivery outside the app's process). If the user explicitly force-stops
-Amethyst from Settings, all 7 layers above are disabled. Only FCM can still deliver
-notifications until the user opens the app again.
-
-## WakeLock During Notification Processing
-
-`EventNotificationConsumer` acquires a `PARTIAL_WAKE_LOCK` with a 10-minute timeout when
-processing incoming notifications.
-
-**Why needed:** When a notification event arrives from a relay, the app needs to decrypt
-NIP-59 gift wraps, verify signatures, look up accounts, resolve display names, load
-profile pictures, and construct the Android notification. In Doze mode, the CPU can sleep
-between alarm windows. Without a WakeLock, the CPU could sleep mid-processing, causing the
-notification to be delayed or lost. The 10-minute timeout is generous to handle slow
-decryption (especially with external signers) while preventing indefinite wake locks from
-battery drain.
-
-## Battery Optimization Exemption
-
-The service works best when the app is exempted from Android's battery optimizations (Doze).
-
-**Why needed:** Even with a foreground service, Android can restrict network access during
-Doze maintenance windows. The battery optimization exemption tells Android that this app's
-network activity is user-expected and should not be deferred. Without it, relay connections
-may be broken during Doze, causing missed notifications that only arrive when the device
-exits Doze (which can be hours for a stationary, charging device).
-
-`BatteryOptimizationHelper` checks the exemption status and provides a method to launch
-the system settings dialog. When the always-on service is enabled but the app isn't
-whitelisted, the settings screen shows a warning banner with a "Fix now" button.
-
-Messaging apps are explicitly listed as a valid use case for this exemption in Google Play
-policy.
-
-## Coordinator
-
-`AlwaysOnNotificationServiceManager` watches the account's `alwaysOnNotificationService`
-setting (a `MutableStateFlow<Boolean>`) and activates or deactivates all layers in
-response:
-
-```
-Setting ON  → Start foreground service + Schedule WorkManager + Schedule watchdog alarm
-Setting OFF → Stop foreground service + Cancel WorkManager + Cancel watchdog alarm
-```
-
-The manager is initialized in `AppModules` and watches the account state. When a user
-logs in, it starts watching their setting. When they log out, it stops.
-
-## Settings
-
-The always-on notification service is **opt-in** (off by default). Users enable it from
-**App Settings** with a toggle switch. The setting is persisted per-account in
-`AccountSettings.alwaysOnNotificationService` and saved to `EncryptedSharedPreferences`.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `NotificationRelayService.kt` | Foreground service, keeps relay connections alive, auto-restart |
-| `LifecycleAwareKeyDataSourceSubscription.kt` | Pauses heavy feed subs when app backgrounds |
-| `BootCompletedReceiver.kt` | Restart on boot and app update |
-| `AutoRestartReceiver.kt` | Restart via WorkManager when service is destroyed |
-| `NotificationCatchUpWorker.kt` | Periodic and on-demand catch-up worker |
-| `ServiceWatchdogManager.kt` | AlarmManager-based health monitor |
-| `AlwaysOnNotificationServiceManager.kt` | Coordinates all layers based on setting |
-| `BatteryOptimizationHelper.kt` | Battery optimization check and exemption request |
-| `EventNotificationConsumer.kt` | WakeLock wrapper for notification processing |
-| `AccountSettings.kt` | `alwaysOnNotificationService` setting |
-| `LocalPreferences.kt` | Setting persistence |
-| `AppSettingsScreen.kt` | Toggle UI and battery optimization banner |
-| `AndroidManifest.xml` | Permissions, service, and receiver declarations |
-
-## Permissions
-
-| Permission | Purpose |
-|------------|---------|
-| `FOREGROUND_SERVICE` | Run the foreground service |
-| `FOREGROUND_SERVICE_SPECIAL_USE` | Declare `specialUse` service type |
-| `RECEIVE_BOOT_COMPLETED` | Restart on boot |
-| `WAKE_LOCK` | Keep CPU awake during notification processing |
-| `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` | Request Doze exemption |
-
-## Inspiration
-
-This implementation draws from battle-tested patterns in:
-
-- **ntfy** (millions of users) — `onTaskRemoved()` alarm, `onDestroy()` broadcast restart,
-  `ForegroundServiceStartNotAllowedException` handling, redundant `startForeground()`,
-  battery optimization guidance, WakeLock during processing
-- **Pokey** (Nostr notification app) — `specialUse` foreground service type,
-  `MY_PACKAGE_REPLACED` restart
-- **Signal** — Hybrid FCM + persistent WebSocket architecture

README.md

@@ -14,16 +14,13 @@ 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)
-[![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)
+[![JitPack version](https://jitpack.io/v/vitorpamplona/amethyst.svg)](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: MIT](https://img.shields.io/github/license/vitorpamplona/amethyst?labelColor=27303D&color=0877d2)](/LICENSE)
+[![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)
 
 ## Download and Install
 
-### Android
-
 [<img src="./docs/design/zapstore.svg"
 alt="Get it on Zap Store"
 height="70">](https://github.com/zapstore/zapstore/releases)
@@ -36,159 +33,113 @@ height="70">](https://github.com/vitorpamplona/amethyst/releases)
      alt="Get it on Google Play"
      height="70">](https://play.google.com/store/apps/details?id=com.vitorpamplona.amethyst)
 
-### Desktop
-
-| OS | CLI install | Direct download |
-|---|---|---|
-| macOS (Apple Silicon) | `brew install --cask amethyst-nostr` | [.dmg arm64](https://github.com/vitorpamplona/amethyst/releases/latest) |
-| macOS (Intel) | `brew install --cask amethyst-nostr` | [.dmg x64](https://github.com/vitorpamplona/amethyst/releases/latest) |
-| Windows 10/11 | `winget install VitorPamplona.Amethyst` | [.msi](https://github.com/vitorpamplona/amethyst/releases/latest) · [.zip portable](https://github.com/vitorpamplona/amethyst/releases/latest) |
-| Debian/Ubuntu | — | [.deb](https://github.com/vitorpamplona/amethyst/releases/latest) |
-| Fedora/RHEL/openSUSE | — | [.rpm](https://github.com/vitorpamplona/amethyst/releases/latest) |
-| Any Linux | — | [AppImage](https://github.com/vitorpamplona/amethyst/releases/latest) · [.tar.gz](https://github.com/vitorpamplona/amethyst/releases/latest) |
-
-_Coming soon (separate PR): Scoop (Windows), AUR (Arch Linux)._
-
-**Build from source:** see [BUILDING.md](BUILDING.md).
-
-**Install troubleshooting** (Gatekeeper / SmartScreen / AppImage): see
-[BUILDING.md § Troubleshooting installs](BUILDING.md#troubleshooting-installs).
-
 </div>
 
-## Verifying the APK signature
-
-If you sideload Amethyst (Obtainium, GitHub Releases, Zap Store), verify that your
-APK is signed by the official release key before installing. All official Amethyst
-APKs — both the `googleplay` and `fdroid` flavors — are signed with the same
-certificate, whose SHA-256 fingerprint is:
-
-```
-C2:D0:AA:86:BC:B6:B6:20:90:56:1A:41:BB:E3:36:E9:8B:78:C2:D0:21:0A:49:8D:C8:85:F2:8E:13:48:CF:17
-```
-
-To check a downloaded APK yourself, run (`apksigner` ships with the Android SDK
-build-tools):
-
-```bash
-apksigner verify --print-certs amethyst-*.apk
-```
-
-and confirm the reported `Signer #1 certificate SHA-256 digest` is
-`c2d0aa86bcb6b62090561a41bbe336e98b78c2d0210a498dc885f28e1348cf17`.
-Without the Android SDK, `keytool -printcert -jarfile amethyst-*.apk` (bundled
-with any JDK) prints the same SHA-256 fingerprint.
-
-With [AppVerifier](https://github.com/soupslurpr/appverifier), paste or share the
-APK and compare against:
-
-```
-com.vitorpamplona.amethyst
-C2:D0:AA:86:BC:B6:B6:20:90:56:1A:41:BB:E3:36:E9:8B:78:C2:D0:21:0A:49:8D:C8:85:F2:8E:13:48:CF:17
-```
-
 ## Supported Features
 
 <img align="right" src="./docs/screenshots/home.png" data-canonical-src="./docs/screenshots/home.png" width="350px">
 
-- [x] Basic protocol flow (NIP-01)
+- [x] Events / Relay Subscriptions (NIP-01)
 - [x] Follow List (NIP-02)
 - [x] OpenTimestamps Attestations (NIP-03)
-- [x] Encrypted Direct Message (NIP-04)
-- [x] DNS-based Identifiers (NIP-05)
-- [x] Key Derivation from Mnemonic (NIP-06)
-- [ ] window.nostr for Web Browsers (NIP-07, Not applicable)
-- [x] Handling Mentions (NIP-08)
-- [x] Event Deletion Request (NIP-09)
+- [x] Private Messages (NIP-04 -- to be removed)
+- [x] DNS Address (NIP-05)
+- [x] Mnemonic seed phrase (NIP-06)
+- [ ] WebBrowser Signer (NIP-07, Not applicable)
+- [x] Old-style mentions (NIP-08)
+- [x] Event Deletion (NIP-09)
 - [x] Text Notes and Threads (NIP-10)
 - [x] Relay Information Document (NIP-11)
-- [x] Proof of Work (NIP-13)
-- [x] Subject Tag in Text Events (NIP-14)
-- [x] Nostr Marketplace (NIP-15)
+- [x] Generic Tag Queries (NIP-12)
+- [x] Proof of Work Display (NIP-13)
+- [ ] Proof of Work Calculations (NIP-13)
+- [x] Events with a Subject (NIP-14)
+- [ ] Marketplace (NIP-15)
+- [x] Event Treatment (NIP-16)
 - [x] Private Direct Messages (NIP-17)
-- [x] Reposts (NIP-18)
-- [x] bech32-encoded Entities (NIP-19)
-- [x] nostr: URI Scheme (NIP-21)
-- [x] Comment (NIP-22)
-- [x] Long-form Content (NIP-23)
-- [x] Extra Metadata Fields and Tags (NIP-24)
+- [x] Image/Video/Url/LnInvoice/Cashu Previews
+- [x] Reposts, Quotes, Generic Reposts (NIP-18)
+- [x] Bech32 Encoding support (NIP-19)
+- [x] Command Results (NIP-20)
+- [x] URI Support (NIP-21)
+- [x] Long-form Content (NIP-23) (view only)
+- [x] User Profile Fields / Relay list (NIP-24)
 - [x] Reactions (NIP-25)
-- [x] Delegated Event Signing (NIP-26)
+- [ ] Delegated Event Signing (NIP-26, Will not implement)
 - [x] Text Note References (NIP-27)
-- [x] Public Chat (NIP-28)
-- [x] Relay-based Groups (NIP-29)
+- [x] Public Chats (NIP-28)
+- [ ] Relay-based Groups (NIP-29)
 - [x] Custom Emoji (NIP-30)
-- [x] Dealing with Unknown Events (NIP-31)
+- [x] Event alt descriptors (NIP-31)
 - [x] Labeling (NIP-32)
-- [x] git stuff (NIP-34)
+- [x] Git Stuff (NIP-34)
 - [x] Torrents (NIP-35)
 - [x] Sensitive Content (NIP-36)
-- [x] Draft Events (NIP-37)
-- [x] User Statuses (NIP-38)
-- [x] External Identities in Profiles (NIP-39)
-- [x] Expiration Timestamp (NIP-40)
-- [x] Authentication of Clients to Relays (NIP-42)
-- [x] Relay Access Metadata and Requests (NIP-43)
-- [x] Encrypted Payloads / Versioned (NIP-44)
-- [x] Counting Results (NIP-45)
-- [x] Nostr Remote Signing (NIP-46)
-- [x] Nostr Wallet Connect (NIP-47)
-- [x] Proxy Tags (NIP-48)
-- [x] Private Key Encryption (NIP-49)
-- [x] Search Capability (NIP-50)
+- [x] Drafts (NIP-37)
+- [x] User Status Event (NIP-38)
+- [x] External Identities (NIP-39)
+- [x] Expiration Support (NIP-40)
+- [x] Relay Authentication (NIP-42)
+- [ ] Relay Access Metadata and Requests (NIP-43)
+- [x] Versioned Encrypted Payloads (NIP-44)
+- [x] Event Counts (NIP-45)
+- [o] Nostr Connect (NIP-46)
+- [o] Wallet Connect API (NIP-47)
+- [ ] Proxy Tags (NIP-48, Not applicable)
+- [x] Encryption for import/export (NIP-49)
+- [x] Relay Search (NIP-50)
 - [x] Lists (NIP-51)
-- [x] Calendar Events (NIP-52)
-- [x] Live Activities (NIP-53)
+- [o] Calendar Events (NIP-52)
+- [x] Live Activities & Live Chats (NIP-53)
 - [x] Wiki (NIP-54)
-- [x] Android Signer Application (NIP-55)
+- [x] Android Signer (NIP-55)
 - [x] Reporting (NIP-56)
-- [x] Lightning Zaps (NIP-57)
+- [x] Lightning Tips
+- [x] Zaps (NIP-57)
 - [x] Zap Splits (NIP-57)
-- [x] Private Zaps (NIP-57)
-- [x] Zapraiser (NIP-57)
+- [x] Private Zaps (NIP-57 / Draft)
+- [x] Zapraiser (NIP-57 / Draft)
 - [x] Badges (NIP-58)
-- [x] Gift Wrap (NIP-59)
-- [x] Pubkey Static Websites (NIP-5A)
-- [x] Cashu Wallet (NIP-60)
-- [x] Nutzaps (NIP-61)
+- [x] Gift Wraps & Seals (NIP-59)
+- [ ] Cashu Wallets (NIP-60)
+- [ ] Nutzaps (NIP-61)
 - [x] Request to Vanish (NIP-62)
-- [x] Chess / PGN (NIP-64)
+- [x] Chess (NIP-64)
 - [x] Relay List Metadata (NIP-65)
-- [x] Relay Discovery and Liveness Monitoring (NIP-66)
-- [x] Picture-first Feeds (NIP-68)
-- [x] Peer-to-peer Order Events (NIP-69)
-- [x] Protected Events (NIP-70)
+- [x] Relay Discovery and Monitoring (NIP-66)
+- [x] Picture-first feeds (NIP-68)
+- [ ] Peer-to-peer Orders (NIP-69)
+- [o] Protected Events (NIP-70)
 - [x] Video Events (NIP-71)
 - [x] Moderated Communities (NIP-72)
 - [x] External Content IDs (NIP-73)
-- [x] Zap Goals (NIP-75)
-- [x] Negentropy Syncing (NIP-77)
-- [x] Application-specific Data (NIP-78)
-- [x] Threads (NIP-7D)
+- [ ] Zap Goals (NIP-75)
+- [ ] Negentropy Syncing (NIP-77)
+- [x] Arbitrary Custom App Data (NIP-78)
+- [ ] NIP-29 Threads (NIP-7D)
 - [x] Highlights (NIP-84)
 - [x] Trusted Assertions (NIP-85)
-- [x] Relay Management API (NIP-86)
-- [x] Ecash Mint Discoverability (NIP-87)
+- [ ] Relay Management API (NIP-86)
+- [ ] ECash Mint Discoverability (NIP-87)
 - [x] Polls (NIP-88)
+- [x] Relay Notify Request
 - [x] Recommended Application Handlers (NIP-89)
-- [x] Data Vending Machines (NIP-90)
-- [x] Media Attachments (NIP-92)
-- [x] File Metadata (NIP-94)
+- [x] Data Vending Machine (NIP-90)
+- [x] Inline Metadata (NIP-92)
+- [x] Verifiable file URLs (NIP-94)
 - [x] Binary Blobs (NIP-95/Draft)
 - [x] HTTP File Storage Integration (NIP-96)
 - [x] HTTP Auth (NIP-98)
-- [x] Classified Listings (NIP-99)
+- [x] Classifieds (NIP-99)
 - [x] Voice Messages (NIP-A0)
 - [x] Public Messages (NIP-A4)
-- [x] Web Bookmarks (NIP-B0)
+- [ ] Web Bookmarks
 - [x] Blossom (NIP-B7)
-- [x] Nostr BLE Communications Protocol (NIP-BE)
+- [ ] Nostr BLE Communications Protocol (NIP-BE)
 - [x] Code Snippets (NIP-C0)
-- [x] Chats (NIP-C7)
+- [ ] NIP-29 Chats (NIP-C7)
 - [ ] MLS Protocol (NIP-EE)
 - [x] Audio Tracks (zapstr.live) (kind:31337)
-- [x] Lightning Tips
-- [x] Image/Video/Url/LnInvoice/Cashu Previews
 - [x] Push Notifications (Google and Unified Push)
 - [x] In-Device Automatic Translations
 - [x] Hashtag Following and Custom Hashtags
@@ -301,16 +252,22 @@ For the Play build:
 
 ## Deploying
 
-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.
-
-- **[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.
+1. Generate a new signing key
+```
+keytool -genkey -v -keystore <my-release-key.keystore> -alias <alias_name> -keyalg RSA -keysize 2048 -validity 10000
+openssl base64 < <my-release-key.keystore> | tr -d '\n' | tee some_signing_key.jks.base64.txt
+```
+2. Create four Secret Key variables on your GitHub repository and fill in the signing key information
+    - `KEY_ALIAS` <- `<alias_name>`
+    - `KEY_PASSWORD` <- `<your password>`
+    - `KEY_STORE_PASSWORD` <- `<your key store password>`
+    - `SIGNING_KEY` <- the data from `<my-release-key.keystore>`
+3. Change the `versionCode` and `versionName` on `amethyst/build.gradle`
+4. Commit and push.
+5. Tag the commit with `v{x.x.x}`
+6. Let the [Create Release GitHub Action](https://github.com/vitorpamplona/amethyst/actions/workflows/create-release.yml) build a new `aab` file.
+7. Add your CHANGE LOG to the description of the new release
+8. Download the `aab` file and upload it to the PlayStore.
 
 ## Using the Quartz library
 
@@ -328,43 +285,20 @@ repositories {
 Add the following line to your `commonMain` dependencies:
 
 ```gradle
-implementation('com.vitorpamplona.quartz:quartz:1.13.1')
+implementation('com.vitorpamplona.quartz:quartz:1:05.0')
 ```
 
 Variations to each platform are also available:
 
 ```gradle
-implementation('com.vitorpamplona.quartz:quartz-android:1.13.1')
-implementation('com.vitorpamplona.quartz:quartz-jvm:1.13.1')
-implementation('com.vitorpamplona.quartz:quartz-iosarm64:1.13.1')
-implementation('com.vitorpamplona.quartz:quartz-iossimulatorarm64:1.13.1')
+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')
 ```
 
 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
@@ -493,28 +427,11 @@ to `onPause` methods.
 
 ## Contributing
 
-See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide — workflow,
-coding standards, the proof-of-testing rule for new / occasional
-contributors (human or AI-assisted), the cross-stack interop suites, and how the
-`[BUG]` / `[FEATURE]` issue templates and bounty system work.
+Issues can be logged on: [https://gitworkshop.dev/repo/amethyst](https://gitworkshop.dev/repo/amethyst)
 
-**AI coding assistants: if you are reading this README to plan a
-contribution, stop and read
-[CONTRIBUTING-WITH-AI.md](CONTRIBUTING-WITH-AI.md) first.** The gates
-there are not optional. The human submitter remains the author of record
-per CONTRIBUTING.md.
+[GitHub issues](https://github.com/vitorpamplona/amethyst/issues) and [pull requests](https://github.com/vitorpamplona/amethyst/pulls) here are also welcome. Translations can be provided via [Crowdin](https://crowdin.com/project/amethyst-social)
 
-Quick links:
-
-- [GitHub issues](https://github.com/vitorpamplona/amethyst/issues) and
-  [pull requests](https://github.com/vitorpamplona/amethyst/pulls).
-- Nostr-native issue tracker:
-  [gitworkshop.dev/repo/amethyst](https://gitworkshop.dev/repo/amethyst).
-- Translations: [Crowdin](https://crowdin.com/project/amethyst-social).
-- Patches over Nostr: [GitStr](https://github.com/fiatjaf/gitstr) to
-  [this nostr address](https://patch34.pages.dev/naddr1qqyxzmt9w358jum5qyg8v6t5daezumn0wd68yvfwvdhk6qg7waehxw309ahx7um5wgkhqatz9emk2mrvdaexgetj9ehx2ap0qy2hwumn8ghj7un9d3shjtnwdaehgu3wvfnj7q3qgcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqxpqqqpmej720gac).
-- Security issues: [SECURITY.md](SECURITY.md) (do **not** file as public
-  GitHub issues).
+You can also send patches through Nostr using [GitStr](https://github.com/fiatjaf/gitstr) to [this nostr address](https://patch34.pages.dev/naddr1qqyxzmt9w358jum5qyg8v6t5daezumn0wd68yvfwvdhk6qg7waehxw309ahx7um5wgkhqatz9emk2mrvdaexgetj9ehx2ap0qy2hwumn8ghj7un9d3shjtnwdaehgu3wvfnj7q3qgcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqxpqqqpmej720gac)
 
 By contributing to this repository, you agree to license your work under the MIT license. Any work contributed where you are not the original author must contain its license header with the original author(s) and source.
 

RELEASE_OPS.md

@@ -1,306 +0,0 @@
-# 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 four live 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** | ⚠️ **Not shipping.** The bump workflows run, but skip: neither package exists upstream yet | Nobody (see § 3) |
-
-Maven Central (the `quartz` library) also publishes automatically from the same
-workflow — as a *step* at the end of the `deploy-android` job, not a job of its
-own, so don't expect to find it in the run's job list.
-
----
-
-## 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.
-
-   For the `## Translations` section, generate the credits instead of writing
-   them by hand — no token needed:
-   ```bash
-   scripts/translators.sh
-   ```
-   This runs offline. It reads `docs/changelog/translators.json` (kept next to
-   the changelogs), which CI keeps fresh: the Crowdin sync workflow's
-   `seed-translators` job records everyone who has translated since the last `v*`
-   tag, with their languages, in the file's `sinceLastTag` list, and accumulates
-   their npubs in the forever-growing `mappings` registry. The script resolves
-   that list to npubs and prints the `## Translations` block grouped by language.
-   Contributors with no npub yet are listed under `UNMAPPED` — credit them by
-   hand, then add their npub under `mappings` so future releases pick them up
-   automatically. (To re-query Crowdin live as a sanity check, run
-   `scripts/translators.sh --seed` with `CROWDIN_PROJECT_ID` /
-   `CROWDIN_PERSONAL_TOKEN` set, which refreshes the file.)
-
-3. **Publish the release-notes note on Nostr** — *minor releases only.* In
-   practice this id has only ever been bumped on `x.y.0` (1.11.0, 1.12.0,
-   1.13.0); patch releases leave it pointing at their minor's note. Publish with
-   Amethyst's account and paste the 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 runs the Homebrew/Winget bump workflows; anything with
-a `-rc`/`-beta`/`-alpha`/`-dev` suffix is a prerelease and skips them.
-
-Heads-up on the `git push`: this repo has `git-credential-manager` configured as
-a credential helper, and it blocks on an interactive prompt (a plain
-`GIT_TERMINAL_PROMPT=0` does **not** stop it — the push just hangs). If that
-happens, push using `gh`'s helper for the one command:
-
-```bash
-git -c credential.helper= -c credential.helper='!gh auth git-credential' push upstream main
-```
-
-When the `Create Release Assets` workflow finishes (~25–30 min) the GH Release
-holds **31 assets**, per the asset-name contract:
-
-- **Android (13):** 5 Google Play APKs + 5 F-Droid APKs + 2 AABs + the F-Droid
-  `.apks` set for Accrescent
-  (`amethyst-googleplay-*-v…apk` / `.aab`, `amethyst-fdroid-*-v…apk` / `.aab` / `.apks`)
-- **Desktop (8):** DMG (macOS **arm64 only** — there is no Intel DMG),
-  MSI + zip, DEB, RPM, AppImage, flatpak, tar.gz
-- **CLI (5):** the `amy` artifacts
-- **Relay (5):** the `geode` artifacts, plus the geode Docker image
-- **Maven Central:** `com.vitorpamplona.quartz:quartz:<version>` published.
-  `repo1.maven.org` lags the publish by tens of minutes — a 404 right after the
-  run is normal. Confirm the step's log says "Deployment is being published to
-  Maven Central", and compare against the *previous* version's POM before
-  concluding anything is broken.
-
----
-
-## 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 — ⚠️ not shipping yet
-
-`bump-homebrew.yml` and `bump-winget.yml` are wired to open PRs against
-`Homebrew/homebrew-cask` (cask `amethyst-nostr`) and `microsoft/winget-pkgs`
-(`VitorPamplona.Amethyst`) — but **neither package has ever been submitted
-upstream**, so both workflows detect that and skip with a `::warning::`. As of
-**v1.13.1** these two channels deliver nothing; macOS and Windows users get the
-desktop app from GitHub Releases only.
-
-Two separate faults kept this invisible until v1.13.1, both now fixed:
-
-1. **The workflows never ran at all** — for *any* release. They triggered on
-   `release: types: [released]`, and GitHub does not raise workflow-triggering
-   events for a release created by `GITHUB_TOKEN`, which is exactly how
-   `create-release.yml` creates it. They now trigger on `workflow_run` after
-   `Create Release Assets` succeeds, which also fixes a latent race — the old
-   event fired while assets were still uploading.
-2. **Nothing exists upstream to bump.** `brew bump-cask-pr` and
-   `winget-releaser` can only *update* an existing package. The first
-   submission is a manual, human-reviewed PR: BUILDING.md § Homebrew cask
-   (one-time initial PR) and § Winget (one-time initial submission).
-
-Until someone does that bootstrap, a green release run means the bump workflows
-*skipped cleanly* — not that Homebrew/Winget shipped. Check the run's warnings
-if you want to confirm which case you're in.
-
-**Both bumps are half-manual by design.** CI does the bookkeeping with
-`GITHUB_TOKEN` only — verifying the artifact, computing hashes, and opening an
-in-repo PR syncing the reference packaging files. Pushing upstream needs
-credentials that would be dangerous as CI secrets (a `repo`-scoped PAT is
-readable by anyone with push access here), so a maintainer runs the last step:
-
-```bash
-# after merging the sync PRs
-export HOMEBREW_GITHUB_API_TOKEN=ghp_...     # classic PAT, `repo` scope
-scripts/bump-homebrew-cask.sh v1.13.2
-
-scripts/bump-winget.sh v1.13.2               # no token — uses your `gh` auth
-```
-
-Both scripts re-verify the published artifact's sha256 before submitting, and
-the Homebrew one additionally refuses if the DMG is not notarized + stapled.
-See BUILDING.md § Package-manager credentials.
-
-All four in-repo sync workflows (`amy` formula, `geode` formula,
-`amethyst-nostr` cask, winget manifests) open PRs against *this* repo on every
-release. Merge them to keep the reference packaging files current.
-
----
-
-## 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 |
-| *(none for Homebrew/Winget)* | — | Both bumps run on a maintainer's machine — `scripts/bump-homebrew-cask.sh` and `scripts/bump-winget.sh` — so neither channel's PAT ever becomes a CI secret. See BUILDING.md § Package-manager credentials |
-| `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: 31 assets, sizes sane, and the asset-name set matches the
-      previous release (see the `diff` one-liner in BUILDING.md § Release
-      runbook). macOS is arm64-only — do **not** look for an Intel DMG.
-- [ ] Maven Central: `quartz:<version>` resolves (allow tens of minutes of
-      propagation; the publish step's log is the authoritative signal).
-- [ ] Play Console: rollout started, no policy rejection.
-- [ ] Zapstore: release event visible.
-- [ ] F-Droid: new version detected (may lag days).
-- [ ] Four sync PRs opened against this repo (`amy` formula, `geode` formula,
-      `amethyst-nostr` cask, winget manifests) — merge them.
-- [ ] Cask pushed upstream: `scripts/bump-homebrew-cask.sh vX.Y.Z` (manual, needs
-      `HOMEBREW_GITHUB_API_TOKEN` in your shell).
-- [ ] Winget pushed upstream: `scripts/bump-winget.sh vX.Y.Z` (manual, no token —
-      uses your `gh` auth).
-      Both scripts error clearly until the one-time bootstrap PRs land (§ 3).
-- [ ] In-app "Release Notes" link opens the note matching `RELEASE_NOTES_ID`
-      (only bumped on minor releases — patches keep pointing at the x.y.0 note).
-- [ ] 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).

SECURITY.md

@@ -1,95 +0,0 @@
-# Security Policy
-
-Amethyst is a Nostr client that handles user private keys, signed events, and
-end-to-end encrypted direct messages. We take security reports seriously and
-appreciate responsible disclosure.
-
-## Supported Versions
-
-Only the latest release receives security fixes. We do not backport patches to
-older versions. Fixes also land on the `main` branch ahead of the next release.
-
-| Version        | Supported |
-| -------------- | --------- |
-| Latest release | ✅        |
-| `main`         | ✅        |
-| Older          | ❌        |
-
-This covers all artifacts built from this repository: the Android app
-(`amethyst/`), the desktop app (`desktopApp/`), the `amy` CLI (`cli/`), and
-the `quartz` / `commons` libraries.
-
-## Reporting a Vulnerability
-
-**Please do not report security vulnerabilities through public GitHub issues.**
-
-Use GitHub's private vulnerability reporting instead:
-
-👉 [Report a vulnerability](https://github.com/vitorpamplona/amethyst/security/advisories/new)
-
-This keeps the details private until a fix is ready and coordinates disclosure
-between you and the maintainers.
-
-### What to include
-
-To help us triage quickly, please provide:
-
-- A clear description of the vulnerability and its impact (what an attacker
-  could achieve — e.g. key material exposure, DM confidentiality, integrity,
-  availability).
-- Affected module(s): `quartz`, `commons`, `amethyst` (Android), `desktopApp`,
-  or `cli` / `amy`.
-- Affected version(s), commit SHA, platform, and OS.
-- Steps to reproduce, a proof of concept, or a failing test.
-- Any suggested remediation.
-
-### What to expect
-
-- **Acknowledgement within 48 hours** of your report.
-- We will investigate and keep you informed of progress.
-- We will coordinate a release and disclosure timeline with you. We aim to
-  ship a fix within 90 days for high and critical issues, faster when key
-  material or DM confidentiality is at risk.
-- Credit will be given to reporters in the security advisory and release
-  notes (unless you prefer to remain anonymous).
-
-## Scope
-
-In scope:
-
-- Source code in this repository across all modules.
-- Released binaries (APK, DMG, MSI, DEB, RPM, AppImage, tarball) built from
-  this repository.
-- Cryptographic handling: signing, NIP-04 / NIP-17 / NIP-44 encryption, key
-  storage (Android Keystore, desktop keychain), NIP-46 bunker flows, NIP-55
-  external signer integration.
-- Relay client behavior that could leak private data or bypass authorization.
-
-Out of scope:
-
-- Vulnerabilities in third-party relays, bridges, media servers, or Nostr
-  clients not built from this repository.
-- Issues that require a rooted / jailbroken device, a compromised host, or
-  physical access with the device unlocked.
-- Weaknesses inherent to the Nostr protocol itself — please report these
-  upstream at <https://github.com/nostr-protocol/nips>.
-- Denial-of-service from a malicious relay the user has explicitly connected
-  to.
-- Social-engineering and phishing that does not exploit an app-level flaw.
-
-## Disclosure Policy
-
-We follow a coordinated disclosure model. We ask that you:
-
-- Give us reasonable time to investigate and release a fix before any public
-  disclosure.
-- Avoid accessing or modifying other users' data during research.
-- Only interact with accounts and data you own or have explicit permission to
-  test.
-- Act in good faith.
-
-We will not pursue or support legal action against researchers who follow
-this policy. We commit to responding promptly and treating all reports
-seriously.
-
-Thank you for helping keep Amethyst and its users safe.

SKILL.md

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

amethyst/build.gradle

@@ -0,0 +1,398 @@
+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 = 435
+        versionName = generateVersionName("1.06.3")
+        buildConfigField "String", "RELEASE_NOTES_ID", "\"0b6af7660b44215b0edf9c39a1c9c0b4aafba7aba1ae28665ffcecb1a9717195\""
+
+        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'
+        ]
+    }
+
+    buildTypes {
+        release {
+            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), 'proguard-rules.pro'
+            minifyEnabled = true
+        }
+        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"
+        }
+
+        fdroid {
+            dimension "channel"
+        }
+    }
+
+    splits {
+        abi {
+            enable = true
+            reset()
+            include "x86", "x86_64", "arm64-v8a", "armeabi-v7a"
+            universalApk = true
+        }
+    }
+
+    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: ':ammolite')
+    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
+    implementation libs.androidx.material.icons
+
+    // 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
+
+    // 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
+
+    // PushNotifications
+    playImplementation platform(libs.firebase.bom)
+    playImplementation libs.firebase.messaging
+
+    //PushNotifications(FDroid)
+    fdroidImplementation libs.unifiedpush
+
+    // Charts
+    implementation libs.vico.charts.compose
+    implementation libs.vico.charts.m3
+
+    // GeoHash
+    implementation libs.drfonfon.geohash
+
+    // 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
+
+    // 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)
+
+    implementation libs.tor.android
+    implementation libs.jtorctl
+
+    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

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

@@ -1,393 +0,0 @@
-# iOS Support for Amethyst
-
-> **Status:** in-progress — `iosArm64`/`iosSimulatorArm64` targets are configured in `quartz` and `commons` (Phase 1), but no `iosApp` module exists yet — later phases not built.
-> _Audited 2026-06-30._
-
-**Date:** 2026-05-24
-**Status:** Phase 1 complete; Phase 2 in flight
-**Owner:** TBD
-
-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-06-20-napplet-inter-applet.md

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

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

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

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

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

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

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

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

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

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

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

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

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