brand: phoenix in the remaining mobile/PWA assets; drop dead splash rasters

Rounds out the phoenix rebrand for assets the earlier logo.svg swap
missed:

- public/icon-192.png / icon-512.png (PWA install icons, referenced by
  manifest.webmanifest) still had the old bolt-on-circle mark.
- Android's push-notification status-bar icon (ic_stat_ditto, all
  densities) was carrying an even older mark — a ringed-planet icon
  from 'Ditto', the project two forks back. Regenerated as a white
  phoenix silhouette (status-bar icons must be flat white on
  transparent; the OS tints them).
- android/.../splash_icon_vector.xml, the actual live Android 12+
  splash icon (wired via styles.xml's windowSplashScreenAnimatedIcon),
  had the old double-bolt path hardcoded. Replaced with the phoenix
  path and recomputed the scale/center math for its 1446x1246 viewBox.
- ios/.../Splash.imageset (wired into LaunchScreen.storyboard) had an
  even older blue crossed-arrow mark predating Agora. Regenerated as
  the brand-orange phoenix on white, matching the existing small
  centered-mark proportions.

Also deleted the legacy per-density drawable*/splash.png and
drawable/splash_icon.png rasters: confirmed unreferenced by any theme,
manifest, or code (the app fully migrated to the Android 12
SplashScreen API / splash_icon_vector.xml), so they were dead weight
carrying outdated branding no user could ever see.

generate-icons.sh now produces all of the above so future logo changes
regenerate everything in one pass instead of missing assets again.

Note: unlike the web assets, the Android/iOS changes here only take
effect on the next native app build + store release — there's no web
deploy step for them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.agents/skills/capacitor-compat/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: capacitor-compat
+description: Browser-API gotchas inside Capacitor's WKWebView (iOS) and Android WebView — which common web APIs silently fail, the downloadTextFile/openUrl helpers that bridge web and native, platform detection, and the installed Capacitor plugins. Load when writing code that interacts with file downloads, external URLs, or platform-specific behavior.
+---
+
+# Capacitor Compatibility
+
+Ditto runs inside Capacitor's WKWebView on iOS and WebView on Android. Several common web APIs **do not work** in this environment. Always account for native platforms when writing code that interacts with browser-specific features.
+
+## What Doesn't Work in WKWebView (iOS)
+
+- **`<a download>` file downloads** — programmatically creating an anchor with `a.download` and clicking it silently fails. WKWebView ignores the `download` attribute entirely.
+- **`<a target="_blank">` new tabs** — programmatic clicks on anchors with `target="_blank"` are blocked. There are no tabs in a native app.
+- **`window.open()`** — may be blocked or behave unexpectedly without user-gesture context.
+
+For a deeper list of Apple Lockdown Mode restrictions that also affect WKWebView, load the **`lockdown-mode`** skill.
+
+## File Downloads and URL Opening
+
+`src/lib/downloadFile.ts` provides two utilities that handle the web/native split automatically. **Always use these** instead of manually constructing anchors.
+
+### `downloadTextFile(filename, content)`
+
+Saves a text file to the user's device. On web it uses the `<a download>` pattern. On native it writes to the Capacitor cache directory via `@capacitor/filesystem` and presents the native share sheet via `@capacitor/share`.
+
+```typescript
+import { downloadTextFile } from '@/lib/downloadFile';
+
+await downloadTextFile('backup.txt', fileContents);
+```
+
+### `openUrl(url)`
+
+Opens a URL in a new browser tab on web, or presents the native share sheet on Capacitor.
+
+```typescript
+import { openUrl } from '@/lib/downloadFile';
+
+await openUrl('https://example.com/image.jpg');
+```
+
+**CRITICAL**: Never use `document.createElement('a')` with `.click()` for downloads or opening URLs. The utilities above work correctly on all platforms; manual anchors silently fail on iOS.
+
+## Detecting Native Platforms
+
+Use `Capacitor.isNativePlatform()` from `@capacitor/core` when you need platform-specific behavior:
+
+```typescript
+import { Capacitor } from '@capacitor/core';
+
+if (Capacitor.isNativePlatform()) {
+  // iOS or Android
+} else {
+  // Web browser
+}
+```
+
+Reserve platform forks for cases where behavior genuinely differs (share sheets, secure storage, haptics). Most UI code should stay platform-agnostic.
+
+## Installed Capacitor Plugins
+
+- `@capacitor/app` — app lifecycle events (deep links, back button)
+- `@capacitor/core` — core runtime and platform detection
+- `@capacitor/filesystem` — read/write files on the native filesystem
+- `@capacitor/haptics` — native haptics
+- `@capacitor/keyboard` — keyboard control (hide accessory bar, etc.)
+- `@capacitor/local-notifications` — schedule local push notifications
+- `@capacitor/share` — native share sheet
+- `@capacitor/status-bar` — control the native status-bar style
+- `@capgo/capacitor-autofill-save-password` — iOS keychain autofill for nsec
+- `capacitor-secure-storage-plugin` — OS-level secure storage (iOS Keychain / Android KeyStore)
+
+After adding or removing plugins, run `npm run cap:sync` to update the native projects.

.agents/skills/ci-cd-publishing/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: ci-cd-publishing
+description: Ditto's release and publishing pipeline — cutting a version tag, Zapstore APK publishing with NIP-46 bunker auth, nsite web deploys via nsyte, and Google Play AAB uploads via fastlane supply. Includes GitLab CI variable setup and credential rotation.
+---
+
+# CI/CD Pipeline and Publishing
+
+Ditto uses GitLab CI (`.gitlab-ci.yml`) to run tests on every commit, deploy the web app to nsite on every default-branch push, and build + publish Android binaries to Zapstore and Google Play on every tag. Load this skill when setting up CI credentials, rotating a signing key, diagnosing a failed publish, or adding a new publishing target.
+
+## Pipeline Overview
+
+| Stage     | Runs on                   | Job                                     |
+|-----------|---------------------------|-----------------------------------------|
+| `test`    | every commit (not tags)   | `npm run test`                          |
+| `deploy`  | default branch only       | `deploy-nsite` (Vite build → nsyte)     |
+| `build`   | tags only                 | `build-apk` (signed APK + AAB) + `build-ipa` (signed IPA on the Mac runner) |
+| `release` | tags only                 | GitLab Release with APK / AAB / IPA links |
+| `publish` | tags only                 | `publish-zapstore` + `publish-google-play` + `publish-app-store` |
+
+## Creating a Release
+
+Releases are triggered by pushing a version tag:
+
+```bash
+npm run release
+```
+
+This creates a tag in the format `v2026.03.14+abc1234` (date + short commit hash) and pushes it to GitLab, which triggers the `build-apk`, `release`, `publish-zapstore`, and `publish-google-play` jobs.
+
+For the full versioning / changelog / native-build workflow, load the **`release`** skill.
+
+## Zapstore Publishing
+
+The `publish-zapstore` CI job uploads signed APKs to [Zapstore](https://zapstore.dev/) using the [`zsp`](https://github.com/zapstore/zsp) CLI and NIP-46 bunker signing via Amber.
+
+**Configuration files:**
+
+- `zapstore.yaml` — app metadata for Zapstore (name, tags, icon, supported NIPs)
+- `.gitlab-ci.yml` — the `publish-zapstore` job definition
+
+**GitLab CI/CD variables** (Settings → CI/CD → Variables):
+
+| Variable | Description | Protected | Masked | Raw |
+|---|---|---|---|---|
+| `ZAPSTORE_BUNKER_URL` | NIP-46 bunker URL (`bunker://<pubkey>?relay=...`). No `secret` param needed after initial auth. | Yes | No | Yes |
+| `ZAPSTORE_CLIENT_KEY` | Hex private key used as the NIP-46 client identity for bunker communication | Yes | Yes | Yes |
+| `ANDROID_KEYSTORE_BASE64` | Base64-encoded Android signing keystore | Yes | Yes | Yes |
+| `KEYSTORE_PASSWORD` | Android keystore password | Yes | Yes | Yes |
+| `KEY_PASSWORD` | Android key password | Yes | Yes | Yes |
+
+### How NIP-46 bunker auth works in CI
+
+NIP-46 bunker signing requires two keys: the **user's key** (held by Amber) and a **client key** (the CI runner's identity). The bunker authorizes specific client pubkeys — once authorized, the client can request signatures without re-approval.
+
+The `publish-zapstore` job restores the client key from `ZAPSTORE_CLIENT_KEY` into `~/.config/zsp/bunker-keys/<bunker-pubkey>.key` before running `zsp`, so the bunker recognizes the CI runner as an already-authorized client.
+
+### Initial setup (one-time)
+
+Run the NIP-46 client-initiated auth script:
+
+```bash
+node scripts/nip46-auth.mjs
+```
+
+This generates a `nostrconnect://` URI. Import/paste it into Amber and approve the connection. The script outputs the `bunker://` URI and client key hex, and writes the client key to `~/.config/zsp/bunker-keys/`. Update the GitLab CI/CD variables with the printed values.
+
+Options:
+- `--relay <url>` — relay for NIP-46 communication (default: `wss://relay.ditto.pub`)
+- `--name <name>` — app name shown to the signer (default: `Ditto`)
+- `--timeout <sec>` — how long to wait for approval (default: 300)
+
+After authorization, the bunker recognizes the client key and no secret or manual approval is needed for CI runs. If the client key is rotated, run the script again and update the GitLab variables.
+
+## nsite Publishing
+
+The `deploy-nsite` CI job deploys the Vite build to [nsite](https://nsite.run) on every push to the default branch using [nsyte](https://github.com/sandwichfarm/nsyte). The job uploads `dist/` to Blossom servers and publishes site manifest events to Nostr relays.
+
+nsyte uses a NIP-46 bunker credential called **nbunksec** — a bech32-encoded string bundling the bunker pubkey, client secret key, and relay info into a single self-contained token. It's passed to nsyte via `--sec`.
+
+**GitLab CI/CD variables:**
+
+| Variable | Description | Protected | Masked | Raw |
+|---|---|---|---|---|
+| `NSITE_NBUNKSEC` | nbunksec credential from `nsyte ci`. Must start with `nbunksec1`. | Yes | Yes | Yes |
+
+### Initial setup (one-time)
+
+1. Install nsyte locally:
+   ```bash
+   curl -fsSL https://nsyte.run/get/install.sh | bash
+   ```
+2. Generate the CI credential:
+   ```bash
+   nsyte ci
+   ```
+   This guides you through connecting a NIP-46 bunker (e.g. Amber) and outputs an `nbunksec1...` string. The credential is shown only once.
+3. Add the `nbunksec1...` value as `NSITE_NBUNKSEC` in GitLab CI/CD settings. Mark it as **Protected** and **Masked**.
+
+### Configured relays and servers
+
+Relays the deploy job publishes to:
+
+- `wss://relay.ditto.pub`
+- `wss://relay.nsite.lol`
+- `wss://relay.dreamith.to`
+- `wss://relay.primal.net`
+
+Blossom servers:
+
+- `https://blossom.primal.net`
+- `https://blossom.ditto.pub`
+- `https://blossom.dreamith.to`
+
+The `--use-fallback-relays` and `--use-fallback-servers` flags include nsyte's built-in defaults for broader coverage. The `--fallback "/index.html"` flag enables SPA client-side routing.
+
+### Credential rotation
+
+To rotate the nsite credential:
+
+1. Revoke the old bunker connection in your signer app.
+2. Run `nsyte ci` again to generate a new `nbunksec1...` string.
+3. Update the `NSITE_NBUNKSEC` variable in GitLab CI/CD settings.
+
+## Google Play Publishing
+
+The `publish-google-play` CI job uploads Android AABs to [Google Play](https://play.google.com/store/apps/details?id=pub.ditto.app) using [fastlane supply](https://docs.fastlane.tools/actions/supply/). It runs after a successful AAB build and uploads directly to the production track.
+
+**GitLab CI/CD variables:**
+
+| Variable | Description | Protected | Masked | Raw |
+|---|---|---|---|---|
+| `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` | **Base64-encoded** contents of the Google Play API service account key JSON. The CI job decodes with `base64 -d` before passing to `fastlane supply`. | Yes | Yes | No |
+
+### Initial setup (one-time)
+
+1. Create or reuse a project in [Google Cloud Console](https://console.cloud.google.com/projectcreate).
+2. Enable the [Google Play Developer API](https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/) for that project.
+3. In Google Cloud Console, go to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts), create a service account, and download a JSON key file for it.
+4. In Google Play Console, go to [Users & Permissions](https://play.google.com/console/users-and-permissions), click **Invite new users**, enter the service account email, and grant it permission to manage releases for `pub.ditto.app`.
+5. **Base64-encode** the key file:
+
+   ```bash
+   # Linux
+   base64 -w0 service-account.json
+
+   # macOS
+   base64 -i service-account.json | tr -d '\n'
+   ```
+
+6. Add the base64-encoded value as `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` in GitLab CI/CD settings. Mark it as **Protected** and **Masked**. **Do not paste the raw JSON** — the CI script expects base64 and will fail to decode a raw value.
+
+### Key points
+
+- The job uploads the signed **AAB** (not APK) — Google Play requires App Bundles.
+- Uploads go directly to the **production** track. Google's review process still applies before the update reaches users.
+- Metadata, screenshots, and store-listing description are managed in the Play Console (the job uses `--skip_upload_metadata`, `--skip_upload_images`, `--skip_upload_screenshots`).
+- **Changelogs ("What's new in this version")** are uploaded from `android/fastlane/metadata/android/en-US/changelogs/<versionCode>.txt`, generated at CI time from the release summary paragraph in `CHANGELOG.md`. See "Release notes pipeline" below.
+- The same signing keystore used for Zapstore is reused here (`ANDROID_KEYSTORE_BASE64`, `KEYSTORE_PASSWORD`, `KEY_PASSWORD`).
+
+## App Store Publishing
+
+Ditto's iOS pipeline is split across two jobs:
+
+- **`build-ipa`** (stage `build`, `tags: [macos]`) runs on the self-hosted Mac runner. Decodes the App Store Connect API key, fetches the encrypted distribution cert + provisioning profile via fastlane match, builds the web assets, runs `cap sync ios`, stamps the marketing version into `project.pbxproj`, then `fastlane build_ipa` produces a signed App Store IPA at `artifacts/Ditto.ipa`. The IPA is uploaded to the GitLab Generic Packages registry as `Ditto-${CI_COMMIT_TAG}.ipa` (mirrors how `build-apk` publishes the APK and AAB) and exposed as a CI artifact for downstream jobs.
+- **`publish-app-store`** (stage `publish`, `tags: [macos]`) also runs on the self-hosted Mac runner. Consumes the IPA artifact via `needs: [build-ipa]` and the release-notes artifact via `needs: [release-notes]`. Decodes the API key, copies the release-notes summary into `ios/fastlane/metadata/en-US/release_notes.txt`, and runs `fastlane submit_release` which calls `deliver` to upload metadata + push the prebuilt IPA + auto-submit for App Store review. **macOS is required** even though the IPA is already signed: `fastlane deliver` shells out to Apple's iTMSTransporter / altool to upload the binary, and those tools only ship inside Xcode. A Linux container ran into `No such file or directory @ dir_chdir0` from `JavaTransporterExecutor#execute` because `Helper.itms_path` resolved to a missing Xcode path.
+
+The Mac runner is therefore used for both iOS jobs. For runner administration (operating the Mac, restarting the agent, viewing logs, rotating signing certs), load the **`mac-runner`** skill.
+
+**Configuration files:**
+
+- `ios/fastlane/Fastfile` — exposes four lanes:
+  - `build_ipa` — setup_ci → match (readonly, with API key) → increment_build_number → build_app. Used by CI's `build-ipa`.
+  - `submit_release` — reads `IPA_PATH` env var, calls deliver against the prebuilt IPA. Used by CI's `publish-app-store`.
+  - `release` — combines build_ipa + submit_release; convenience for local one-shot runs.
+  - `submit_only` — debug lane that skips build/upload and only runs deliver against an already-uploaded build (set `BUILD_NUMBER` + `VERSION` env vars). See the `mac-runner` skill.
+- `ios/fastlane/Appfile` — bundle identifier and team ID
+- `ios/fastlane/Matchfile` — points at the shared `soapbox-pub/certificates` repo
+- `ios/fastlane/metadata/en-US/release_notes.txt` — placeholder; CI overwrites it with the release summary paragraph from `CHANGELOG.md` per release
+- `.gitlab-ci.yml` — `build-ipa` and `publish-app-store` both run on the Mac runner (`tags: [macos]`)
+
+**Code signing storage**: a private GitLab repo `soapbox-pub/certificates` holds encrypted distribution certs and provisioning profiles, managed by [fastlane match](https://docs.fastlane.tools/actions/match/). Match handles cert/profile lifecycle: one passphrase decrypts everything; the same repo can hold signing material for multiple Soapbox iOS apps under team `GZLTTH5DLM`.
+
+**App Store Connect auth**: a long-lived [App Store Connect API key](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api) (`.p8` file + key ID + issuer ID) authenticates `match`, `deliver`, and `pilot`. Avoids 2FA prompts that would interrupt CI.
+
+**Distribution**: `submit_for_review: true` automatically pushes the build into Apple's review queue once uploaded. `automatic_release: false` keeps a human-controlled final gate — once Apple approves, you click "Release" in the App Store Connect web UI to publish to users. To remove the manual gate, flip `automatic_release` to `true` in `ios/fastlane/Fastfile`.
+
+**Release notes**: copied from the `release-notes` job's artifact `artifacts/release-notes-summary.txt` (the leading plaintext paragraph of the version's `CHANGELOG.md` section) into `ios/fastlane/metadata/en-US/release_notes.txt`, uploaded by `deliver` as the App Store "What's New in This Version" text. See "Release notes pipeline" below.
+
+**IPA distribution beyond the App Store**: `build-ipa` uploads the signed IPA to the GitLab Generic Packages registry, and the `release` job links it from the GitLab Release page. The IPA is signed with the App Store distribution profile, so it isn't directly sideloadable — installation goes through Apple's review process — but having it as a stable artifact lays the groundwork for AltStore or ad-hoc distribution later (which would require a separate provisioning profile).
+
+**GitLab CI/CD variables:**
+
+| Variable | Description | Protected | Masked | Raw |
+|---|---|---|---|---|
+| `MATCH_PASSWORD` | Symmetric passphrase used by match to encrypt/decrypt certs and profiles. The single most important secret — losing it makes the cert repo unreadable. | Yes | Yes | Yes |
+| `MATCH_GIT_BASIC_AUTHORIZATION` | Base64 of `username:deploy-token` for HTTPS clone of the certificates repo. Generated from a `read_repository`-scoped deploy token on `soapbox-pub/certificates`. | Yes | Yes | Yes |
+| `APP_STORE_CONNECT_API_KEY_ID` | App Store Connect API key ID (10 chars). | Yes | No | Yes |
+| `APP_STORE_CONNECT_API_KEY_ISSUER_ID` | App Store Connect issuer ID (UUID). | Yes | No | Yes |
+| `APP_STORE_CONNECT_API_KEY_P8_BASE64` | Base64-encoded contents of the `.p8` private key file. CI decodes with `base64 -d` into `~/.private_keys/AuthKey_<KEY_ID>.p8` and removes it in `after_script`. | Yes | Yes | Yes |
+| `FASTLANE_KEYCHAIN_PASSWORD` | Password for the ephemeral keychain `setup_ci` creates per build. Random per setup; keep stable across runs. | Yes | Yes | Yes |
+
+### Initial setup (one-time)
+
+1. **Provision the Mac runner.** See the **`mac-runner`** skill for hardware/launchd setup, Xcode, Homebrew, fastlane, and `gitlab-runner` registration.
+
+2. **Create the App Store Connect API key.** Log in to [App Store Connect](https://appstoreconnect.apple.com) → Users and Access → Integrations → App Store Connect API → Generate. Use the **App Manager** role (sufficient for `deliver`'s upload + submit-for-review). Download the `.p8` file (one-time download — Apple won't show it again). Note the **Key ID** (10-char string next to the key) and the **Issuer ID** (UUID at the top of the API page).
+
+   Set the three GitLab CI variables:
+   ```bash
+   # Replace <ISSUER_ID>, <KEY_ID>, and the path to your .p8
+   curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+     "https://gitlab.com/api/v4/projects/$PROJECT_ID/variables" \
+     --data-urlencode "key=APP_STORE_CONNECT_API_KEY_ISSUER_ID" \
+     --data-urlencode "value=<ISSUER_ID>" \
+     --data-urlencode "protected=true" --data-urlencode "raw=true"
+   # repeat for APP_STORE_CONNECT_API_KEY_ID
+   # for the .p8, base64 first:
+   base64 -i AuthKey_<KEY_ID>.p8 | tr -d '\n'  # paste this as APP_STORE_CONNECT_API_KEY_P8_BASE64 (masked)
+   ```
+
+3. **Create the certificates repo.** A private GitLab repo at `soapbox-pub/certificates` holds match-encrypted certs/profiles. Create a project deploy token on it (Settings → Repository → Deploy tokens) with `read_repository` scope. Encode `username:token` as base64 → set as `MATCH_GIT_BASIC_AUTHORIZATION` (protected, masked, raw).
+
+4. **Generate `MATCH_PASSWORD` and `FASTLANE_KEYCHAIN_PASSWORD`.** Both are arbitrary strong random strings — `openssl rand -base64 32 | tr -d '=+/' | head -c 32` works. Store them as protected, masked GitLab variables.
+
+5. **Bootstrap match certs via a one-shot CI job** (preferred over running match locally — avoids the macOS keychain UI permission dialogs that fastlane bug [#15185](https://github.com/fastlane/fastlane/issues/15185) trips on newer macOS):
+
+   a. Create a temporary write-scoped GitLab variable. The deploy token is `read_repository`; for the initial cert creation match needs to push. Encode `username:write-pat` as base64 and set it as `MATCH_GIT_BASIC_AUTHORIZATION_WRITE` (Protected, Masked, Raw).
+
+   b. Add a temporary `setup-match` job to `.gitlab-ci.yml` that runs on the macos runner with `setup_ci` (which creates an ephemeral keychain — bypasses the GUI permission issue):
+
+      ```yaml
+      setup-match:
+        stage: publish
+        tags: [macos]
+        rules:
+          - if: $SETUP_MATCH == "1"
+            when: manual
+        script:
+          - export ASC_KEY_PATH="$HOME/.private_keys/AuthKey_${APP_STORE_CONNECT_API_KEY_ID}.p8"
+          - mkdir -p "$HOME/.private_keys" && chmod 700 "$HOME/.private_keys"
+          - echo "$APP_STORE_CONNECT_API_KEY_P8_BASE64" | base64 -d > "$ASC_KEY_PATH"
+          - chmod 600 "$ASC_KEY_PATH"
+          - cd ios
+          - export MATCH_GIT_BASIC_AUTHORIZATION="$MATCH_GIT_BASIC_AUTHORIZATION_WRITE"
+          - unset APP_STORE_CONNECT_API_KEY_PATH || true
+          - |
+            cat > Fastfile.setup <<'RUBY'
+            default_platform(:ios)
+            platform :ios do
+              lane :setup do
+                setup_ci
+                api_key = {
+                  key_id: ENV.fetch("APP_STORE_CONNECT_API_KEY_ID"),
+                  issuer_id: ENV.fetch("APP_STORE_CONNECT_API_KEY_ISSUER_ID"),
+                  key: File.binread(ENV.fetch("ASC_KEY_PATH")),
+                  duration: 1200,
+                  in_house: false,
+                }
+                match(type: "appstore", readonly: false, api_key: api_key, force_for_new_devices: true)
+              end
+            end
+            RUBY
+          - mv fastlane/Fastfile fastlane/Fastfile.bak
+          - mv Fastfile.setup fastlane/Fastfile
+          - fastlane setup
+          - mv fastlane/Fastfile.bak fastlane/Fastfile
+        after_script:
+          - rm -f "$HOME/.private_keys"/AuthKey_*.p8 || true
+      ```
+
+   c. Trigger the pipeline manually with `SETUP_MATCH=1`:
+
+      ```bash
+      curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+        "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipeline" \
+        --data-urlencode "ref=main" \
+        --data-urlencode "variables[][key]=SETUP_MATCH" \
+        --data-urlencode "variables[][value]=1"
+      # Then play the manual setup-match job
+      ```
+
+   d. Once the job succeeds (cert + profile pushed to the certificates repo), **delete the `setup-match` job from `.gitlab-ci.yml` and the `MATCH_GIT_BASIC_AUTHORIZATION_WRITE` variable**. They're only needed for bootstrap.
+
+### Yearly cert renewal
+
+Apple distribution certs expire annually. Renewal is one command per year, run on any Mac:
+
+```bash
+cd ~/Projects/ditto/ios
+fastlane match nuke distribution      # revokes old cert in Apple's portal, removes from match repo
+fastlane match appstore               # creates new cert + profile, encrypts, commits, pushes
+```
+
+CI's next tag run picks up the new files automatically (`match(... readonly: true)`).
+
+### Disaster recovery (Mac dies / new developer joins)
+
+```bash
+git clone https://gitlab.com/soapbox-pub/ditto.git
+cd ditto/ios
+fastlane match appstore --readonly    # decrypts existing certs/profiles using MATCH_PASSWORD
+```
+
+No re-issuance of certs needed — the cert repo is the source of truth.
+
+### App Store Connect API key rotation
+
+App Store Connect API keys can be revoked anytime. To rotate:
+
+1. App Store Connect → Users and Access → Integrations → App Store Connect API → Generate new key
+2. Download the new `.p8`, note the new key ID
+3. Update `APP_STORE_CONNECT_API_KEY_ID` and `APP_STORE_CONNECT_API_KEY_P8_BASE64` in GitLab variables
+4. (Issuer ID stays the same — it's per-team, not per-key)
+5. Revoke the old key in App Store Connect
+
+### Key points
+
+- `build-ipa` (Mac) produces a signed **IPA** (App Store distribution format) and uploads it to GitLab's Generic Packages registry. `publish-app-store` (also Mac) submits it to Apple via `deliver`.
+- Builds go to **App Store Connect**, automatically submit for review, but do **not** auto-release after approval. The final "Release" click is manual in the web UI.
+- Marketing version comes from the git tag (`v2.1.0` → `MARKETING_VERSION = 2.1.0`); build number comes from `CI_PIPELINE_IID`.
+- Release notes ("What's New in This Version") come from the release-notes summary paragraph (see "Release notes pipeline" below).
+- `setup_ci` (in `build-ipa`) creates an ephemeral keychain per build, so the runner never touches the login keychain — works whether or not a GUI session is logged in.
+- `publish-app-store` does no code signing, but it still needs macOS: `fastlane deliver` shells out to Apple's iTMSTransporter / altool to upload the binary, and those tools only ship inside Xcode.
+
+## Release notes pipeline
+
+Release notes for all three storefronts (App Store, Google Play, GitLab Release page) and the in-app version-update toast are derived from a single source: `CHANGELOG.md`.
+
+**The `release-notes` job** (stage `build`, default `node:22` image, runs only on `v*` tags) calls `scripts/extract-release-notes.mjs` twice and publishes two artifacts:
+
+- `artifacts/release-notes.md` — the full section for this version (summary paragraph + `### Added` / `### Changed` / etc. lists). Used as the GitLab Release description.
+- `artifacts/release-notes-summary.txt` — only the leading plaintext paragraph (max 500 chars by convention). Used as the App Store / Play Store "What's new" text. Falls back to `Ditto vX.Y.Z` if the section has no summary paragraph.
+
+**Downstream consumers** all pull from the `release-notes` job via `needs:`:
+
+| Consumer | Job | Artifact used |
+|---|---|---|
+| GitLab Release description | `release` | `release-notes.md` |
+| App Store "What's New" | `publish-app-store` | `release-notes-summary.txt` → copied to `ios/fastlane/metadata/en-US/release_notes.txt` → uploaded by `deliver` |
+| Play Store "What's new" | `publish-google-play` | `release-notes-summary.txt` → copied to `android/fastlane/metadata/android/en-US/changelogs/<versionCode>.txt` → uploaded by `supply` |
+| In-app toast | `src/components/VersionCheck.tsx` (runtime) | Re-parses `public/CHANGELOG.md` via `parseChangelog()` and reads `entry.summary` (with a fallback to the legacy first-bullet behavior) |
+
+**The summary format** is documented in the `release` skill — a single plaintext paragraph immediately under the `## [X.Y.Z] - YYYY-MM-DD` heading, before any `### Category`. The script enforces nothing on the parser side; CI emits a warning when the summary exceeds 500 chars but does not fail the build.
+
+**To preview locally** what each storefront will receive:
+
+```bash
+node scripts/extract-release-notes.mjs vX.Y.Z              # full GitLab Release body
+node scripts/extract-release-notes.mjs vX.Y.Z --summary    # storefront blurb
+```

.agents/skills/file-uploads/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: file-uploads
+description: Upload files (images, media, attachments) from the browser to a Blossom server via the useUploadFile hook, and attach them to Nostr events with NIP-94 imeta tags.
+---
+
+# File Uploads on Nostr
+
+This project includes a `useUploadFile` hook that uploads files to Blossom servers and returns NIP-94-compatible tags. Use it whenever a feature needs to accept a user-provided file (avatars, banners, post attachments, etc.).
+
+## The `useUploadFile` Hook
+
+```tsx
+import { useUploadFile } from "@/hooks/useUploadFile";
+
+function MyComponent() {
+  const { mutateAsync: uploadFile, isPending: isUploading } = useUploadFile();
+
+  const handleUpload = async (file: File) => {
+    try {
+      // Returns an array of NIP-94-compatible tags.
+      // The first tag is the `url` tag; its second element is the file URL.
+      const tags = await uploadFile(file);
+      const url = tags[0][1];
+      // ...use the url
+    } catch (error) {
+      // ...handle errors (show a toast, etc.)
+    }
+  };
+
+  // ...rest of component
+}
+```
+
+The hook is a TanStack Query mutation, so `isPending` can drive loading UI and `mutateAsync` integrates cleanly with `async`/`await` flows.
+
+## Attaching Files to Events
+
+### Kind 0 (profile metadata)
+
+Use the plain URL in the relevant JSON field:
+
+```ts
+const tags = await uploadFile(file);
+const url = tags[0][1];
+
+createEvent({
+  kind: 0,
+  content: JSON.stringify({ ...existingMetadata, picture: url }),
+});
+```
+
+### Kind 1 (text notes) and other content events
+
+Append the URL to `content`, and add one `imeta` tag per file. `imeta` carries the NIP-94 metadata (mime type, dimensions, blurhash, etc.) that the uploader returned:
+
+```ts
+const tags = await uploadFile(file); // e.g. [["url", "https://..."], ["m", "image/png"], ["dim", "1024x768"], ...]
+const url = tags[0][1];
+
+// Flatten the NIP-94 tags into a single imeta tag value.
+const imeta = tags.map(([name, value]) => `${name} ${value}`);
+
+createEvent({
+  kind: 1,
+  content: `Check this out ${url}`,
+  tags: [["imeta", ...imeta]],
+});
+```
+
+Repeat the pattern (one `imeta` tag per file) for multiple attachments.
+
+## Common Patterns
+
+- **Avatar / banner pickers:** wrap an `<input type="file" accept="image/*">` and call `uploadFile` on change; on success, update the relevant profile field and publish a kind 0 event.
+- **Post composers:** call `uploadFile` for each selected file before publishing the note, then build `imeta` tags alongside `content`.
+- **Progress UI:** use `isPending` from the mutation to disable the submit button and show a spinner or skeleton.
+- **Error handling:** wrap `uploadFile` in `try/catch` and surface failures via `useToast` — network and Blossom-server errors are common and should never break the UI.
+
+## Constraints
+
+- The hook requires a logged-in user (Blossom auth is signed by the user's signer). Guard uploads behind `useCurrentUser`.
+- Don't store or display raw `File` objects after upload — always use the returned URL.
+- Large files may take time; prefer `mutateAsync` over `mutate` so the caller can `await` completion before publishing an event that references the URL.

.agents/skills/git-workflow/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: git-workflow
+description: Ditto's git conventions — validating changes before committing, writing commit messages that match project style, and attributing regressions with a Regression-of trailer so the release changelog skill can filter them from the "Fixed" section.
+---
+
+# Git Workflow
+
+Ditto expects every completed task to end with a git commit. This skill covers the pre-commit validation loop, commit-message conventions, and the `Regression-of:` trailer used by the release skill to filter intra-release regressions from the changelog.
+
+## Pre-commit Validation
+
+**Your task is not finished until the code type-checks and builds without errors.** In priority order:
+
+1. **Type Checking** (required) — `tsc --noEmit`
+2. **Building/Compilation** (required) — `vite build`
+3. **Linting** (recommended; fix anything critical) — `eslint`
+4. **Tests** (if available) — `vitest run`
+5. **Git commit** (required)
+
+The full `npm run test` script runs all of these in sequence; running it is equivalent to steps 1–4.
+
+## Using Git
+
+Use `git status` and `git diff` to review changes, and `git log` to learn the project's commit-message conventions before writing a new one. If you make a mistake, `git checkout` restores files.
+
+When your changes are complete and validated, create a commit with a message that focuses on **why** the change was made (not just **what**). Summaries should fit on one line; a body is warranted for non-trivial changes.
+
+**Always commit when you are finished making changes. Non-negotiable — every completed task ends with a commit. Don't leave uncommitted changes.**
+
+## Contributing Guide
+
+When preparing changes for a merge request, also follow the guidelines in `CONTRIBUTING.md`. It includes a self-review checklist (step 8) that should be run against your diff before committing.
+
+## Attributing Regressions
+
+When a commit fixes a bug that was introduced by an identifiable prior commit, add a `Regression-of:` trailer at the bottom of the commit message body referencing the offending commit's short SHA:
+
+```
+Fix missing background on expanded emoji picker in feeds
+
+The compose box overhaul accidentally dropped the bg-background class
+when refactoring the picker out of QuickReactMenu.
+
+Regression-of: 3aa08ba9
+```
+
+This is a standard Git trailer (compatible with `git interpret-trailers`) that records the cause-and-effect link directly in history. It is consumed by the `release` skill to detect intra-release regressions and exclude them from the changelog's "Fixed" section, and it makes future debugging and post-mortems substantially faster.
+
+### When to add it
+
+- The commit fixes a bug (not a new feature, refactor, or doc change).
+- The introducing commit is identifiable with reasonable effort.
+
+### When to skip it
+
+- The bug is pre-existing with no clear single origin.
+- The behavior was always wrong (no regression).
+- The introducing commit cannot be determined after a brief search.
+
+### Finding the introducing commit
+
+- `git log -S '<removed-or-changed-string>'` — find commits that touched a specific string.
+- `git log --oneline -- path/to/file` — list all commits touching a file.
+- `git blame -L <start>,<end> -- path/to/file` — find who last changed specific lines.
+
+This convention is **strongly recommended but not required.** When the origin is non-obvious, prioritize shipping the fix over hunting indefinitely.

.agents/skills/mac-runner/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: mac-runner
+description: Operate the self-hosted GitLab Runner on the Mac that builds Ditto's iOS IPA. Covers SSH access, restarting the runner, viewing logs, updating Xcode, debugging fastlane locally, and rotating match certificates.
+---
+
+# Mac Runner Operations
+
+Ditto's iOS pipeline runs two CI jobs on a self-hosted GitLab Runner on a MacBook in the rack: `build-ipa` (signs and builds the IPA via Xcode + fastlane match) and `publish-app-store` (uploads the IPA via `fastlane deliver`, which shells out to Apple's iTMSTransporter — that tool only ships inside Xcode, so this job can't run on Linux). This skill covers operating the Mac.
+
+This skill covers operating the runner: SSH access, restarting after crashes or Xcode updates, watching logs, debugging fastlane locally, and rotating the match certificates. For initial provisioning, App Store Connect API key creation, and GitLab CI variable setup, load the **`ci-cd-publishing`** skill.
+
+## Quick reference
+
+| Need | Command |
+|---|---|
+| SSH in | `ssh alex@alexs-air.lan` |
+| Runner status | `gitlab-runner status` |
+| Restart runner | `gitlab-runner restart` (after `eval "$(/opt/homebrew/bin/brew shellenv)"`) |
+| Stdout log | `tail -f ~/gitlab-runner.out.log` |
+| Stderr log | `tail -f ~/gitlab-runner.err.log` |
+| Runner config | `~/.gitlab-runner/config.toml` |
+| LaunchAgent plist | `~/Library/LaunchAgents/gitlab-runner.plist` |
+
+## Architecture
+
+- **Host**: `alexs-air.lan` (Apple Silicon MacBook, macOS 26+, Xcode 26+)
+- **User**: `alex` (the runner runs in user-mode so it can access keychain and Xcode UI tooling)
+- **Tooling**: Homebrew (`/opt/homebrew`), `gitlab-runner`, `node@22`, `ruby@3.3`, fastlane installed as a user gem under `~/.gem/ruby/3.3.0/`
+- **Service**: launchd LaunchAgent at `~/Library/LaunchAgents/gitlab-runner.plist`. `KeepAlive=true` (auto-restart on crash) and `RunAtLoad=true` (starts on login). The agent loads when `alex` logs in via auto-login at boot.
+- **Tags**: `macos`, `ios`, `xcode` — both `build-ipa` and `publish-app-store` in `.gitlab-ci.yml` target this runner. `publish-app-store` doesn't sign anything, but it still needs Xcode's bundled iTMSTransporter to push the IPA to App Store Connect.
+- **Shell setup**: `~/.bash_profile` sources brew shellenv and prepends `~/.gem/ruby/3.3.0/bin` and `/opt/homebrew/opt/ruby@3.3/bin` to `PATH` so `bash --login` (the runner's executor) finds fastlane + ruby 3.3.
+
+### Why Ruby 3.3, not the brewed 4.0
+
+Brewed `fastlane` (current version) ships running on Ruby 4.0 from `brew install ruby`. Ruby 4.0's OpenSSL bindings hit fastlane bug [#20553](https://github.com/fastlane/fastlane/issues/20553) — `OpenSSL::PKey::EC.new(pem)` raises "invalid curve name" for `prime256v1` keys, which breaks every App Store Connect API key signing operation. Ruby 3.3.x doesn't have this bug. So we install fastlane via `gem install fastlane --user-install` on `ruby@3.3` instead of `brew install fastlane`.
+
+### Why IPv6 is disabled on Wi-Fi
+
+`networksetup -setv6off Wi-Fi` is set because Ruby's net/http on this machine attempted IPv6 to `rubygems.org` first and timed out (~30 s per request). Disabling IPv6 on the Wi-Fi interface forces IPv4 immediately. To re-enable: `sudo networksetup -setv6automatic Wi-Fi`.
+
+## Verifying the runner is healthy
+
+From any machine:
+
+```bash
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/runners/53111580" \
+  | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['status'], d['online'])"
+```
+
+Expected: `online True`. If `offline` or `not_connected`, SSH in and check:
+
+```bash
+ssh alex@alexs-air.lan
+gitlab-runner status
+ps aux | grep gitlab-runner
+tail -50 ~/gitlab-runner.err.log
+```
+
+## Restarting the runner
+
+After a Mac reboot, the runner should start automatically via the LaunchAgent. To restart manually:
+
+```bash
+ssh alex@alexs-air.lan
+eval "$(/opt/homebrew/bin/brew shellenv)"
+gitlab-runner restart
+```
+
+If `gitlab-runner restart` reports "service not installed", reinstall:
+
+```bash
+gitlab-runner install
+gitlab-runner start
+```
+
+This rewrites the LaunchAgent plist.
+
+## Watching a CI job run live
+
+```bash
+ssh alex@alexs-air.lan 'tail -f ~/gitlab-runner.out.log'
+```
+
+The runner streams build output to stdout. The same output appears in the GitLab job UI.
+
+## Updating Xcode
+
+After a major Xcode update:
+
+```bash
+ssh alex@alexs-air.lan
+sudo xcodebuild -license accept     # accept the new license non-interactively
+xcode-select --install              # ensure command-line tools are present
+xcodebuild -version                 # confirm version
+```
+
+Then trigger a no-op tag rebuild (e.g. cut a patch release) to verify the runner still works.
+
+## Debugging fastlane locally
+
+If `build-ipa` fails in CI, reproduce on the Mac. The env vars below mirror what CI sets up:
+
+```bash
+ssh alex@alexs-air.lan
+cd ~/Projects/ditto
+git pull origin main
+eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# Match what CI provides
+export CI_COMMIT_TAG=v2.x.y
+export CI_PIPELINE_IID=99999
+export MATCH_PASSWORD='<from GitLab CI variables>'
+export MATCH_GIT_BASIC_AUTHORIZATION='<base64 of ci-readonly:gldt-...>'
+export APP_STORE_CONNECT_API_KEY_ID=<key-id>
+export APP_STORE_CONNECT_API_KEY_ISSUER_ID=<issuer-id>
+export ASC_KEY_PATH=~/.private_keys/AuthKey_<key-id>.p8
+
+# Build web assets and sync to Capacitor iOS project (CI does this in before_script)
+npm ci
+npx vite build -l error
+cp dist/index.html dist/404.html
+npx cap sync ios
+node scripts/patch-cap-config.mjs
+
+# Stamp marketing version (CI does this in script)
+VERSION="${CI_COMMIT_TAG#v}"
+sed -i '' "s/MARKETING_VERSION = [0-9.]*;/MARKETING_VERSION = ${VERSION};/g" ios/App/App.xcodeproj/project.pbxproj
+
+# Run the build lane
+cd ios
+fastlane build_ipa
+```
+
+This produces the IPA at `../artifacts/Ditto.ipa` exactly like CI. Add `--verbose` for detailed output.
+
+To also test the submission step end-to-end (this calls Apple, so be ready to "Remove from Review" in App Store Connect afterward):
+
+```bash
+export IPA_PATH="$HOME/Projects/ditto/artifacts/Ditto.ipa"
+fastlane submit_release
+```
+
+Or, to debug *just* the submission against an already-uploaded build without rebuilding, use the `submit_only` lane (see "Debugging App Store submission with the `submit_only` lane" below).
+
+## Rotating match certificates (yearly)
+
+Apple distribution certs expire one year after issuance. To renew:
+
+```bash
+ssh alex@alexs-air.lan
+cd ~/Projects/ditto/ios
+eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# Set Apple credentials (API key path)
+export MATCH_PASSWORD='<from GitLab CI variables>'
+
+# Revoke the expiring cert in Apple's portal and remove from the match repo
+fastlane match nuke distribution
+
+# Issue a new cert, generate a new App Store profile, encrypt, commit, push
+fastlane match appstore \
+  --api_key_path ~/.private_keys/AuthKey_<KEY_ID>.p8 \
+  --api_key_id <KEY_ID> \
+  --api_issuer_id <ISSUER_ID>
+```
+
+CI's next tag run picks up the new files via `match(... readonly: true)`. No GitLab variables to update.
+
+## Debugging App Store submission with the `submit_only` lane
+
+The `Fastfile` exposes a second lane, `submit_only`, that skips build/archive/upload and just runs `deliver` against an already-uploaded build. Useful when the binary is fine but the metadata/submission step is failing — iterate in ~30 seconds instead of waiting for a full ~6-minute CI build.
+
+```bash
+ssh alex@alexs-air.lan
+export PATH="$HOME/.gem/ruby/3.3.0/bin:/opt/homebrew/opt/ruby@3.3/bin:$PATH"
+cd ~/Projects/ditto/ios
+
+# Make sure the .p8 is on disk; CI's after_script wipes it after each job
+scp $LAPTOP:/path/to/AuthKey_<KEY_ID>.p8 ~/.private_keys/
+
+export ASC_KEY_PATH=$HOME/.private_keys/AuthKey_<KEY_ID>.p8
+export APP_STORE_CONNECT_API_KEY_ID=<KEY_ID>
+export APP_STORE_CONNECT_API_KEY_ISSUER_ID=<ISSUER_ID>
+export BUILD_NUMBER=<existing-build-number-on-ASC>
+export VERSION=<marketing-version, e.g. 2.14.3>
+
+fastlane submit_only
+```
+
+The lane expects the version to exist in App Store Connect with a `VALID` build attached. It uploads metadata (`./fastlane/metadata/en-US/release_notes.txt`) and calls `submit_for_review`. If Apple rejects, fix the Fastfile, re-run — no rebuild needed.
+
+If Apple has already accepted the submission for that version, you'll need to "Remove from Review" in App Store Connect (only available while state is `WAITING_FOR_REVIEW`, not `IN_REVIEW`) before re-running, or bump the build number.
+
+## Inspecting App Store Connect state directly
+
+When fastlane's error messages aren't enough, query Apple's API directly. There's no installed CLI — use the JWT signing recipe Apple documents. A working Ruby snippet lives in this skill's troubleshooting history; the short version:
+
+```ruby
+require "json"; require "openssl"; require "net/http"; require "base64"
+key_pem = File.read(ENV["ASC_KEY_PATH"])
+ec = OpenSSL::PKey::EC.new(key_pem)
+header = { alg: "ES256", kid: ENV["APP_STORE_CONNECT_API_KEY_ID"], typ: "JWT" }
+payload = { iss: ENV["APP_STORE_CONNECT_API_KEY_ISSUER_ID"], iat: Time.now.to_i, exp: Time.now.to_i + 1200, aud: "appstoreconnect-v1" }
+def b64(s); Base64.urlsafe_encode64(s, padding: false); end
+si = b64(JSON.generate(header)) + "." + b64(JSON.generate(payload))
+sig_der = ec.sign(OpenSSL::Digest::SHA256.new, si)
+asn = OpenSSL::ASN1.decode(sig_der)
+r = asn.value[0].value.to_s(2); s = asn.value[1].value.to_s(2)
+r = ("\x00".b * (32 - r.bytesize)) + r if r.bytesize < 32
+s = ("\x00".b * (32 - s.bytesize)) + s if s.bytesize < 32
+jwt = si + "." + b64(r + s)
+# Now: GET https://api.appstoreconnect.apple.com/v1/apps?filter[bundleId]=pub.ditto.app
+# with header Authorization: Bearer <jwt>
+```
+
+Useful endpoints:
+- `GET /v1/apps?filter[bundleId]=pub.ditto.app` → app id
+- `GET /v1/apps/<id>/appStoreVersions` → version list with `appStoreState`
+- `GET /v1/apps/<id>/builds?sort=-uploadedDate` → recent builds and processing state
+- `GET /v1/appStoreVersions/<id>/appStoreVersionLocalizations` → release notes (`whatsNew`)
+
+## What can go wrong
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Runner shows offline in GitLab | Mac rebooted, auto-login disabled, or LaunchAgent unloaded | SSH in, `gitlab-runner status`, `gitlab-runner restart` |
+| Build fails: "unable to find Xcode" | Xcode auto-updated and changed path, or command-line tools missing | `xcode-select --install`, `sudo xcodebuild -license accept` |
+| Build fails: "no signing certificate found" | match cert expired, was revoked manually, or `MATCH_PASSWORD` mismatched | Run yearly rotation procedure above |
+| Build fails: keychain locked / "User interaction is not allowed" | `setup_ci` failed to create the temporary keychain | Verify `FASTLANE_KEYCHAIN_PASSWORD` is set in GitLab CI variables |
+| Build fails: ASC API key invalid | Key was revoked or rotated | Generate a new key and update `APP_STORE_CONNECT_API_KEY_*` variables |
+| "Build already exists" from `deliver` | Previous tag's IPA had the same `CFBundleVersion`; fastlane's `increment_build_number` didn't bump because the value already matched `CI_PIPELINE_IID` | Push a new tag (each new tag has a new pipeline ID) |
+| Apple precheck rejects metadata | Encryption export compliance, IDFA, content rights flags don't match `Fastfile` | Update `submission_information` in `ios/fastlane/Fastfile` |
+| `OpenSSL::PKey::PKeyError: invalid curve name` | fastlane is running on brewed Ruby 4.0, which has a broken OpenSSL EC parser ([fastlane#20553](https://github.com/fastlane/fastlane/issues/20553)) | Use `ruby@3.3` from brew and install fastlane as a user gem (`gem install fastlane --user-install`); ensure `~/.bash_profile` puts `~/.gem/ruby/3.3.0/bin` on PATH ahead of `/opt/homebrew/bin` |
+| `gem install` / `bundle install` hangs for >30s per request | Ruby's net/http tries IPv6 to rubygems.org and times out on this network | `sudo networksetup -setv6off Wi-Fi` (per-interface, persistent until reboot) |
+| `Unresolved conflict between options: 'api_key_path' and 'api_key'` | `app_store_connect_api_key` action sets `APP_STORE_CONNECT_API_KEY_PATH` env var (path to `.p8`), match's same-named env var expects a JSON descriptor | Build the API key hash inline in the Fastfile (don't call `app_store_connect_api_key`); read `.p8` from a non-conflicting var like `ASC_KEY_PATH` |
+| `[match] Could not find the newly generated certificate installed` when running match interactively on macOS 26+ | [fastlane#15185](https://github.com/fastlane/fastlane/issues/15185) — the new-cert verification step trips on partition list and keychain trust | Run cert generation **in CI** via the bootstrap procedure in the `ci-cd-publishing` skill (uses `setup_ci`'s ephemeral keychain). Don't run `fastlane match appstore` interactively. |
+| iOS build fails: `No "iOS Development" signing certificate matching team ID` | The Xcode project uses `CODE_SIGN_STYLE=Automatic`; xcodebuild tries to find a Development cert even for Release builds | Override via `xcargs: "CODE_SIGN_STYLE=Manual CODE_SIGN_IDENTITY='Apple Distribution' PROVISIONING_PROFILE_SPECIFIER='match AppStore <bundle-id>' DEVELOPMENT_TEAM=<team>"` in the Fastfile (already configured) |
+| `vite.config.ts: Unexpected token 'c', "concurrent"... is not valid JSON` | GitLab Runner sets `CONFIG_FILE=/Users/alex/.gitlab-runner/config.toml` in the job environment, which collides with vite's `process.env.CONFIG_FILE ?? "./ditto.json"` lookup | Already fixed: use `DITTO_CONFIG_FILE` for the override env var |
+| `whatsNew is missing` from `submit_for_review` | `metadata_path: "./metadata"` resolves relative to fastlane's cwd (`ios/`), not its config dir (`ios/fastlane/`); fastlane silently uploads zero locales | Use `metadata_path: "./fastlane/metadata"` (already configured) |
+| `appStoreVersions ... is not in valid state` | Apple won't accept submission because the version is past `PREPARE_FOR_SUBMISSION` (already submitted, in review, or shipped) | "Remove from Review" in App Store Connect if `WAITING_FOR_REVIEW`, or cut a new version |
+| `An attribute value is not acceptable for the current resource state. - contentRightsDeclaration` | Apple rejects PATCH on locked App-level fields when `submission_information` includes `content_rights_*` | Drop `content_rights_*` from `submission_information` in the Fastfile (already configured) |
+
+## When the Mac dies
+
+1. Get a replacement Mac. Install Xcode from the App Store.
+2. Run the **`ci-cd-publishing`** skill's "Initial setup" — but skip the App Store Connect API key step (you already have it). Re-register the runner with the same `macos` tag.
+3. Restore signing identity: `cd ditto/ios && fastlane match appstore --readonly` decrypts the existing certs/profiles using `MATCH_PASSWORD`.
+4. No reissuance, no revocation, no GitLab variable updates needed. The certificates repo is the source of truth.

.agents/skills/merge-upstream/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: merge-upstream
+description: Merge upstream changes from the Ditto repo (which Agora is a fork of) into Agora's main branch. Load when the user asks to "merge upstream", "pull from Ditto", "sync with Ditto", or otherwise update Agora with new commits from soapbox-pub/ditto.
+---
+
+# Merge Upstream from Ditto
+
+Agora is a fork of [Ditto](https://gitlab.com/soapbox-pub/ditto). This skill walks through pulling new commits from upstream Ditto and merging them into Agora's `main` branch, while making philosophy-aware decisions on merge conflicts.
+
+## Philosophy: Agora vs. Ditto
+
+Agora has diverged from Ditto on purpose in several areas. When resolving conflicts, side with Agora's direction unless the upstream change is clearly a generic bug fix or improvement that applies to both. Known divergences:
+
+- **No Blobbi** — Agora has removed Blobbi support. If an upstream change adds or modifies Blobbi-related code, prefer to drop the Blobbi parts rather than reintroduce them.
+- **Lightning-only wallet** — Agora uses a Breeze Lightning wallet. **No onchain functionality exists in Agora**, even though Ditto includes it. Reject upstream onchain wallet code; keep onchain-related conflicts resolved to Agora's Lightning-only path.
+- **General rule** — if upstream reintroduces a feature Agora deliberately removed, the deliberate removal wins. When in doubt, ask the user before resolving a conflict that touches a known divergence.
+
+Spend a moment scanning the conflict for these themes before mechanically resolving line-by-line.
+
+## Procedure
+
+### Step 1: Ensure the `ditto` remote exists
+
+Check the current remotes:
+
+```bash
+git remote -v
+```
+
+If `ditto` is not listed (pointing to `https://gitlab.com/soapbox-pub/ditto.git` or the equivalent `git@gitlab.com:soapbox-pub/ditto.git`), add it:
+
+```bash
+git remote add ditto https://gitlab.com/soapbox-pub/ditto.git
+```
+
+If a `ditto` remote exists but points elsewhere, fix it with `git remote set-url ditto <url>`.
+
+### Step 2: Confirm a clean working tree on `main`
+
+```bash
+git status
+git branch --show-current
+```
+
+The working tree must be clean and the current branch must be `main`. If not, stop and ask the user how to proceed — do not stash or switch branches automatically.
+
+### Step 3: Fetch from Ditto
+
+```bash
+git fetch ditto
+```
+
+### Step 4: Preview what's incoming
+
+Show the user (or at least review yourself) the commits that will be merged before merging:
+
+```bash
+git log --oneline main..ditto/main
+```
+
+If the list is empty, Agora is already up to date — stop here and tell the user.
+
+### Step 5: Merge `ditto/main` into `main`
+
+```bash
+git merge ditto/main
+```
+
+If the merge succeeds without conflicts, proceed to Step 7.
+
+### Step 6: Resolve conflicts (if any)
+
+For each conflicted file:
+
+1. Re-read the Philosophy section above.
+2. Inspect the conflict with `git diff` and decide based on Agora's direction, not just textual merge.
+3. For Blobbi-related conflicts, drop the Blobbi side.
+4. For onchain-wallet conflicts, keep Agora's Lightning-only path.
+5. For ambiguous cases that touch a known divergence, **ask the user** before resolving.
+6. After resolving each file, `git add <file>`.
+
+When all conflicts are resolved, complete the merge:
+
+```bash
+git commit
+```
+
+Git will pre-populate a merge commit message listing the conflicted files. Keep that information and add a short note about how non-trivial conflicts were resolved (especially anything touching the divergences above), so the resolution rationale is preserved in history.
+
+### Step 7: Validate the merge
+
+Run the full test script to confirm the merged tree still type-checks, lints, tests, and builds:
+
+```bash
+npm run test
+```
+
+If anything fails, fix it before declaring the merge done. Failures after an upstream merge are common — a removed Blobbi reference may now be re-imported by new upstream code, or onchain wallet types may leak into Lightning-only code paths. Fix forward in new commits on top of the merge commit; do not amend the merge commit itself.
+
+### Step 8: Report back
+
+Tell the user:
+
+- How many commits were merged (`git rev-list --count main@{1}..main`).
+- Which files had conflicts and how each was resolved.
+- Whether `npm run test` passed.
+- That the merge is **not** pushed — the user decides when to push.
+
+**Do not push to `origin` automatically.** The user will push when they're ready.

.agents/skills/nip19-routing/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: nip19-routing
+description: Implement or populate the root-level NIP-19 router (/:nip19) that handles npub, nprofile, note, nevent, and naddr identifiers. Covers decoding, secure filter construction, and type-specific rendering for profiles, notes, events, and addressable events.
+---
+
+# NIP-19 Identifier Routing
+
+NIP-19 defines the bech32-encoded identifiers used throughout Nostr (`npub1...`, `note1...`, `naddr1...`, etc.). This project routes all of them through a single root-level page at `/:nip19`, implemented by `src/pages/NIP19Page.tsx`.
+
+Use this skill when the user wants to populate the `NIP19Page` sections with real views, add a new identifier type, or build links that point into the Nostr routing system.
+
+## Identifier Reference
+
+| Prefix       | Payload                                                          | Use when…                                                    |
+|--------------|------------------------------------------------------------------|--------------------------------------------------------------|
+| `npub1`      | 32-byte public key                                               | Simple user reference                                        |
+| `nprofile1`  | Public key + optional relay hints + petname                      | User reference with relay context                            |
+| `note1`      | 32-byte event ID (kind:1 text notes only, per NIP-10)            | Referencing a short text note/thread                         |
+| `nevent1`    | Event ID + optional relay hints + author pubkey + kind           | Any event kind, or notes where you need relay/author context |
+| `naddr1`     | `kind` + `pubkey` + `identifier` (`d` tag) + optional relay hints | Addressable events (kind 30000-39999): articles, products    |
+| `nsec1`      | Private key                                                      | **Never display or route** — treat as a 404                  |
+| `nrelay1`    | Relay URL                                                        | Deprecated                                                   |
+
+### `note1` vs `nevent1`
+
+- `note1` carries only an event ID, and is canonically tied to kind:1 text notes.
+- `nevent1` can reference **any** kind and can carry relay hints + author pubkey. Prefer `nevent1` for non-kind-1 events or when you want to ship relay hints with a link.
+
+### `npub1` vs `nprofile1`
+
+- `npub1` is just a pubkey.
+- `nprofile1` adds relay hints and a petname. Prefer it for shareable profile links where discoverability matters.
+
+## Routing Rules
+
+1. **All NIP-19 identifiers are handled at the URL root**: `/:nip19` in `AppRouter.tsx`. Never nest them under paths like `/note/:id` or `/profile/:npub`.
+2. **Invalid, vacant, or unsupported identifiers** (including `nsec1` and `nrelay1`) render the 404 page. The `NIP19Page` boilerplate already handles this.
+3. **Addressable event URLs must include the author**. `naddr1` already encodes `pubkey` + `kind` + `identifier`, which is exactly what a secure query filter needs. If you ever design an alternative URL, use the shape `/:npub/:dtag`, never `/:dtag` alone — otherwise anyone can publish a conflicting event with the same `d` tag.
+
+## Decoding and Filtering
+
+Nostr relay filters only accept hex strings. Always decode the NIP-19 identifier before building a filter.
+
+```ts
+import { nip19 } from 'nostr-tools';
+
+const decoded = nip19.decode(value); // throws on invalid input
+
+switch (decoded.type) {
+  case 'npub': {
+    const pubkey = decoded.data; // hex string
+    return nostr.query([{ kinds: [0], authors: [pubkey], limit: 1 }]);
+  }
+
+  case 'nprofile': {
+    const { pubkey /*, relays */ } = decoded.data;
+    return nostr.query([{ kinds: [0], authors: [pubkey], limit: 1 }]);
+  }
+
+  case 'note': {
+    const id = decoded.data;
+    return nostr.query([{ ids: [id], kinds: [1], limit: 1 }]);
+  }
+
+  case 'nevent': {
+    const { id /*, relays, author, kind */ } = decoded.data;
+    return nostr.query([{ ids: [id], limit: 1 }]);
+  }
+
+  case 'naddr': {
+    const { kind, pubkey, identifier } = decoded.data;
+    return nostr.query([{
+      kinds: [kind],
+      authors: [pubkey],        // critical: prevents d-tag spoofing
+      '#d': [identifier],
+      limit: 1,
+    }]);
+  }
+
+  default:
+    // nsec, nrelay, unknown → 404
+    throw new Error('Unsupported Nostr identifier');
+}
+```
+
+### Common mistakes
+
+```ts
+// ❌ Passing bech32 into a filter
+nostr.query([{ ids: [naddr] }]);
+
+// ❌ Addressable lookup without the author — anyone can spoof the d-tag
+nostr.query([{ kinds: [30023], '#d': [slug] }]);
+
+// ✅ Decode first, then include author
+const { kind, pubkey, identifier } = nip19.decode(naddr).data;
+nostr.query([{ kinds: [kind], authors: [pubkey], '#d': [identifier] }]);
+```
+
+## Populating `NIP19Page`
+
+`src/pages/NIP19Page.tsx` already:
+
+- Decodes `params.nip19` with `nip19.decode`.
+- Branches on `decoded.type` with a section for each supported identifier.
+- Redirects invalid / unsupported identifiers to the 404 page.
+- Provides a responsive container wrapper.
+
+To turn it into a real router, replace each placeholder section with a concrete component:
+
+| `decoded.type`        | Typical view                                                  |
+|-----------------------|---------------------------------------------------------------|
+| `npub` / `nprofile`   | Profile page: header from kind 0, feed of the user's events   |
+| `note`                | Single kind:1 text note with thread + replies                 |
+| `nevent`              | Generic event renderer; branch on `kind` for specialized UIs  |
+| `naddr`               | Addressable-event view (article, product, community, etc.)    |
+
+Inside each branch, pass the decoded payload (not the raw bech32 string) to a child component. That keeps filter construction colocated with the fetching hook and removes any chance of a re-decode mismatch.
+
+## Linking to NIP-19 Routes
+
+When building links elsewhere in the app:
+
+```tsx
+import { nip19 } from 'nostr-tools';
+import { Link } from 'react-router-dom';
+
+// To a profile
+<Link to={`/${nip19.npubEncode(pubkey)}`}>Profile</Link>
+
+// To an addressable event (article, product, …)
+<Link to={`/${nip19.naddrEncode({ kind, pubkey, identifier, relays })}`}>
+  Open
+</Link>
+
+// To a specific event of any kind, with relay hints
+<Link to={`/${nip19.neventEncode({ id, relays, author, kind })}`}>Open</Link>
+```
+
+Always encode with the **most specific** identifier you have context for (`nprofile` > `npub`, `nevent` > `note`, `naddr` for addressable). The extra metadata makes links more robust across relays.
+
+## Security Recap
+
+- Decode **before** querying.
+- For addressable events, always include `authors: [pubkey]` in the filter — the `d` tag alone is not a trust boundary.
+- Treat `nsec1` and any unknown/invalid identifier as 404. Never render, log, or echo a decoded `nsec`.

.agents/skills/nip85-stats/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: nip85-stats
+description: Fetch pre-computed engagement stats (follower count, post count, reply count, reaction count, zap amounts, etc.) for users, events, and addressable events via a NIP-85 Trusted Assertion provider. Provides useNip85UserStats, useNip85EventStats, and useNip85AddrStats hooks backed by a configurable provider pubkey in AppConfig.
+---
+
+# NIP-85 Trusted Assertion Stats
+
+[NIP-85](https://github.com/nostr-protocol/nips/blob/master/85.md) defines "Trusted Assertions" — events published by a service provider that carry pre-computed stats (follower counts, reaction counts, zap totals, etc.) for users and events. Clients that would otherwise need to load thousands of events to compute these numbers can instead query a single addressable event from a trusted provider.
+
+This skill adds three hooks — `useNip85UserStats`, `useNip85EventStats`, `useNip85AddrStats` — and a configurable `nip85StatsPubkey` field on `AppConfig` so you can swap providers.
+
+## Kinds Used
+
+| Kind  | Subject                      | `d` tag value              |
+| ----- | ---------------------------- | -------------------------- |
+| 30382 | User                         | user pubkey (hex)          |
+| 30383 | Event (regular, kind 1 etc.) | event id (hex)             |
+| 30384 | Addressable event            | `<kind>:<pubkey>:<d-tag>`  |
+
+The hooks query one replaceable event at a time (`limit: 1`), filtered by `authors: [statsPubkey]` and `#d`. **Filtering by `authors` is required** — without it, anyone could publish a fake assertion with the same `d` tag and the client would accept it.
+
+## Files Provided by This Skill
+
+| Skill file | Copy to |
+|---|---|
+| `files/hooks/useNip85Stats.ts` | `src/hooks/useNip85Stats.ts` |
+
+## Setup Instructions
+
+### 1. Copy the Hooks File
+
+Copy `.agents/skills/nip85-stats/files/hooks/useNip85Stats.ts` into `src/hooks/useNip85Stats.ts`. It imports `@nostrify/react`, `@tanstack/react-query`, and `@/hooks/useAppContext`, all already present in the template.
+
+### 2. Add `nip85StatsPubkey` to `AppConfig`
+
+In `src/contexts/AppContext.ts`, add the field to the `AppConfig` interface:
+
+```typescript
+export interface AppConfig {
+  // ...existing fields...
+  /** Hex pubkey of the NIP-85 Trusted Assertion provider. Empty = disabled. */
+  nip85StatsPubkey: string;
+}
+```
+
+### 3. Update the Zod Schema in `AppProvider.tsx`
+
+In `src/components/AppProvider.tsx`, add the field to `AppConfigSchema`:
+
+```typescript
+const AppConfigSchema = z.object({
+  // ...existing fields...
+  nip85StatsPubkey: z.string().refine(
+    (val) => val.length === 0 || /^[0-9a-f]{64}$/i.test(val),
+    { message: 'Must be empty or a 64-character hex pubkey' },
+  ),
+}) satisfies z.ZodType<AppConfig>;
+```
+
+### 4. Set the Default in `App.tsx`
+
+Pick a provider pubkey and add it to `defaultConfig`. The ditto.pub provider is a reasonable default:
+
+```typescript
+const defaultConfig: AppConfig = {
+  // ...existing fields...
+  nip85StatsPubkey: '5f68e85ee174102ca8978eef302129f081f03456c884185d5ec1c1224ab633ea',
+};
+```
+
+Set to `''` to ship with stats disabled.
+
+### 5. Update `TestApp.tsx`
+
+In `src/test/TestApp.tsx`, add the field to the test default config. Use an empty string so tests don't hit a live provider:
+
+```typescript
+const defaultConfig: AppConfig = {
+  // ...existing fields...
+  nip85StatsPubkey: '',
+};
+```
+
+## Usage
+
+### User stats (kind 30382)
+
+```tsx
+import { useNip85UserStats } from '@/hooks/useNip85Stats';
+
+function FollowerCount({ pubkey }: { pubkey: string }) {
+  const { data: stats } = useNip85UserStats(pubkey);
+  if (!stats) return null; // no provider configured or no assertion yet
+  return <span>{stats.followers.toLocaleString()} followers</span>;
+}
+```
+
+### Event stats (kind 30383)
+
+```tsx
+import { useNip85EventStats } from '@/hooks/useNip85Stats';
+
+function NoteStats({ eventId }: { eventId: string }) {
+  const { data: stats } = useNip85EventStats(eventId);
+  if (!stats) return null;
+  return (
+    <div className="flex gap-3 text-sm text-muted-foreground">
+      <span>{stats.reactionCount} reactions</span>
+      <span>{stats.repostCount} reposts</span>
+      <span>{stats.commentCount} comments</span>
+      <span>{stats.zapAmount} sats</span>
+    </div>
+  );
+}
+```
+
+### Addressable event stats (kind 30384)
+
+The `addr` argument is the full NIP-01 event address `<kind>:<pubkey>:<d-tag>`:
+
+```tsx
+import { useNip85AddrStats } from '@/hooks/useNip85Stats';
+
+function ArticleStats({ kind, pubkey, identifier }: { kind: number; pubkey: string; identifier: string }) {
+  const { data: stats } = useNip85AddrStats(`${kind}:${pubkey}:${identifier}`);
+  if (!stats) return null;
+  return <span>{stats.reactionCount} reactions</span>;
+}
+```
+
+## Behavior Notes
+
+- **Graceful degradation:** The hooks return `null` (not an error) when `nip85StatsPubkey` is empty or the provider has no assertion for the subject. Always render defensively — NIP-85 is an optimization, not a source of truth.
+- **Short timeouts:** Each query is wrapped in a 2-second `AbortSignal.timeout` so a slow stats relay never blocks the UI.
+- **Cached by TanStack Query:** `staleTime` is 30s for event/addr stats and 60s for user stats. Results are keyed on `[kind, subject, statsPubkey]`, so swapping providers invalidates the cache automatically.
+- **Missing tags = 0:** A tag absent from the assertion is reported as `0` rather than `undefined`, matching NIP-85's "no data" semantics.
+- **Not the source of truth:** For interactive features (did *this* user like *this* post?) you still need to query the underlying reaction/zap/repost events. NIP-85 only provides aggregate counts.
+
+## Extending the Stats
+
+The hooks expose a small subset of the tags defined in NIP-85. To surface more (e.g. `zap_amt_sent`, `rank`, `first_created_at`), extend the return types and pull additional tags via `getIntTag`:
+
+```typescript
+export interface Nip85UserStats {
+  followers: number;
+  postCount: number;
+  rank: number;            // new
+  zapAmtReceived: number;  // new
+}
+
+// inside useNip85UserStats queryFn
+return {
+  followers: getIntTag(tags, 'followers'),
+  postCount: getIntTag(tags, 'post_cnt'),
+  rank: getIntTag(tags, 'rank'),
+  zapAmtReceived: getIntTag(tags, 'zap_amt_recd'),
+};
+```
+
+See the full tag table in [NIP-85](https://github.com/nostr-protocol/nips/blob/master/85.md).
+
+## Exposing a Provider Picker (Optional)
+
+If you want the user to change providers at runtime, add an input bound to `config.nip85StatsPubkey` and call `updateConfig` with a validated 64-char hex value:
+
+```tsx
+import { useAppContext } from '@/hooks/useAppContext';
+
+function StatsProviderInput() {
+  const { config, updateConfig } = useAppContext();
+  return (
+    <input
+      value={config.nip85StatsPubkey}
+      onChange={(e) => {
+        const v = e.target.value.trim().toLowerCase();
+        if (v === '' || /^[0-9a-f]{64}$/.test(v)) {
+          updateConfig(() => ({ nip85StatsPubkey: v }));
+        }
+      }}
+      placeholder="64-char hex pubkey (blank to disable)"
+    />
+  );
+}
+```
+
+## Related NIPs
+
+- [NIP-85](https://github.com/nostr-protocol/nips/blob/master/85.md) — Trusted Assertions (this skill)
+- [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) — Addressable event addressing (`<kind>:<pubkey>:<d-tag>`)
+- [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md) — Zaps (the underlying events `zap_amount` / `zap_cnt` aggregate)

.agents/skills/nip85-stats/files/hooks/useNip85Stats.ts

@@ -0,0 +1,156 @@
+import { useNostr } from '@nostrify/react';
+import { useQuery } from '@tanstack/react-query';
+import { useAppContext } from '@/hooks/useAppContext';
+
+/** Engagement counts exposed by NIP-85 kind 30383 (events) and 30384 (addressable events). */
+export interface Nip85EventStats {
+  commentCount: number;
+  repostCount: number;
+  reactionCount: number;
+  zapCount: number;
+  /** Zap amount in sats. */
+  zapAmount: number;
+}
+
+/** A subset of NIP-85 kind 30382 (user) stats — extend as needed. */
+export interface Nip85UserStats {
+  followers: number;
+  postCount: number;
+}
+
+/**
+ * Read an integer tag value from a NIP-85 assertion event. Returns 0 when missing
+ * or unparseable, which mirrors the semantics of "no data" in NIP-85.
+ */
+function getIntTag(tags: string[][], tagName: string): number {
+  const tag = tags.find(([name]) => name === tagName);
+  if (!tag?.[1]) return 0;
+  const n = parseInt(tag[1], 10);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Fetches NIP-85 event stats (kind 30383) from the configured stats pubkey.
+ * Returns `null` when no stats pubkey is configured or the provider has no
+ * assertion for this event.
+ */
+export function useNip85EventStats(eventId: string | undefined) {
+  const { nostr } = useNostr();
+  const { config } = useAppContext();
+  const statsPubkey = config.nip85StatsPubkey;
+
+  return useQuery<Nip85EventStats | null>({
+    queryKey: ['nip85-event-stats', eventId, statsPubkey],
+    queryFn: async ({ signal }) => {
+      if (!eventId || !statsPubkey) return null;
+
+      const combined = AbortSignal.any([signal, AbortSignal.timeout(2000)]);
+
+      try {
+        const events = await nostr.query(
+          [{ kinds: [30383], authors: [statsPubkey], '#d': [eventId], limit: 1 }],
+          { signal: combined },
+        );
+
+        if (events.length === 0) return null;
+
+        const { tags } = events[0];
+        return {
+          commentCount: getIntTag(tags, 'comment_cnt'),
+          repostCount: getIntTag(tags, 'repost_cnt'),
+          reactionCount: getIntTag(tags, 'reaction_cnt'),
+          zapCount: getIntTag(tags, 'zap_cnt'),
+          zapAmount: getIntTag(tags, 'zap_amount'),
+        };
+      } catch {
+        return null;
+      }
+    },
+    enabled: !!eventId && !!statsPubkey,
+    staleTime: 30 * 1000,
+    retry: false,
+  });
+}
+
+/**
+ * Fetches NIP-85 user stats (kind 30382) from the configured stats pubkey.
+ * Returns `null` when no stats pubkey is configured or the provider has no
+ * assertion for this pubkey.
+ */
+export function useNip85UserStats(pubkey: string | undefined) {
+  const { nostr } = useNostr();
+  const { config } = useAppContext();
+  const statsPubkey = config.nip85StatsPubkey;
+
+  return useQuery<Nip85UserStats | null>({
+    queryKey: ['nip85-user-stats', pubkey, statsPubkey],
+    queryFn: async ({ signal }) => {
+      if (!pubkey || !statsPubkey) return null;
+
+      const combined = AbortSignal.any([signal, AbortSignal.timeout(2000)]);
+
+      try {
+        const events = await nostr.query(
+          [{ kinds: [30382], authors: [statsPubkey], '#d': [pubkey], limit: 1 }],
+          { signal: combined },
+        );
+
+        if (events.length === 0) return null;
+
+        const { tags } = events[0];
+        return {
+          followers: getIntTag(tags, 'followers'),
+          postCount: getIntTag(tags, 'post_cnt'),
+        };
+      } catch {
+        return null;
+      }
+    },
+    enabled: !!pubkey && !!statsPubkey,
+    staleTime: 60 * 1000,
+    retry: false,
+  });
+}
+
+/**
+ * Fetches NIP-85 addressable event stats (kind 30384) from the configured
+ * stats pubkey. The `addr` argument is the full NIP-01 event address string,
+ * e.g. `30023:<pubkey>:<d-tag>`.
+ */
+export function useNip85AddrStats(addr: string | undefined) {
+  const { nostr } = useNostr();
+  const { config } = useAppContext();
+  const statsPubkey = config.nip85StatsPubkey;
+
+  return useQuery<Nip85EventStats | null>({
+    queryKey: ['nip85-addr-stats', addr, statsPubkey],
+    queryFn: async ({ signal }) => {
+      if (!addr || !statsPubkey) return null;
+
+      const combined = AbortSignal.any([signal, AbortSignal.timeout(2000)]);
+
+      try {
+        const events = await nostr.query(
+          [{ kinds: [30384], authors: [statsPubkey], '#d': [addr], limit: 1 }],
+          { signal: combined },
+        );
+
+        if (events.length === 0) return null;
+
+        const { tags } = events[0];
+        return {
+          commentCount: getIntTag(tags, 'comment_cnt'),
+          repostCount: getIntTag(tags, 'repost_cnt'),
+          reactionCount: getIntTag(tags, 'reaction_cnt'),
+          zapCount: getIntTag(tags, 'zap_cnt'),
+          zapAmount: getIntTag(tags, 'zap_amount'),
+        };
+      } catch {
+        return null;
+      }
+    },
+    enabled: !!addr && !!statsPubkey,
+    staleTime: 30 * 1000,
+    retry: false,
+  });
+}

.agents/skills/nostr-direct-messages/SKILL.md

@@ -1,478 +0,0 @@
----
-name: nostr-direct-messages
-description: Implement Nostr direct messaging features, build chat interfaces, or work with encrypted peer-to-peer communication (NIP-04 and NIP-17).
----
-
-# Direct Messaging on Nostr
-
-This project includes a complete direct messaging system supporting both NIP-04 (legacy) and NIP-17 (modern, more private) encrypted messages with real-time subscriptions, optimistic updates, and a persistent cache-first local storage.
-
-**The DM system is not enabled by default** - follow the setup instructions below to add messaging functionality to your application.
-
-## Setup Instructions
-
-### 1. Add DMProvider to Your App
-
-First, add the `DMProvider` to your app's provider tree in `src/App.tsx`:
-
-```tsx
-// Add these imports at the top of src/App.tsx
-import { DMProvider, type DMConfig } from '@/components/DMProvider';
-import { PROTOCOL_MODE } from '@/lib/dmConstants';
-
-// Add this configuration before your App component
-const dmConfig: DMConfig = {
-  // Enable or disable DMs entirely
-  enabled: true, // Set to true to enable messaging functionality
-
-  // Choose one protocol mode:
-  // PROTOCOL_MODE.NIP04_ONLY - Force NIP-04 (legacy) only
-  // PROTOCOL_MODE.NIP17_ONLY - Force NIP-17 (private) only
-  // PROTOCOL_MODE.NIP04_OR_NIP17 - Allow users to choose between NIP-04 and NIP-17 (defaults to NIP-17)
-  protocolMode: PROTOCOL_MODE.NIP17_ONLY, // Recommended for new apps
-};
-
-// Then wrap your app components with DMProvider:
-export function App() {
-  return (
-    <UnheadProvider head={head}>
-      <AppProvider storageKey="nostr:app-config" defaultConfig={defaultConfig}>
-        <QueryClientProvider client={queryClient}>
-          <NostrLoginProvider storageKey='nostr:login'>
-            <NostrProvider>
-              <NostrSync />
-              <DMProvider config={dmConfig}>
-                <TooltipProvider>
-                  <Toaster />
-                  <Suspense>
-                    <AppRouter />
-                  </Suspense>
-                </TooltipProvider>
-              </DMProvider>
-            </NostrProvider>
-          </NostrLoginProvider>
-        </QueryClientProvider>
-      </AppProvider>
-    </UnheadProvider>
-  );
-}
-```
-
-### 2. Configure DM Settings
-
-The `DMConfig` object supports the following options:
-
-- `enabled` (boolean, default: `false`) - Enable/disable entire DM system. When false, no messages are loaded, stored, or processed.
-- `protocolMode` (ProtocolMode, default: `PROTOCOL_MODE.NIP17_ONLY`) - Which protocols to support:
-  - `PROTOCOL_MODE.NIP04_ONLY` - Legacy encryption only
-  - `PROTOCOL_MODE.NIP17_ONLY` - Modern private messages (recommended)
-  - `PROTOCOL_MODE.NIP04_OR_NIP17` - Support both protocols (for backwards compatibility)
-
-**Note**: The DM system uses domain-based IndexedDB naming (`nostr-dm-store-${hostname}`) to prevent conflicts between multiple apps on the same domain.
-
-## Quick Start
-
-### 1. Send Messages
-
-```tsx
-import { useDMContext } from '@/hooks/useDMContext';
-import { MESSAGE_PROTOCOL } from '@/lib/dmConstants';
-
-function ComposeMessage({ recipientPubkey }: { recipientPubkey: string }) {
-  const { sendMessage } = useDMContext();
-  const [content, setContent] = useState('');
-
-  const handleSend = async () => {
-    await sendMessage({
-      recipientPubkey,
-      content,
-      protocol: MESSAGE_PROTOCOL.NIP17, // Uses NIP-44 encryption + gift wrapping
-    });
-    setContent('');
-  };
-
-  return (
-    <form onSubmit={(e) => { e.preventDefault(); handleSend(); }}>
-      <textarea
-        value={content}
-        onChange={(e) => setContent(e.target.value)}
-        placeholder="Type a message..."
-      />
-      <button type="submit">Send</button>
-    </form>
-  );
-}
-```
-
-### 2. Display Conversations
-
-```tsx
-import { useDMContext } from '@/hooks/useDMContext';
-import { useAuthor } from '@/hooks/useAuthor';
-import { genUserName } from '@/lib/genUserName';
-
-function ConversationList({ onSelectConversation }: { onSelectConversation: (pubkey: string) => void }) {
-  const { conversations, isLoading } = useDMContext();
-
-  if (isLoading) {
-    return <div>Loading conversations...</div>;
-  }
-
-  return (
-    <div className="space-y-2">
-      {conversations.map((conversation) => (
-        <ConversationItem
-          key={conversation.pubkey}
-          conversation={conversation}
-          onClick={() => onSelectConversation(conversation.pubkey)}
-        />
-      ))}
-    </div>
-  );
-}
-
-function ConversationItem({ conversation, onClick }: {
-  conversation: ConversationSummary;
-  onClick: () => void;
-}) {
-  const author = useAuthor(conversation.pubkey);
-  const displayName = author.data?.metadata?.name || genUserName(conversation.pubkey);
-  const avatarUrl = author.data?.metadata?.picture;
-
-  return (
-    <button onClick={onClick} className="w-full p-3 hover:bg-accent rounded-lg">
-      <div className="flex items-center gap-3">
-        <Avatar>
-          <AvatarImage src={avatarUrl} />
-          <AvatarFallback>{displayName.slice(0, 2).toUpperCase()}</AvatarFallback>
-        </Avatar>
-        <div className="flex-1 text-left">
-          <div className="font-medium">{displayName}</div>
-          <div className="text-sm text-muted-foreground truncate">
-            {conversation.lastMessage?.decryptedContent || 'No messages yet'}
-          </div>
-        </div>
-      </div>
-    </button>
-  );
-}
-```
-
-### 3. Display Messages in a Conversation
-
-```tsx
-import { useConversationMessages } from '@/hooks/useConversationMessages';
-import { useCurrentUser } from '@/hooks/useCurrentUser';
-
-function MessageThread({ conversationPubkey }: { conversationPubkey: string }) {
-  const { user } = useCurrentUser();
-  const { messages, hasMoreMessages, loadEarlierMessages } = useConversationMessages(conversationPubkey);
-
-  return (
-    <div className="flex flex-col space-y-2">
-      {hasMoreMessages && (
-        <button onClick={loadEarlierMessages} className="text-sm text-muted-foreground">
-          Load earlier messages
-        </button>
-      )}
-
-      {messages.map((message) => {
-        const isFromMe = message.pubkey === user?.pubkey;
-
-        return (
-          <div
-            key={message.id}
-            className={cn(
-              "flex",
-              isFromMe ? "justify-end" : "justify-start"
-            )}
-          >
-            <div className={cn(
-              "max-w-[70%] rounded-lg px-4 py-2",
-              isFromMe ? "bg-primary text-primary-foreground" : "bg-muted"
-            )}>
-              {message.error ? (
-                <span className="text-red-500">🔒 {message.error}</span>
-              ) : (
-                <p className="whitespace-pre-wrap break-words">
-                  {message.decryptedContent}
-                </p>
-              )}
-              {message.isSending && (
-                <span className="text-xs opacity-50">Sending...</span>
-              )}
-            </div>
-          </div>
-        );
-      })}
-    </div>
-  );
-}
-```
-
-## Using the Complete Messaging Interface
-
-For a fully-featured messaging UI out of the box, use the `DMMessagingInterface` component:
-
-```tsx
-import { DMMessagingInterface } from "@/components/dm/DMMessagingInterface";
-
-function MessagesPage() {
-  return (
-    <div className="container mx-auto p-4 h-screen">
-      <DMMessagingInterface />
-    </div>
-  );
-}
-```
-
-The `DMMessagingInterface` component provides a complete messaging UI with:
-- Conversation list with Active/Requests tabs
-- Message thread view with pagination
-- Compose area with file upload support
-- Real-time message updates
-- Mobile-responsive layout (shows one panel at a time on mobile)
-
-It requires no props and works automatically when wrapped in `DMProvider`.
-
-**For custom layouts**, see the "Building Custom Messaging UIs" section below for individual components (`DMConversationList`, `DMChatArea`, `DMStatusInfo`).
-
-## Sending Files with Messages
-
-```tsx
-import { useDMContext } from '@/hooks/useDMContext';
-import { useUploadFile } from '@/hooks/useUploadFile';
-import { MESSAGE_PROTOCOL } from '@/lib/dmConstants';
-import type { FileAttachment } from '@/contexts/DMContext';
-
-function ComposeWithFiles({ recipientPubkey }: { recipientPubkey: string }) {
-  const { sendMessage } = useDMContext();
-  const { mutateAsync: uploadFile, isPending: isUploading } = useUploadFile();
-  const [content, setContent] = useState('');
-  const [selectedFile, setSelectedFile] = useState<File | null>(null);
-
-  const handleSend = async () => {
-    let attachments: FileAttachment[] | undefined;
-
-    // Upload file if one is selected
-    if (selectedFile) {
-      const tags = await uploadFile(selectedFile);
-
-      attachments = [{
-        url: tags[0][1], // URL from first tag
-        mimeType: selectedFile.type,
-        size: selectedFile.size,
-        name: selectedFile.name,
-        tags: tags
-      }];
-    }
-
-    await sendMessage({
-      recipientPubkey,
-      content,
-      protocol: MESSAGE_PROTOCOL.NIP17,
-      attachments,
-    });
-
-    setContent('');
-    setSelectedFile(null);
-  };
-
-  return (
-    <form onSubmit={(e) => { e.preventDefault(); handleSend(); }}>
-      <textarea
-        value={content}
-        onChange={(e) => setContent(e.target.value)}
-        placeholder="Type a message..."
-      />
-
-      <input
-        type="file"
-        onChange={(e) => setSelectedFile(e.target.files?.[0] || null)}
-      />
-
-      {selectedFile && <div>Selected: {selectedFile.name}</div>}
-
-      <button type="submit" disabled={isUploading}>
-        {isUploading ? 'Uploading...' : 'Send'}
-      </button>
-    </form>
-  );
-}
-```
-
-## Protocol Comparison
-
-### NIP-04 (Legacy)
-- **Encryption**: NIP-04 (simpler, older)
-- **Metadata**: Sender and recipient visible to relays
-- **Event Kind**: Kind 4
-- **Use When**: Compatibility with older clients
-
-### NIP-17 (Modern & Private)
-- **Encryption**: NIP-44 (stronger)
-- **Metadata**: Hidden via gift wrapping (NIP-59)
-- **Event Kinds**: Kind 14 (text), Kind 15 (files)
-- **Wrapped In**: Kind 1059 (Gift Wrap) with ephemeral keys
-- **Use When**: Maximum privacy (recommended)
-
-**Key Privacy Features of NIP-17:**
-- Sender identity hidden (uses random ephemeral keys)
-- Timestamps randomized (±2 days) to hide send time
-- Dual gift wraps (recipient + sender) for message history
-
-## Advanced Features
-
-### Conversation Categorization
-
-The system automatically categorizes conversations:
-
-```tsx
-const { conversations } = useDMContext();
-
-// Filter by category
-const knownConversations = conversations.filter(c => c.isKnown);
-const requestConversations = conversations.filter(c => c.isRequest);
-
-// isKnown = true if user has sent at least one message
-// isRequest = true if only received messages, never replied
-```
-
-### Loading States
-
-```tsx
-const { isLoading, loadingPhase, scanProgress } = useDMContext();
-
-// Check overall loading state
-if (isLoading) {
-  console.log('Current phase:', loadingPhase);
-  // LOADING_PHASES.CACHE - Loading from local cache
-  // LOADING_PHASES.RELAYS - Querying relays
-  // LOADING_PHASES.SUBSCRIPTIONS - Setting up real-time updates
-  // LOADING_PHASES.READY - Fully loaded
-}
-
-// Display scan progress for large message histories
-if (scanProgress.nip17) {
-  console.log(`NIP-17: ${scanProgress.nip17.current} messages - ${scanProgress.nip17.status}`);
-}
-```
-
-### Clear Cache and Refresh
-
-```tsx
-import { useDMContext } from '@/hooks/useDMContext';
-
-function SettingsButton() {
-  const { clearCacheAndRefetch } = useDMContext();
-
-  const handleClearCache = async () => {
-    await clearCacheAndRefetch();
-    // Clears IndexedDB cache and reloads all messages from relays
-  };
-
-  return (
-    <button onClick={handleClearCache}>
-      Clear Message Cache
-    </button>
-  );
-}
-```
-
-## Architecture Notes
-
-### Data Flow
-1. **Cache First**: Messages load instantly from encrypted IndexedDB cache
-2. **Background Sync**: New messages fetched from relays in parallel
-3. **Real-time Updates**: WebSocket subscriptions for live messages
-4. **Optimistic UI**: Sent messages appear immediately, confirmed on relay response
-
-### Storage
-- **IndexedDB**: All messages stored locally with NIP-44 encryption
-- **Per-User Storage**: Separate encrypted store for each logged-in user
-- **Automatic Sync**: Debounced writes (15s) + immediate on new messages
-
-### Performance
-- **Parallel Queries**: NIP-04 and NIP-17 messages fetched simultaneously
-- **Batched Loading**: Messages loaded in batches (1000/batch, 20k limit)
-- **Pagination**: Conversation messages paginated (25/page)
-- **Deduplication**: Automatic filtering of duplicate messages by ID
-
-### Security
-- **NIP-44 Encryption**: Modern authenticated encryption for all NIP-17 messages
-- **Local Encryption**: IndexedDB storage encrypted with user's NIP-44 key
-- **Ephemeral Keys**: Random keys for NIP-17 gift wraps (sender anonymity)
-- **No Plaintext**: Decrypted content never persisted unencrypted
-- **Domain Isolation**: IndexedDB databases are namespaced by hostname to prevent data conflicts
-
-## Building Custom Messaging UIs
-
-For advanced use cases, you can use the individual DM components to build custom layouts:
-
-### Available Components
-
-**`DMConversationList`** - Conversation sidebar with tabs
-```tsx
-import { DMConversationList } from '@/components/dm/DMConversationList';
-
-<DMConversationList
-  selectedPubkey={selectedPubkey}
-  onSelectConversation={(pubkey) => setSelectedPubkey(pubkey)}
-  onStatusClick={() => setShowStatus(true)} // optional
-  className="h-full"
-/>
-```
-
-**`DMChatArea`** - Message thread and compose area
-```tsx
-import { DMChatArea } from '@/components/dm/DMChatArea';
-
-<DMChatArea
-  pubkey={selectedPubkey}
-  onBack={() => setSelectedPubkey(null)} // optional, for mobile back button
-  className="h-full"
-/>
-```
-
-**`DMStatusInfo`** - Debug/status panel
-```tsx
-import { DMStatusInfo } from '@/components/dm/DMStatusInfo';
-
-<DMStatusInfo clearCacheAndRefetch={clearCacheAndRefetch} />
-```
-
-### Custom Layout Example
-
-```tsx
-import { useState } from 'react';
-import { DMConversationList } from '@/components/dm/DMConversationList';
-import { DMChatArea } from '@/components/dm/DMChatArea';
-
-function CustomMessagingLayout() {
-  const [selectedPubkey, setSelectedPubkey] = useState<string | null>(null);
-
-  return (
-    <div className="flex h-screen">
-      {/* Custom sidebar */}
-      <aside className="w-64 border-r">
-        <DMConversationList
-          selectedPubkey={selectedPubkey}
-          onSelectConversation={setSelectedPubkey}
-        />
-      </aside>
-
-      {/* Custom main area */}
-      <main className="flex-1">
-        {selectedPubkey ? (
-          <DMChatArea pubkey={selectedPubkey} />
-        ) : (
-          <div className="flex items-center justify-center h-full">
-            <p>Select a conversation to start messaging</p>
-          </div>
-        )}
-      </main>
-    </div>
-  );
-}
-```
-

.agents/skills/nostr-encryption/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: nostr-encryption
+description: Encrypt and decrypt content for Nostr direct messages, gift wraps, or any feature that needs NIP-44 (or legacy NIP-04) ciphertext, using the logged-in user's signer.
+---
+
+# Nostr Encryption and Decryption
+
+The logged-in user exposes a `signer` object that matches the NIP-07 signer interface. The signer handles all cryptographic operations internally — including ECDH, conversation-key derivation, and AEAD — so your code never touches a private key.
+
+**Always use the signer interface for encryption. Never ask the user for their private key, and never derive a shared secret yourself.**
+
+## NIP-44 (preferred)
+
+NIP-44 is the modern, authenticated encryption scheme used for DMs (NIP-17), gift wraps (NIP-59), and most new encrypted payloads.
+
+```ts
+import { useCurrentUser } from "@/hooks/useCurrentUser";
+
+function useEncryptedNote() {
+  const { user } = useCurrentUser();
+
+  if (!user) throw new Error("Must be logged in");
+
+  // Guard: older signers may not support NIP-44 yet.
+  if (!user.signer.nip44) {
+    throw new Error(
+      "Please upgrade your signer extension to a version that supports NIP-44 encryption",
+    );
+  }
+
+  // Encrypt a message to a recipient (use your own pubkey to encrypt to self).
+  const ciphertext = await user.signer.nip44.encrypt(
+    recipientPubkey,
+    "hello world",
+  );
+
+  // Decrypt a message from a sender (use the *other party's* pubkey).
+  const plaintext = await user.signer.nip44.decrypt(senderPubkey, ciphertext);
+
+  return plaintext;
+}
+```
+
+### Key points
+
+- `encrypt(peerPubkey, plaintext)` — `peerPubkey` is the **other party's** hex public key. For self-encryption (notes, backups), pass `user.pubkey`.
+- `decrypt(peerPubkey, ciphertext)` — `peerPubkey` is the author of the ciphertext you're decrypting (for an incoming DM, this is the sender's pubkey).
+- Both methods are async and may throw if the signer rejects the request or the ciphertext is malformed. Wrap calls in `try/catch`.
+- The signer handles conversation-key caching; repeated calls for the same peer are cheap.
+
+## NIP-04 (legacy)
+
+NIP-04 is only needed when interacting with older clients that haven't adopted NIP-44. The API mirrors NIP-44:
+
+```ts
+if (!user.signer.nip04) {
+  throw new Error("Signer does not support NIP-04");
+}
+
+const ciphertext = await user.signer.nip04.encrypt(peerPubkey, plaintext);
+const plaintext = await user.signer.nip04.decrypt(peerPubkey, ciphertext);
+```
+
+Prefer NIP-44 for anything new. Only fall back to NIP-04 when a spec or peer explicitly requires it.
+
+## Patterns
+
+### Encrypt-to-self (drafts, private notes)
+
+```ts
+const ciphertext = await user.signer.nip44.encrypt(user.pubkey, draft);
+createEvent({ kind: 30078, content: ciphertext, tags: [["d", "my-draft"]] });
+```
+
+### Decrypt an incoming DM (NIP-17 / NIP-59)
+
+For gift-wrapped DMs, you'll typically decrypt the outer wrap, then the inner seal, then read the rumor's content. Each decryption uses the *sender* of that specific layer as the peer pubkey.
+
+### Guarding the UI
+
+Always check `user.signer.nip44` (or `nip04`) before calling encryption methods. Remote signers and older browser extensions may not implement every interface, and catching the missing-capability case lets you show a useful message ("Please upgrade your signer") instead of an unhandled promise rejection.

.agents/skills/nostr-kind-design/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: nostr-kind-design
+description: Decide whether to reuse an existing NIP or mint a new kind, design tag structures that relays can index, choose what goes in content vs. tags, and document new kinds or extensions in NIP.md. Load when authoring a new schema — not when wiring up rendering for a kind that already exists (use nostr-kind-rendering for that).
+---
+
+# Nostr Kinds — Design and Schema
+
+Load this skill when:
+
+- Minting a new event kind for a Ditto feature.
+- Extending an existing NIP with new tags.
+- Deciding whether an existing NIP covers a use case or whether a custom kind is warranted.
+- Documenting a custom kind or extension in `NIP.md`.
+
+**Not this skill** — if an existing NIP/kind covers your use case and you only need to render it in Ditto's UI, use the **`nostr-kind-rendering`** skill instead.
+
+## Choosing Between Existing NIPs and Custom Kinds
+
+1. **Thorough NIP review first.** Browse the NIP index, then read candidate NIPs in detail. The goal is to find the closest existing solution.
+2. **Prefer extending existing NIPs** over creating custom kinds, even at the cost of minor schema compromises. Custom kinds fragment the ecosystem.
+3. **When an existing NIP is close but not perfect**, use its kind as the base and add domain-specific tags. Document the extension in `NIP.md`.
+4. **Only mint a new kind** when no existing NIP covers the core functionality, the data structure is fundamentally different, or the use case requires different storage characteristics (regular vs. replaceable vs. addressable).
+5. **If a tool to generate a new kind number is available, you MUST call it.** Never pick an arbitrary number.
+6. **Custom kinds MUST include a NIP-31 `alt` tag** with a human-readable description of the event's purpose.
+
+**Example decision:**
+
+```
+Need: Equipment marketplace for farmers
+Options:
+  1. NIP-15 (Marketplace)   — too structured for peer-to-peer sales
+  2. NIP-99 (Classifieds)   — good fit, extensible with farming tags
+  3. Custom kind            — perfect fit, no interoperability
+
+Decision: NIP-99 + farming-specific tags.
+```
+
+## Kind Ranges
+
+An event's kind number determines storage semantics:
+
+- **Regular** (1000 ≤ kind < 10000) — stored permanently by relays. Notes, articles, etc.
+- **Replaceable** (10000 ≤ kind < 20000) — only the latest event per `pubkey+kind` is kept. Profile metadata, contact lists, mute lists.
+- **Addressable** (30000 ≤ kind < 40000) — identified by `pubkey+kind+d-tag`; only the latest per combo is kept. Long-form content, products, definitions.
+
+Kinds below 1000 are "legacy"; storage is per-kind (e.g. kind 1 is regular, kind 3 is replaceable).
+
+## Tag Design Principles
+
+- **Kind = schema, tags = semantics.** Don't mint a new kind just to represent a different category of the same data.
+- **Relays only index single-letter tags.** Use `t` for categories so filters like `'#t': ['electronics']` work at the relay level. Multi-letter tags (`product_type`, etc.) force inefficient client-side filtering.
+- **Filter at the relay**, not in JavaScript:
+
+  ```ts
+  // ❌ Fetch everything, filter locally
+  const events = await nostr.query([{ kinds: [30402] }]);
+  const filtered = events.filter((e) => hasTag(e, 'product_type', 'electronics'));
+
+  // ✅ Filter at the relay
+  const events = await nostr.query([{ kinds: [30402], '#t': ['electronics'] }]);
+  ```
+
+- **For Ditto-specific niches** (community apps, regional variants), tag events with a `t` value and query on it. Don't do this for generic platforms — it would silo content.
+
+## Content vs. Tags
+
+- **`content`** — large freeform text or existing industry-standard JSON (GeoJSON, FHIR, Tiled maps). Kind 0 is the one exception where structured JSON goes in content.
+- **Tags** — queryable metadata, structured data, anything you might filter on.
+- **Empty content is fine.** `content: ""` is idiomatic for tag-only events.
+- **If you need to filter by a field, it must be a tag** — relays don't index content.
+
+```json
+// ✅ Queryable
+{ "kind": 30402, "content": "",
+  "tags": [["d", "product-123"], ["title", "Camera"], ["price", "250"], ["t", "photography"]] }
+
+// ❌ Structured data buried in content
+{ "kind": 30402, "content": "{\"title\":\"Camera\",\"price\":250}", "tags": [["d", "product-123"]] }
+```
+
+## `NIP.md`
+
+`NIP.md` documents Ditto's custom kinds and any extensions to existing NIPs. Whenever you mint a new kind or change a custom schema, **create or update `NIP.md`** with the tag list, content format, and intended usage. If a kind you add is effectively the same shape as an existing NIP, note the NIP reference rather than duplicating the spec.
+
+Standard NIPs (like NIP-84 Highlights, NIP-23 Articles) do **not** go in `NIP.md` — only Ditto-custom kinds and Ditto-specific extensions.
+
+## After Designing — What's Next?
+
+Once you've settled on a kind number and tag shape, you still need to render it in Ditto's UI. Load the **`nostr-kind-rendering`** skill for the full multi-location registration checklist (feed cards, detail pages, embedded previews, kind-label maps, notifications, feed-toggle registration).

.agents/skills/nostr-kind-rendering/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: nostr-kind-rendering
+description: Add UI rendering for an event kind Ditto doesn't yet display — feed cards, detail pages, embedded previews, notifications, routes, feed-toggle registration, and the several kind-label maps (KIND_LABELS, KIND_HEADER_MAP, NOTIFICATION_KIND_NOUNS, CommentContext) that must stay in sync. Load when asked to "support / display / render" a NIP or kind number, when a kind renders blank or as "Kind 12345", or when quote embeds of a kind show "This event kind is not supported".
+---
+
+# Nostr Kinds — UI Rendering Checklist
+
+Ditto's kind dispatch is **spread across many files** by design — feed cards, detail pages, embedded previews, notifications, and several kind-label maps each have their own rendering requirements. The central `KIND_LABELS` registry covers the easy cases, but most context-specific maps (grammar, icons, verbs) cannot be derived mechanically and must be updated manually.
+
+**Missing any location causes visible bugs**: a kind might render blank in quote posts, show "Kind 12345" as a label, skip its action header, tombstone as "This event kind is not supported" in embeds, or — worst of all — have its content fed through the kind-1 tokenizer and auto-linkify URLs/hashtags that weren't authored by the event creator.
+
+**When in doubt, grep for an existing kind number like `30617` or `9802`** — you'll find every registration point you need to mirror.
+
+## Decision: Feed-toggle + dedicated page, or just rendering?
+
+Before touching code, pick one:
+
+- **Just render it everywhere Nostr content appears** (no feed toggle, no dedicated page). Use when the kind is niche or only reached via direct links / quote embeds. Minimal surface — steps 1–6 below.
+- **Add a feed toggle + optional dedicated page.** Use when users should be able to browse events of this kind or opt them in/out of their home feed. Requires the feed registration (step 7) and `AppConfig` triple (step 8).
+
+When the user asks generally to "support" a kind, ask which direction they want if it's not obvious from context.
+
+## Checklist
+
+### 1. Content card component (`src/components/`)
+
+Create `<MyKindCard event={event} />` that renders the event's tags/content appropriately.
+
+- **Never run event content through the kind-1 tokenizer** (`<NoteContent>` / `<TruncatedNoteContent>`) unless the kind's content is actually free-form user prose. Quote-type content (highlights, snippets, citations) contains URLs and hashtags from the *source*, not the event author — tokenizing them is misleading.
+- Render plaintext with `whitespace-pre-wrap break-words` inside a `<p>` instead.
+- Route any event-sourced URLs (`r` tags, media URLs, source links) through `sanitizeUrl()` from `@/lib/sanitizeUrl` before using them in `href`/`src`.
+- Support an `expanded` prop if the card looks different on the detail page than in the feed.
+
+### 2. Feed card dispatch (`src/components/NoteCard.tsx`)
+
+Three edits in this file:
+
+1. **Flag block** (around lines 384–435): add `const isMyKind = event.kind === XXXX;`.
+2. **`isTextNote` negation list** (around lines 440–475): add `&& !isMyKind`. Without this, unknown kinds fall through to `UnknownKindContent` (showing only the `alt` tag).
+3. **Content dispatch ternary** (around lines 578–692): add `) : isMyKind ? (<MyKindCard event={event} />`.
+4. **`KIND_HEADER_MAP`** (around lines 1710+): add an entry so the feed shows "Alice shared a *noun*" or similar. Pattern:
+   ```ts
+   9802: {
+     icon: Highlighter,
+     action: "shared a",
+     noun: "highlight",
+     nounRoute: "/highlights",  // omit if no dedicated page
+   },
+   ```
+5. Import the card component and any new lucide icons.
+
+### 3. Detail page dispatch (`src/pages/PostDetailPage.tsx`)
+
+Mirror the three NoteCard edits:
+
+1. **Flag block** (around lines 1021–1098): `const isMyKind = event.kind === XXXX;`.
+2. **`isTextNote` negation list**: add `&& !isMyKind`.
+3. **Content dispatch ternary** (around lines 2147–2251): add `) : isMyKind ? (<MyKindCard event={event} expanded />`.
+
+The loading-state title uses `shellTitleForKind()`, which falls through to `KIND_LABELS` — no override needed unless the kind belongs to a group ("Music Details") or needs composite grammar.
+
+### 4. Central kind label (`src/lib/kindLabels.ts`)
+
+Add a **capitalized noun phrase, no articles** to the `KIND_LABELS` map:
+
+```ts
+9802: 'Highlight',
+```
+
+This is consumed by the detail-page loading title, nsite permission prompt, signer nudge toasts, and addressable-event preview headers. Ignoring this gives "Kind 9802" everywhere it appears.
+
+### 5. Context-specific label and icon maps
+
+Each of these maps exists because the surrounding UI needs a different grammatical form. They are **not derived** from `KIND_LABELS` and must be updated manually.
+
+- **`src/components/CommentContext.tsx`** — `KIND_LABELS` (uses articles: `'a highlight'`, `'an article'`) and `KIND_ICONS` (lucide component reference). Rendered as "Commenting on {label}". Without an entry you get "an unsupported event".
+- **`src/pages/NotificationsPage.tsx`** — `NOTIFICATION_KIND_NOUNS` (bare lowercase nouns: `'highlight'`, `'article'`). Rendered as "reacted to your {noun}". Without an entry you get "post" as a fallback.
+- **`src/components/NoteCard.tsx`** — `KIND_HEADER_MAP` (already covered in step 2).
+
+### 6. Embedded previews (`src/components/EmbeddedNote.tsx`)
+
+The quote-embed dispatcher in `EmbeddedNote` (around lines 65–110) routes kinds to dedicated compact cards. **Without a branch here, non-content kinds fall through to `EmbeddedNoteCard`, which either:**
+
+- Shows only the NIP-31 `alt` tag (if present), or
+- Tombstones as "This event kind is not supported", or
+- **Feeds the event's `content` through the kind-1 tokenizer** if the kind is mistakenly treated as a content-kind — auto-linkifying URLs and hashtags that weren't authored by the event creator. This is a security/UX bug.
+
+For any kind whose `content` isn't freeform user prose, add an explicit dispatch branch even if it just renders a minimal compact card. Pattern:
+
+```tsx
+if (event.kind === 9802) {
+  return <EmbeddedHighlightCard event={event} className={className} disableHoverCards={disableHoverCards} />;
+}
+```
+
+Then define the compact card using `EmbeddedCardShell` for the author row + navigation, and render the kind-specific body inside. See `EmbeddedHighlightCard` and `EmbeddedBadgeAwardCard` for reference.
+
+`src/components/EmbeddedNaddr.tsx` works similarly for addressable kinds — add a branch there if your kind is addressable.
+
+### 7. Feed/sidebar registration (`src/lib/extraKinds.ts`)
+
+Only needed if you decided on "feed-toggle + dedicated page" above. Add an `ExtraKindDef`:
+
+```ts
+{
+  kind: 9802,
+  id: 'highlights',
+  showKey: 'showHighlights',
+  feedKey: 'feedIncludeHighlights',
+  label: 'Highlights',
+  description: 'Noteworthy excerpts from articles, posts, and the web (NIP-84)',
+  route: 'highlights',          // omit for feed-only registration
+  addressable: false,
+  section: 'social',            // feed | media | social | development | whimsy
+  blurb: 'Longer marketing copy shown in the info modal.',
+},
+```
+
+Then:
+
+- **Sidebar icon** (`src/lib/sidebarItems.tsx`) — add `{ id: "highlights", label: "Highlights", path: "/highlights", icon: Highlighter }` to `SIDEBAR_ITEMS`, and import the icon at the top. `CONTENT_KIND_ICONS` picks up the icon automatically from the sidebar definition.
+- **Route** (`src/AppRouter.tsx`) — add `const highlightsDef = getExtraKindDef("highlights")!;` at the top of the file and a `<Route path="/highlights" element={<KindFeedPage kind={highlightsDef.kind} title={highlightsDef.label} icon={sidebarItemIcon("highlights", "size-5")} />} />` above the catch-all `*` route.
+
+### 8. `AppConfig` triple (required if you added feed/sidebar toggle keys in step 7)
+
+Three files must stay in sync, or the build fails or the setting silently no-ops:
+
+1. **`src/contexts/AppContext.ts`** — add the fields to the `FeedSettings` interface with JSDoc comments.
+2. **`src/lib/schemas.ts`** — add the same fields to `FeedSettingsSchema` as `z.boolean().optional()`. `DittoConfigSchema` is derived from `AppConfigSchema` with `.strict()` mode, so any `ditto.json` field missing from Zod is a build error.
+3. **`src/App.tsx`** — add the default value in the initial `feedSettings` block.
+4. **`src/test/TestApp.tsx`** — mirror the default in test config so component tests work.
+
+Convention: `show*` toggles default to `true` (sidebar entries visible), `feedInclude*` toggles default to `false` for niche content, `true` for core feed content.
+
+### 9. Notification integration (if applicable)
+
+Load this step when the kind represents an interaction with the user's content (reactions, reposts, highlights, awards, etc.) — i.e. when an event author "does something with" another user's content via an `e`/`a`/`p` tag.
+
+**Six files** to update:
+
+1. **`src/hooks/useEncryptedSettings.ts`** — add `highlights?: boolean` (or equivalent) to the `notificationPreferences` object.
+2. **`src/lib/notificationKinds.ts`** — add the kind to `ALL_NOTIFICATION_KINDS` and add a `if (p.X !== false) kinds.push(XXXX);` line in `getEnabledNotificationKinds`.
+3. **`src/lib/notificationTemplates.ts`** — add a `NOTIFICATION_TEMPLATES` entry with a title and body for nostr-push server-side notifications.
+4. **`src/pages/NotificationSettings.tsx`** — extend `NotificationPrefKey` union, add a row to `NOTIFICATION_TYPES` with icon/label/description/kinds.
+5. **`src/hooks/useNotifications.ts`** — extend `groupKey` (decide if events of this kind group by referenced event or stand alone), and if it's a "did something to your content" kind, add it to the author-ownership filter so users only get notified for interactions with their own content.
+6. **`src/pages/NotificationsPage.tsx`** — add a case to `GroupedNotificationView`'s switch; write `MyKindNotification` + `MyKindNotificationGroup` components modeled on `RepostNotification` / `LikeNotification`.
+
+### 10. Spam guards (`src/lib/feedUtils.ts`)
+
+If the kind has required tags (NIP-spec-mandated references, minimum content, etc.), add a check in `shouldHideFeedEvent` to hide events that don't meet the minimum bar. This pre-filters events before `NoteCard` mounts them, avoiding layout shifts from components that would return `null`.
+
+Example:
+
+```ts
+// NIP-84 highlights with no excerpt AND no source reference.
+if (event.kind === 9802) {
+  const hasContent = event.content.trim().length > 0;
+  const hasSource = event.tags.some(([n]) => n === 'a' || n === 'e' || n === 'r');
+  if (!hasContent && !hasSource) return true;
+}
+```
+
+### 11. `NIP.md` (custom kinds only)
+
+If the kind is a Ditto-custom kind or a Ditto-specific extension of an existing NIP, document it in `NIP.md` — see the **`nostr-kind-design`** skill for the format. Standard NIPs (like NIP-84, NIP-23) do not go in `NIP.md`.
+
+## Validation
+
+After making changes, run `npm run test` — it runs `tsc --noEmit`, `eslint`, `vitest`, and `vite build` in sequence. All must pass. Additions to the `AppConfig` triple in particular frequently break the build if one of the four files is missed.
+
+## Why so many locations?
+
+These are genuinely different UI contexts (feed cards, detail pages, embedded previews, comment-context labels, notifications, sidebar routes) with different rendering requirements and grammar needs. The central `KIND_LABELS` in `src/lib/kindLabels.ts` handles the common "what to call this kind" case, but feed headers, comment-context text, and notification verbs each need their own grammar, and notification integration involves a whole independent subsystem.
+
+## Bugs that signal a missed step
+
+- **"Kind 12345" shown as a label** → step 4 (`KIND_LABELS`).
+- **"an unsupported event" in CommentContext** → step 5 (`CommentContext` maps).
+- **"reacted to your **post**"** when it should say "highlight" → step 5 (`NOTIFICATION_KIND_NOUNS`).
+- **No action header above a feed card** → step 2.4 (`KIND_HEADER_MAP`).
+- **Blank / `alt`-only card in quote embeds** → step 6 (`EmbeddedNote` dispatcher).
+- **URLs/hashtags in quoted text auto-linkified** → step 6 (embedded dispatcher forgot to bypass the kind-1 tokenizer).
+- **Kind doesn't appear in the home feed even with the toggle on** → step 7 (`ExtraKindDef` missing `feedKey`).
+- **Build error mentioning a missing `FeedSettings` field** → step 8 (one of the three files out of sync).
+- **Users not notified when their content is interacted with** → step 9 (notification stack).

.agents/skills/nostr-publishing/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: nostr-publishing
+description: Publish Nostr events with useNostrPublish. Covers the basic publishing pattern, safely mutating replaceable and addressable events (read-modify-write via fetchFreshEvent + prev), published_at preservation, and d-tag collision prevention for new addressable content.
+---
+
+# Publishing Nostr Events
+
+Use this skill when a feature needs to publish events — notes, reactions, list updates, profile edits, addressable content, etc. Covers the `useNostrPublish` hook, the correct read-modify-write pattern for replaceable/addressable lists, and d-tag collision prevention.
+
+## The `useNostrPublish` Hook
+
+`useNostrPublish` publishes an event through the app's connection pool and auto-adds a `client` tag. Always guard calls with `useCurrentUser` — publishing requires a signer.
+
+```tsx
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+import { useNostrPublish } from '@/hooks/useNostrPublish';
+
+export function PostForm() {
+  const { user } = useCurrentUser();
+  const { mutate: createEvent } = useNostrPublish();
+
+  if (!user) return <span>You must be logged in to post.</span>;
+
+  return (
+    <button onClick={() => createEvent({ kind: 1, content: 'hello' })}>
+      Post
+    </button>
+  );
+}
+```
+
+Prefer `mutateAsync` over `mutate` when the caller needs to `await` the published event (e.g. to navigate to the new event's page, or to chain another publish).
+
+## Mutating Replaceable and Addressable Events (CRITICAL)
+
+Replaceable (kind 10000-19999) and addressable (kind 30000-39999) events require a **read-modify-write** cycle: fetch the current event, modify its tags, publish a new version. **Never read from the TanStack Query cache before mutating** — the cache can be stale from another device or a rapid prior operation, and republishing stale data silently drops the user's data.
+
+Use `fetchFreshEvent()` from `src/lib/fetchFreshEvent.ts` inside every mutation, and **always pass the fetched event as `prev`** so `useNostrPublish` can preserve `published_at`:
+
+```typescript
+import { fetchFreshEvent } from '@/lib/fetchFreshEvent';
+
+// Inside a mutation function:
+const prev = await fetchFreshEvent(nostr, {
+  kinds: [10003],
+  authors: [user.pubkey],
+});
+const currentTags = prev?.tags ?? [];
+// ...modify tags...
+await publishEvent({
+  kind: 10003,
+  content: prev?.content ?? '',
+  tags: newTags,
+  prev: prev ?? undefined,
+});
+```
+
+This applies to all list-type hooks (bookmarks, pins, interests, follow sets, badges, etc.). See `useFollowActions` and `useMuteList` for complete examples.
+
+### The `prev` Property on Event Templates
+
+`useNostrPublish` accepts an optional `prev` property on the event template — the **previous version** of the event being replaced. The hook uses it to manage the `published_at` tag (NIP-24) automatically:
+
+- **First publish (no `prev`)** — `published_at` is set equal to `created_at`.
+- **Update (`prev` provided)** — `published_at` is preserved from the old event.
+- **Old event lacks `published_at`** — nothing is fabricated.
+- **Caller already set `published_at` in tags** — left alone.
+
+**Convention**: name the local variable `prev` at the call site (not `freshEvent` or `latestEvent`) so it reads naturally when passed to `publishEvent`:
+
+```typescript
+const prev = await fetchFreshEvent(nostr, { kinds: [3], authors: [user.pubkey] });
+// ...
+await publishEvent({ kind: 3, content: prev?.content ?? '', tags: newTags, prev: prev ?? undefined });
+```
+
+`prev` is stripped from the template before signing — it never appears in the published Nostr event.
+
+## D-Tag Collision Prevention for Addressable Events
+
+Addressable events (kind 30000-39999) are identified by `pubkey + kind + d-tag`. Publishing an event with the same d-tag as an existing one **silently replaces** it. This is by design for intentional updates (edit flows), but dangerous when creating *new* content with user-derived d-tags (slugs from titles, user-entered identifiers, etc.).
+
+### When to check for collisions
+
+- **Must check** when the d-tag is derived from user input (slugified titles, user-entered identifiers, etc.).
+- **No check needed** when the d-tag is a `crypto.randomUUID()`, a canonical format with an embedded pubkey prefix, or intentionally the same as an existing event (edit/update flows).
+
+### Implementation pattern
+
+Before publishing a **new** addressable event with a user-derived d-tag, query for an existing event with that d-tag. If one exists, block the publish and tell the user to change the identifier.
+
+```typescript
+// Before publishing a new addressable event:
+const slug = slugify(title, { lower: true, strict: true });
+
+const existing = await nostr.query([
+  { kinds: [30023], authors: [user.pubkey], '#d': [slug], limit: 1 },
+]);
+
+if (existing.length > 0) {
+  toast({
+    title: 'Slug already in use',
+    description: 'Change the slug or edit the existing item.',
+    variant: 'destructive',
+  });
+  return;
+}
+
+// Safe to publish
+publishEvent({ kind: 30023, content, tags: [['d', slug], ...otherTags] });
+```
+
+**Skip the check in edit mode** — when the user explicitly loaded an existing event to update, overwriting is the intended behavior.
+
+Prefer UUID or canonical formats when the d-tag doesn't need to be human-readable. Only use slugified input when the d-tag will appear in URLs or needs to be meaningful to users, and always add a collision check.

.agents/skills/nostr-queries/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: nostr-queries
+description: Query Nostr events efficiently with useNostr + TanStack Query. Covers the standard useQuery pattern, combining related kinds into a single request to avoid rate limiting, and validating events with required tags or strict schemas.
+---
+
+# Querying Nostr Events
+
+Use this skill when building a hook that fetches Nostr events. Covers the standard `useNostr` + `useQuery` pattern, efficient query design (combining kinds to avoid relay round-trips), and event validation for kinds with required tags.
+
+## The Standard Pattern
+
+Combine `useNostr` with TanStack Query in a custom hook. Pass the abort signal from `c.signal` into `nostr.query` so cancelled queries free relay resources:
+
+```typescript
+import { useNostr } from '@nostrify/react';
+import { useQuery } from '@tanstack/react-query';
+
+function usePosts() {
+  const { nostr } = useNostr();
+
+  return useQuery({
+    queryKey: ['posts'],
+    queryFn: async (c) => {
+      const events = await nostr.query(
+        [{ kinds: [1], limit: 20 }],
+        { signal: c.signal },
+      );
+      return events;
+    },
+  });
+}
+```
+
+Transform events into a domain model inside the `queryFn` if needed — callers should rarely see raw `NostrEvent`s. Multiple calls to `nostr.query()` inside one `queryFn` are fine for compound queries that can't be expressed as a single filter.
+
+## Efficient Query Design
+
+**Always minimize the number of separate round-trips** to relays. Each query consumes relay capacity and may count against rate limits.
+
+**✅ Efficient — single query with multiple kinds:**
+
+```typescript
+// Query repost variants in one request
+const events = await nostr.query([{
+  kinds: [1, 6, 16],
+  '#e': [eventId],
+  limit: 150,
+}]);
+
+// Separate by kind in JavaScript
+const notes = events.filter((e) => e.kind === 1);
+const reposts = events.filter((e) => e.kind === 6);
+const genericReposts = events.filter((e) => e.kind === 16);
+```
+
+**❌ Inefficient — three separate round-trips:**
+
+```typescript
+const [notes, reposts, genericReposts] = await Promise.all([
+  nostr.query([{ kinds: [1], '#e': [eventId] }]),
+  nostr.query([{ kinds: [6], '#e': [eventId] }]),
+  nostr.query([{ kinds: [16], '#e': [eventId] }]),
+]);
+```
+
+### Optimization rules
+
+1. **Combine kinds** into one filter: `kinds: [1, 6, 16]`.
+2. **Use multiple filter objects** in a single `nostr.query()` call when different tag filters are needed simultaneously.
+3. **Raise the `limit`** when combining kinds so you still receive enough of each type.
+4. **Split by kind in JavaScript**, not by making separate requests.
+5. **Respect relay capacity** — heavy parallel queries can trigger rate limits even when each individually would be fine.
+
+## Event Validation
+
+For kinds with required tags or strict schemas (most custom kinds, anything beyond kind 1), filter query results through a validator before returning them. Loose kinds (kind 1 text notes) rarely need validation — all tags are optional and `content` is freeform.
+
+```typescript
+import type { NostrEvent } from '@nostrify/nostrify';
+
+// Example validator for NIP-52 calendar events
+function validateCalendarEvent(event: NostrEvent): boolean {
+  if (![31922, 31923].includes(event.kind)) return false;
+
+  const d = event.tags.find(([n]) => n === 'd')?.[1];
+  const title = event.tags.find(([n]) => n === 'title')?.[1];
+  const start = event.tags.find(([n]) => n === 'start')?.[1];
+  if (!d || !title || !start) return false;
+
+  // Date-based events require YYYY-MM-DD
+  if (event.kind === 31922 && !/^\d{4}-\d{2}-\d{2}$/.test(start)) return false;
+
+  // Time-based events require a unix timestamp
+  if (event.kind === 31923) {
+    const ts = parseInt(start);
+    if (isNaN(ts) || ts <= 0) return false;
+  }
+
+  return true;
+}
+
+function useCalendarEvents() {
+  const { nostr } = useNostr();
+  return useQuery({
+    queryKey: ['calendar-events'],
+    queryFn: async (c) => {
+      const events = await nostr.query(
+        [{ kinds: [31922, 31923], limit: 20 }],
+        { signal: c.signal },
+      );
+      return events.filter(validateCalendarEvent);
+    },
+  });
+}
+```
+
+Validation is a correctness layer, not a security layer. For trust-sensitive queries (admin actions, addressable events, moderator approvals), also constrain `authors` — see the `nostr-security` skill.

.agents/skills/nostr-relay-pools/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: nostr-relay-pools
+description: Query or publish to specific Nostr relays or curated relay groups using nostr.relay() and nostr.group(), instead of the default connection pool. Useful for debugging, testing, specialized relays, or geographically-targeted publishing.
+---
+
+# Targeted Nostr Relay Connections
+
+By default, the `nostr` object returned from `useNostr` uses the app's connection pool: it reads from one of the configured relays and publishes to all of them. For most features this is exactly what you want.
+
+Use this skill when you need **more granular control** — talking to a single relay, a curated group of relays, or debugging a specific relay's behavior.
+
+## Single Relay: `nostr.relay(url)`
+
+```ts
+import { useNostr } from '@nostrify/react';
+
+function useSpecificRelay() {
+  const { nostr } = useNostr();
+
+  // Connect to a specific relay
+  const relay = nostr.relay('wss://relay.damus.io');
+
+  // Query from this relay only
+  const events = await relay.query([{ kinds: [1], limit: 15 }]);
+
+  // Publish to this relay only
+  await relay.event({ kind: 1, content: 'Hello from a specific relay!' });
+}
+```
+
+**Good fits:**
+
+- Testing a relay's behavior in isolation
+- Debugging connectivity or rate-limiting issues
+- Querying content that only lives on a specialized relay (paid relays, private relays, niche communities)
+- Health checks / admin tooling
+
+## Relay Group: `nostr.group(urls)`
+
+```ts
+import { useNostr } from '@nostrify/react';
+
+function useRelayGroup() {
+  const { nostr } = useNostr();
+
+  // Create a group of specific relays
+  const relayGroup = nostr.group([
+    'wss://relay.damus.io',
+    'wss://relay.primal.net',
+    'wss://nos.lol',
+  ]);
+
+  // Query from all relays in the group (deduplicated)
+  const events = await relayGroup.query([{ kinds: [1], limit: 15 }]);
+
+  // Publish to all relays in the group
+  await relayGroup.event({ kind: 1, content: 'Hello from a relay group!' });
+}
+```
+
+**Good fits:**
+
+- Publishing to a curated set of trusted relays for a specific feature
+- Community-scoped queries (e.g. a set of relays known to host a particular topic)
+- Geographic/region-targeted delivery
+- Load-balancing reads across a known-good subset
+
+## API Consistency
+
+Both the `relay` object and the `group` object expose the **same interface** as the top-level `nostr` object:
+
+- `.query(filters, opts?)` — request events matching filters
+- `.req(filters, opts?)` — open a streaming subscription
+- `.event(event)` — publish a signed event
+- All other Nostrify methods
+
+This means you can drop them into any existing hook or helper that expects a `nostr`-shaped object.
+
+## Choosing Between Pool, Group, and Single Relay
+
+| Scenario                                           | Use                 |
+|----------------------------------------------------|---------------------|
+| Default app queries, best reach for publishing     | `nostr` (pool)      |
+| Trusted subset, community-specific publishing      | `nostr.group([…])`  |
+| Single-relay debugging or specialized relay access | `nostr.relay(url)`  |
+
+## Tips
+
+- **Don't hard-code user-facing relay lists.** If a feature should publish to "the user's write relays", read from `AppContext.config.relayMetadata` (NIP-65) instead of hard-coding URLs.
+- **Compose with TanStack Query.** Wrap `relay.query(...)` / `group.query(...)` inside a `useQuery` hook exactly as you would with the default `nostr` object; the caching layer is identical.
+- **Handle unreachable relays.** Specific relays can be offline, rate-limited, or slow. Always wrap calls in `try/catch` and respect the abort signal from the query function (`c.signal`).
+- **Avoid leaking subscriptions.** When using `.req(...)` for streaming, always close the subscription on unmount (`controller.abort()` or the returned disposer).

.agents/skills/nostr-security/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: nostr-security
+description: Threat model and defenses for Ditto as a web Nostr client — why XSS is catastrophic when nsec keys live in localStorage, CSP as defense-in-depth, URL and CSS sanitization for untrusted event data, and author filtering for trust-sensitive queries (admin actions, moderators, addressable events, NIP-72 communities). Load when building trust-boundary features, rendering user-controlled URLs or markup, interpolating event data into CSS, or reviewing the app's security posture.
+---
+
+# Nostr Security
+
+## Threat model
+
+**Nostr private keys (`nsec`) are stored in plaintext in `localStorage`.** Any JavaScript running on the origin can read them with `localStorage.getItem('nostr-login')`. A successful XSS = instant, silent, irreversible key theft — no rotation, no revocation, permanent impersonation across every Nostr client the user ever touches. External signers (NIP-07 extension, NIP-46 bunker) don't change this: an XSS can still ask the active signer to sign arbitrary events, drain funds via zaps, or scrape DMs as they decrypt.
+
+**Treat every piece of untrusted data as a script-injection vector** — event tags, `content`, metadata, URL params, relay responses.
+
+## Defense-in-depth
+
+**Content Security Policy.** `index.html` ships a restrictive CSP: `default-src 'none'`, `script-src 'self'` (no inline scripts, no `eval`), `base-uri 'self'`, `connect-src 'self' https: wss:`. The one intentional gap is `style-src 'unsafe-inline'` — required by Tailwind/shadcn — which means **CSS injection is not blocked by CSP; sanitization is on you**. When modifying CSP, only narrow it. Never add `'unsafe-eval'`, `'unsafe-inline'` on `script-src`, `http:`, or wildcard sources.
+
+**Never use `dangerouslySetInnerHTML`, `innerHTML`, `insertAdjacentHTML`, or `document.write`** with event data, URL params, or any other untrusted string. React's JSX auto-escapes interpolated strings — the moment you bypass that, CSP alone won't save you. If you must render HTML from event data, pipe it through a strict allowlist sanitizer (DOMPurify, already installed) at the parse layer.
+
+**Sanitize URLs and CSS values** — see §1 and §2.
+
+## 1. URL sanitization
+
+Any URL from event tags, `content`, metadata fields (`picture`, `banner`, `website`, `nip05`, etc.), or relay hints is untrusted. Threats beyond `javascript:` XSS: `data:` resource exhaustion / phishing, `http://` IP leaks, relative paths triggering same-origin requests, malformed strings crashing downstream parsers.
+
+**Use the shipped helper at `src/lib/sanitizeUrl.ts`:**
+
+```ts
+import { sanitizeUrl } from '@/lib/sanitizeUrl';
+
+// Single URL — returns the normalised href, or undefined if not valid https
+const url = sanitizeUrl(getTag(event.tags, 'url'));
+if (url) {
+  // safe to use in any context
+}
+
+// Array of URLs — filter out invalid entries
+const links = getAllTags(event.tags, 'r')
+  .map(([, v]) => sanitizeUrl(v))
+  .filter((v): v is string => !!v);
+```
+
+`sanitizeUrl` returns the normalised `href` string only when the URL parses successfully **and** uses the `https:` protocol. All other inputs (malformed URLs, `javascript:`, `data:`, `http:`, relative paths, etc.) return `undefined`.
+
+**Sanitize at the parse layer.** When writing a parser function that extracts URLs from event tags (e.g. `parseThemeDefinition`, `parseBadgeDefinition`), apply `sanitizeUrl()` before returning the parsed data. This way every downstream consumer is automatically protected without needing to remember to sanitize at each usage site.
+
+**When sanitization is NOT required:** URLs matched by a regex that constrains the protocol (e.g. `NoteContent`'s tokenizer matching `https?://...` — the regex *is* the sanitizer), hardcoded/app-generated URLs (relay configs, internal routes), and strings rendered as plain text that never land in an attribute, CSS value, or network request.
+
+## 2. CSS injection
+
+Event data interpolated into CSS (a `<style>` element, `style=""`, or an injected stylesheet) is a CSS injection vector. A `"`, `)`, `}`, or `;` in the value can break out of the string context and inject rules — overlay phishing, hide UI, exfiltrate via `background-image: url()` requests.
+
+Common surfaces: `background-image: url("${url}")`, `font-family: "${family}"`, `@font-face { src: url("${url}") }`.
+
+**Mitigation:**
+
+- **URLs in `url()`** — use `sanitizeUrl()`. The `URL` constructor percent-encodes `"`, `)`, `\` and rejects non-`https:`. This is already done for theme event background and font URLs in `src/lib/themeEvent.ts`.
+- **Non-URL strings** (font-family, animation names) — use `sanitizeCssString()` from `src/lib/fontLoader.ts`, which allowlists Unicode letters/numbers, spaces, hyphens, underscores, apostrophes, and periods:
+
+```ts
+import { sanitizeUrl } from '@/lib/sanitizeUrl';
+import { sanitizeCssString } from '@/lib/fontLoader';
+
+// ❌ UNSAFE
+style.textContent = `body { background-image: url("${rawUrl}"); font-family: "${rawFamily}"; }`;
+
+// ✅ SAFE — validate URLs, allowlist identifiers
+const bgUrl = sanitizeUrl(rawUrl);
+const family = sanitizeCssString(rawFamily ?? '');
+if (bgUrl && family) {
+  style.textContent = `body { background-image: url("${bgUrl}"); font-family: "${family}"; }`;
+}
+```
+
+If you can't justify the exact characters you're allowing, the policy is wrong.
+
+## 3. Author filtering for trust-sensitive queries
+
+Even with perfect XSS defenses, an attacker can publish forged events your UI will trust unless queries constrain `authors`. Relays are dumb pipes — any matching event comes back.
+
+**Filter by `authors` when:**
+
+- Querying admin/moderator/owner events — use a hardcoded trusted-pubkey list (e.g. `ADMIN_PUBKEYS` from `src/lib/admins`).
+- Querying addressable events (kinds 30000–39999) — the `d` tag alone is not a trust boundary; the `(kind, pubkey, d)` triple is.
+- Querying user-owned replaceable events (profile metadata, relay lists, mute lists) — `authors: [userPubkey]`.
+
+**Do NOT filter by `authors`** for public UGC (kind 1 notes, reactions, zaps, discovery feeds) — anyone can post there by design.
+
+```ts
+// ❌ Anyone can publish kind 30078 with this d-tag and self-appoint
+nostr.query([{ kinds: [30078], '#d': ['pathos-organizers'], limit: 1 }]);
+
+// ✅ Only trust the admin list
+nostr.query([{ kinds: [30078], authors: ADMIN_PUBKEYS, '#d': ['pathos-organizers'], limit: 1 }]);
+```
+
+**Routes for addressable/replaceable events must include the author** — otherwise the route handler can't construct a secure filter:
+
+```tsx
+// ❌ Any pubkey can squat the slug
+<Route path="/article/:slug" element={<Article />} />
+// ✅ Filter can include authors
+<Route path="/article/:npub/:slug" element={<Article />} />
+```
+
+### NIP-72 community moderation
+
+Kind 4550 approvals are only trustworthy if signed by a moderator from the community definition (kind 34550). Two-step query:
+
+```ts
+// 1. Fetch community definition — author-filter by the owner.
+const [community] = await nostr.query([{
+  kinds: [34550], authors: [communityOwnerPubkey], '#d': [communityId], limit: 1,
+}]);
+if (!community) return [];
+
+// 2. Extract moderator pubkeys from `p` tags with role "moderator".
+const moderators = community.tags
+  .filter(([n, , , role]) => n === 'p' && role === 'moderator')
+  .map(([, pubkey]) => pubkey);
+
+// 3. Query approvals — only from moderators.
+const approvals = await nostr.query([{
+  kinds: [4550],
+  authors: moderators,
+  '#a': [`34550:${communityOwnerPubkey}:${communityId}`],
+  limit: 100,
+}]);
+```
+
+Without step 3's `authors` filter, anyone can publish a kind 4550 "approval".
+
+## Pre-merge checklist
+
+- [ ] No `dangerouslySetInnerHTML` / `innerHTML` / `document.write` with untrusted data.
+- [ ] CSP unchanged or narrowed; no new `'unsafe-eval'`, `'unsafe-inline'` on `script-src`, `http:`, or wildcards.
+- [ ] Every event-sourced URL passes `sanitizeUrl()` before reaching `href`, `src`, `srcSet`, `poster`, iframe `src`, or CSS.
+- [ ] Every event-sourced string in CSS passes `sanitizeUrl()` (URLs) or `sanitizeCssString()` (identifiers).
+- [ ] Every trust-sensitive query includes `authors`.
+- [ ] Routes for addressable/replaceable events carry the author in the URL.

.agents/skills/release/SKILL.md

@@ -87,6 +87,8 @@ Prepend a new section to `CHANGELOG.md` directly below the `# Changelog` heading
 ```markdown
 ## [X.Y.Z] - YYYY-MM-DD
 
+A short single-paragraph summary of this release written in plain prose -- max 500 characters. This appears on the App Store, Google Play, and the in-app "what's new" toast.
+
 ### Added
 - Description of new features
 
@@ -100,7 +102,100 @@ Prepend a new section to `CHANGELOG.md` directly below the `# Changelog` heading
 - Description of removed features
 ```
 
-**Rules:**
+#### The Summary Paragraph
+
+Every release section MUST start with a single plaintext paragraph (not a bullet, not a heading) that summarises the release for app-store-style audiences:
+
+- **Single paragraph, plain prose.** No bullets, no headings, no Markdown formatting beyond plain text.
+- **Max ~500 characters.** Apple App Store and Google Play both cap "What's new" text at 500. The CI `release-notes` job warns when the summary is longer.
+- **Audience: end users discovering the update.** Describe the most noticeable user-visible changes; omit internal cleanups even if they're in the bullets below.
+- **Tone matches the bullets.** Present-tense, no Nostr jargon, no NIP/kind numbers (see Rules below).
+- **Maintenance releases** -- write a one-sentence summary like `A behind-the-scenes maintenance release with no user-facing changes.` Don't leave it blank; the CI fallback `Ditto vX.Y.Z` is a last resort for legacy entries, not new ones.
+
+The same paragraph is used in three places automatically:
+- **App Store** -- "What's New in This Version" via fastlane `deliver`
+- **Google Play** -- "What's new in this version" via fastlane `supply` `metadata/android/<lang>/changelogs/<versionCode>.txt`
+- **In-app toast** -- the `What's new in vX.Y.Z` toast that fires when users load a new version (see `src/components/VersionCheck.tsx`)
+- The full section (summary + lists) goes into the GitLab Release description.
+
+Extraction is handled by `scripts/extract-release-notes.mjs`; you don't have to write store-specific copy.
+
+#### Changelog Quality Checklist
+
+Before drafting any entries, run through this checklist. It is NOT optional -- skipping steps here is the most common way a release goes out with misleading notes.
+
+##### 5.1. Diff the code, not just the commit log
+
+Commit messages describe intent at the moment of commit; they over- and under-represent the cumulative effect at release time. Before drafting entries, **run a real diff** for each area of substantial change:
+
+```bash
+# Full diff between tags
+git diff v<prev>..HEAD
+
+# Or narrowed to an area you're unsure about
+git diff v<prev>..HEAD -- src/components/ComposeBox.tsx
+```
+
+Only the diff reveals intra-release churn (commits that cancel each other out, bugs introduced and then fixed, refactors that land and get reverted). Reading commit messages alone is insufficient.
+
+##### 5.2. Trace every candidate "Fixed" entry to its origin commit
+
+For each bug fix you're considering listing, find the commit that introduced the bug.
+
+**Fast path -- check for `Regression-of:` trailers** (see AGENTS.md "Attributing Regressions"). If the fix commit declares its origin in a trailer, you don't need to hunt:
+
+```bash
+# List all commits in the release window with their Regression-of trailers (if any)
+git log v<prev>..HEAD --no-merges \
+  --format='%h %s%n  Regression-of: %(trailers:key=Regression-of,valueonly,separator=%x20)'
+```
+
+For each `Regression-of: <sha>` entry, check whether `<sha>` is also in the release window:
+
+```bash
+# Returns 0 if <sha> is BEFORE v<prev> (pre-existing bug -> legit "Fixed" entry)
+# Returns non-zero if <sha> is AFTER v<prev> (intra-release -> omit from "Fixed")
+git merge-base --is-ancestor <sha> v<prev>
+```
+
+**Fallback -- manual tracing** (when no trailer is present):
+
+```bash
+# Show the history of a file across all commits
+git log --oneline v<prev>..HEAD -- path/to/file.tsx
+
+# Or blame the specific lines the fix touched
+git blame -L <start>,<end> -- path/to/file.tsx
+```
+
+**If the introducing commit is also in this release window (i.e. after the previous tag), the bug is intra-release.** The user on the previous version never experienced it. Do NOT list it as a "Fixed" entry. Fold it into the relevant "Added" or "Changed" entry, or omit it entirely.
+
+##### 5.3. The "Would a user on the previous version notice this?" test
+
+The changelog describes the delta between the previous release and this one **from the user's perspective** -- not the development history. Before writing each entry, ask:
+
+> "Did a user on the previous published version experience this exact thing?"
+
+- If they experienced a broken state that is now fixed: **"Fixed" entry**
+- If they experienced the old behavior and now see new behavior: **"Changed" or "Added" entry**
+- If they never saw either state (introduced AND resolved within this release window): **omit entirely**
+
+This applies to more than just bugs:
+- A feature added and then reverted in the same release: omit both
+- A refactor that was done and then undone: omit both
+- A performance regression introduced and then fixed: omit both
+- A typo introduced in a new string and then corrected: mention the new string (if user-facing) as a single "Added"/"Changed" entry, with no "Fixed" entry
+
+##### 5.4. Worked example -- intra-release bug
+
+> **Scenario:** Commit A overhauls the compose box and, as a side effect, breaks the background of the expanded emoji picker. Commit B, later in the same release window, restores the background.
+>
+> **Correct changelog:** One "Added" entry describing the compose box overhaul. The emoji picker background is part of the finished state the user receives.
+>
+> **Incorrect changelog:** An "Added" entry for the overhaul AND a "Fixed" entry for the emoji picker background. The user on the previous version never saw the broken background; listing it invents a problem they didn't have and makes the release notes read like a developer changelog.
+
+#### Rules
+
 - Only include categories that have entries (omit empty categories)
 - Write **user-facing descriptions**, not raw commit messages
 - Keep descriptions concise -- one line per change
@@ -109,9 +204,9 @@ Prepend a new section to `CHANGELOG.md` directly below the `# Changelog` heading
 - Focus on what the user sees/experiences, not internal implementation details
 - Use the current date in YYYY-MM-DD format
 - **Never use Nostr protocol jargon.** NIP numbers (e.g., "NIP-89", "NIP-17"), kind numbers (e.g., "kind 30078"), and other protocol-level references must not appear in the changelog. Describe the feature in plain language from the user's perspective. For example, write "App cards for Nostr apps" instead of "App cards for Nostr apps (NIP-89)". The changelog audience is end users, not protocol developers.
-- **Collapse related work into one entry.** If a feature was added and then fixed/tweaked across multiple commits in the same release, present the finished result as a single "Added" entry. Never list something as "Added" and then also list fixes for that same thing -- the user sees the end product, not the development history.
+- **Only ship what the user sees.** If a bug was introduced AND fixed within this release, the user never saw it -- omit the fix entirely (or fold the net result into the relevant Added/Changed entry). The same applies to features that were added and reverted, refactors that cancel out, and any other intra-release churn. See the Changelog Quality Checklist above (especially 5.2 and 5.3) for the procedure to verify this.
+- **Collapse related work into one entry.** If a feature was added and then tweaked across multiple commits in the same release, present the finished result as a single "Added" entry. Never list something as "Added" and then also list fixes for that same thing -- the user sees the end product, not the development history.
 - **Omit purely internal changes.** CI fixes, build pipeline tweaks, developer tooling, and infrastructure changes should be omitted from the changelog entirely unless they have a direct, visible impact on the user experience. The changelog is for users, not developers.
-- **Compare the actual code between versions** to understand what really changed, rather than just reading commit messages. Commit messages may over- or under-represent the significance of changes.
 
 ### Step 6: Update Version in All Files
 
@@ -190,8 +285,12 @@ git push origin main vX.Y.Z
 
 This triggers the GitLab CI pipeline which will:
 1. Build a signed Android APK and AAB
-2. Create a GitLab Release with download links
-3. Publish the APK to Zapstore
+2. Build a signed iOS IPA on the self-hosted Mac runner
+3. Extract release notes (full body + summary paragraph) from `CHANGELOG.md`
+4. Create a GitLab Release with APK / AAB / IPA download links
+5. Publish the APK to Zapstore
+6. Publish the AAB to Google Play (production track) with the summary as the "What's new" text
+7. Submit the iOS IPA to App Store Connect for review with the summary as the "What's New" text
 
 ### Step 12: Confirm
 
@@ -212,11 +311,15 @@ After pushing, inform the user:
 
 ## CI Pipeline
 
-The CI pipeline (`.gitlab-ci.yml`) is triggered by tags matching the pattern `/^v\d+\.\d+\.\d+$/` (e.g., `v2.1.0`). It runs three jobs:
+The CI pipeline (`.gitlab-ci.yml`) is triggered by tags matching the pattern `/^v\d+\.\d+\.\d+$/` (e.g., `v2.1.0`). It runs seven jobs:
 
 1. **build-apk**: Builds signed Android APK and AAB, stamps `versionName` and `versionCode` into the build
-2. **release**: Creates a GitLab Release with the changelog content and download links
-3. **publish-zapstore**: Publishes the APK to Zapstore
+2. **build-ipa**: Builds the signed App Store IPA on the self-hosted Mac runner (`tags: [macos]`); stamps `MARKETING_VERSION` and `CFBundleVersion` into the Xcode project. The IPA is uploaded to GitLab's Generic Packages registry and exposed as a CI artifact for downstream jobs
+3. **release-notes**: Extracts the version's changelog section and summary paragraph from `CHANGELOG.md` into two artifacts (`release-notes.md` and `release-notes-summary.txt`) consumed by `release`, `publish-app-store`, and `publish-google-play`
+4. **release**: Creates a GitLab Release with the full changelog section and APK / AAB / IPA download links
+5. **publish-zapstore**: Publishes the APK to Zapstore
+6. **publish-google-play**: Uploads the AAB to Google Play production track and writes the release summary to `metadata/android/en-US/changelogs/<versionCode>.txt`
+7. **publish-app-store**: Submits the prebuilt IPA to App Store Connect for review with the release summary as the "What's New" text. Runs on the self-hosted Mac runner (`tags: [macos]`) because `fastlane deliver` shells out to Apple's iTMSTransporter to upload the IPA, and that tool only ships inside Xcode — the previous Linux runner crashed at the upload step with `No such file or directory @ dir_chdir0` because `Helper.itms_path` resolved to a missing Xcode path. The build appears in App Store Connect within ~30 minutes; Apple's human review then takes 24-48 hours typically. Once approved, you must release manually in App Store Connect (`automatic_release: false`) — this is the final human gate. For runner operations, match cert rotation, and debugging, load the **`mac-runner`** skill.
 
 ## Troubleshooting
 

.agents/skills/testing/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: testing
+description: Write Vitest unit tests for React components and hooks using the project's `TestApp` wrapper, jsdom environment, and pre-mocked browser APIs (localStorage, matchMedia, scrollTo, IntersectionObserver, ResizeObserver). Also covers the project policy on when to create new test files.
+---
+
+# Testing
+
+Load this skill when the user asks you to write a test, diagnose a bug with a test, or add coverage for a component/hook. Running the existing test script is a standing requirement (see `AGENTS.md` → *Validating Your Changes*) and doesn't require this skill.
+
+## Policy: when to create new test files
+
+**Do not create new test files unless one of these applies:**
+
+1. The user explicitly asks for tests.
+2. The user describes a specific bug and asks for tests to diagnose it.
+3. The user says a problem persists after you tried to fix it.
+
+Never write tests because tool results show failures, because you think tests would be helpful, or because you added a new feature. The request must come from the user.
+
+If none of the above apply, stop — don't create a test file. Keep running the existing test script as usual.
+
+## Test setup
+
+The project uses **Vitest + jsdom** with **React Testing Library** and **jest-dom** matchers. Global setup lives in `src/test/setup.ts` and mocks these browser APIs that jsdom doesn't provide (or that Node's built-ins conflict with):
+
+- `localStorage` — a Map-backed mock, because Node 22's built-in `localStorage` lacks the Web Storage API surface jsdom expects
+- `window.matchMedia`
+- `window.scrollTo`
+- `IntersectionObserver`
+- `ResizeObserver`
+
+If your component needs another browser API, extend `src/test/setup.ts` rather than mocking per-file.
+
+## Writing a component test
+
+Wrap rendered components in `TestApp` (`src/test/TestApp.tsx`) so all context providers — `UnheadProvider`, `AppProvider`, `QueryClientProvider`, `NostrLoginProvider`, `NostrProvider`, `BrowserRouter`, etc. — are available. Without it, hooks like `useQuery`, `useNostr`, `useAppContext`, or `useNavigate` will throw.
+
+```tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { TestApp } from '@/test/TestApp';
+import { MyComponent } from './MyComponent';
+
+describe('MyComponent', () => {
+  it('renders correctly', () => {
+    render(<TestApp><MyComponent /></TestApp>);
+    expect(screen.getByText('Expected text')).toBeInTheDocument();
+  });
+});
+```
+
+## Writing a hook test
+
+Use `renderHook` from `@testing-library/react` and pass `TestApp` as the `wrapper`:
+
+```tsx
+import { describe, it, expect } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { TestApp } from '@/test/TestApp';
+import { useMyHook } from './useMyHook';
+
+describe('useMyHook', () => {
+  it('returns expected data', async () => {
+    const { result } = renderHook(() => useMyHook(), { wrapper: TestApp });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toBeDefined();
+  });
+});
+```
+
+Files placed next to the code under test with the `.test.ts` / `.test.tsx` suffix are picked up automatically. For reference, see `src/test/ErrorBoundary.test.tsx`.
+
+## Running tests
+
+The `npm test` script runs `tsc --noEmit`, `eslint`, `vitest run`, and `vite build` in sequence. Always run it after changes — a passing test file alone doesn't mean your task is done.
+
+For fast iteration, run just Vitest:
+
+```bash
+npx vitest run
+```
+
+Or in watch mode while editing:
+
+```bash
+npx vitest
+```

.agents/skills/theming/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: theming
+description: Customize Ditto's visual design — install Google Fonts via @fontsource, change the color scheme, configure light/dark themes, and apply consistent component styling patterns with Tailwind and CSS variables.
+---
+
+# Theming, Fonts, and Color Schemes
+
+Use this skill when the user wants to change fonts, colors, light/dark appearance, or general visual styling. Ditto ships with a light/dark theme system built on CSS custom properties and Tailwind v3, plus a `useTheme` hook for runtime switching.
+
+## Adding Fonts
+
+Any Google Font can be installed via the `@fontsource` / `@fontsource-variable` packages.
+
+1. **Install the font package.** Prefer the variable version when available.
+   ```bash
+   npm install @fontsource-variable/inter
+   ```
+   Package naming:
+   - `@fontsource-variable/<font-name>` — variable fonts (preferred; one file, all weights)
+   - `@fontsource/<font-name>` — static fonts
+
+2. **Import the font once** in `src/main.tsx`:
+   ```ts
+   import '@fontsource-variable/inter';
+   ```
+
+3. **Register the family** in `tailwind.config.ts`:
+   ```ts
+   export default {
+     theme: {
+       extend: {
+         fontFamily: {
+           sans: ['Inter Variable', 'Inter', 'system-ui', 'sans-serif'],
+         },
+       },
+     },
+   };
+   ```
+
+### Suggested families by use case
+
+- **Modern / Clean:** Inter Variable, Outfit Variable, Manrope
+- **Professional / Corporate:** Roboto, Open Sans, Source Sans Pro
+- **Creative / Artistic:** Poppins, Nunito, Comfortaa
+- **Monospace / Code:** JetBrains Mono, Fira Code, Source Code Pro
+
+For expressive hierarchies, pair a sans body font with a display/serif heading font (e.g. Inter + Playfair Display) and expose the second family as `fontFamily.serif` or `fontFamily.display` in Tailwind.
+
+### Runtime font loading from Nostr events
+
+Ditto also supports loading fonts referenced from Nostr events (theme events, letter stationery, etc.) through `src/lib/fontLoader.ts`. That path is separate from the build-time `@fontsource` approach — it constructs `@font-face` rules at runtime from sanitized URLs. Never feed event data through the `@fontsource` path; always go through `fontLoader` so the URL and family name are passed through `sanitizeUrl()` and `sanitizeCssString()` (see the `nostr-security` skill).
+
+## Color Schemes
+
+Colors are defined as CSS custom properties in `src/index.css` under two selectors:
+
+- `:root` — light-mode values
+- `.dark` — dark-mode overrides
+
+When the user requests a new color scheme:
+
+1. **Update both `:root` and `.dark`** in `src/index.css`. Each variable is an HSL triplet (no `hsl()` wrapper), e.g. `--primary: 222 47% 11%;`.
+2. **Keep contrast ratios ≥ 4.5:1** for body text and interactive elements. Test both modes.
+3. **Prefer extending Tailwind's palette** (`tailwind.config.ts`) over hard-coding hex values in components — this keeps the theme consistent and dark-mode-friendly.
+4. **Apply colors through semantic tokens** (`bg-primary`, `text-muted-foreground`, `border-input`) rather than raw palette names when possible, so future theme changes propagate.
+
+The shadcn/ui components consume these semantic tokens, so changing the variables automatically restyles the entire component library.
+
+## Light/Dark Theme Switching
+
+Ditto includes:
+
+- **`useTheme` hook** (`src/hooks/useTheme.ts`) — read and set the current theme programmatically.
+- **CSS custom properties** in `src/index.css` — one set in `:root`, dark overrides in `.dark`.
+- **Automatic persistence** via the `AppContext` config (`config.theme`), saved to local storage.
+
+To add a theme toggle:
+
+```tsx
+import { useTheme } from '@/hooks/useTheme';
+import { Button } from '@/components/ui/button';
+import { Moon, Sun } from 'lucide-react';
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
+    >
+      {theme === 'dark' ? <Sun className="size-4" /> : <Moon className="size-4" />}
+    </Button>
+  );
+}
+```
+
+## Component Styling Patterns
+
+- **Class merging:** use the `cn()` utility (`@/lib/utils`) to combine conditional classes and override defaults without class-order bugs.
+- **Variants:** follow shadcn/ui's `class-variance-authority` pattern for component variants (`variant`, `size`). Copy an existing `ui/` component as a template.
+- **Responsive design:** lean on Tailwind breakpoints (`sm:`, `md:`, `lg:`) rather than JS media queries. Use `useIsMobile` only when layout must change based on JS-measured viewport.
+- **Interactive states:** always define `hover:`, `focus-visible:`, and `disabled:` states for clickable elements. Focus rings should use `ring-ring` / `ring-offset-background` so they pick up theme colors.
+- **Spacing:** an 8px grid (Tailwind's default 4-based scale) keeps visual rhythm consistent. Common paddings: `p-4`, `p-6`; gaps: `gap-2`, `gap-4`.
+- **Depth:** soft shadows (`shadow-sm`, `shadow-md`), subtle gradients, and `rounded-lg` / `rounded-xl` corners match Ditto's aesthetic. Avoid heavy drop shadows.
+
+### Negative z-index gotcha
+
+When placing decorative elements behind content with `-z-10` (e.g. blurred background gradients), **add `isolate` to the parent container**. Without `isolate`, the negative z-index escapes the local stacking context and the element disappears behind the page's background color.
+
+```tsx
+<section className="relative isolate">
+  <div className="absolute inset-0 -z-10 bg-gradient-to-br from-primary/20 to-transparent" />
+  {/* content */}
+</section>
+```
+
+## Design Quality Checklist
+
+Before finishing a visual change, verify:
+
+- [ ] Both light and dark modes look correct — no hard-coded colors, all text readable.
+- [ ] Contrast ratios meet WCAG AA (≥ 4.5:1 for body, ≥ 3:1 for large text).
+- [ ] Interactive elements have visible `hover`, `focus-visible`, and `disabled` states.
+- [ ] Layout is responsive down to ~360px width without horizontal scroll.
+- [ ] Animations respect `prefers-reduced-motion` (Tailwind: `motion-safe:` / `motion-reduce:`).
+- [ ] Spacing is consistent — no one-off `p-[13px]` style values.

.env.example

@@ -3,5 +3,12 @@ VITE_PLAUSIBLE_DOMAIN="example.tld"
 VITE_PLAUSIBLE_ENDPOINT="https://plausible.example.tld/api/event"
 # Hex pubkey of the nostr-push server (found in nostr-push startup logs as "worker_pubkey")
 VITE_NOSTR_PUSH_PUBKEY=""
+# Canonical origin used when generating shareable URLs (QR codes, copy-link, remote-login callbacks).
+# Primarily useful for native (Capacitor) builds, where window.location.origin is capacitor://localhost.
+# Example: VITE_SHARE_ORIGIN="https://agora.spot"
+VITE_SHARE_ORIGIN=""
+# DeepL-backed translation worker for user-generated content.
+# Example: VITE_TRANSLATE_WORKER_URL="https://agora-translate.<your-subdomain>.workers.dev"
+VITE_TRANSLATE_WORKER_URL="https://agora-translate.lemonknowsall.workers.dev/"
 # Set to "*" to allow any host in the Vite dev server (eg. when proxying through a custom domain)
-# ALLOWED_HOSTS="*"
+# ALLOWED_HOSTS="*"

.gitignore

@@ -11,6 +11,8 @@ node_modules
 dist
 dist-ssr
 *.local
+.eslintcache
+.tsbuildinfo
 yarn.lock
 deploy.sh
 

.gitlab-ci.yml

@@ -26,13 +26,55 @@ test:
   script:
     - npm run test
 
-deploy-nsite:
+# Deploy the built web app to agora.spot on venus.vps via rsync over SSH.
+# Uses the per-site jailed deploy key documented in GITLAB_DEPLOY.md.
+# DEPLOY_SSH_KEY and DEPLOY_TARGET are protected CI/CD variables; they're
+# only exposed to jobs on the protected default branch.
+deploy-web:
   stage: deploy
   timeout: 10 minutes
   rules:
     - if: $CI_COMMIT_TAG
       when: never
-    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH && $DEPLOY_SSH_KEY && $DEPLOY_TARGET
+  # Vite inlines VITE_* env vars at build time. These are sourced directly from
+  # project-level CI/CD variables, which are already present in the job
+  # environment — do NOT re-declare them here as `KEY: $KEY`. That self-reference
+  # overwrites the real value with the literal string "$KEY" whenever the source
+  # variable is out of scope (e.g. a Protected variable on an unprotected ref),
+  # which is how "$VITE_TRANSLATE_WORKER_URL" leaked into the built app.
+  script:
+    # Build the web app
+    - npm ci
+    - npm run build
+    - cp dist/index.html dist/404.html
+
+    # Install rsync + ssh client and load the deploy key
+    - apt-get update -qq && apt-get install -y --no-install-recommends rsync openssh-client >/dev/null
+    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
+    - echo "$DEPLOY_SSH_KEY" | tr -d '\r' > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519
+    - ssh-keyscan -H "${DEPLOY_TARGET##*@}" >> ~/.ssh/known_hosts 2>/dev/null
+
+    # Two-phase rsync: upload hashed assets first, then index.html and sw.js,
+    # so the site never serves an index.html that points at assets that
+    # haven't finished uploading. sw.js is in the second pass for the same
+    # reason — it's a stable filename that all browsers re-fetch to check
+    # for updates, so we want it to land last. The destination ":/" is the
+    # rrsync jail root on venus, which maps to /var/www/agora.spot/.
+    - rsync -av --exclude=/sw.js --exclude=/index.html -e "ssh -i ~/.ssh/id_ed25519" dist/ "${DEPLOY_TARGET}:/"
+    - rsync -av -e "ssh -i ~/.ssh/id_ed25519" dist/index.html dist/sw.js "${DEPLOY_TARGET}:/"
+
+# Disabled: nsite deploy not needed right now; re-enable by restoring the
+# rules below to run on default branch (and ensure NSITE_NBUNKSEC is set).
+deploy-nsite:
+  stage: deploy
+  timeout: 10 minutes
+  rules:
+    - when: never
+  # rules:
+  #   - if: $CI_COMMIT_TAG
+  #     when: never
+  #   - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
   variables:
     NSYTE_VERSION: "v0.24.1"
   script:
@@ -50,28 +92,45 @@ deploy-nsite:
       nsyte deploy ./dist
       -i
       --sec "$NSITE_NBUNKSEC"
-      --name ditto
+      --name agora
       --relays "wss://relay.ditto.pub,wss://relay.nsite.lol,wss://relay.dreamith.to,wss://relay.primal.net"
       --servers "https://blossom.primal.net,https://blossom.ditto.pub,https://blossom.dreamith.to"
       --fallback "/index.html"
       --use-fallback-relays
       --use-fallback-servers
 
-build-web:
+release-notes:
   stage: build
-  timeout: 10 minutes
+  timeout: 2 minutes
   needs: []
   rules:
-    - if: $CI_COMMIT_TAG
-      when: never
-    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
   script:
-    - npm ci
-    - npm run build
-    - cp dist/index.html dist/404.html
+    # Extract release notes from CHANGELOG.md for this tag.
+    # release-notes.md is the full section (summary + bulleted lists), used as
+    # the GitLab Release description. release-notes-summary.txt is the leading
+    # plaintext paragraph only, used as the App Store / Play Store release
+    # blurb. Falls back to "Agora vX.Y.Z" when the section has no summary.
+    - mkdir -p artifacts
+    - node scripts/extract-release-notes.mjs "$CI_COMMIT_TAG" > artifacts/release-notes.md
+    - node scripts/extract-release-notes.mjs "$CI_COMMIT_TAG" --summary > artifacts/release-notes-summary.txt
+    - echo "--- release-notes.md ---"
+    - cat artifacts/release-notes.md
+    - echo "--- release-notes-summary.txt (length $(wc -c < artifacts/release-notes-summary.txt)) ---"
+    - cat artifacts/release-notes-summary.txt
+    - echo "------------------------"
+    # Warn (don't fail) when the summary exceeds the documented 500-character
+    # limit so the user spots it before App Store / Play Store reject the upload.
+    - |
+      SUMMARY_LEN=$(wc -c < artifacts/release-notes-summary.txt)
+      if [ "$SUMMARY_LEN" -gt 501 ]; then
+        echo "WARNING: release-notes-summary.txt is $SUMMARY_LEN bytes; convention is <=500."
+      fi
   artifacts:
     paths:
-      - dist/
+      - artifacts/release-notes.md
+      - artifacts/release-notes-summary.txt
+    expire_in: 90 days
 
 build-apk:
   stage: build
@@ -108,23 +167,33 @@ build-apk:
     # Write local.properties for Gradle
     - echo "sdk.dir=$ANDROID_SDK_ROOT" > android/local.properties
 
-    # Decode signing keystore and migrate JKS -> PKCS12 for Gradle compatibility
+    # Decode signing keystore and migrate JKS -> PKCS12 for Gradle compatibility.
+    # PKCS12 conceptually uses one password for the store and every entry; if the
+    # store and key passwords differ, keytool protects the migrated entry with the
+    # STORE password regardless of -destkeypass, so Gradle's later read with the
+    # key password fails ("Given final block not properly padded"). Unlock the
+    # source key with its own password ($KEY_PASSWORD), then write the PKCS12 with
+    # a single uniform password ($KEY_PASSWORD) for both store and entry so the
+    # key.properties below is internally consistent.
     - echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > android/app/my-upload-key.jks
     - keytool -importkeystore
         -srckeystore android/app/my-upload-key.jks
         -destkeystore android/app/my-upload-key.keystore
         -deststoretype pkcs12
         -srcstorepass "$KEYSTORE_PASSWORD"
-        -deststorepass "$KEYSTORE_PASSWORD"
         -srcalias upload
         -destalias upload
+        -srckeypass "$KEY_PASSWORD"
+        -deststorepass "$KEY_PASSWORD"
+        -destkeypass "$KEY_PASSWORD"
         -noprompt
     - rm android/app/my-upload-key.jks
 
-    # Write key.properties from CI/CD variables
+    # Write key.properties from CI/CD variables. The PKCS12 above uses
+    # $KEY_PASSWORD uniformly, so both storePassword and keyPassword point to it.
     - |
       cat > android/key.properties << EOF
-      storePassword=$KEYSTORE_PASSWORD
+      storePassword=$KEY_PASSWORD
       keyPassword=$KEY_PASSWORD
       keyAlias=upload
       storeFile=my-upload-key.keystore
@@ -154,24 +223,24 @@ build-apk:
 
     # Copy APK to a predictable artifact path
     - mkdir -p artifacts
-    - cp android/app/build/outputs/apk/release/app-release.apk "artifacts/Ditto.apk"
-    - cp android/app/build/outputs/bundle/release/app-release.aab "artifacts/Ditto.aab"
+    - cp android/app/build/outputs/apk/release/app-release.apk "artifacts/Agora.apk"
+    - cp android/app/build/outputs/bundle/release/app-release.aab "artifacts/Agora.aab"
     - ls -lh artifacts/
 
     # Upload to Generic Packages registry for a stable public download URL
     - |
       curl --fail --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
-        --upload-file "artifacts/Ditto.apk" \
-        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/ditto/${CI_COMMIT_TAG}/Ditto-${CI_COMMIT_TAG}.apk"
+        --upload-file "artifacts/Agora.apk" \
+        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/agora/${CI_COMMIT_TAG}/Agora-${CI_COMMIT_TAG}.apk"
     - |
       curl --fail --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
-        --upload-file "artifacts/Ditto.aab" \
-        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/ditto/${CI_COMMIT_TAG}/Ditto-${CI_COMMIT_TAG}.aab"
+        --upload-file "artifacts/Agora.aab" \
+        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/agora/${CI_COMMIT_TAG}/Agora-${CI_COMMIT_TAG}.aab"
 
   artifacts:
     paths:
-      - artifacts/Ditto.apk
-      - artifacts/Ditto.aab
+      - artifacts/Agora.apk
+      - artifacts/Agora.aab
     expire_in: 90 days
   cache:
     key: android-gradle
@@ -179,35 +248,109 @@ build-apk:
       - android/.gradle/
       - .gradle/
 
+build-ipa:
+  stage: build
+  tags:
+    - macos
+  timeout: 20 minutes
+  needs: []
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  variables:
+    LANG: en_US.UTF-8
+    LC_ALL: en_US.UTF-8
+    FASTLANE_HIDE_CHANGELOG: "1"
+    FASTLANE_SKIP_UPDATE_CHECK: "1"
+  before_script:
+    # PATH is set up via ~/.bash_profile on the runner host (brew + Ruby 3.3 + user gems)
+    - node --version
+    - ruby --version
+    - fastlane --version | head -3
+
+    # Decode the App Store Connect API key (.p8) into a private location.
+    # The Fastfile reads this directly via File.binread. We pass the API
+    # key into match so it contacts Apple's portal to verify the cert is
+    # still valid for the team — fails fast on a revoked / expired cert.
+    - mkdir -p "$HOME/.private_keys"
+    - chmod 700 "$HOME/.private_keys"
+    - export ASC_KEY_PATH="$HOME/.private_keys/AuthKey_${APP_STORE_CONNECT_API_KEY_ID}.p8"
+    - echo "$APP_STORE_CONNECT_API_KEY_P8_BASE64" | base64 -d > "$ASC_KEY_PATH"
+    - chmod 600 "$ASC_KEY_PATH"
+    # Avoid env-var collision: match's APP_STORE_CONNECT_API_KEY_PATH expects
+    # a JSON descriptor; we pass the API key inline via the Fastfile.
+    - unset APP_STORE_CONNECT_API_KEY_PATH || true
+
+    # Build web assets and sync to Capacitor iOS project
+    - npm ci
+    - npx vite build -l error
+    - cp dist/index.html dist/404.html
+    - npx cap sync ios
+    - node scripts/patch-cap-config.mjs
+  script:
+    # Stamp marketing version from the git tag (e.g. v2.1.0 -> 2.1.0)
+    - VERSION="${CI_COMMIT_TAG#v}"
+    - echo "Building iOS version $VERSION (build ${CI_PIPELINE_IID}) from tag $CI_COMMIT_TAG"
+    - >-
+      /usr/bin/sed -i ''
+      "s/MARKETING_VERSION = [0-9.]*;/MARKETING_VERSION = ${VERSION};/g"
+      ios/App/App.xcodeproj/project.pbxproj
+
+    # Run match (cert verify + decrypt) and build_app to produce the IPA.
+    # build_app writes ./artifacts/Agora.ipa relative to the project root.
+    - cd ios
+    - fastlane build_ipa
+    - cd ..
+
+    # Move the IPA to a stable name in the artifact directory.
+    - ls -lh artifacts/
+    - test -f artifacts/Agora.ipa
+
+    # Upload to the Generic Packages registry for a stable public download URL,
+    # mirroring how build-apk publishes the APK and AAB.
+    - |
+      curl --fail --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
+        --upload-file "artifacts/Agora.ipa" \
+        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/agora/${CI_COMMIT_TAG}/Agora-${CI_COMMIT_TAG}.ipa"
+  after_script:
+    # Wipe the API key so nothing sensitive sticks around between jobs.
+    - rm -f "$HOME/.private_keys"/AuthKey_*.p8 || true
+  artifacts:
+    paths:
+      - artifacts/Agora.ipa
+    expire_in: 90 days
+
 release:
   stage: release
   image: registry.gitlab.com/gitlab-org/release-cli:latest
   needs:
-    - build-apk
+    - job: build-apk
+      artifacts: false
+    - job: build-ipa
+      artifacts: false
+    - job: release-notes
+      artifacts: true
   rules:
     - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
   script:
     - echo "Creating release for $CI_COMMIT_TAG"
-    # Extract the latest changelog section for the release description.
-    # Reads from "## [version]" to the next "## [" or end of file.
-    - |
-      VERSION="${CI_COMMIT_TAG#v}"
-      RELEASE_NOTES=$(awk "/^## \\[${VERSION}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md)
-      if [ -z "$RELEASE_NOTES" ]; then
-        RELEASE_NOTES="Ditto ${CI_COMMIT_TAG}"
-      fi
-    - echo "$RELEASE_NOTES" > release-notes.md
+    - test -f artifacts/release-notes.md
+    - echo "--- release-notes.md ---"
+    - cat artifacts/release-notes.md
+    - echo "------------------------"
   release:
     tag_name: $CI_COMMIT_TAG
     name: $CI_COMMIT_TAG
-    description: './release-notes.md'
+    description: './artifacts/release-notes.md'
     assets:
       links:
-        - name: Ditto-${CI_COMMIT_TAG}.apk
-          url: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/ditto/${CI_COMMIT_TAG}/Ditto-${CI_COMMIT_TAG}.apk
+        - name: Agora-${CI_COMMIT_TAG}.apk
+          url: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/agora/${CI_COMMIT_TAG}/Agora-${CI_COMMIT_TAG}.apk
           link_type: package
-        - name: Ditto-${CI_COMMIT_TAG}.aab
-          url: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/ditto/${CI_COMMIT_TAG}/Ditto-${CI_COMMIT_TAG}.aab
+        - name: Agora-${CI_COMMIT_TAG}.aab
+          url: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/agora/${CI_COMMIT_TAG}/Agora-${CI_COMMIT_TAG}.aab
+          link_type: package
+        - name: Agora-${CI_COMMIT_TAG}.ipa
+          url: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/agora/${CI_COMMIT_TAG}/Agora-${CI_COMMIT_TAG}.ipa
           link_type: package
 
 publish-zapstore:
@@ -230,7 +373,7 @@ publish-zapstore:
     - mkdir -p ~/.config/zsp/bunker-keys
     - echo "$ZAPSTORE_CLIENT_KEY" > ~/.config/zsp/bunker-keys/${BUNKER_PUBKEY}.key
 
-    - APK_PATH="artifacts/Ditto.apk"
+    - APK_PATH="artifacts/Agora.apk"
     - VERSION="${CI_COMMIT_TAG#v}"
     - sed -i "2i release_source:\ ./${APK_PATH}" zapstore.yaml
     - sed -i "2i version:\ ${VERSION}" zapstore.yaml
@@ -240,7 +383,10 @@ publish-google-play:
   stage: publish
   image: ruby:3.3
   needs:
-    - build-apk
+    - job: build-apk
+      artifacts: true
+    - job: release-notes
+      artifacts: true
   rules:
     - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
   script:
@@ -249,18 +395,87 @@ publish-google-play:
     # Decode base64-encoded service account JSON to a temp file
     - echo "$GOOGLE_PLAY_SERVICE_ACCOUNT_JSON" | base64 -d > /tmp/play-service-account.json
 
-    # Upload the AAB to Google Play production track
+    # Build the fastlane supply metadata layout for the changelog.
+    # supply maps changelogs/<versionCode>.txt to the Play Console "What's
+    # new in this version" field. versionCode matches what build-apk stamped
+    # into build.gradle (= CI_PIPELINE_IID).
+    - VERSION_CODE="${CI_PIPELINE_IID}"
+    - CHANGELOG_DIR="android/fastlane/metadata/android/en-US/changelogs"
+    - mkdir -p "$CHANGELOG_DIR"
+    - cp artifacts/release-notes-summary.txt "${CHANGELOG_DIR}/${VERSION_CODE}.txt"
+    - echo "--- ${CHANGELOG_DIR}/${VERSION_CODE}.txt ---"
+    - cat "${CHANGELOG_DIR}/${VERSION_CODE}.txt"
+    - echo "-------------------------------------------"
+
+    # Upload the AAB to Google Play production track with the changelog.
     - >-
       fastlane supply
-      --aab artifacts/Ditto.aab
-      --package_name pub.ditto.app
+      --aab artifacts/Agora.aab
+      --package_name spot.agora.app
       --track production
       --json_key /tmp/play-service-account.json
+      --metadata_path android/fastlane/metadata/android
       --skip_upload_metadata
-      --skip_upload_changelogs
       --skip_upload_images
       --skip_upload_screenshots
       --skip_upload_apk
 
     # Clean up
     - rm -f /tmp/play-service-account.json
+
+publish-app-store:
+  stage: publish
+  # Runs on the self-hosted Mac runner, same as build-ipa. fastlane's `deliver`
+  # action shells out to Apple's iTMSTransporter / altool to upload the IPA
+  # binary, and those tools ship inside Xcode. On a generic Linux container
+  # the upload step crashes with `No such file or directory @ dir_chdir0`
+  # because `Helper.itms_path` resolves to a path inside Xcode that doesn't
+  # exist. The IPA is already signed in `build-ipa`; we just need an Apple
+  # tool to push it, which means macOS.
+  tags:
+    - macos
+  needs:
+    - job: build-ipa
+      artifacts: true
+    - job: release-notes
+      artifacts: true
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  variables:
+    LANG: en_US.UTF-8
+    LC_ALL: en_US.UTF-8
+    FASTLANE_HIDE_CHANGELOG: "1"
+    FASTLANE_SKIP_UPDATE_CHECK: "1"
+  before_script:
+    # PATH is set up via ~/.bash_profile on the runner host (brew + Ruby 3.3 + user gems)
+    - ruby --version
+    - fastlane --version | head -3
+
+    # Decode the App Store Connect API key (.p8) into a private location.
+    # The Fastfile reads this directly via File.binread.
+    - mkdir -p "$HOME/.private_keys"
+    - chmod 700 "$HOME/.private_keys"
+    - export ASC_KEY_PATH="$HOME/.private_keys/AuthKey_${APP_STORE_CONNECT_API_KEY_ID}.p8"
+    - echo "$APP_STORE_CONNECT_API_KEY_P8_BASE64" | base64 -d > "$ASC_KEY_PATH"
+    - chmod 600 "$ASC_KEY_PATH"
+    # Avoid env-var collision: match's APP_STORE_CONNECT_API_KEY_PATH expects
+    # a JSON descriptor; we pass the API key inline via the Fastfile.
+    - unset APP_STORE_CONNECT_API_KEY_PATH || true
+  script:
+    - test -f artifacts/Agora.ipa
+    - test -f artifacts/release-notes-summary.txt
+
+    # Use the release summary paragraph as the App Store "What's New" text.
+    # Generated by the release-notes job from CHANGELOG.md.
+    - mkdir -p ios/fastlane/metadata/en-US
+    - cp artifacts/release-notes-summary.txt ios/fastlane/metadata/en-US/release_notes.txt
+    - echo "--- release_notes.txt ---"
+    - cat ios/fastlane/metadata/en-US/release_notes.txt
+    - echo "-------------------------"
+
+    # Submit the prebuilt IPA from build-ipa to App Store Connect for review.
+    - export IPA_PATH="$CI_PROJECT_DIR/artifacts/Agora.ipa"
+    - cd ios
+    - fastlane submit_release
+  after_script:
+    - rm -f "$HOME/.private_keys"/AuthKey_*.p8 || true

.gitlab/merge_request_templates/Default.md

@@ -1,4 +1,4 @@
-Thanks for contributing to Ditto! Please read [CONTRIBUTING.md](CONTRIBUTING.md) in full before submitting -- it covers everything you need to get your MR accepted.
+Thanks for contributing to Agora! Please read [CONTRIBUTING.md](CONTRIBUTING.md) in full before submitting -- it covers everything you need to get your MR accepted.
 
 ## Related Issue
 
@@ -29,9 +29,9 @@ Closes #
 ## Philosophy Alignment
 
 <!-- Answer this question for your change: -->
-<!-- "Does this make Ditto more magnetic, more threatening to the status quo, -->
+<!-- "Does this make Agora more magnetic, more threatening to the status quo, -->
 <!-- and more peaceful to inhabit?" -->
-<!-- See: https://about.ditto.pub/philosophy -->
+<!-- See: CONTRIBUTING.md -> "Understanding Agora" -->
 <!-- For bug fixes: "Bug fix -- restores intended behavior" is acceptable. -->
 
 ## How to Test
@@ -50,7 +50,7 @@ Closes #
 ### Process
 
 - [ ] I read `AGENTS.md` before starting
-- [ ] I read the [Ditto Philosophy](https://about.ditto.pub/philosophy)
+- [ ] I read "Understanding Agora" in `CONTRIBUTING.md`
 - [ ] I used plan/research mode before writing code
 - [ ] I used Claude Opus 4.6 (or equivalent frontier model)
 

.npmrc

@@ -0,0 +1 @@
+legacy-peer-deps=true

.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-  "editor.tabSize": 2
+  "editor.tabSize": 2,
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

CHANGELOG.md

@@ -1,398 +1,127 @@
 # Changelog
 
-## [2.6.6] - 2026-04-12
+## [2.9.1] - 2026-06-27
 
-### Fixed
-- Emoji and mention autocomplete dropdowns no longer get clipped by the compose box
-- Emoji shortcodes now render as color emoji instead of plain text glyphs
-- Dialogs and input fields on Android are no longer obscured by the virtual keyboard
-- Signing requests on Android are more reliable and no longer silently fail after switching apps
-
-## [2.6.5] - 2026-04-11
+The Venezuela earthquake relief appeal now rallies behind every campaign on the ground, not just one. The home banner and relief page showcase a live, swipeable carousel of all Venezuelan relief efforts, with a running total of everything raised so far — so you can pick exactly who to help.
 
 ### Changed
-- Apps and games load significantly faster on Android with smarter prefetching and server affinity
-- Native loading spinners replace HTML-based ones on iOS and Android for a smoother experience
 
-### Fixed
-- External API requests on Android no longer fail due to hostname restrictions
-- iOS App Store compliance issues resolved
+- The Venezuela relief appeal now showcases every Venezuelan relief campaign in a live, auto-scrolling carousel you can swipe through, with a combined raised total across all of them, instead of featuring a single campaign.
 
-## [2.6.4] - 2026-04-11
+## [2.9.0] - 2026-06-25
+
+A big one. Private messaging arrives with a fast, searchable inbox you can reply to in your own language. Campaign organizers can now get verified by trusted reviewers through a guided sign-up, and verified badges appear right on campaigns. There's a new Venezuela earthquake relief appeal that takes you straight to donations, plus optional Tor routing on Android, separate Public and Private wallets, faster donation scanning, and refreshed profiles, settings, and login.
 
 ### Added
-- iCloud Keychain integration on iOS -- your login credentials are now saved and restored automatically across devices
+
+- Private direct messages: a dedicated inbox you can search by name, start new chats with inline recipient lookup, page back through old conversations, and read incoming messages translated into your language.
+- Get verified: a guided sign-up for trusted reviewers to set up a verifier profile, publish a public "how we verify" statement, and vouch for campaigns. Verified badges now show on campaign pages, and a short tutorial walks you through it.
+- A Venezuela earthquake relief appeal — a home-page banner, a one-time popup, and a shareable page that bakes in the relief campaign so you can read its story and donate without leaving.
+- Optional Tor routing on Android for added privacy.
+- Separate Public and Private wallets, keeping your spending and your private silent-payment funds cleanly apart.
+- A "Don't have Bitcoin?" prompt on campaign pages that points first-time donors to Cash App.
+- An always-visible language switcher in the top navigation, and a corporate sponsorship page.
 
 ### Changed
-- Empty feeds show a friendlier state with a discover button to help you find people to follow
-- Signup flow simplified -- cleaner profile step with a single Continue button
+
+- Redesigned profiles with cleaner stats, a merged campaigns view, and a themed raised total.
+- Redesigned Settings into an Apple-style grouped layout.
+- Reworked the login and onboarding flow, including a new welcome screen built around the Agora brand.
+- Silent-payment donations now scan faster and keep working in the background, with a progress bar on the private wallet.
+- The home page now shows every featured campaign instead of capping the list.
 
 ### Fixed
-- Avatar fallback now shows the user's initial instead of a question mark
-- Android 16+ devices no longer have content hidden behind system bars
-- Signup dialog background clears properly when switching between light and dark themes
-- Sticky compose button stays anchored to the bottom even on empty feeds
 
-## [2.6.3] - 2026-04-10
+- The audio, music, and podcast pages no longer crash.
+- Backfilled and corrected translations across all sixteen languages.
+
+## [2.8.9] - 2026-06-02
+
+Adds an in-app prompt to grab the Android app from Zapstore, makes it easier to start or explore campaigns right from the home page, and irons out a batch of language and display fixes.
 
 ### Added
-- Lightning invoices embedded in posts now render as tappable payment cards
-- Blobbi companions in the feed reflect their current condition and projected health
+
+- A prompt to download the Android app from Zapstore, shown to mobile web visitors on the home page, in the account menu, and in the slide-out menu.
+- A "Start a campaign" button alongside "Browse all" in the middle of the home page.
 
 ### Changed
-- Profile headers are cleaner -- lightning addresses and verification badges moved out of the way, and website URLs no longer show a trailing slash
-- Login credentials are saved to your browser's built-in password manager for easier sign-in across sessions
-- "Request to Vanish" renamed to "Delete Account" for clarity
+
+- The "Explore campaigns" button now appears for everyone, not just logged-out visitors.
 
 ### Fixed
-- Badge image uploads now show a recommended 1:1 aspect ratio hint so your badges don't get cropped unexpectedly
-- Security hardening for URLs and styles sourced from the network
 
-## [2.6.2] - 2026-04-08
+- Switching languages now takes effect immediately instead of showing stale text.
+- The reply box and the replies heading on a post now show up in your chosen language.
+- Account balances keep their Latin numerals regardless of display language.
+- Filled in missing translations on the "Why Agora" screen.
 
-### Added
-- Share follow packs and follow sets via link -- recipients see an immersive preview with member avatars, a "Follow All" button, and a combined feed from everyone in the pack
-- Curated home feed with a mix of photos, short videos, livestreams, and music -- content types are spaced out so your timeline stays fresh and varied
-- "Write a letter" option on profile menus for a more personal way to reach out
-- Push vs persistent notification delivery option on Android
+## [2.8.8] - 2026-06-02
+
+Fixes the app icon proportions and updates the loading splash to the Agora bolt.
+
+### Fixed
+
+- App icon no longer appears squashed.
+- Loading splash now shows the Agora bolt instead of the old logo.
+
+## [2.8.7] - 2026-06-02
+
+Fixes the top navigation bar rendering behind the status bar on Android.
+
+### Fixed
+
+- Top navigation bar now clears the system status bar on Android.
+
+## [2.8.6] - 2026-06-02
+
+Refreshes the app icon to the orange Agora bolt mark across Android, iOS, and the web.
 
 ### Changed
-- Webxdc games and apps always open fullscreen for a more immersive experience
-- Login credentials are now stored in the device's secure keychain on iOS and Android instead of plain local storage
-- Profile fields now appear inline instead of in a separate right sidebar
-- Trending hashtags removed from the logged-out homepage for a cleaner first impression
 
-### Fixed
-- Webxdc and nsites work natively on iOS and Android without relying on browser sandboxing tricks
-- File downloads now save directly to Documents on iOS and Android instead of silently failing
-- Mobile search no longer scrolls the page behind it and properly hides the bottom navigation bar
-- iOS swipe-back navigation works correctly throughout the app
-- Blobbi companions appear reliably on profiles instead of sometimes going missing
-- IndexedDB no longer crashes on devices with Lockdown Mode enabled
+- Update the app icon to the current Agora bolt on a brand-orange background.
 
-## [2.6.1] - 2026-04-06
+## [2.8.5] - 2026-06-02
+
+A maintenance release that fixes the Android build so signed releases publish correctly. No user-facing changes.
+
+## [2.8.4] - 2026-06-02
+
+A maintenance release that fixes the Android build so signed releases publish correctly. No user-facing changes.
+
+## [2.8.3] - 2026-06-02
+
+A maintenance release that fixes the Android build so signed releases publish correctly. No user-facing changes.
+
+## [2.8.2] - 2026-06-02
+
+A maintenance release that fixes the Android build pipeline so signed releases publish correctly. No user-facing changes.
+
+## [2.8.1] - 2026-06-02
+
+Agora becomes a home for putting your money where your heart is. Launch and back fundraising campaigns, rally around organizations with their own events and pledges, and send support straight from a built-in Bitcoin and Lightning wallet. Explore the world through immersive country pages, chat with a new AI agent, and move through a faster, cleaner app with a fresh look throughout.
 
 ### Added
-- Manage your interest tabs (hashtags and locations) from the settings page
-- Edit button on custom profile tabs so you can tweak them without recreating from scratch
-- Follow packs and follow sets now show author info and action headers in the feed
-- Posts now show whether they were created or updated, so you can tell when something's been edited
+
+- Fundraising campaigns as the new home surface — create, edit, and back campaigns, set goals, add beneficiaries, and follow progress.
+- Organizations with their own events, pledges, members, and moderation tools.
+- Built-in wallet for sending Bitcoin and Lightning payments, with transaction history and balances shown in USD.
+- One-tap support: zap posts, profiles, campaigns, and organizations.
+- AI agent chat with a model selector, tool-calling, and slash commands.
+- Immersive country pages with anthems, flags, weather, and a country-scoped feed, plus a new Discover square for exploring the world.
+- Comments and reactions on campaigns, and donation receipts shown inline.
 
 ### Changed
-- Webxdc games and apps run in a more secure sandbox with stricter content policies and private subdomains
-- Nsite previews now use the same secure sandbox as webxdc apps
-- Blobbi items work as instant abilities instead of consumable inventory -- no more fiddly quantity pickers
 
-### Fixed
-- Desktop tab bar no longer overflows when you have lots of tabs -- scroll arrows appear automatically
-- Mobile compose box no longer randomly collapses or becomes unclickable
-- Profile avatar and banner lightbox no longer hides behind the right sidebar
-- Infinite scroll on custom profile tab feeds no longer reloads the same content
-- Reaction emoji are now visible on each row in the interactions modal
-- Missing bottom border on collapsed thread expand button restored
+- Refreshed Agora branding, navigation, and app icons throughout.
+- Streamlined onboarding with country and people follows.
+- Polished campaign, organization, and donation flows end to end.
 
-## [2.6.0] - 2026-04-05
+### Removed
+
+- Direct messaging and ephemeral geo chat.
+
+## [1.0.0] - 2026-04-30
 
 ### Added
-- Follow links and QR codes -- share a link or scannable code that lets anyone follow you with one tap, complete with your themed profile preview and recent posts
-- Immersive Blobbi hatching ceremony -- crack your egg through cinematic stages with shaking animations, a burst of light, sparkles, typewriter dialog, and a naming moment
 
-### Changed
-- Footer links redesigned as compact icon chips for a cleaner look
-- Custom emoji now render crisp at small sizes with pixel-perfect scaling
-
-### Fixed
-- Custom themes now apply correctly when logging in on a new device
-- Settings and preferences sync reliably across devices
-- Mobile sidebar links no longer clip into the safe area
-- Blobbi page background overlay now appears properly on custom themes
-- Blobbi companion state no longer resets unexpectedly from stale cache data
-- Letter compose picker no longer gets hidden behind the top navigation arc
-
-## [2.5.2] - 2026-04-04
-
-### Added
-- See who voted on each poll option -- tap the vote count to open a voters list with avatar stacks and per-option filter tabs
-- Poll votes now appear as activity cards in feeds and on detail pages
-
-### Fixed
-- Threads and replies load more reliably by following relay and author hints when fetching parent events
-
-## [2.5.1] - 2026-04-03
-
-### Fixed
-- Lightbox now reliably appears above all content, not just when opened from photo galleries
-
-## [2.5.0] - 2026-04-03
-
-### Added
-- Run nsites and web apps directly inside Ditto -- hit the "Run" button on any nsite or app card to preview it in an overlay without leaving your feed
-- File uploads in the poll composer -- attach images and media to your polls
-- Blobbi posts now appear in the homepage feed
-
-### Changed
-- Profile media sidebar fills remaining slots with photos from text posts when there aren't enough dedicated media posts
-- App cards now show banner images and improved layout
-
-### Fixed
-- Lightbox no longer appears behind the right sidebar
-- Compose box corners are properly rounded
-- Clicking buttons or links inside a post card no longer accidentally navigates to the post detail page
-
-## [2.4.1] - 2026-04-02
-
-### Added
-- Rich cards for Zapstore app releases and assets -- see download links, version info, platform badges, and hashes right in your feed
-
-### Fixed
-- First-hatch tour now shows for accounts that were onboarded before the tour existed, so no one misses the hatching moment
-
-## [2.4.0] - 2026-04-02
-
-### Added
-- First-hatch tour: a guided experience for hatching your very first Blobbi egg, with progressive crack animations, an inline card flow, and a reveal moment
-- Customizable bottom bar: rearrange or hide any item in the navigation bar to make Ditto feel like yours
-- Mission surface card in the feed that surfaces your active quests at a glance
-
-### Changed
-- Missions redesigned as a quest board with collapsible cards and a lighter aesthetic
-- "Edit Profile" mission now completes when you update any profile field, not just wall-specific edits
-- Media tab on profiles now shows only photos, videos, and other media -- not plain text posts
-- Blobbi onboarding state now syncs to your profile so it follows you across devices
-
-### Fixed
-- Notification dot no longer reappears after you've already marked notifications as read
-- Dialogs no longer fly up when the mobile keyboard opens
-
-## [2.3.1] - 2026-04-02
-
-### Changed
-- Drafts now save instantly to your device and sync to relays in the background, with a cloud sync indicator so you always know the status
-
-### Fixed
-- Dialogs stay visible above the keyboard on mobile instead of getting hidden behind it
-- Editing an existing article no longer incorrectly warns about a duplicate slug
-- Switching between rich text and markdown source mode no longer clears your content
-- Fix crash when editing in markdown source mode
-
-## [2.3.0] - 2026-04-02
-
-### Added
-- In-app article editor with a rich text toolbar, image uploads, auto-saving drafts, and a "My Articles" tab to manage drafts and published articles
-
-### Fixed
-- Custom emoji no longer stretch to fill their container
-- Mobile drawer now closes when tapping footer links like Changelog or Privacy
-- Logged-out users now default to the global tab on content feeds instead of seeing an empty follows tab
-
-## [2.2.11] - 2026-04-02
-
-### Fixed
-- Fix crash caused by the "What's new" toast firing outside the router
-
-## [2.2.10] - 2026-04-02
-
-### Added
-- App cards for Nostr apps now display in feeds and detail pages with hero images, icons, and quick-launch buttons
-- "What's new" toast appears after an app update with a changelog preview and link to the full changelog
-
-### Changed
-- Changelog page redesigned with a hero section for the latest release, collapsible older entries, and category icons inline with each item
-
-### Fixed
-- Compose box now fully resets to its collapsed state after posting, including poll options and media trays
-
-## [2.2.9] - 2026-04-01
-
-### Added
-- Emoji pack creator and editor with drag-and-drop image upload, auto-generated identifiers, and description field
-- Blobbi companions now appear in feeds and post detail pages
-
-### Changed
-- Blobbi shop redesigned with a tile layout and instant buy -- no more categories or accessory tabs
-- Emoji packs without any valid emojis are now hidden from feeds
-- Custom emoji shortcode collisions across packs are automatically resolved with pack-prefixed names
-
-## [2.2.8] - 2026-04-01
-
-### Added
-- Full threaded reply trees on post detail pages with collapsible deep branches and "Show X more replies" for sibling threads
-- Broadcast button in the Event JSON dialog to re-publish any event to your relays
-
-### Changed
-- My Badges tab overhauled with drag-and-drop reordering, a scrollable list, and a showcase-style carousel for pending badges
-- Encrypted letter envelopes now show the mailing side first (sender and recipient), then flip to reveal the wax seal
-- Blobbi companions are more expressive -- richer status reactions, sleeping visuals, and body effects like dirt and hunger cues
-
-### Fixed
-- Notification dot not clearing after marking notifications as read
-- Followers/following modal staying open after navigating to a profile
-
-## [2.2.7] - 2026-03-31
-
-### Fixed
-- Nushu script in encrypted letters now renders correctly on Android and iOS
-
-## [2.2.6] - 2026-03-31
-
-### Added
-- Encrypted letters now appear as interactive 3D envelopes with Nushu script -- flip and open them to reveal the secret writing inside
-- Zap receipts and profile metadata events now render in feeds and detail pages
-- Remote signer callback page for login flows with Amber, Primal, and other signing apps
-
-### Changed
-- Post action buttons extracted into a reusable PostActionBar component
-- Badge detail page streamlined with unified tab bar
-
-### Fixed
-- Hashtags now support accented and Unicode characters
-- Letter compose opens correctly from notifications and the letters page
-- Letter font picker loads fonts so each option previews in the correct typeface
-- Zap comment positioned inside the right column instead of floating with offset
-- Safe-area padding on pinned SubHeaderBar only applies when scrolled to top
-
-## [2.2.5] - 2026-03-30
-
-### Fixed
-- Crash when dragging profile tabs to reorder them
-
-## [2.2.4] - 2026-03-30
-
-### Changed
-- Profiles now have an emoji reaction button instead of a zap button -- express yourself with any emoji or custom emoji right on someone's profile
-- Zap moved to the profile overflow menu so it's still one tap away
-
-### Fixed
-- Crash on the notifications page caused by malformed badge award tags
-- Deleting a badge now also deletes all awards you issued for it
-- Custom emoji reactions missing their image tag no longer render as broken shortcodes
-- Deletion requests for addressable events now include both `e` and `a` tags for broader relay compatibility
-- Profile reactions no longer collapse into a single grouped notification
-- Oversized reaction emoji in comment context headers
-
-## [2.2.3] - 2026-03-30
-
-### Added
-- Letters now have an overflow menu, reply button, and a grid layout for browsing
-- Independent feed toggles for comments and generic reposts in content settings
-- Sidebar items are now visible to logged-out users so newcomers can explore everything
-
-### Changed
-- Compose textarea expands smoothly as you type instead of snapping to a new height
-- Blobbi stickers auto-shrink near card edges and clip cleanly at rounded boundaries
-
-### Fixed
-- Feed gaps when replies are disabled no longer cause missing posts
-- Avatar shape no longer flashes on load
-- Top bar arc no longer flickers during navigation transitions
-- Letter drawing-only sends, sticker drag bounds, and theme event preservation
-- Notification rendering for badges and letters
-- Duplicate React keys in content settings
-- Layout rendering warning when switching views
-
-## [2.2.2] - 2026-03-29
-
-### Added
-- Dedicated photo upload flow for sharing photos
-- Pull-to-refresh on all feed pages
-- 3D tilt effect on badge images -- hover over badges to see them pop
-- Multi-select badge awarding with indicators for already-sent badges
-- Badge list recovery dialog for restoring profile badge lists
-- Compact badge row preview in embedded profile badges events
-- Custom emoji usage tracking so your most-used custom emojis appear in the quick-react bar
-- Release notes now included in Zapstore publishing
-- Changelog link in the app footer
-
-### Changed
-- "Vines" renamed to "Divines" everywhere in the app
-- Custom emojis appear first in the emoji picker, right after recent
-- Threaded comment view now shows the parent event as a NoteCard with kind action headers
-
-### Fixed
-- Delete post dialog no longer freezes the feed on desktop
-- Amber login on Android now properly retries when returning from the background
-- Key downloads on Android save to the correct location
-- Custom emoji SVGs render correctly in the emoji-mart picker
-- Double-tap reactions now properly show the emoji on the post
-- Emoji shortcode autocomplete text and highlight colors
-- Profile skeleton no longer flickers for brand-new users with no metadata
-- Event links now route correctly for all event types
-- Badge notifications are now clickable
-- Custom profile tab form no longer retains fields from a previously edited tab
-- Double line under profile tabs in edit mode
-- Inconsistent use of "geocache" vs "treasures" terminology
-- Search page "N new posts" pill no longer shows unfiltered count
-- Stale-cache overwrites in replaceable event mutations
-- Click-through on delete confirmation and note menu items
-
-## [2.2.1] - 2026-03-28
-
-### Fixed
-- New posts no longer cause scroll jumps -- they buffer while you're reading and appear with a tap
-- Mobile header no longer shows double-layered backgrounds on notched devices
-- Pinned tabs stay properly positioned when scrolling on mobile
-- Signer approval toasts no longer fire in rapid succession on unstable connections
-- Toasts are easier to swipe away on mobile
-- Content warnings now blur thumbnails in the media grid
-
-## [2.2.0] - 2026-03-28
-
-### Added
-- Blobbi virtual pets -- adopt an egg, hatch it, evolve it into one of 16 adult forms, and care for it with feeding, cleaning, medicine, music, and singing
-- Blobbi companion that follows you around the app, tracks your cursor, blinks, expresses emotions, and reacts to what you're doing
-- Blobbi shop and inventory system with items that affect your pet's stats
-- Daily missions with reroll, care streaks, and stage-based rewards
-- Immersive full-screen divines experience on both mobile and desktop with floating controls
-- Relay information panel on the network settings page
-- Link preview cards now display inside quoted posts instead of raw URLs
-- Nsec paste guard warns you before accidentally pasting private keys outside the login field
-- Remote signer UX improvements for Amber users on Android
-- Badge awards now trigger push notifications
-- Badges display in profile bio section with a "Give badge" option in the profile menu
-
-### Changed
-- Notification "Mentions" tab now shows only pure mentions, filtering out replies
-- Notification preferences ("only from people I follow") now properly apply to push notifications, native Android notifications, and the unread dot
-- Upgraded from React 18 to React 19
-- Reduced initial bundle size by ~50% with improved code splitting and lazy loading
-
-### Fixed
-- Zapping Primal users no longer produces an error
-- Hashtag feeds now match case-insensitively for parity with search results
-- Mobile top bar arc no longer lingers on pages without tabs
-- Give Badge dialog and profile menu action handlers
-
-## [2.1.1] - 2026-03-27
-
-### Added
-- Emoji picker and shortcode autocomplete in zap comment box
-- Zap button on badge detail view
-- Theme descriptions now display on "updated their theme" posts and detail pages
-- Badge thumbnail previews in award notifications
-- Letter notifications with envelope card preview
-- Kind-specific labels in notification text instead of generic "post"
-
-### Fixed
-- Compose modal no longer closes when dismissing emoji picker on mobile
-- Compose preview overflow is now scrollable in modal
-- Toast notifications swipe up to dismiss on mobile instead of sideways
-- File downloads and URL opening work correctly on iOS
-- Badges page no longer shows infinite skeleton when logged out
-
-## [2.1.0] - 2026-03-26
-
-### Added
-- Letters -- a Wii Mail-inspired inbox for sending decorated letters to friends, complete with custom stationery, hand-drawn stickers, emoji stickers, fonts, and a send animation with envelope and wax seal
-- Attach a color moment or theme to your letter as a gift -- recipients can tap to apply it instantly
-- Stationery picker pulls from your color moments, followed users' themes, and built-in presets
-- Freehand drawing canvas for creating one-of-a-kind sticker doodles
-- Letters page added to the sidebar with a custom mailbox icon
-
-## [2.0.1] - 2026-03-26
-
-### Added
-- Tap the version number in settings to see what's new
-
-## [2.0.0] - 2026-03-26
-
-Initial release of Ditto 2.0 -- a complete rewrite of Ditto.
+- Initial Agora 3 release.

CONTRIBUTING.md

@@ -1,42 +1,42 @@
-# Contributing to Ditto
+# Contributing to Agora
 
-We welcome contributions, but we have high standards. Ditto is a carefully designed product with a specific vision, and every merge request must meet that bar. This guide exists to help you succeed.
+We welcome contributions, but we have high standards. Agora is a carefully designed product with a specific vision, and every merge request must meet that bar. This guide exists to help you succeed.
 
 **Required reading before you start:**
 
-- [Ditto Philosophy](https://about.ditto.pub/philosophy) -- the product vision. Your change must align with it.
-- [Contributing Guide](https://about.ditto.pub/contributing) -- the upstream contribution process.
+- [Understanding Agora](#understanding-agora) -- the product vision. Your change must align with it.
+- This `CONTRIBUTING.md` guide -- the contribution process for this repository.
 - `AGENTS.md` in this repo -- the codebase conventions. Your AI tool should load this file.
 
-## Understanding Ditto
+## Understanding Agora
 
-Ditto is a carnival, not a platform. Before contributing, you need to understand what that means.
+Agora is a carnival, not a platform. Before contributing, you need to understand what that means.
 
 ### The product decision filter
 
-Every change to Ditto should pass this test:
+Every change to Agora should pass this test:
 
-> *Does this make Ditto more magnetic, more threatening to the status quo, and more peaceful to inhabit?*
+> *Does this make Agora more magnetic, more threatening to the status quo, and more peaceful to inhabit?*
 
-- **Magnetic** -- Ditto attracts through experience, not ideology. People don't need to understand Nostr to love it. They need to feel something they haven't felt online since the early web. Features should be odd, intriguing, and captivating -- not generic social media clones.
-- **Threatening to the status quo** -- Ditto threatens mainstream platforms when someone opens it and thinks: *"Why can't my platform do this?"* Theming, games, treasure hunts, interoperable micro-apps -- these are things walled gardens can't replicate.
-- **Peaceful to inhabit** -- Ditto displaces argument with creation, conformity with expression, and consumption with participation. No ads, no engagement-optimized algorithms, no outrage incentives.
+- **Magnetic** -- Agora attracts through experience, not ideology. People don't need to understand Nostr to love it. They need to feel something they haven't felt online since the early web. Features should be odd, intriguing, and captivating -- not generic social media clones.
+- **Threatening to the status quo** -- Agora threatens mainstream platforms when someone opens it and thinks: *"Why can't my platform do this?"* Theming, games, treasure hunts, interoperable micro-apps -- these are things walled gardens can't replicate.
+- **Peaceful to inhabit** -- Agora displaces argument with creation, conformity with expression, and consumption with participation. No ads, no engagement-optimized algorithms, no outrage incentives.
 
 If a change does all three, it belongs. If it only does one, think harder. If it does none, it doesn't belong here.
 
-### What Ditto is NOT
+### What Agora is NOT
 
 - A Twitter/X clone with decentralization bolted on
 - A place to replicate features that mainstream platforms already do well
 - A showcase for generic UI components or boilerplate social features
 
-### What Ditto IS
+### What Agora IS
 
 - A convergence point for interoperable Nostr experiences (games, treasure hunts, magic decks, themes, color moments, live streams, and things nobody has imagined yet)
 - A place where profiles feel like worlds, not business cards
 - The most fun you've had on the internet in years
 
-Read the [full philosophy](https://about.ditto.pub/philosophy) for the complete vision.
+Read the full "Understanding Agora" section above for the complete vision.
 
 ## What we accept
 
@@ -44,17 +44,19 @@ Read the [full philosophy](https://about.ditto.pub/philosophy) for the complete
 
 One bug, one merge request. Fix exactly one thing. Don't bundle unrelated changes, don't sneak in refactors, don't "clean up while you're in there." Small, focused MRs get reviewed fast. Large ones sit.
 
+When the bug was introduced by an identifiable prior commit, add a `Regression-of: <short-sha>` trailer to the bottom of your commit message. See AGENTS.md "Attributing Regressions" for the convention.
+
 ### New features and significant changes
 
-Every feature MR must link to an existing open issue and clearly align with the [Ditto Philosophy](https://about.ditto.pub/philosophy). The philosophy alignment section in the MR template is where you make the case for why your change belongs in Ditto. If you can't articulate that clearly, the change probably doesn't belong.
+Every feature MR must link to an existing open issue and clearly align with the "Understanding Agora" section in this file. The philosophy alignment section in the MR template is where you make the case for why your change belongs in Agora. If you can't articulate that clearly, the change probably doesn't belong.
 
 If you have an idea for a feature that doesn't have an issue yet:
 
-1. Build it as a standalone Nostr app first (see [Contributing Guide](https://about.ditto.pub/contributing)).
+1. Build it as a standalone Nostr app first (then document traction/feedback in the linked issue).
 2. Prove it works and get user feedback.
 3. Open an issue to discuss integration.
 
-**Feature MRs that don't link to an issue or don't align with the Ditto Philosophy will be closed.** Our open issues are our internal roadmap -- some require deep product context. If your implementation doesn't match the product vision, it will be closed regardless of code quality.
+**Feature MRs that don't link to an issue or don't align with the Agora Philosophy will be closed.** Our open issues are our internal roadmap -- some require deep product context. If your implementation doesn't match the product vision, it will be closed regardless of code quality.
 
 ## Required tools
 
@@ -80,7 +82,7 @@ Read `AGENTS.md` in the repo root. This is the single source of truth for how co
 
 ### 4. Read the philosophy
 
-Read the [Ditto Philosophy](https://about.ditto.pub/philosophy). Ditto is a carnival, not a platform. Your change should feel like it belongs in Ditto -- not like it was transplanted from a generic social media template. Apply the product decision filter above.
+Read "Understanding Agora" in this file. Agora is a carnival, not a platform. Your change should feel like it belongs in Agora -- not like it was transplanted from a generic social media template. Apply the product decision filter above.
 
 ### 5. Plan before you code
 
@@ -131,6 +133,7 @@ maintain it long-term. For each finding, state the file, line, and issue.
 - [ ] Are there any new images >100KB or other large binary assets that should be hosted externally?
 - [ ] Is there any use of dangerouslySetInnerHTML, eval, innerHTML, or SVG string interpolation?
 - [ ] Is any data from a Nostr event (tags, content, pubkey, URLs) used in a security-sensitive context (href, src, query filter, trust decision) without validation?
+- [ ] If this is a bug fix and the offending commit is identifiable, does the commit message include a `Regression-of: <short-sha>` trailer? (See AGENTS.md "Attributing Regressions".)
 
 Skip anything a linter or type checker would catch. Focus on logic, data flow, and intent.
 
@@ -163,7 +166,7 @@ Fill out every field in the MR template. Incomplete MRs will not be reviewed.
 ## What gets your MR closed without review
 
 - No linked issue
-- Feature MRs with no clear alignment with the [Ditto Philosophy](https://about.ditto.pub/philosophy)
+- Feature MRs with no clear alignment with "Understanding Agora" in this file
 - Features that fail the product decision filter (not magnetic, not threatening to the status quo, not peaceful)
 - Incomplete MR template (missing checklist, screenshots, or preview URL)
 - Changes that go beyond what was asked for (scope creep)

Dockerfile

@@ -0,0 +1,15 @@
+FROM node:22-alpine AS builder
+WORKDIR /app
+RUN apk add --no-cache git
+COPY package*.json ./
+COPY .npmrc ./
+COPY scripts/ ./scripts/
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=builder /app/dist /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

NOSTR_WEBXDC.md

@@ -1,116 +0,0 @@
-NIP-DC
-======
-
-Nostr Webxdc
-------------
-
-`draft` `optional`
-
-This NIP defines how to share and run [webxdc](https://webxdc.org/) apps over Nostr. Webxdc apps are `.xdc` (ZIP) files containing sandboxed HTML5 applications. They are attached to regular Nostr events using `imeta` tags (NIP-92), and state is coordinated through a unique identifier.
-
-This spec covers public webxdc communication only. Private communication may be addressed in a future update.
-
-## Attachment
-
-A webxdc app is attached to any event by including the `.xdc` file URL in the content and an `imeta` tag with MIME type `application/x-webxdc`.
-
-The `imeta` tag SHOULD include a `webxdc` property with a randomly generated unique string. This serves as the coordination identifier for state updates and realtime channels. If omitted, the app can still run but state won't work.
-
-```json
-{
-  "kind": 1,
-  "content": "Let's play chess! https://blossom.example.com/abc123.xdc",
-  "tags": [
-    ["imeta",
-      "url https://blossom.example.com/abc123.xdc",
-      "m application/x-webxdc",
-      "x a1b2c3d4e5f6...",
-      "webxdc 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
-    ]
-  ]
-}
-```
-
-A webxdc MAY also be published as a kind `1063` (NIP-94) file metadata event:
-
-```json
-{
-  "kind": 1063,
-  "content": "A collaborative chess game. Play with friends over Nostr!",
-  "tags": [
-    ["url", "https://blossom.example.com/abc123.xdc"],
-    ["m", "application/x-webxdc"],
-    ["x", "a1b2c3d4e5f6..."],
-    ["alt", "Webxdc app: Chess"],
-    ["webxdc", "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"]
-  ]
-}
-```
-
-## Kind `4932`: State Update
-
-A regular event carrying a state update, mapping to the webxdc [`sendUpdate()`](https://webxdc.org/docs/spec/sendUpdate.html) API. Updates are ordered by `created_at` and assigned serial numbers by the client.
-
-### Tags
-
-- `i`: The `webxdc` identifier from the originating event (required)
-- `alt`: NIP-31 human-readable description (required)
-- `info`: Short info message, max ~50 chars (optional)
-- `document`: Document name being edited (optional)
-- `summary`: Short summary text, e.g. "8 votes" (optional)
-
-The optional tags correspond to fields in the webxdc `sendUpdate()` API.
-
-### Content
-
-JSON-serialized payload from `sendUpdate()`.
-
-```json
-{
-  "kind": 4932,
-  "content": "{\"move\":\"e2e4\",\"player\":\"white\"}",
-  "tags": [
-    ["i", "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"],
-    ["alt", "Webxdc update"],
-    ["info", "White played e2-e4"]
-  ]
-}
-```
-
-## Kind `20932`: Realtime Data (Ephemeral)
-
-An ephemeral event carrying realtime data, mapping to the webxdc [`joinRealtimeChannel`](https://webxdc.org/docs/spec/joinRealtimeChannel.html) API. Relays forward these to active subscribers but do not store them.
-
-### Tags
-
-- `i`: The `webxdc` identifier from the originating event (required)
-
-### Content
-
-Base64-encoded `Uint8Array` payload (max 128,000 bytes raw).
-
-```json
-{
-  "kind": 20932,
-  "content": "SGVsbG8gZnJvbSBucHViMWFiYy4uLg==",
-  "tags": [
-    ["i", "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"]
-  ]
-}
-```
-
-## Flow
-
-1. A user uploads a `.xdc` file (e.g. to Blossom) and publishes an event with the URL in content and an `imeta` tag. The `imeta` SHOULD include a `webxdc` property.
-2. A client detects the `imeta` tag, downloads the `.xdc`, extracts it, and runs `index.html` in a sandboxed iframe or webview.
-3. `sendUpdate()` publishes a kind `4932` event with the `webxdc` identifier in an `i` tag.
-4. The client subscribes to kind `4932` events with `#i` matching the identifier and delivers them via `setUpdateListener()`.
-5. `joinRealtimeChannel()` subscribes to kind `20932` events with `#i` matching the identifier. `send()` publishes ephemeral kind `20932` events. `leave()` closes the subscription.
-6. `selfAddr` and `selfName` MAY map to the user's npub and display name, or any other values.
-
-## Security Considerations
-
-- Webxdc apps MUST be sandboxed with no network access, per the [webxdc spec](https://webxdc.org/docs/spec/messenger.html).
-- Clients SHOULD verify the `.xdc` file hash (`x` tag) before running it.
-- All communication in this spec is public. Webxdc apps designed for private chats or small groups may not work as expected.
-- Webxdc apps have no access to Nostr signatures or identity verification. Any participant can claim to be anyone within the app. Apps should not rely on `selfAddr` or `selfName` for trust decisions.

README.md

@@ -1,24 +1,24 @@
-# Ditto
+# Eranos
 
-Your content. Your vibe. Your rules. A fun, customizable [Nostr](https://nostr.com/) client that puts you in control.
+Power to the people.
 
-**[ditto.pub](https://ditto.pub)** | **[Docs](https://docs.ditto.pub)** | **[Source](https://gitlab.com/soapbox-pub/ditto)**
+Eranos is a Nostr client focused on community ownership, expressive identity, and censorship resistance. This repository is the Eranos-branded app, a Grin-only fork of Agora (itself built from the Ditto codebase). All Bitcoin and Lightning payment rails have been removed; Grin payments land in a later phase.
 
-## About
+**[eranos.fund](https://eranos.fund)** | **Upstream: [Agora](https://gitlab.com/soapbox-pub/agora-3)**
 
-Ditto is an open-source, decentralized social media client built on the Nostr protocol. It's designed for people who want to have fun online without feeding the Big Tech machine. Express yourself with custom themes, Lightning payments, and an ever-growing set of content types -- all while owning your identity and data.
+## What This Repo Is
 
-Made by [Soapbox](https://soapbox.pub).
+- Eranos product identity (name, theme, assets, native IDs)
+- Ditto-derived implementation with broad Nostr feature coverage
+- Configurable deployment defaults via `eranos.json`
 
 ## Features
 
-- **Theming** -- 9 built-in theme presets, 19 CSS token properties for full customization, and the ability to publish and share themes as Nostr events
-- **Infinite Content Types** -- Text notes, articles, short-form videos (Divines), live streams, polls, follow packs, color moments, magic decks, geocaching, and Webxdc mini-apps
-- **Lightning Payments** -- Zap posts and profiles with sats via Nostr Wallet Connect (NWC) or WebLN
-- **Private Messaging** -- End-to-end encrypted DMs (NIP-04 and NIP-17)
-- **Comments** -- Comment on anything: posts, URLs, profiles, hashtags, books, and more (NIP-22)
-- **Self-Hosting** -- Builds to static HTML/JS/CSS. Deploy anywhere -- GitHub Pages, Netlify, Vercel, a VPS, or a Raspberry Pi
-- **Mobile** -- Android native app via Capacitor, responsive design for all screen sizes
+- **Community-first social client**: notes, articles, comments, reposts, reactions, and rich event rendering
+- **Theming system**: built-in presets + custom color/font/background themes that can be shared as events
+- **Private messaging**: NIP-04 and NIP-17 direct messages
+- **Mobile app shell**: Capacitor-powered Android/iOS wrappers
+- **Self-hostable**: static web build + configurable relay and upload infrastructure
 
 ## Getting Started
 
@@ -30,13 +30,43 @@ Made by [Soapbox](https://soapbox.pub).
 ### Development
 
 ```sh
-git clone https://gitlab.com/soapbox-pub/ditto.git
-cd ditto
+git clone <this-repo>
+cd eranos
 npm install
 npm run dev
 ```
 
-The dev server starts at `http://localhost:8080`.
+Development server: `http://localhost:8080`
+
+### Docker Getting Started
+
+Use Docker Compose when you want the nginx reverse-proxy stack (necessary if you want decryptable media in messages - kind 15s of NIP 17):
+
+```sh
+git clone <this-repo>
+cd eranos
+cp .env.example .env
+docker compose up --build
+```
+
+Proxy URL: `http://localhost:8083`
+
+This starts:
+
+- `vite` service on the internal Docker network (`vite:8080`)
+- `web` service (`nginx`) on host port `8082`, proxying to Vite with websocket support
+
+Stop stack:
+
+```sh
+docker compose down
+```
+
+Production-style container build:
+
+```sh
+docker compose -f docker-compose.prod.yml up --build
+```
 
 ### Build
 
@@ -44,66 +74,58 @@ The dev server starts at `http://localhost:8080`.
 npm run build
 ```
 
-The built site is output to `dist/`.
+Build output: `dist/`
 
-### Test
-
-Runs type-checking, linting, unit tests, and a production build:
+### Validate
 
 ```sh
 npm test
 ```
 
+This runs type-checking, linting, unit tests, and production build checks.
+
 ## Configuration
 
-Ditto is configured through a `ditto.json` file at the project root, read at build time. This file is gitignored so each deployment can have its own configuration.
+Build-time config is read from `eranos.json` (gitignored by default so each deployment can provide its own values).
 
 ```jsonc
 {
   "theme": "dark",
   "relayMetadata": {
     "relays": [
-      { "url": "wss://relay.ditto.pub", "read": true, "write": true }
+      { "url": "wss://relay.ditto.pub", "read": true, "write": true },
+      { "url": "wss://relay.primal.net", "read": true, "write": true },
+      { "url": "wss://relay.damus.io", "read": true, "write": true }
     ]
   },
-  "blossomServers": ["https://blossom.ditto.pub"],
-  "feedSettings": {
-    "showPosts": true,
-    "showReposts": true,
-    "showArticles": true
-    // ...and more content type toggles
-  }
+  "blossomServers": [
+    "https://blossom.ditto.pub",
+    "https://blossom.primal.net/"
+  ]
 }
 ```
 
-Configuration is resolved in three layers (highest priority first):
+Configuration priority (highest first):
 
-1. **User settings** stored in localStorage
-2. **Build config** from `ditto.json`
-3. **Hardcoded defaults**
+1. User settings (local storage)
+2. Build config (`eranos.json`)
+3. Hardcoded app defaults
 
-Use an alternate config file path with: `CONFIG_FILE=./my-config.json npm run build`
+Use a custom config path:
 
-### Custom Branding
-
-For self-hosted instances:
-
-- Replace `public/logo.svg` and `public/logo.png` with your logo
-- Update the app name in `index.html` and `public/manifest.webmanifest`
-- Replace `public/og-image.jpg` for social sharing previews
-- Set default relays and upload servers in `ditto.json`
+```sh
+CONFIG_FILE=./my-config.json npm run build
+```
 
 ## Deployment
 
-Ditto builds to static files and can be deployed anywhere that serves HTML.
+Eranos builds to static files and can be deployed to any static host.
 
-- **GitHub Pages / GitLab Pages** -- Push to `main` and CI auto-deploys
-- **Netlify / Vercel** -- Connect your fork and deploy. A `_redirects` file is included for SPA routing
-- **VPS / Any web server** -- Build and copy `dist/` to your server. Configure SPA routing (e.g., Nginx `try_files $uri $uri/ /index.html`)
+- GitLab/GitHub Pages
+- Netlify/Vercel
+- VPS or any web server with SPA routing fallback
 
-### Android
-
-Build a native Android app with [Capacitor](https://capacitorjs.com/):
+For Android:
 
 ```sh
 npm run build
@@ -114,41 +136,23 @@ npx cap open android
 ## Tech Stack
 
 | Layer | Technology |
-|---|---|
+| --- | --- |
 | Framework | React 18 |
 | Build | Vite |
 | Language | TypeScript |
 | Styling | TailwindCSS 3 + shadcn/ui |
-| Routing | React Router 6 |
+| Routing | React Router |
 | Data | TanStack Query |
 | Nostr | Nostrify + nostr-tools |
 | Mobile | Capacitor |
 | Testing | Vitest + React Testing Library |
 
-## Project Structure
-
-```
-src/
-  components/     UI components (100+), including shadcn/ui primitives
-  hooks/          Custom React hooks (65+)
-  pages/          Page components for each route (30+)
-  contexts/       React context providers
-  lib/            Utilities and shared logic
-  test/           Test setup and helpers
-public/           Static assets, icons, manifest
-```
-
 ## Contributing
 
-We welcome contributions but have high standards. Please read the full [Contributing Guide](CONTRIBUTING.md) before submitting a merge request. The short version:
-
-- **Bug fixes**: One bug, one MR. Keep it small and focused.
-- **New features**: Must link to an existing issue and align with the [Ditto Philosophy](https://about.ditto.pub/philosophy).
-- **Required**: Live preview URL, before/after screenshots, completed self-review checklist.
-- **Required tools**: Claude Opus 4.6 (or latest frontier model), an AI coding agent with plan mode.
-
-Read the [Ditto Philosophy](https://about.ditto.pub/philosophy) to understand what Ditto is and isn't.
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a merge request.
 
 ## License
 
 [AGPL-3.0](LICENSE)
+
+🤖 Built with AI pair-programming assistance (Claude)

android/app/build.gradle

@@ -7,15 +7,22 @@ if (keystorePropertiesFile.exists()) {
 }
 
 android {
-    namespace = "pub.ditto.app"
+    namespace = "fund.eranos.app"
     compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
-        applicationId "pub.ditto.app"
+        applicationId "fund.eranos.app"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
         versionCode 1
-        versionName "2.6.6"
+        versionName "2.9.1"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        // The arti-mobile AAR bundles large native Rust libraries for every
+        // ABI (~45 MB total). Restrict to the ABIs we actually ship/test:
+        // arm64-v8a + armeabi-v7a (real devices) and x86_64 (emulators).
+        // Drop x86_64 here if you only ever test on physical devices.
+        ndk {
+            abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86_64'
+        }
         aaptOptions {
              // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
              // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
@@ -51,10 +58,20 @@ repositories {
 dependencies {
     implementation fileTree(include: ['*.jar'], dir: 'libs')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.core:core:$androidxCoreVersion"
     implementation "androidx.coordinatorlayout:coordinatorlayout:$androidxCoordinatorLayoutVersion"
     implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
     implementation project(':capacitor-android')
     implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+    // Tor in Rust (arti) — prebuilt AAR from Guardian Project's gpmaven repo
+    // (source pinned to an immutable commit in the root build.gradle).
+    // Provides org.torproject.arti.ArtiProxy used by TorController.
+    // The resolved AAR is checksum-verified below (verifyArtiChecksum).
+    implementation 'org.torproject:arti-mobile:1.7.0.1'
+    // arti pulls androidx.webkit in transitively but only at runtime; we
+    // compile against ProxyController/WebViewFeature in TorController, so
+    // declare it explicitly on the app's compile classpath.
+    implementation "androidx.webkit:webkit:$androidxWebkitVersion"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
@@ -63,6 +80,49 @@ dependencies {
 
 apply from: 'capacitor.build.gradle'
 
+// Supply-chain pin for the arti-mobile AAR. It carries a native library with
+// network-proxy privileges and is sourced from Guardian Project's gpmaven repo,
+// so we verify the resolved artifact's SHA-256 against a value pinned here.
+// A mismatch fails the build before any APK is assembled. To bump arti, update
+// the version + repo commit (root build.gradle) and replace this checksum after
+// re-verifying a fresh download.
+ext.artiMobileSha256 = 'cbdb34ce3cdb32f755f25f6dd05a2d1eb9a44025a17ec9202729816e2a3af05b'
+
+task verifyArtiChecksum {
+    doLast {
+        def artifact = configurations.releaseRuntimeClasspath
+            .resolvedConfiguration
+            .resolvedArtifacts
+            .find { it.moduleVersion.id.group == 'org.torproject' && it.moduleVersion.id.name == 'arti-mobile' }
+
+        if (artifact == null) {
+            throw new GradleException("arti-mobile artifact not found on the runtime classpath; cannot verify Tor native library.")
+        }
+
+        def actual = java.security.MessageDigest.getInstance("SHA-256")
+            .digest(artifact.file.bytes)
+            .collect { String.format('%02x', it) }
+            .join('')
+
+        if (actual != project.ext.artiMobileSha256) {
+            throw new GradleException(
+                "arti-mobile AAR checksum mismatch!\n" +
+                "  expected: ${project.ext.artiMobileSha256}\n" +
+                "  actual:   ${actual}\n" +
+                "  file:     ${artifact.file}\n" +
+                "Refusing to build a Tor proxy from an unverified native artifact."
+            )
+        }
+        logger.lifecycle("Verified arti-mobile AAR checksum (${actual}).")
+    }
+}
+
+afterEvaluate {
+    tasks.matching { it.name.startsWith('assemble') || it.name.startsWith('bundle') }.configureEach {
+        dependsOn verifyArtiChecksum
+    }
+}
+
 try {
     def servicesJSON = file('google-services.json')
     if (servicesJSON.text) {

android/app/capacitor.build.gradle

@@ -10,6 +10,7 @@ android {
 apply from: "../capacitor-cordova-android-plugins/cordova.variables.gradle"
 dependencies {
     implementation project(':capacitor-app')
+    implementation project(':capacitor-barcode-scanner')
     implementation project(':capacitor-filesystem')
     implementation project(':capacitor-haptics')
     implementation project(':capacitor-keyboard')

android/app/proguard-rules.pro

@@ -7,7 +7,7 @@
 
 # Keep Capacitor classes (WebView JS bridge)
 -keep class com.getcapacitor.** { *; }
--keep class pub.ditto.app.** { *; }
+-keep class fund.eranos.app.** { *; }
 
 # Keep WebView JS interfaces
 -keepclassmembers class * {
@@ -19,6 +19,18 @@
 -dontwarn okio.**
 -keep class okhttp3.** { *; }
 
+# Barcode scanner plugin (@capacitor/barcode-scanner -> OutSystems ionbarcode)
+# references Gson's @SerializedName, but Gson isn't on the release classpath.
+# Suppress the missing-class warning, keep the annotation attribute, and keep
+# the plugin's model classes so R8 doesn't strip/rename serialized fields.
+-dontwarn com.google.gson.**
+-keepattributes *Annotation*
+-keep class com.outsystems.plugins.barcode.** { *; }
+
+# Keep arti (Tor) classes — ArtiJNI declares native methods invoked from the
+# Rust .so via JNI, so its names must not be obfuscated/stripped.
+-keep class org.torproject.arti.** { *; }
+
 # Uncomment this to preserve the line number information for
 # debugging stack traces.
 #-keepattributes SourceFile,LineNumberTable

android/app/src/main/AndroidManifest.xml

@@ -3,6 +3,8 @@
 
     <application
         android:allowBackup="true"
+        android:fullBackupContent="@xml/backup_rules"
+        android:dataExtractionRules="@xml/data_extraction_rules"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
         android:roundIcon="@mipmap/ic_launcher_round"
@@ -22,12 +24,12 @@
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
 
-            <!-- Deep links: open ditto.pub URLs in the app -->
+            <!-- Deep links: open eranos.fund URLs in the app -->
             <intent-filter android:autoVerify="true">
                 <action android:name="android.intent.action.VIEW" />
                 <category android:name="android.intent.category.DEFAULT" />
                 <category android:name="android.intent.category.BROWSABLE" />
-                <data android:scheme="https" android:host="ditto.pub" />
+                <data android:scheme="https" android:host="eranos.fund" />
             </intent-filter>
 
         </activity>
@@ -56,4 +58,8 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-feature android:name="android.hardware.camera" android:required="false" />
 </manifest>

android/app/src/main/java/fund/eranos/app/DittoNotificationPlugin.java

@@ -1,4 +1,4 @@
-package pub.ditto.app;
+package fund.eranos.app;
 
 import android.app.ForegroundServiceStartNotAllowedException;
 import android.content.Context;

android/app/src/main/java/fund/eranos/app/MainActivity.java

@@ -1,4 +1,4 @@
-package pub.ditto.app;
+package fund.eranos.app;
 
 import android.app.ForegroundServiceStartNotAllowedException;
 import android.content.Context;
@@ -8,6 +8,12 @@ import android.net.Uri;
 import android.os.Build;
 import android.os.Bundle;
 import android.util.Log;
+import android.view.View;
+import android.webkit.WebView;
+
+import androidx.core.graphics.Insets;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowInsetsCompat;
 
 import com.getcapacitor.BridgeActivity;
 
@@ -19,7 +25,14 @@ public class MainActivity extends BridgeActivity {
     protected void onCreate(Bundle savedInstanceState) {
         // Register native plugins before super.onCreate.
         registerPlugin(DittoNotificationPlugin.class);
-        registerPlugin(SandboxPlugin.class);
+        registerPlugin(TorPlugin.class);
+
+        // If the user enabled Tor (apply on relaunch), start arti BEFORE
+        // super.onCreate so the WebView SOCKS proxy override is installed
+        // before the WebView issues any network request — no leak window.
+        if (TorController.isEnabled(this)) {
+            TorController.getInstance().start(getApplicationContext());
+        }
 
         super.onCreate(savedInstanceState);
 
@@ -48,6 +61,35 @@ public class MainActivity extends BridgeActivity {
 
         // Handle notification tap deep link
         handleNotificationIntent(getIntent());
+
+        // The Android WebView reports env(safe-area-inset-*) as 0, so inject the
+        // real system-bar insets as CSS variables (--safe-area-inset-top/bottom)
+        // that the web layer consumes (see src/index.css). Without this, the top
+        // nav renders behind the status bar in the APK.
+        applySafeAreaInsets();
+    }
+
+    /**
+     * Read the status-bar (top) and navigation-bar (bottom) insets and write
+     * them into the WebView as CSS pixel variables. Re-applies on every inset
+     * change (rotation, status-bar show/hide, etc.).
+     */
+    private void applySafeAreaInsets() {
+        final WebView webView = getBridge().getWebView();
+        if (webView == null) return;
+
+        ViewCompat.setOnApplyWindowInsetsListener(webView, (v, insets) -> {
+            Insets bars = insets.getInsets(WindowInsetsCompat.Type.systemBars());
+            float density = getResources().getDisplayMetrics().density;
+            int topPx = Math.round(bars.top / density);
+            int bottomPx = Math.round(bars.bottom / density);
+            String js =
+                "document.documentElement.style.setProperty('--safe-area-inset-top','" + topPx + "px');" +
+                "document.documentElement.style.setProperty('--safe-area-inset-bottom','" + bottomPx + "px');";
+            v.post(() -> webView.evaluateJavascript(js, null));
+            return insets;
+        });
+        ViewCompat.requestApplyInsets(webView);
     }
 
     @Override
@@ -64,7 +106,7 @@ public class MainActivity extends BridgeActivity {
     private void handleNotificationIntent(Intent intent) {
         if (intent == null) return;
         Uri data = intent.getData();
-        if (data != null && "ditto.pub".equals(data.getHost())) {
+        if (data != null && "eranos.fund".equals(data.getHost())) {
             String path = data.getPath();
             if (path != null && !path.isEmpty()) {
                 // Wait for WebView to be ready, then navigate

android/app/src/main/java/fund/eranos/app/NostrPoller.java

@@ -1,4 +1,4 @@
-package pub.ditto.app;
+package fund.eranos.app;
 
 import android.app.NotificationChannel;
 import android.app.NotificationManager;
@@ -337,7 +337,7 @@ public class NostrPoller {
         if (manager == null) return;
 
         Intent intent = new Intent(context, MainActivity.class);
-        intent.setData(Uri.parse("https://ditto.pub/notifications"));
+        intent.setData(Uri.parse("https://eranos.fund/notifications"));
         intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP);
         PendingIntent pendingIntent = PendingIntent.getActivity(
                 context, id, intent,

android/app/src/main/java/fund/eranos/app/NotificationRelayService.java

@@ -1,4 +1,4 @@
-package pub.ditto.app;
+package fund.eranos.app;
 
 import android.app.AlarmManager;
 import android.app.ForegroundServiceStartNotAllowedException;
@@ -83,7 +83,7 @@ public class NotificationRelayService extends Service {
     // + REQ + up to 5 events + EOSE + metadata fetch + disconnect.
     private static final long FETCH_WAKELOCK_TIMEOUT_MS = 30_000;
 
-    private static final String ACTION_FETCH = "pub.ditto.app.ACTION_FETCH";
+    private static final String ACTION_FETCH = "fund.eranos.app.ACTION_FETCH";
 
     // Backoff bounds for relay connect failures (separate from alarm interval).
     private static final long INITIAL_BACKOFF_MS = 1_000;

android/app/src/main/java/fund/eranos/app/TorController.java

@@ -0,0 +1,381 @@
+package fund.eranos.app;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.util.Log;
+
+import androidx.annotation.Nullable;
+import androidx.webkit.ProxyConfig;
+import androidx.webkit.ProxyController;
+import androidx.webkit.WebViewFeature;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.net.InetSocketAddress;
+import java.net.Proxy;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.torproject.arti.ArtiProxy;
+
+import okhttp3.OkHttpClient;
+import okhttp3.Request;
+import okhttp3.Response;
+
+/**
+ * Process-wide controller for the optional Tor (arti) mode on Android.
+ *
+ * <p>When enabled, this starts a local SOCKS5 proxy backed by arti (Tor in
+ * Rust) and — via {@link ArtiProxy.ArtiProxyBuilder#setWrapWebView(boolean)} —
+ * installs an Android {@code ProxyController} override so that <em>all</em>
+ * Capacitor WebView traffic (every {@code fetch} and relay {@code WebSocket})
+ * is routed through Tor. No changes to the TypeScript HTTP layer are needed.
+ *
+ * <p>The enabled flag is persisted to {@link SharedPreferences} by
+ * {@link TorPlugin} and read here at startup from {@link MainActivity}, so arti
+ * auto-starts on a cold launch <em>before</em> the WebView loads — there is no
+ * pre-bootstrap leak window. Beyond that, activation is live: the settings
+ * toggle calls {@link #start}/{@link #stop} (bridged through {@link TorPlugin}),
+ * which start or stop arti immediately while also updating the persisted flag.
+ *
+ * <p>Pluggable transports (obfs4 via IPtProxy) are intentionally not wired up
+ * yet — the builder already exposes {@code setObfs4Port}/{@code setBridgeLines}
+ * for a future censorship-resistance layer.
+ */
+public class TorController {
+
+    private static final String TAG = "TorController";
+
+    /** Local SOCKS5 port arti listens on (arti's own default). */
+    public static final int SOCKS_PORT = 9150;
+
+    static final String PREFS_NAME = "tor_config";
+    static final String KEY_ENABLED = "enabled";
+
+    /** Endpoint used to confirm a working Tor circuit (small JSON response). */
+    private static final String PROBE_URL = "https://check.torproject.org/api/ip";
+    // Re-verify continuously (gently) so the status reflects current reality.
+    private static final long PROBE_INTERVAL_SECONDS = 10;
+    /** After this long without a successful probe, surface a soft "failed". */
+    private static final long SOFT_TIMEOUT_SECONDS = 120;
+
+    // Status values mirrored to JS (see src/lib/tor.ts TorStatus).
+    public static final String STATUS_DISABLED = "disabled";
+    public static final String STATUS_CONNECTING = "connecting";
+    public static final String STATUS_CONNECTED = "connected";
+    public static final String STATUS_FAILED = "failed";
+
+    /** Receives status changes so the Capacitor plugin can forward them to JS. */
+    public interface StatusListener {
+        void onTorStatus(String status, int bootstrapPercent, @Nullable String error, @Nullable String exitIp);
+    }
+
+    private static volatile TorController instance;
+
+    private final Object lock = new Object();
+    private final AtomicBoolean started = new AtomicBoolean(false);
+
+    private ArtiProxy artiProxy;
+    private ScheduledExecutorService scheduler;
+
+    private volatile String status = STATUS_DISABLED;
+    private volatile int bootstrapPercent = 0;
+    @Nullable private volatile String error = null;
+    /** Tor exit-node IP from the last successful check (for verification UI). */
+    @Nullable private volatile String exitIp = null;
+    /** Consecutive failed probes; used to debounce CONNECTED -> reconnecting. */
+    private int consecutiveFailures = 0;
+    @Nullable private volatile StatusListener listener;
+    private volatile long startedAtMs = 0;
+
+    private TorController() {}
+
+    public static TorController getInstance() {
+        if (instance == null) {
+            synchronized (TorController.class) {
+                if (instance == null) {
+                    instance = new TorController();
+                }
+            }
+        }
+        return instance;
+    }
+
+    /** Whether Tor is enabled in persisted preferences (read at cold-launch startup). */
+    public static boolean isEnabled(Context context) {
+        SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        return prefs.getBoolean(KEY_ENABLED, false);
+    }
+
+    /**
+     * Persist the enabled flag only. This controls whether arti auto-starts on
+     * the next cold launch; it does not start or stop arti now. For live
+     * activation call {@link #start}/{@link #stop}, which also persist the flag.
+     */
+    public static void setEnabled(Context context, boolean enabled) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit()
+                .putBoolean(KEY_ENABLED, enabled)
+                .apply();
+    }
+
+    public void setListener(@Nullable StatusListener listener) {
+        this.listener = listener;
+        // Replay the current status so a freshly-attached listener is in sync.
+        if (listener != null) {
+            listener.onTorStatus(status, bootstrapPercent, error, exitIp);
+        }
+    }
+
+    public String getStatus() {
+        return status;
+    }
+
+    public int getBootstrapPercent() {
+        return bootstrapPercent;
+    }
+
+    @Nullable
+    public String getError() {
+        return error;
+    }
+
+    @Nullable
+    public String getExitIp() {
+        return exitIp;
+    }
+
+    /**
+     * Start arti and install the WebView proxy override. Idempotent: a second
+     * call while already running is a no-op. Heavy work runs off the caller's
+     * thread so this is safe to invoke from {@code MainActivity.onCreate}.
+     */
+    public void start(Context context) {
+        if (!started.compareAndSet(false, true)) {
+            return;
+        }
+        final Context appContext = context.getApplicationContext();
+        exitIp = null;
+        consecutiveFailures = 0;
+        // Install the fail-closed WebView proxy override synchronously, BEFORE
+        // the WebView loads (start() is called from MainActivity.onCreate ahead
+        // of super.onCreate). With no direct fallback, any request that arti
+        // can't carry fails instead of leaking out directly — even during the
+        // bootstrap window when arti isn't connected yet.
+        applyWebViewProxy();
+        updateStatus(STATUS_CONNECTING, 0, null);
+        startedAtMs = System.currentTimeMillis();
+
+        Thread t = new Thread(() -> {
+            try {
+                synchronized (lock) {
+                    // NB: we do NOT use setWrapWebView(true) — arti's helper
+                    // appends a DIRECT fallback (fail-open). We set our own
+                    // fail-closed override in applyWebViewProxy() instead.
+                    artiProxy = ArtiProxy.Builder(appContext)
+                            .setSocksPort(SOCKS_PORT)
+                            .setLogListener(this::onArtiLog)
+                            .build();
+                    artiProxy.start();
+                }
+                Log.d(TAG, "arti started on socks://127.0.0.1:" + SOCKS_PORT);
+                beginConnectivityProbe();
+            } catch (Throwable e) {
+                Log.e(TAG, "Failed to start arti", e);
+                updateStatus(STATUS_FAILED, bootstrapPercent, String.valueOf(e.getMessage()));
+            }
+        }, "arti-start");
+        t.setDaemon(true);
+        t.start();
+    }
+
+    /** Stop arti and route the WebView back to a direct connection. Safe to
+     *  call live (toggle off) — clears the SOCKS proxy override so traffic
+     *  doesn't get stranded on the now-stopped proxy. */
+    public void stop() {
+        // Remove the WebView SOCKS override first so new requests go direct.
+        clearWebViewProxy();
+        synchronized (lock) {
+            if (scheduler != null) {
+                scheduler.shutdownNow();
+                scheduler = null;
+            }
+            if (artiProxy != null) {
+                try {
+                    artiProxy.stop();
+                } catch (Throwable e) {
+                    Log.w(TAG, "Error stopping arti", e);
+                }
+                artiProxy = null;
+            }
+        }
+        started.set(false);
+        exitIp = null;
+        updateStatus(STATUS_DISABLED, 0, null);
+    }
+
+    /** Re-run the connectivity probe (used by a "Retry" action in the gate). */
+    public void retry() {
+        if (!started.get()) {
+            return;
+        }
+        consecutiveFailures = 0;
+        startedAtMs = System.currentTimeMillis();
+        if (!STATUS_CONNECTED.equals(status)) {
+            updateStatus(STATUS_CONNECTING, bootstrapPercent, null);
+        }
+        beginConnectivityProbe();
+    }
+
+    // --- internals -------------------------------------------------------
+
+    /**
+     * Route the WebView through arti's SOCKS proxy, FAIL-CLOSED. There is no
+     * {@code addDirect()} fallback, so when Tor can't carry a request it fails
+     * rather than leaking to a direct connection. localhost is bypassed (it's
+     * the local Capacitor asset server, never remote traffic).
+     */
+    private void applyWebViewProxy() {
+        try {
+            if (WebViewFeature.isFeatureSupported(WebViewFeature.PROXY_OVERRIDE)) {
+                ProxyConfig config = new ProxyConfig.Builder()
+                        .addProxyRule("socks://127.0.0.1:" + SOCKS_PORT)
+                        // No addDirect() — fail closed.
+                        .addBypassRule("localhost")
+                        .addBypassRule("127.0.0.1")
+                        .build();
+                ProxyController.getInstance().setProxyOverride(config, Runnable::run, () -> {});
+            }
+        } catch (Throwable e) {
+            Log.w(TAG, "Error applying WebView proxy override", e);
+        }
+    }
+
+    /** Remove the app-wide WebView SOCKS proxy override so the WebView reverts
+     *  to a direct connection. */
+    private void clearWebViewProxy() {
+        try {
+            if (WebViewFeature.isFeatureSupported(WebViewFeature.PROXY_OVERRIDE)) {
+                ProxyController.getInstance().clearProxyOverride(Runnable::run, () -> {});
+            }
+        } catch (Throwable e) {
+            Log.w(TAG, "Error clearing WebView proxy override", e);
+        }
+    }
+
+    private static final Pattern PERCENT = Pattern.compile("(\\d{1,3})\\s*%");
+
+    private void onArtiLog(String line) {
+        if (line == null) return;
+        Log.d("artilog", line);
+        // Best-effort bootstrap progress for the UI. arti's log format isn't a
+        // stable API, so the connectivity probe (below) remains authoritative
+        // for the definitive "connected" signal.
+        Matcher m = PERCENT.matcher(line);
+        if (m.find()) {
+            try {
+                int pct = Integer.parseInt(m.group(1));
+                if (pct >= 0 && pct <= 100 && pct >= bootstrapPercent
+                        && !STATUS_CONNECTED.equals(status)) {
+                    updateStatus(STATUS_CONNECTING, pct, null);
+                }
+            } catch (NumberFormatException ignored) {
+            }
+        }
+    }
+
+    private void beginConnectivityProbe() {
+        synchronized (lock) {
+            if (scheduler != null) {
+                scheduler.shutdownNow();
+            }
+            scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
+                Thread th = new Thread(r, "tor-probe");
+                th.setDaemon(true);
+                return th;
+            });
+            final ScheduledExecutorService s = scheduler;
+            final OkHttpClient client = new OkHttpClient.Builder()
+                    .proxy(new Proxy(Proxy.Type.SOCKS, new InetSocketAddress("127.0.0.1", SOCKS_PORT)))
+                    .connectTimeout(20, TimeUnit.SECONDS)
+                    .readTimeout(20, TimeUnit.SECONDS)
+                    .build();
+
+            // Probe continuously (no shutdown on success). check.torproject.org
+            // reports whether the request actually exited via Tor, so we only
+            // report CONNECTED when IsTor is true — and we keep re-verifying so a
+            // dropped circuit downgrades the status instead of lying.
+            s.scheduleWithFixedDelay(() -> {
+                Request req = new Request.Builder()
+                        .url(PROBE_URL)
+                        .header("Accept", "application/json")
+                        .build();
+                try (Response resp = client.newCall(req).execute()) {
+                    String body = resp.body() != null ? resp.body().string() : "";
+                    boolean isTor = false;
+                    String ip = null;
+                    try {
+                        JSONObject json = new JSONObject(body);
+                        isTor = json.optBoolean("IsTor", false);
+                        ip = json.has("IP") ? json.optString("IP", null) : null;
+                    } catch (JSONException ignored) {
+                        // Non-JSON response — treat as not-via-Tor below.
+                    }
+
+                    if (resp.isSuccessful() && isTor) {
+                        consecutiveFailures = 0;
+                        exitIp = ip;
+                        updateStatus(STATUS_CONNECTED, 100, null);
+                    } else if (resp.isSuccessful()) {
+                        // Reached the internet but NOT through Tor — a leak/bypass.
+                        // This should not happen with the SOCKS proxy, but report
+                        // it honestly rather than claiming a Tor connection.
+                        consecutiveFailures = 0;
+                        exitIp = ip;
+                        updateStatus(STATUS_FAILED, bootstrapPercent,
+                                "Connected to the internet, but not through Tor.");
+                    } else {
+                        handleProbeFailure();
+                    }
+                } catch (Exception e) {
+                    handleProbeFailure();
+                }
+            }, 0, PROBE_INTERVAL_SECONDS, TimeUnit.SECONDS);
+        }
+    }
+
+    /** A probe couldn't reach Tor. Debounce CONNECTED, surface FAILED after the
+     *  soft timeout while still connecting. */
+    private void handleProbeFailure() {
+        consecutiveFailures++;
+        if (STATUS_CONNECTED.equals(status)) {
+            // Tolerate a couple of transient blips before downgrading.
+            if (consecutiveFailures >= 3) {
+                exitIp = null;
+                updateStatus(STATUS_CONNECTING, bootstrapPercent,
+                        "Lost the Tor circuit; reconnecting…");
+            }
+            return;
+        }
+        long elapsed = (System.currentTimeMillis() - startedAtMs) / 1000;
+        if (elapsed >= SOFT_TIMEOUT_SECONDS && !STATUS_FAILED.equals(status)) {
+            updateStatus(STATUS_FAILED, bootstrapPercent,
+                    "Couldn't reach the Tor network. Your network may be blocking Tor.");
+        }
+    }
+
+    private void updateStatus(String newStatus, int percent, @Nullable String err) {
+        this.status = newStatus;
+        this.bootstrapPercent = percent;
+        this.error = err;
+        StatusListener l = this.listener;
+        if (l != null) {
+            l.onTorStatus(newStatus, percent, err, exitIp);
+        }
+    }
+}

android/app/src/main/java/fund/eranos/app/TorPlugin.java

@@ -0,0 +1,102 @@
+package fund.eranos.app;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+/**
+ * Capacitor bridge for the Tor (arti) mode.
+ *
+ * <p>Mirrors {@link DittoNotificationPlugin}'s pattern: JS configures native
+ * state, native owns the work. On a cold launch arti auto-starts from
+ * {@link MainActivity} based on the persisted flag. At runtime the settings
+ * toggle activates Tor live via {@link #start}/{@link #stop}, which start or
+ * stop arti immediately and update the persisted flag. ({@link #setEnabled}
+ * persists the flag only, without touching the running proxy.) Live bootstrap
+ * status is pushed to JS via the {@code torStatus} event.
+ *
+ * <p>JS interface: see {@code src/lib/tor.ts}.
+ */
+@CapacitorPlugin(name = "Tor")
+public class TorPlugin extends Plugin {
+
+    private static final String EVENT_STATUS = "torStatus";
+
+    @Override
+    public void load() {
+        // Forward native status changes to JS listeners. Attaching also replays
+        // the current status, keeping a newly-mounted JS gate in sync.
+        TorController.getInstance().setListener((status, bootstrapPercent, error, exitIp) -> {
+            JSObject data = new JSObject();
+            data.put("status", status);
+            data.put("bootstrapPercent", bootstrapPercent);
+            data.put("error", error);
+            data.put("exitIp", exitIp);
+            notifyListeners(EVENT_STATUS, data);
+        });
+    }
+
+    /** Whether Tor is enabled in persisted preferences. */
+    @PluginMethod
+    public void isEnabled(PluginCall call) {
+        JSObject ret = new JSObject();
+        ret.put("enabled", TorController.isEnabled(getContext()));
+        call.resolve(ret);
+    }
+
+    /**
+     * Persist the enabled flag only, without starting or stopping arti now.
+     * Controls whether arti auto-starts on the next cold launch. For live
+     * activation use {@link #start}/{@link #stop}.
+     */
+    @PluginMethod
+    public void setEnabled(PluginCall call) {
+        Boolean enabled = call.getBoolean("enabled");
+        if (enabled == null) {
+            call.reject("Missing 'enabled' boolean");
+            return;
+        }
+        TorController.setEnabled(getContext(), enabled);
+        call.resolve();
+    }
+
+    /** Start arti now (live activation). Also persists enabled=true so it
+     *  auto-starts on the next cold launch. */
+    @PluginMethod
+    public void start(PluginCall call) {
+        TorController.setEnabled(getContext(), true);
+        TorController.getInstance().start(getContext());
+        call.resolve();
+    }
+
+    /** Stop arti now (live deactivation) and clear the WebView proxy. Also
+     *  persists enabled=false. */
+    @PluginMethod
+    public void stop(PluginCall call) {
+        TorController.setEnabled(getContext(), false);
+        TorController.getInstance().stop();
+        call.resolve();
+    }
+
+    /** Current connection status (synchronous snapshot). */
+    @PluginMethod
+    public void getStatus(PluginCall call) {
+        TorController controller = TorController.getInstance();
+        JSObject ret = new JSObject();
+        ret.put("enabled", TorController.isEnabled(getContext()));
+        ret.put("status", controller.getStatus());
+        ret.put("bootstrapPercent", controller.getBootstrapPercent());
+        ret.put("error", controller.getError());
+        ret.put("exitIp", controller.getExitIp());
+        call.resolve(ret);
+    }
+
+    /** Re-run the connectivity probe (for a "Retry" action in the gate). */
+    @PluginMethod
+    public void retry(PluginCall call) {
+        TorController.getInstance().retry();
+        call.resolve();
+    }
+}

android/app/src/main/java/pub/ditto/app/SandboxPlugin.java

@@ -1,552 +0,0 @@
-package pub.ditto.app;
-
-import android.graphics.Color;
-import android.graphics.PorterDuff;
-import android.os.Handler;
-import android.os.Looper;
-import android.util.Base64;
-import android.util.Log;
-import android.view.Gravity;
-import android.view.View;
-import android.view.ViewGroup;
-import android.webkit.JavascriptInterface;
-import android.webkit.WebResourceRequest;
-import android.webkit.WebResourceResponse;
-import android.webkit.WebSettings;
-import android.webkit.WebView;
-import android.webkit.WebViewClient;
-import android.widget.FrameLayout;
-import android.widget.ProgressBar;
-import androidx.coordinatorlayout.widget.CoordinatorLayout;
-
-import com.getcapacitor.JSObject;
-import com.getcapacitor.Plugin;
-import com.getcapacitor.PluginCall;
-import com.getcapacitor.PluginMethod;
-import com.getcapacitor.annotation.CapacitorPlugin;
-
-import org.json.JSONException;
-import org.json.JSONObject;
-
-import java.io.ByteArrayInputStream;
-import java.io.InputStream;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.UUID;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.CountDownLatch;
-import java.util.concurrent.TimeUnit;
-
-/**
- * Capacitor plugin that creates isolated Android WebViews for sandboxed content.
- *
- * Each sandbox uses shouldInterceptRequest to intercept all requests and forward
- * them to the JS layer as fetch events — the same protocol iframe.diy uses.
- * The React code can serve files identically regardless of platform.
- */
-@CapacitorPlugin(name = "SandboxPlugin")
-public class SandboxPlugin extends Plugin {
-
-    private static final String TAG = "SandboxPlugin";
-    private final Map<String, SandboxInstance> sandboxes = new HashMap<>();
-    private final Handler mainHandler = new Handler(Looper.getMainLooper());
-
-    @PluginMethod
-    public void create(PluginCall call) {
-        String sandboxId = call.getString("id");
-        if (sandboxId == null) {
-            call.reject("Missing required parameter: id");
-            return;
-        }
-
-        JSObject frame = call.getObject("frame");
-        if (frame == null) {
-            call.reject("Missing required parameter: frame");
-            return;
-        }
-
-        int x = frame.optInt("x", 0);
-        int y = frame.optInt("y", 0);
-        int width = frame.optInt("width", 0);
-        int height = frame.optInt("height", 0);
-
-        if (sandboxes.containsKey(sandboxId)) {
-            call.reject("Sandbox already exists: " + sandboxId);
-            return;
-        }
-
-        float density = getActivity().getResources().getDisplayMetrics().density;
-        int pxX = Math.round(x * density);
-        int pxY = Math.round(y * density);
-        int pxWidth = Math.round(width * density);
-        int pxHeight = Math.round(height * density);
-
-        mainHandler.post(() -> {
-            SandboxInstance sandbox = new SandboxInstance(sandboxId, this);
-            sandboxes.put(sandboxId, sandbox);
-
-            // Add the container (WebView + spinner overlay) on top of the
-            // Capacitor WebView. The parent is a CoordinatorLayout — using
-            // the wrong LayoutParams type causes a ClassCastException when
-            // it intercepts touch events.
-            View capWebView = getBridge().getWebView();
-            ViewGroup parent = (ViewGroup) capWebView.getParent();
-            CoordinatorLayout.LayoutParams params = new CoordinatorLayout.LayoutParams(pxWidth, pxHeight);
-            params.leftMargin = pxX;
-            params.topMargin = pxY;
-            parent.addView(sandbox.container, params);
-
-            // The spinner is now visible. Navigation is deferred until the
-            // JS layer calls navigate() — this allows the caller to
-            // pre-fetch blobs while the spinner animates.
-
-            call.resolve();
-        });
-    }
-
-    @PluginMethod
-    public void navigate(PluginCall call) {
-        String sandboxId = call.getString("id");
-        if (sandboxId == null) {
-            call.reject("Missing required parameter: id");
-            return;
-        }
-
-        mainHandler.post(() -> {
-            SandboxInstance sandbox = sandboxes.get(sandboxId);
-            if (sandbox == null) {
-                call.reject("Sandbox not found: " + sandboxId);
-                return;
-            }
-
-            sandbox.webView.loadUrl("https://" + sandboxId + ".sandbox.native/index.html");
-            call.resolve();
-        });
-    }
-
-    @PluginMethod
-    public void updateFrame(PluginCall call) {
-        String sandboxId = call.getString("id");
-        if (sandboxId == null) {
-            call.reject("Missing required parameter: id");
-            return;
-        }
-
-        JSObject frame = call.getObject("frame");
-        if (frame == null) {
-            call.reject("Missing required parameter: frame");
-            return;
-        }
-
-        int x = frame.optInt("x", 0);
-        int y = frame.optInt("y", 0);
-        int width = frame.optInt("width", 0);
-        int height = frame.optInt("height", 0);
-
-        float density = getActivity().getResources().getDisplayMetrics().density;
-        int pxX = Math.round(x * density);
-        int pxY = Math.round(y * density);
-        int pxWidth = Math.round(width * density);
-        int pxHeight = Math.round(height * density);
-
-        mainHandler.post(() -> {
-            SandboxInstance sandbox = sandboxes.get(sandboxId);
-            if (sandbox == null) {
-                call.reject("Sandbox not found: " + sandboxId);
-                return;
-            }
-
-            CoordinatorLayout.LayoutParams params = new CoordinatorLayout.LayoutParams(pxWidth, pxHeight);
-            params.leftMargin = pxX;
-            params.topMargin = pxY;
-            sandbox.container.setLayoutParams(params);
-
-            call.resolve();
-        });
-    }
-
-    @PluginMethod
-    public void respondToFetch(PluginCall call) {
-        String sandboxId = call.getString("id");
-        if (sandboxId == null) {
-            call.reject("Missing required parameter: id");
-            return;
-        }
-        String requestId = call.getString("requestId");
-        if (requestId == null) {
-            call.reject("Missing required parameter: requestId");
-            return;
-        }
-        JSObject response = call.getObject("response");
-        if (response == null) {
-            call.reject("Missing required parameter: response");
-            return;
-        }
-
-        SandboxInstance sandbox = sandboxes.get(sandboxId);
-        if (sandbox == null) {
-            call.reject("Sandbox not found: " + sandboxId);
-            return;
-        }
-
-        int status = response.optInt("status", 200);
-        String statusText = response.optString("statusText", "OK");
-        String bodyBase64 = response.optString("body", null);
-
-        Map<String, String> headers = new HashMap<>();
-        JSONObject headersObj = response.optJSONObject("headers");
-        if (headersObj != null) {
-            for (java.util.Iterator<String> it = headersObj.keys(); it.hasNext(); ) {
-                String key = it.next();
-                headers.put(key, headersObj.optString(key));
-            }
-        }
-
-        sandbox.resolveRequest(requestId, status, statusText, headers, bodyBase64);
-
-        call.resolve();
-    }
-
-    @PluginMethod
-    public void postMessage(PluginCall call) {
-        String sandboxId = call.getString("id");
-        if (sandboxId == null) {
-            call.reject("Missing required parameter: id");
-            return;
-        }
-        JSObject message = call.getObject("message");
-        if (message == null) {
-            call.reject("Missing required parameter: message");
-            return;
-        }
-
-        SandboxInstance sandbox = sandboxes.get(sandboxId);
-        if (sandbox == null) {
-            call.reject("Sandbox not found: " + sandboxId);
-            return;
-        }
-
-        mainHandler.post(() -> sandbox.postMessageToWebView(message.toString()));
-
-        call.resolve();
-    }
-
-    @PluginMethod
-    public void destroy(PluginCall call) {
-        String sandboxId = call.getString("id");
-        if (sandboxId == null) {
-            call.reject("Missing required parameter: id");
-            return;
-        }
-
-        mainHandler.post(() -> {
-            SandboxInstance sandbox = sandboxes.remove(sandboxId);
-            if (sandbox != null) {
-                ViewGroup parent = (ViewGroup) sandbox.container.getParent();
-                if (parent != null) {
-                    parent.removeView(sandbox.container);
-                }
-                sandbox.webView.destroy();
-            }
-            call.resolve();
-        });
-    }
-
-    void emitFetchRequest(String sandboxId, String requestId, JSObject request) {
-        JSObject data = new JSObject();
-        data.put("id", sandboxId);
-        data.put("requestId", requestId);
-        data.put("request", request);
-        notifyListeners("fetch", data);
-    }
-
-    void emitScriptMessage(String sandboxId, JSObject message) {
-        JSObject data = new JSObject();
-        data.put("id", sandboxId);
-        data.put("message", message);
-        notifyListeners("scriptMessage", data);
-    }
-
-    /**
-     * A single sandboxed WebView instance.
-     */
-    private static class SandboxInstance {
-        final String id;
-        /** Wrapper layout that holds the WebView and the loading overlay. */
-        final FrameLayout container;
-        final WebView webView;
-        final SandboxPlugin plugin;
-        private final ConcurrentHashMap<String, PendingRequest> pendingRequests = new ConcurrentHashMap<>();
-        /** Native spinner overlay, shown while the sandbox content loads. */
-        private ProgressBar spinner;
-
-        SandboxInstance(String id, SandboxPlugin plugin) {
-            this.id = id;
-            this.plugin = plugin;
-
-            this.container = new FrameLayout(plugin.getActivity());
-            this.webView = new WebView(plugin.getActivity());
-
-            WebSettings settings = webView.getSettings();
-            settings.setJavaScriptEnabled(true);
-            settings.setDomStorageEnabled(true);
-            settings.setAllowFileAccess(false);
-            settings.setAllowContentAccess(false);
-            settings.setDatabaseEnabled(true);
-
-            webView.setBackgroundColor(Color.parseColor("#14161f"));
-
-            // Add JavaScript interface for script->native communication.
-            webView.addJavascriptInterface(new SandboxBridge(this), "__sandboxNative");
-
-            // Inject the bridge script and intercept requests.
-            webView.setWebViewClient(new SandboxWebViewClient(this));
-
-            // Build the container: WebView fills it, spinner overlays on top.
-            container.addView(webView, new FrameLayout.LayoutParams(
-                    ViewGroup.LayoutParams.MATCH_PARENT,
-                    ViewGroup.LayoutParams.MATCH_PARENT));
-
-            // Native spinner overlay — uses the Android indeterminate
-            // ProgressBar which animates on the render thread, so it keeps
-            // spinning even when the main/IO threads are busy.
-            spinner = new ProgressBar(plugin.getActivity());
-            spinner.setIndeterminate(true);
-            spinner.getIndeterminateDrawable().setColorFilter(
-                    Color.parseColor("#7c5cdc"), PorterDuff.Mode.SRC_IN);
-            FrameLayout.LayoutParams spinnerParams = new FrameLayout.LayoutParams(
-                    dpToPx(plugin, 32), dpToPx(plugin, 32), Gravity.CENTER);
-            container.addView(spinner, spinnerParams);
-
-            // Dark background behind the spinner.
-            View overlay = new View(plugin.getActivity());
-            overlay.setBackgroundColor(Color.parseColor("#14161f"));
-            // Insert the overlay between the WebView (index 0) and spinner (index 1)
-            // so it covers the WebView but sits behind the spinner.
-            container.addView(overlay, 1, new FrameLayout.LayoutParams(
-                    ViewGroup.LayoutParams.MATCH_PARENT,
-                    ViewGroup.LayoutParams.MATCH_PARENT));
-        }
-
-        /** Remove the native loading overlay. Safe to call multiple times. */
-        void hideSpinner() {
-            if (spinner != null) {
-                // Remove spinner and overlay (indices 2 and 1 after WebView at 0).
-                if (container.getChildCount() > 2) container.removeViewAt(2); // spinner
-                if (container.getChildCount() > 1) container.removeViewAt(1); // overlay
-                spinner = null;
-            }
-        }
-
-        private static int dpToPx(SandboxPlugin plugin, int dp) {
-            float density = plugin.getActivity().getResources().getDisplayMetrics().density;
-            return Math.round(dp * density);
-        }
-
-        void postMessageToWebView(String jsonString) {
-            String js = "(function() { " +
-                    "if (window.__sandboxBridge && window.__sandboxBridge.onMessage) { " +
-                    "window.__sandboxBridge.onMessage(" + jsonString + "); " +
-                    "} " +
-                    "})();";
-            webView.evaluateJavascript(js, null);
-        }
-
-        void resolveRequest(String requestId, int status, String statusText,
-                            Map<String, String> headers, String bodyBase64) {
-            PendingRequest pending = pendingRequests.remove(requestId);
-            if (pending == null) return;
-
-            byte[] bodyBytes = null;
-            if (bodyBase64 != null && !bodyBase64.equals("null")) {
-                try {
-                    bodyBytes = Base64.decode(bodyBase64, Base64.DEFAULT);
-                } catch (Exception e) {
-                    Log.w(TAG, "Base64 decode failed for request " + requestId, e);
-                }
-            }
-
-            String contentType = headers.getOrDefault("Content-Type", "application/octet-stream");
-            String encoding = contentType.contains("text/") ? "UTF-8" : null;
-
-            InputStream body = bodyBytes != null
-                    ? new ByteArrayInputStream(bodyBytes)
-                    : new ByteArrayInputStream(new byte[0]);
-
-            WebResourceResponse response = new WebResourceResponse(
-                    contentType, encoding, status, statusText, headers, body
-            );
-
-            pending.resolve(response);
-        }
-    }
-
-    /**
-     * WebViewClient that intercepts all requests and forwards them to JS.
-     */
-    private static class SandboxWebViewClient extends WebViewClient {
-        private final SandboxInstance sandbox;
-        private boolean bridgeInjected = false;
-
-        SandboxWebViewClient(SandboxInstance sandbox) {
-            this.sandbox = sandbox;
-        }
-
-        @Override
-        public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
-            String url = request.getUrl().toString();
-
-            // Only intercept requests to the sandbox domain.
-            if (!url.contains(".sandbox.native")) {
-                return null;
-            }
-
-            String requestId = UUID.randomUUID().toString();
-
-            // Create a pending request with a blocking latch.
-            PendingRequest pending = new PendingRequest();
-            sandbox.pendingRequests.put(requestId, pending);
-
-            // Rewrite URL to include the sandbox ID for the JS handler.
-            String path = request.getUrl().getPath();
-            if (path == null || path.isEmpty()) path = "/";
-            String rewrittenURL = "https://" + sandbox.id + ".sandbox.native" + path;
-
-            // Serialise the request.
-            JSObject serialisedRequest = new JSObject();
-            serialisedRequest.put("url", rewrittenURL);
-            serialisedRequest.put("method", request.getMethod());
-
-            JSObject headers = new JSObject();
-            for (Map.Entry<String, String> entry : request.getRequestHeaders().entrySet()) {
-                headers.put(entry.getKey(), entry.getValue());
-            }
-            serialisedRequest.put("headers", headers);
-            serialisedRequest.put("body", JSONObject.NULL);
-
-            // Emit to JS.
-            sandbox.plugin.emitFetchRequest(sandbox.id, requestId, serialisedRequest);
-
-            // Block until JS responds. Each asset is fetched from a Blossom
-            // server over the network, so we need a generous timeout.  The
-            // WebView IO thread pool has ~6 threads; if all are blocked,
-            // subsequent requests queue until a thread frees up.
-            WebResourceResponse response = pending.awaitResponse(60000);
-
-            if (response != null) {
-                return response;
-            }
-
-            // Timeout — return error response.
-            sandbox.pendingRequests.remove(requestId);
-            return new WebResourceResponse(
-                    "text/plain", "UTF-8", 504,
-                    "Gateway Timeout", new HashMap<>(),
-                    new ByteArrayInputStream("Request timed out".getBytes())
-            );
-        }
-
-        @Override
-        public void onPageFinished(WebView view, String url) {
-            super.onPageFinished(view, url);
-
-            if (!bridgeInjected) {
-                bridgeInjected = true;
-                view.evaluateJavascript(getBridgeScript(), null);
-            }
-
-            // Remove the native spinner once the first page has finished
-            // loading (all initial resources resolved). This runs on the
-            // main thread, so the removal is safe.
-            sandbox.hideSpinner();
-        }
-
-        private String getBridgeScript() {
-            return "(function() {" +
-                    "'use strict';" +
-                    "var messageListeners = [];" +
-                    "window.__sandboxBridge = {" +
-                    "  onMessage: function(data) {" +
-                    "    var event = {" +
-                    "      data: data," +
-                    "      origin: 'https://" + sandbox.id + ".sandbox.native'," +
-                    "      source: window.parent," +
-                    "      type: 'message'" +
-                    "    };" +
-                    "    for (var i = 0; i < messageListeners.length; i++) {" +
-                    "      try { messageListeners[i](event); } catch(e) {}" +
-                    "    }" +
-                    "  }" +
-                    "};" +
-                    "var origAdd = window.addEventListener;" +
-                    "window.addEventListener = function(type, fn, opts) {" +
-                    "  if (type === 'message' && typeof fn === 'function') messageListeners.push(fn);" +
-                    "  return origAdd.call(window, type, fn, opts);" +
-                    "};" +
-                    "var origRemove = window.removeEventListener;" +
-                    "window.removeEventListener = function(type, fn, opts) {" +
-                    "  if (type === 'message') {" +
-                    "    var idx = messageListeners.indexOf(fn);" +
-                    "    if (idx !== -1) messageListeners.splice(idx, 1);" +
-                    "  }" +
-                    "  return origRemove.call(window, type, fn, opts);" +
-                    "};" +
-                    "if (!window.parent || window.parent === window) window.parent = {};" +
-                    "window.parent.postMessage = function(data) {" +
-                    "  if (data && typeof data === 'object' && data.jsonrpc === '2.0') {" +
-                    "    try { window.__sandboxNative.postMessage(JSON.stringify(data)); } catch(e) {}" +
-                    "  }" +
-                    "};" +
-                    "})();";
-        }
-    }
-
-    /**
-     * JavaScript interface exposed to the sandbox WebView.
-     */
-    private static class SandboxBridge {
-        private final SandboxInstance sandbox;
-
-        SandboxBridge(SandboxInstance sandbox) {
-            this.sandbox = sandbox;
-        }
-
-        @JavascriptInterface
-        public void postMessage(String json) {
-            try {
-                JSONObject obj = new JSONObject(json);
-                JSObject jsObj = new JSObject();
-                for (java.util.Iterator<String> it = obj.keys(); it.hasNext(); ) {
-                    String key = it.next();
-                    jsObj.put(key, obj.get(key));
-                }
-                sandbox.plugin.emitScriptMessage(sandbox.id, jsObj);
-            } catch (JSONException e) {
-                Log.w(TAG, "Failed to parse script message", e);
-            }
-        }
-    }
-
-    /**
-     * A pending request that blocks the WebViewClient IO thread until JS
-     * responds with the complete resource.
-     */
-    private static class PendingRequest {
-        private volatile WebResourceResponse response;
-        private final CountDownLatch latch = new CountDownLatch(1);
-
-        void resolve(WebResourceResponse response) {
-            this.response = response;
-            latch.countDown();
-        }
-
-        WebResourceResponse awaitResponse(long timeoutMs) {
-            try {
-                latch.await(timeoutMs, TimeUnit.MILLISECONDS);
-            } catch (InterruptedException e) {
-                Thread.currentThread().interrupt();
-            }
-            return response;
-        }
-    }
-}

android/app/src/main/res/drawable-v24/ic_launcher_foreground.xml

@@ -1,50 +0,0 @@
-<vector xmlns:android="http://schemas.android.com/apk/res/android"
-    android:width="108dp"
-    android:height="108dp"
-    android:viewportWidth="100"
-    android:viewportHeight="100">
-
-    <!--
-      Ditto logo from public/logo.svg.
-      SVG viewBox is "-5 -10 100 100", so we shift all paths by (+5, +10)
-      to place the origin at (0,0) for the 100x100 viewport.
-      Then scale to 60% around the content center (50, 40) to fit within
-      Android's adaptive icon safe zone (66% of 108dp).
-    -->
-
-    <group
-        android:translateX="5"
-        android:translateY="10"
-        android:scaleX="0.7"
-        android:scaleY="0.7"
-        android:pivotX="50"
-        android:pivotY="40">
-
-        <!-- path1: bottom arc / bottom-right swash -->
-        <path
-            android:fillColor="#FFFFFF"
-            android:pathData="m 71.719615,49.36907 -0.62891,0.37109 c -0.12891,0.07031 -0.26172,0.14844 -0.39062,0.21875 -3.9883,10.309 -14.008,17.617 -25.699,17.617 -4.1211,0 -8.0312,-0.89844 -11.539,-2.5391 -0.12891,0.03906 -0.26172,0.07031 -0.39063,0.10156 l -0.35156,0.08984 h -0.02734 l -0.25,0.05859 -0.07813,0.01953 -0.10938,0.03125 c -0.55859,0.12891 -1.1289,0.26172 -1.6992,0.39062 -0.10156,0.03125 -0.19922,0.05078 -0.30078,0.07031 l -0.30078,0.10156 -0.18359,0.0078 c -0.26953,0.05859 -1.3086,0.26953 -1.3086,0.26953 -0.28906,0.05859 -0.55859,0.10937 -0.82813,0.17187 4.9805,3.3086 10.961,5.2305 17.371,5.2305 15.059,0 27.699,-10.602 30.828,-24.738 -0.75,0.48828 -1.5195,0.96875 -2.2891,1.4414 -0.59375,0.36328 -1.2031,0.72656 -1.8242,1.0859 z" />
-
-        <!-- path2: small left accent dot/arc -->
-        <path
-            android:fillColor="#FFFFFF"
-            android:pathData="m 30.926615,29.47807 c 0.36328,-0.48828 0.75,-0.95312 1.1523,-1.3828 0.75781,-0.80469 0.71484,-2.0703 -0.08984,-2.8281 -0.80469,-0.75781 -2.0703,-0.71484 -2.8281,0.08984 -0.50781,0.53906 -0.99219,1.125 -1.4492,1.7383 -0.65625,0.88672 -0.47266,2.1406 0.41406,2.7969 0.35938,0.26562 0.77344,0.39453 1.1875,0.39453 0.61719,0 1.2227,-0.27734 1.6133,-0.80859 z" />
-
-        <!-- path3: left vertical bar -->
-        <path
-            android:fillColor="#FFFFFF"
-            android:pathData="m 26.742615,32.67807 c -1.0586,-0.3125 -2.1719,0.29687 -2.4805,1.3594 -0.55859,1.9062 -0.83984,3.9141 -0.83984,5.9609 0,2.3789 0.39062,4.7227 1.1602,6.9609 0.28516,0.82812 1.0625,1.3516 1.8906,1.3516 0.21484,0 0.43359,-0.03516 0.64844,-0.10938 1.043,-0.35938 1.6016,-1.4961 1.2422,-2.543 -0.625,-1.8203 -0.94141,-3.7227 -0.94141,-5.6602 0,-1.668 0.22656,-3.2969 0.67969,-4.8398 0.30859,-1.0586 -0.30078,-2.168 -1.3594,-2.4805 z" />
-
-        <!-- path4: main ring arc -->
-        <path
-            android:fillColor="#FFFFFF"
-            android:pathData="m 14.691615,48.83807 c 0.10156,0.33984 0.19922,0.67969 0.32812,1.0195 0.42969,1.3516 0.94922,2.6484 1.5781,3.9102 0.10156,-0.01172 0.21094,-0.01172 0.32031,-0.01953 l 0.16016,-0.01172 0.80078,-0.07031 c 0.37109,-0.03906 0.67188,-0.07031 0.98047,-0.10156 0.51172,-0.05859 1.0195,-0.12109 1.5586,-0.19922 l 0.21875,-0.03125 c 0.07031,-0.01172 0.14062,-0.01953 0.21094,-0.03125 -1.2188,-2.2109 -2.1484,-4.6016 -2.7305,-7.1211 -0.16016,-0.71094 -0.30078,-1.4297 -0.39844,-2.1602 -0.19922,-1.3086 -0.30078,-2.6602 -0.30078,-4.0312 0,-0.89844 0.03906,-1.7812 0.12891,-2.6484 0.07031,-0.71094 0.16016,-1.4102 0.28906,-2.1016 2.25,-12.949 13.57,-22.828 27.16,-22.828 6.0508,0 11.648,1.9609 16.211,5.3008 0.57031,0.41016 1.1289,0.85938 1.6719,1.3203 1.6914,1.4219 3.2109,3.0703 4.5,4.8789 0.42969,0.60156 0.83984,1.2109 1.2188,1.8398 1.3203,2.1602 2.3398,4.5117 3.0195,7 0.23828,-0.17188 0.42969,-0.30859 0.62891,-0.46875 0.64844,-0.48047 1.2109,-0.92188 1.7383,-1.3398 0.28125,-0.23047 0.5,-0.41016 0.71094,-0.57812 0.10156,-0.07813 0.19141,-0.16016 0.28125,-0.23828 -0.42969,-1.3516 -0.96094,-2.6484 -1.5898,-3.8984 -0.14062,-0.32812 -0.30859,-0.64844 -0.48047,-0.96875 -0.32812,-0.64844 -0.69922,-1.2891 -1.0898,-1.9102 -1.6797,-2.7109 -3.7695,-5.1406 -6.1719,-7.2188 -0.57031,-0.48828 -1.1484,-0.96875 -1.7617,-1.4102 -0.55859,-0.42188 -1.1406,-0.82812 -1.7305,-1.2109 -4.9414,-3.2188 -10.852,-5.0898 -17.16,-5.0898 -14.961,0 -27.531,10.469 -30.75,24.469 -0.17188,0.67969 -0.30859,1.3711 -0.42188,2.0703 -0.12891,0.73828 -0.21875,1.5 -0.28906,2.2617 -0.07813,0.91016 -0.12109,1.8398 -0.12109,2.7812 0,2.3008 0.25,4.5508 0.71875,6.7109 0.17188,0.71484 0.35156,1.4258 0.5625,2.125 z" />
-
-        <!-- path5: top-right swash / outer arc with tail -->
-        <path
-            android:fillColor="#FFFFFF"
-            android:pathData="m 90.441615,21.60007 c -2.1797,-5.3398 -9.4102,-7.3984 -21,-6.0391 1.8906,1.8906 3.5391,3.9688 4.9297,6.2109 0.28906,0.46094 0.55859,0.92187 0.80859,1.3789 5.5391,-0.12109 7.6094,1.0391 7.8398,1.4492 0.12891,0.46875 -0.55078,2.7305 -4.5898,6.4805 -0.01953,0.01953 -0.03125,0.03125 -0.03906,0.03906 -0.26172,0.23828 -0.51953,0.48047 -0.80078,0.71875 -0.19922,0.17969 -0.41016,0.35938 -0.62891,0.53906 -0.10938,0.10156 -0.21875,0.19141 -0.33984,0.28906 -0.23828,0.19922 -0.5,0.41016 -0.76172,0.62109 -0.12891,0.10156 -0.26172,0.21094 -0.39844,0.32031 -0.42969,0.33984 -0.89063,0.69141 -1.3711,1.0508 -0.26953,0.21094 -0.53906,0.41016 -0.82812,0.60938 -0.32031,0.23047 -0.64062,0.46875 -0.98047,0.69922 0,0.01172 -0.01172,0.01172 -0.01172,0.01172 -0.26953,0.19141 -0.55078,0.37891 -0.82812,0.57031 -0.28125,0.19141 -0.55859,0.37109 -0.85156,0.55859 -0.25,0.16016 -0.5,0.32812 -0.76172,0.48828 -6,3.8984 -13.48,7.7188 -21.379,10.922 -8.0117,3.2383 -15.871,5.6602 -22.93,7.0391 -0.30078,0.05859 -0.60156,0.12109 -0.89062,0.17188 -0.60938,0.12109 -1.2188,0.21875 -1.8203,0.32031 -0.07031,0.01172 -0.12891,0.01953 -0.19922,0.03125 h -0.01953 c -0.28906,0.05078 -0.57031,0.08984 -0.83984,0.12891 -0.30859,0.05078 -0.60938,0.08984 -0.91016,0.12891 -0.57031,0.07813 -1.1094,0.14844 -1.6406,0.21094 -0.35156,0.03906 -0.69141,0.07031 -1.0195,0.10156 -0.30078,0.03125 -0.58984,0.05078 -0.87891,0.07813 -0.48047,0.03125 -0.92969,0.05859 -1.3711,0.07813 -0.39844,0.01953 -0.78125,0.03125 -1.1484,0.03906 -5.5116996,0.10938 -7.5702996,-1.0391 -7.8007996,-1.4492 -0.12891,-0.48047 0.55078,-2.7383 4.6093996,-6.5 -0.12891,-0.48828 -0.26172,-1 -0.37891,-1.5391 -0.51953,-2.4219 -0.78906,-4.8906 -0.78906,-7.3594 0,-0.17969 0,-0.37109 0.01172,-0.55078 -9.2733996,7.082 -13.0229996,13.59 -10.8749996,18.949 1.7383,4.2695 6.7188,6.4492 14.5899996,6.4492 2.8594,0 6.1016,-0.28906 9.7109,-0.87109 0.17188,-0.03125 0.33984,-0.05859 0.51953,-0.08984 0.17188,-0.03125 0.35156,-0.05859 0.51953,-0.08984 l 1.2188,-0.21875 c 0.57031,-0.10156 1.1484,-0.21875 1.7305,-0.33984 0.53125,-0.10938 1.0508,-0.21094 1.5781,-0.32812 0.01172,0 0.03125,-0.01172 0.03906,-0.01172 0.05078,-0.01172 0.08984,-0.01953 0.14062,-0.03125 0.07031,-0.01172 0.12891,-0.03125 0.19922,-0.05078 0.57812,-0.12891 1.1602,-0.26172 1.7383,-0.39844 0.05078,-0.01172 0.10156,-0.03125 0.14844,-0.03906 0.21094,-0.05078 0.42188,-0.10156 0.64062,-0.14844 h 0.01172 c 6.0898,-1.5117 12.559,-3.6406 19.102,-6.2891 6.5508,-2.6602 12.68,-5.6289 18.109,-8.7812 0.21875,-0.12891 0.44141,-0.26172 0.66016,-0.39062 0.58984,-0.33984 1.1797,-0.69141 1.7617,-1.0508 1.5703,-0.96094 3.0586,-1.9297 4.4805,-2.9102 0.12891,-0.08984 0.26172,-0.17969 0.39062,-0.26953 11.242,-7.8477 15.941,-15.09 13.594,-20.938 z" />
-
-    </group>
-
-</vector>

android/app/src/main/res/values/ic_launcher_background.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <color name="ic_launcher_background">#7c52e0</color>
+    <color name="ic_launcher_background">#e9673f</color>
 </resources>

android/app/src/main/res/values/strings.xml

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='utf-8'?>
 <resources>
-    <string name="app_name">Ditto</string>
-    <string name="title_activity_main">Ditto</string>
-    <string name="package_name">pub.ditto.app</string>
-    <string name="custom_url_scheme">pub.ditto.app</string>
+    <string name="app_name">Eranos</string>
+    <string name="title_activity_main">Eranos</string>
+    <string name="package_name">fund.eranos.app</string>
+    <string name="custom_url_scheme">fund.eranos.app</string>
 </resources>

android/app/src/main/res/xml/backup_rules.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Android Auto Backup rules (Android 11 and below).
+
+    Ditto excludes WebView storage (Local Storage, IndexedDB, databases) and
+    any shared_prefs that hold sensitive credentials so they don't end up in
+    Google Drive backups. Keychain/KeyStore entries used by
+    capacitor-secure-storage-plugin are not backed up by default, so we don't
+    need to exclude those explicitly; but we also exclude the plugin's
+    SharedPreferences for defense in depth.
+
+    See: https://developer.android.com/guide/topics/data/autobackup
+-->
+<full-backup-content>
+    <!-- WebView: localStorage, IndexedDB, cookies, caches -->
+    <exclude domain="file" path="app_webview/" />
+    <exclude domain="database" path="webview.db" />
+    <exclude domain="database" path="webviewCache.db" />
+
+    <!-- capacitor-secure-storage-plugin fallback SharedPreferences -->
+    <exclude domain="sharedpref" path="CapacitorSecureStoragePluginSharedPreferences.xml" />
+
+    <!-- Capacitor preferences plugin — may contain app-level settings -->
+    <exclude domain="sharedpref" path="CapacitorStorage.xml" />
+</full-backup-content>

android/app/src/main/res/xml/data_extraction_rules.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Android 12+ data extraction rules.
+
+    Separate rules apply to cloud backups (Google Drive) and device-to-device
+    transfers. Both exclude WebView storage and sensitive SharedPreferences so
+    wallet credentials, login tokens, and cached private data don't leak.
+
+    See: https://developer.android.com/about/versions/12/backup-restore
+-->
+<data-extraction-rules>
+    <cloud-backup>
+        <exclude domain="file" path="app_webview/" />
+        <exclude domain="database" path="webview.db" />
+        <exclude domain="database" path="webviewCache.db" />
+        <exclude domain="sharedpref" path="CapacitorSecureStoragePluginSharedPreferences.xml" />
+        <exclude domain="sharedpref" path="CapacitorStorage.xml" />
+    </cloud-backup>
+    <device-transfer>
+        <exclude domain="file" path="app_webview/" />
+        <exclude domain="database" path="webview.db" />
+        <exclude domain="database" path="webviewCache.db" />
+        <exclude domain="sharedpref" path="CapacitorSecureStoragePluginSharedPreferences.xml" />
+        <exclude domain="sharedpref" path="CapacitorStorage.xml" />
+    </device-transfer>
+</data-extraction-rules>

android/build.gradle

@@ -21,6 +21,18 @@ allprojects {
     repositories {
         google()
         mavenCentral()
+        // Guardian Project's experimental Maven repo, hosting the prebuilt
+        // org.torproject:arti-mobile AAR (Tor in Rust) used for the optional Tor mode.
+        //
+        // Pinned to an immutable commit SHA rather than the mutable `master`
+        // branch: this artifact ships a native library with network-proxy
+        // privileges, so we don't want a force-push or new commit to gpmaven
+        // silently changing what we resolve. To bump arti, update both the
+        // commit below and the checksum pin in `app/build.gradle`, and re-verify
+        // the SHA-256 against a fresh download.
+        //
+        // Commit: guardianproject/gpmaven@b3ee2a63eec4ce37ea22fcc6b1ff009f406f2b13
+        maven { url "https://raw.githubusercontent.com/guardianproject/gpmaven/b3ee2a63eec4ce37ea22fcc6b1ff009f406f2b13" }
     }
 }
 

android/capacitor.settings.gradle

@@ -5,6 +5,9 @@ project(':capacitor-android').projectDir = new File('../node_modules/@capacitor/
 include ':capacitor-app'
 project(':capacitor-app').projectDir = new File('../node_modules/@capacitor/app/android')
 
+include ':capacitor-barcode-scanner'
+project(':capacitor-barcode-scanner').projectDir = new File('../node_modules/@capacitor/barcode-scanner/android')
+
 include ':capacitor-filesystem'
 project(':capacitor-filesystem').projectDir = new File('../node_modules/@capacitor/filesystem/android')
 

android/variables.gradle

@@ -1,5 +1,5 @@
 ext {
-    minSdkVersion = 24
+    minSdkVersion = 26
     compileSdkVersion = 36
     targetSdkVersion = 36
     androidxActivityVersion = '1.11.0'

capacitor.config.ts

@@ -1,8 +1,8 @@
 import type { CapacitorConfig } from '@capacitor/cli';
 
 const config: CapacitorConfig = {
-  appId: 'pub.ditto.app',
-  appName: 'Ditto',
+  appId: 'fund.eranos.app',
+  appName: 'Eranos',
   webDir: 'dist',
   server: {
     androidScheme: 'https',
@@ -16,14 +16,7 @@ const config: CapacitorConfig = {
   ios: {
     backgroundColor: '#14161f',
     contentInset: 'never',
-    scheme: 'Ditto'
-  },
-  plugins: {
-    SystemBars: {
-      // Inject --safe-area-inset-* CSS variables on Android to work around
-      // a Chromium bug (<140) where env(safe-area-inset-*) reports 0.
-      insetsHandling: 'css',
-    },
+    scheme: 'Eranos'
   },
 };
 

docker-compose.prod.yml

@@ -0,0 +1,6 @@
+services:
+  web:
+    build: .
+    restart: unless-stopped
+    expose:
+      - "80"

docker-compose.yml

@@ -0,0 +1,30 @@
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "8083:80"
+    volumes:
+      - ./nginx.dev.conf:/etc/nginx/conf.d/default.conf:ro
+      - ./dist:/usr/share/nginx/html:ro
+    restart: unless-stopped
+    depends_on:
+      - vite
+    networks:
+      - eranos-network
+
+  vite:
+    image: node:22-alpine
+    working_dir: /app
+    # Use host node_modules so new dependencies are picked up after install.
+    command: sh -c "npm install && npm run dev"
+    volumes:
+      - .:/app
+    environment:
+      - NODE_ENV=development
+    networks:
+      - eranos-network
+    restart: unless-stopped
+
+networks:
+  eranos-network:
+    driver: bridge

docs/THEME_SYSTEM.md

@@ -1,383 +0,0 @@
-# Theme System
-
-This document describes the two separate but overlapping theme features in Ditto: the **App Theme** (which controls the local UI) and the **Profile Theme** (which is published to Nostr for others to see). Understanding the distinction is key to working with this codebase.
-
-## Overview
-
-| Concept | Purpose | Scope | Persistence |
-|---|---|---|---|
-| **App Theme** | Controls colors, fonts, and background of the local UI | Local to the user's browser | localStorage + encrypted NIP-78 sync |
-| **Profile Theme** | A set of theme values published as a Nostr event | Public, visible to other users | Kind 16767 replaceable event |
-
-The App Theme and Profile Theme share the same underlying data structure (`ThemeConfig`), and there is an optional bridge between them (`autoShareTheme`), but they are fundamentally independent systems.
-
----
-
-## Part 1: App Theme
-
-The App Theme controls what the user sees in their own browser. It has no inherent connection to Nostr.
-
-### Core Concept: 3 Colors Define Everything
-
-The entire theme is derived from just 3 core colors, defined by the `CoreThemeColors` interface in `src/themes.ts:8`:
-
-```typescript
-interface CoreThemeColors {
-  background: string;  // HSL string, e.g. "228 20% 10%"
-  text: string;        // Text/foreground color
-  primary: string;     // Primary accent (buttons, links, focus rings)
-}
-```
-
-From these 3 values, the system auto-derives 19 CSS tokens (the full `ThemeTokens` set) via `deriveTokensFromCore()` in `src/lib/colorUtils.ts:141`. The derivation algorithm:
-
-- Detects dark/light mode from background luminance (threshold: 0.2)
-- Derives `card` and `popover` surfaces by slightly lightening the background (dark mode) or using it directly (light mode)
-- Derives `secondary` and `muted` surfaces by adjusting background lightness
-- Derives `border` using the primary hue with reduced saturation
-- Computes `mutedForeground` as a dimmer version of the text color
-- Sets `accent = primary` and `ring = primary`
-- Auto-computes `primaryForeground` using WCAG contrast detection (white or dark)
-- Uses fixed red values for `destructive` / `destructiveForeground`
-
-### Theme Modes
-
-The `Theme` type (`src/contexts/AppContext.ts:9`) has four values:
-
-| Mode | Behavior |
-|---|---|
-| `"light"` | Uses the builtin (or configured) light color set |
-| `"dark"` | Uses the builtin (or configured) dark color set |
-| `"system"` | Resolves to `"light"` or `"dark"` based on `prefers-color-scheme`, with a live media query listener |
-| `"custom"` | Uses user-defined colors stored in `config.customTheme` |
-
-**Builtin themes** are defined in `src/themes.ts:102`:
-
-```typescript
-const builtinThemes = {
-  light: { background: '270 50% 97%', text: '270 25% 12%', primary: '270 65% 55%' },
-  dark:  { background: '228 20% 10%', text: '210 40% 98%', primary: '258 70% 60%' },
-};
-```
-
-Self-hosters can override these at build time via `ditto.json` (injected through `import.meta.env.DITTO_CONFIG` in `vite.config.ts`), or at runtime via the `ThemesConfig` in `AppConfig.themes`.
-
-### ThemeConfig
-
-The `ThemeConfig` type (`src/themes.ts:50`) wraps the 3 core colors with optional extras:
-
-```typescript
-interface ThemeConfig {
-  title?: string;
-  colors: CoreThemeColors;
-  font?: ThemeFont;        // { family: string; url?: string }
-  background?: ThemeBackground;  // { url: string; mode?: 'cover' | 'tile'; ... }
-}
-```
-
-This is the canonical type used everywhere: in `AppConfig.customTheme`, in encrypted settings, and in Nostr theme events.
-
-### Theme Presets
-
-Named presets are defined in `src/themes.ts:136` (e.g. `pink`, `toxic`, `sunset`). Each preset includes core colors and optionally a font and background image. Applying a preset sets the app theme to `"custom"` and stores the preset's config as `customTheme`.
-
-### How Themes Apply to the DOM
-
-The theme pipeline has three stages designed to prevent any flash of wrong colors:
-
-#### Stage 1: Pre-React Blocking Script (`public/theme.js`)
-
-A synchronous `<script>` tag in `index.html:43` runs before React mounts. It:
-
-1. Reads `nostr:app-config` from localStorage
-2. Resolves `"system"` via `matchMedia`
-3. Handles legacy presets (`"black"`, `"pink"`)
-4. Sets `document.documentElement.className` to the theme name
-5. Sets `document.body.style.background` to the correct background color
-6. Updates preloader colors (logo and spinner) to match
-
-This prevents any visible flash between the hardcoded dark defaults in `index.html:32` and the user's actual theme.
-
-#### Stage 2: React Provider (`src/components/AppProvider.tsx`)
-
-Three private hooks run during the provider's lifecycle:
-
-**`useApplyTheme`** (line 91) - Uses `useLayoutEffect` (synchronous before paint) to:
-- Resolve the theme mode
-- Build a full CSS string from `CoreThemeColors` via `buildThemeCssFromCore()`
-- Inject/update a `<style id="theme-vars">` element with all 19 CSS custom properties
-- Set `document.documentElement.className` to the resolved theme
-- Remove the inline body style left by `theme.js`
-- When mode is `"system"`, attach a `matchMedia` change listener
-
-**`useApplyFonts`** (line 133) - Loads and applies custom fonts via `loadAndApplyFont()` from `src/lib/fontLoader.ts`.
-
-**`useApplyBackground`** (line 156) - Injects/removes a `<style id="theme-background">` for background images (cover or tile mode).
-
-#### Stage 3: Theme Switch (`src/hooks/useTheme.ts`)
-
-The `setTheme()` function (line 52) performs a flicker-free theme switch:
-
-1. Injects a temporary `<style>` that disables all CSS transitions (`transition: none !important`)
-2. Synchronously builds and applies CSS vars before React re-renders
-3. Updates `document.documentElement.className`
-4. Re-enables transitions after browser paint via `requestAnimationFrame`
-5. Updates localStorage config
-6. Debounce-syncs to encrypted NIP-78 storage (1 second delay)
-
-### How Components Consume Theme Values
-
-#### CSS Custom Properties to Tailwind
-
-`tailwind.config.ts` maps all 19 CSS custom properties to Tailwind color utilities:
-
-```typescript
-colors: {
-  background: 'hsl(var(--background))',
-  foreground: 'hsl(var(--foreground))',
-  primary: { DEFAULT: 'hsl(var(--primary))', foreground: 'hsl(var(--primary-foreground))' },
-  // ... (secondary, destructive, muted, accent, popover, card, border, input, ring)
-}
-```
-
-Components use standard Tailwind classes like `bg-primary`, `text-foreground`, `border-border`, etc. These resolve to `hsl(var(--primary))`, which picks up whichever values are currently set on `:root`.
-
-The `cn()` utility in `src/lib/utils.ts` combines `clsx` (conditional class joining) with `tailwind-merge` (intelligent Tailwind class deduplication).
-
-#### Static CSS
-
-`src/index.css` applies base styles using theme tokens:
-
-```css
-* { @apply border-border; }
-body { @apply bg-background text-foreground; }
-```
-
-The only static CSS custom property is `--radius: 0.75rem`. All color variables are injected dynamically.
-
-### ScopedTheme
-
-The `ScopedTheme` component (`src/components/ScopedTheme.tsx`) applies a different set of theme colors to a DOM subtree by setting CSS variables as inline `style`:
-
-```tsx
-<ScopedTheme colors={someColors} className="rounded-lg p-4">
-  {/* Children here see different --background, --primary, etc. */}
-</ScopedTheme>
-```
-
-It also sets `data-theme-mode="dark"` or `"light"` based on background luminance, for CSS targeting.
-
-### App Theme Persistence
-
-#### Layer 1: localStorage (immediate)
-
-The `useLocalStorage` hook (`src/hooks/useLocalStorage.ts`) stores the full `AppConfig` under key `"nostr:app-config"`. This includes `theme`, `customTheme`, `autoShareTheme`, and `themes`. Changes are reflected immediately and support cross-tab sync via `StorageEvent`.
-
-#### Layer 2: Encrypted NIP-78 Settings (cross-device sync)
-
-The `useEncryptedSettings` hook (`src/hooks/useEncryptedSettings.ts`) stores theme preferences in a kind 30078 addressable event, encrypted to self via NIP-44. The `EncryptedSettings` interface includes `theme`, `customTheme`, and `autoShareTheme` among other app settings.
-
-Key behaviors:
-- Query is delayed 5 seconds after login to avoid competing with feed load
-- Uses optimistic updates with a `pendingSettings` ref for rapid successive mutations
-- A `recentlyWritten()` guard returns true for 10 seconds after a local write to prevent `NostrSync` from overwriting the value that was just saved
-
-#### Sync via NostrSync
-
-The `NostrSync` component (`src/components/NostrSync.tsx`) runs globally and syncs encrypted settings from Nostr on login. For theme-related fields, it:
-
-1. Seeds a `lastSyncedTimestamp` ref on first load to prevent stale events from overwriting local config
-2. Skips application if `recentlyWritten()` is true
-3. Only applies changes if the remote timestamp is newer
-4. Handles legacy theme value migration (`"black"`, `"pink"` to `"custom"`)
-5. Diffs each field individually to avoid unnecessary re-renders
-
----
-
-## Part 2: Profile Theme
-
-The Profile Theme is a public Nostr event that represents a user's chosen theme. Other clients can read it to style that user's profile page, or users can browse and copy each other's themes.
-
-### Nostr Event Kinds
-
-#### Kind 36767: Theme Definition (addressable, multiple per user)
-
-A shareable, named theme that a user has created. Think of these as "published theme presets." Tags:
-
-| Tag | Purpose | Example |
-|---|---|---|
-| `d` | Identifier (slug) | `["d", "ocean-night"]` |
-| `c` | Color (hex + role) | `["c", "#1a1a2e", "background"]` |
-| `f` | Font (family + optional URL) | `["f", "Comfortaa", "https://cdn.jsdelivr.net/..."]` |
-| `bg` | Background (imeta-style variadic) | `["bg", "url https://...", "mode cover", "m image/jpeg"]` |
-| `title` | Display name | `["title", "Ocean Night"]` |
-| `alt` | NIP-31 description | `["alt", "Custom theme: Ocean Night"]` |
-| `t` | Topic tag | `["t", "theme"]` |
-| `description` | Optional description | `["description", "A deep blue theme"]` |
-
-Colors are stored as **hex** in `c` tags (converted to/from HSL internally). The `content` field is empty (legacy events may have JSON in content for backward compatibility).
-
-#### Kind 16767: Active Profile Theme (replaceable, one per user)
-
-The user's currently active profile theme. Same tag structure as kind 36767 but without `d` or `description` tags, and with an optional `a` tag referencing the source theme definition:
-
-| Tag | Purpose |
-|---|---|
-| `c` | Color tags (same as 36767) |
-| `f` | Font tag (same as 36767) |
-| `bg` | Background tag (same as 36767) |
-| `alt` | Always `"Active profile theme"` |
-| `title` | Optional theme name |
-| `a` | Optional reference to source kind 36767 event |
-
-### Hooks
-
-| Hook | File | Purpose |
-|---|---|---|
-| `usePublishTheme` | `src/hooks/usePublishTheme.ts` | Publish/update/delete theme definitions (36767), set/clear active profile theme (16767) |
-| `useUserThemes` | `src/hooks/useUserThemes.ts` | Query all kind 36767 themes by a user, deduplicated by d-tag, sorted newest first |
-| `useActiveProfileTheme` | `src/hooks/useActiveProfileTheme.ts` | Query a user's kind 16767 active profile theme |
-
-### Publishing and Parsing
-
-All event building and parsing is in `src/lib/themeEvent.ts`:
-
-- `buildThemeDefinitionTags()` / `parseThemeDefinition()` - Kind 36767
-- `buildActiveThemeTags()` / `parseActiveProfileTheme()` - Kind 16767
-- `buildColorTags()` / `parseColorTags()` - HSL-to-hex conversion for `c` tags
-- `buildFontTag()` / `parseFontTag()` - Font `f` tags
-- `buildBackgroundTag()` / `parseBackgroundTag()` - Background `bg` tags (imeta-style)
-- `titleToSlug()` - Generate d-tag identifiers from titles
-
-Backward compatibility: if `c` tags are missing, the parser falls back to reading legacy JSON from `content` (handling both the old 19-token format and the 4-color format).
-
----
-
-## Part 3: The Bridge Between App Theme and Profile Theme
-
-The two systems are connected by the **autoShareTheme** setting and the NostrSync component.
-
-### App Theme -> Profile Theme
-
-When `autoShareTheme` is enabled (default: `true`) and the user applies a custom theme via `applyCustomTheme()`, the `useTheme` hook automatically publishes the custom theme as a kind 16767 active profile theme, debounced by 2 seconds.
-
-```
-User picks a custom theme
-  -> applyCustomTheme() in useTheme.ts:88
-    -> Updates local config (localStorage)
-    -> Syncs to encrypted NIP-78 storage (1s debounce)
-    -> If autoShareTheme: publishes kind 16767 (2s debounce)
-```
-
-### Profile Theme -> App Theme
-
-On page load, if `autoShareTheme` is enabled, `NostrSync` (line 174) fetches the user's kind 16767 event and applies it as `customTheme` **without changing the theme mode**. This means:
-
-- If the user is on `theme: "dark"`, their profile theme is stored as `customTheme` but the UI stays in dark mode
-- If the user is on `theme: "custom"`, the profile theme's colors are applied to the UI
-- This allows the profile theme to stay in sync across devices without forcing the user into custom mode
-
-### Theme Definitions (Kind 36767)
-
-Theme definitions are independent of the app theme. Users can create, publish, edit, and delete named themes. Other users can view them in feeds (via `ThemeUpdateCard`) and copy them. These are purely social objects on the Nostr network.
-
----
-
-## Font System
-
-Fonts are managed by `src/lib/fontLoader.ts` and `src/lib/fonts.ts`.
-
-### Bundled Fonts
-
-10 fonts are bundled via `@fontsource` packages with lazy loading (dynamic imports):
-
-| Category | Fonts |
-|---|---|
-| Sans | Inter, DM Sans, Outfit, Montserrat |
-| Serif | Lora, Merriweather, Playfair Display |
-| Mono | JetBrains Mono |
-| Display | Comfortaa |
-| Handwriting | Comic Relief |
-
-Each has a `load()` function and a `cdnUrl` for Nostr event publishing.
-
-### Font Application
-
-Three `<style>` elements manage fonts:
-
-| ID | Purpose |
-|---|---|
-| `theme-font-faces` | `@font-face` rules for remote fonts |
-| `theme-font-overrides` | `html { font-family: "CustomFont", "Inter Variable", ... !important; }` |
-| `theme-vars` | Theme CSS custom properties (not font-specific, but part of the pipeline) |
-
-The `loadAndApplyFont()` function:
-1. Tries to load via bundled `@fontsource` package first
-2. Falls back to injecting a `@font-face` rule from a remote URL
-3. Applies a global font-family override via `<style id="theme-font-overrides">`
-4. Passing `undefined` clears the override (reverts to default Inter)
-
----
-
-## Color Utilities
-
-`src/lib/colorUtils.ts` provides the color math underpinning the theme system:
-
-| Function | Purpose |
-|---|---|
-| `parseHsl` / `formatHsl` | Parse/format HSL strings (`"228 20% 10%"`) |
-| `hslToRgb` / `rgbToHsl` | HSL-RGB conversion |
-| `hexToRgb` / `rgbToHex` | Hex-RGB conversion |
-| `hexToHslString` / `hslStringToHex` | Direct hex-to-HSL-string conversion (used for Nostr `c` tags) |
-| `getLuminance` | WCAG 2.1 relative luminance |
-| `getContrastRatio` / `getContrastRatioHsl` | WCAG contrast ratio between two colors |
-| `isDarkTheme` | Determines if a background is "dark" (luminance < 0.2) |
-| `deriveTokensFromCore` | The core algorithm: 3 colors -> 19 tokens |
-| `tokensToCoreColors` | Extract 3 core colors from a legacy 19-token object |
-
-All colors are stored internally as HSL strings without the `hsl()` wrapper (e.g. `"228 20% 10%"`). The `hsl()` wrapper is added by Tailwind's config (`hsl(var(--background))`).
-
----
-
-## Validation
-
-Theme data is validated with Zod schemas in `src/lib/schemas.ts`:
-
-- `ThemeSchema` - Validates `'dark' | 'light' | 'system' | 'custom'`
-- `CoreThemeColorsSchema` - Validates the 3 HSL string fields
-- `ThemeConfigSchema` - Full config with optional font/background
-- `ThemeConfigCompatSchema` - Accepts both `ThemeConfig` and bare `CoreThemeColors`
-- `ThemeColorsCompatSchema` - Union of current 3-color, old 4-color, and legacy 19-token formats
-- `AppConfigSchema` - Full app config including all theme fields
-- `EncryptedSettingsSchema` - Encrypted settings including theme fields
-
-The `AppProvider` deserializer (`src/components/AppProvider.tsx:32`) validates each top-level field individually with `safeParse`, so a single invalid field doesn't nuke the entire config.
-
----
-
-## File Index
-
-| File | Role |
-|---|---|
-| `src/themes.ts` | Core types (`CoreThemeColors`, `ThemeConfig`, `ThemeTokens`), builtin themes, presets, CSS builders |
-| `src/lib/colorUtils.ts` | Color conversion, contrast detection, token derivation |
-| `src/lib/themeEvent.ts` | Nostr event kinds (36767, 16767), tag building/parsing |
-| `src/lib/fontLoader.ts` | Font loading and CSS injection |
-| `src/lib/fonts.ts` | Bundled font definitions |
-| `src/lib/schemas.ts` | Zod validation schemas |
-| `src/contexts/AppContext.ts` | `Theme` type, `AppConfig` interface, React context |
-| `src/hooks/useTheme.ts` | Primary theme API: `setTheme()`, `applyCustomTheme()`, `setAutoShareTheme()` |
-| `src/hooks/useAppContext.ts` | Context consumer hook |
-| `src/hooks/useEncryptedSettings.ts` | NIP-78 encrypted settings (cross-device sync) |
-| `src/hooks/usePublishTheme.ts` | Publish theme definitions and active profile theme |
-| `src/hooks/useUserThemes.ts` | Query user's theme definitions |
-| `src/hooks/useActiveProfileTheme.ts` | Query user's active profile theme |
-| `src/components/AppProvider.tsx` | Theme application to DOM (`useApplyTheme`, `useApplyFonts`, `useApplyBackground`) |
-| `src/components/NostrSync.tsx` | Cross-device sync for encrypted settings and profile theme |
-| `src/components/ScopedTheme.tsx` | Scoped CSS variable overrides for subtrees |
-| `src/components/ThemeSelector.tsx` | Full settings UI for theme management |
-| `src/components/SidebarThemeDropdown.tsx` | Compact theme picker dropdown |
-| `public/theme.js` | Pre-React blocking script for flash prevention |
-| `index.html` | Hardcoded dark defaults, preloader, blocking script tag |
-| `tailwind.config.ts` | CSS custom property to Tailwind color mapping |
-| `src/index.css` | Base styles using theme tokens |

docs/blobbi/blobbi-tag-schema.md

@@ -1,254 +0,0 @@
-# Blobbi Tag Schema
-
-> **Product Specification** - This document is the canonical source of truth for Blobbi tag definitions.  
-> The runtime schema at `src/lib/blobbi-tag-schema.ts` MUST align with this spec.
-
-## Overview
-
-Blobbi events (Kind 31124) use tags to store all state data. This document defines:
-- All valid tags and their purposes
-- Which tags are required vs optional
-- Which tags persist across stage transitions
-- Which tags should be removed during transitions
-- Deprecated tags that should be filtered out
-
----
-
-## Tag Categories
-
-### 1. System / Metadata Tags
-
-Core protocol-level tags required for event identification and ecosystem membership.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `d` | **Yes** | egg, baby, adult | Yes | system | `blobbi-{pubkeyPrefix12}-{petId10}` | Unique identifier (addressable event d-tag) |
-| `b` | **Yes** | egg, baby, adult | Yes | system | `blobbi:ecosystem:v1` | Ecosystem namespace identifier |
-| `t` | **Yes** | egg, baby, adult | Yes | system | `blobbi` | Topic tag for discoverability |
-| `client` | No | egg, baby, adult | Yes | system | `blobbi` | Client identifier |
-
-### 2. Core Identity Tags
-
-Tags that define the Blobbi's unique identity. These MUST be preserved across all transitions.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `name` | **Yes** | egg, baby, adult | Yes | user | string | Display name (set during adoption) |
-| `seed` | **Yes** | egg, baby, adult | Yes | system | 64 hex chars | Deterministic seed for visual traits |
-| `generation` | No | egg, baby, adult | Yes | system | positive integer | Lineage generation (default: 1) |
-
-**Important**: The `seed` is derived once at creation using `sha256("blobbi:v1|{pubkey}:{d}:{createdAt}")` and MUST NEVER be recomputed.
-
-### 3. Visual Trait Tags
-
-Tags derived deterministically from the seed. These are stored explicitly for fast rendering and compatibility.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `base_color` | No | egg, baby, adult | Yes | generated | CSS hex (e.g., `#F59E0B`) | Primary color |
-| `secondary_color` | No | egg, baby, adult | Yes | generated | CSS hex | Secondary/accent color |
-| `eye_color` | No | egg, baby, adult | Yes | generated | CSS hex | Eye color |
-| `pattern` | No | egg, baby, adult | Yes | generated | `solid\|spotted\|striped\|gradient` | Visual pattern type |
-| `special_mark` | No | egg, baby, adult | Yes | generated | `none\|star\|heart\|sparkle\|blush` | Special decoration |
-| `size` | No | egg, baby, adult | Yes | generated | `small\|medium\|large` | Size category |
-
-**Regenerable**: These tags CAN be regenerated from the seed if missing. However, they should be preserved when present.
-
-### 4. Personality / Trait Tags
-
-Character traits that define the Blobbi's personality. These are generated at creation and MUST persist.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `personality` | No | egg, baby, adult | Yes | generated | string | Core personality type |
-| `trait` | No | egg, baby, adult | Yes | generated | string | Character trait modifier |
-| `favorite_food` | No | egg, baby, adult | Yes | generated | string | Preferred food type |
-| `voice_type` | No | egg, baby, adult | Yes | generated | string | Voice characteristic |
-| `mood` | No | egg, baby, adult | Yes | computed | string | Current emotional state |
-
-**Not Regenerable**: These tags are generated once and MUST be preserved. Do NOT invent values for existing Blobbis that lack these tags.
-
-### 5. Stat Tags
-
-Numeric values representing the Blobbi's current condition. These are actively computed and change frequently.
-
-| Tag | Required | Stages | Persistent | Source | Format | Default | Description |
-|-----|----------|--------|------------|--------|--------|---------|-------------|
-| `hunger` | No | egg, baby, adult | No | computed | 1-100 | 100 | Fullness level |
-| `happiness` | No | egg, baby, adult | No | computed | 1-100 | 100 | Happiness level |
-| `health` | No | egg, baby, adult | No | computed | 1-100 | 100 | Health level |
-| `hygiene` | No | egg, baby, adult | No | computed | 1-100 | 100 | Cleanliness level |
-| `energy` | No | egg, baby, adult | No | computed | 1-100 | 100 | Energy level |
-
-**Stage Transition Behavior**:
-- **Hatch (egg → baby)**: `health` inherited from egg, others reset to 100
-- **Evolve (baby → adult)**: All stats inherited from baby (after decay)
-
-### 6. State / Lifecycle Tags
-
-Tags that track the Blobbi's current lifecycle state.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `stage` | **Yes** | egg, baby, adult | No | system | `egg\|baby\|adult` | Current lifecycle stage |
-| `state` | **Yes** | egg, baby, adult | No | system | `active\|sleeping\|hibernating\|incubating\|evolving` | Activity state |
-| `last_interaction` | **Yes** | egg, baby, adult | No | system | Unix timestamp | Last user action |
-| `last_decay_at` | No | egg, baby, adult | No | system | Unix timestamp | Decay checkpoint |
-
-**State Constraints**:
-- `incubating` is only valid for `stage: egg`
-- `evolving` is only valid for `stage: baby`
-- After hatch/evolve completes, `state` MUST be set to `active`
-
-### 7. Task System Tags
-
-Temporary tags used during incubation and evolution processes. These are REMOVED after stage transitions.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `state_started_at` | No | egg, baby | No | system | Unix timestamp | When incubating/evolving started |
-| `task` | No | egg, baby | No | computed | `["task", "name:value"]` | Task progress (multiple allowed) |
-| `task_completed` | No | egg, baby | No | computed | `["task_completed", "name"]` | Completed tasks (multiple allowed) |
-
-**Transition Behavior**: ALL task system tags MUST be removed when hatch or evolve completes.
-
-### 8. Progression Tags
-
-Long-term progress tracking that persists across all stages.
-
-| Tag | Required | Stages | Persistent | Source | Format | Default | Description |
-|-----|----------|--------|------------|--------|--------|---------|-------------|
-| `experience` | No | egg, baby, adult | Yes | computed | non-negative int | 0 | Total XP |
-| `care_streak` | No | egg, baby, adult | Yes | computed | non-negative int | 0 | Consecutive care days |
-
-### 9. Social / Flag Tags
-
-User preferences and computed flags.
-
-| Tag | Required | Stages | Persistent | Source | Format | Default | Description |
-|-----|----------|--------|------------|--------|--------|---------|-------------|
-| `breeding_ready` | No | egg, baby, adult | Yes | computed | `true\|false` | false | Breeding eligibility |
-
-### 10. Evolution Tags
-
-Tags specific to adult Blobbis.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `adult_type` | No | adult | Yes | computed | string | Evolution form type |
-
-### 11. Extension Tags
-
-Optional tags for themes and crossover features.
-
-| Tag | Required | Stages | Persistent | Source | Format | Description |
-|-----|----------|--------|------------|--------|--------|-------------|
-| `theme` | No | egg, baby, adult | Yes | system | string (e.g., `divine`) | Theme variant |
-| `crossover_app` | No | egg, baby, adult | Yes | system | string (e.g., `divine`) | Crossover app identifier |
-
----
-
-## Deprecated Tags
-
-These tags are from legacy versions and MUST be removed when republishing events.
-
-| Tag | Reason | Replaced By |
-|-----|--------|-------------|
-| `shell_integrity` | Eggs use standard `health` stat | `health` |
-| `egg_temperature` | Warmth handled via UI props | N/A |
-| `incubation_progress` | Replaced by task system | `task`, `task_completed` |
-| `egg_status` | Replaced by standard state | `state` |
-| `fees` | Removed | N/A |
-| `incubation_time` | Uses state_started_at | `state_started_at` |
-| `start_incubation` | Uses state_started_at | `state_started_at` |
-| `interact_6_progress` | Legacy interaction tracking | `["task", "interactions:N"]` |
-
----
-
-## Stage Transition Rules
-
-### Hatch (egg → baby)
-
-**Tags to REMOVE**:
-- `task`
-- `task_completed`
-- `state_started_at`
-
-**Tags to UPDATE**:
-- `stage` → `baby`
-- `state` → `active`
-- `hunger` → `100`
-- `happiness` → `100`
-- `hygiene` → `100`
-- `energy` → `100`
-- `health` → (inherited from egg after decay)
-- `last_interaction` → current timestamp
-- `last_decay_at` → current timestamp
-
-**Tags to PRESERVE (all persistent tags)**:
-- All system tags (`d`, `b`, `t`, `client`)
-- All identity tags (`name`, `seed`, `generation`)
-- All visual tags (colors, pattern, size)
-- All personality tags (if present)
-- All progression tags (`experience`, `care_streak`)
-- All social tags (`breeding_ready`)
-- All extension tags (`theme`, `crossover_app`)
-
-### Evolve (baby → adult)
-
-**Tags to REMOVE**:
-- `task`
-- `task_completed`
-- `state_started_at`
-
-**Tags to UPDATE**:
-- `stage` → `adult`
-- `state` → `active`
-- All stats → (inherited from baby after decay)
-- `last_interaction` → current timestamp
-- `last_decay_at` → current timestamp
-
-**Tags to PRESERVE (all persistent tags)**:
-- Same as hatch, plus all stats are inherited (not reset)
-
-**Tags to ADD (optional)**:
-- `adult_type` → computed based on care history
-
----
-
-## Migration Rules
-
-When migrating legacy Blobbis to canonical format:
-
-1. **Always preserve existing values** - Do not regenerate tags that already exist
-2. **Generate missing required tags** - Derive `seed` if missing using the legacy event's `created_at`
-3. **Remove deprecated tags** - Filter out all tags in the deprecated list
-4. **Repair visual tags** - Regenerate from seed if missing (these are regenerable)
-5. **Do NOT invent personality tags** - If `personality`, `trait`, etc. don't exist, leave them empty
-
----
-
-## Validation Rules
-
-A valid Blobbi event MUST have:
-- `d` tag in canonical format
-- `b` tag = `blobbi:ecosystem:v1`
-- `t` tag = `blobbi`
-- `name` tag (non-empty)
-- `seed` tag (64 hex chars)
-- `stage` tag (valid value)
-- `state` tag (valid value)
-- `last_interaction` tag (valid timestamp)
-
----
-
-## Implementation Checklist
-
-When implementing any flow that modifies Blobbi tags:
-
-- [ ] Start from `canonical.allTags` as the base
-- [ ] Remove only task-specific tags (`task`, `task_completed`, `state_started_at`)
-- [ ] Preserve ALL persistent tags (identity, visual, personality, progression, social, extension)
-- [ ] Filter out deprecated tags
-- [ ] Update only the tags that need to change
-- [ ] Validate required tags are present

eslint.config.js

@@ -8,7 +8,7 @@ import htmlParser from "@html-eslint/parser";
 import customRules from "./eslint-rules/index.js";
 
 export default tseslint.config(
-  { ignores: ["dist", "android", "ios"] },
+  { ignores: ["dist", "android", "ios", ".agents"] },
   {
     extends: [js.configs.recommended, ...tseslint.configs.recommended],
     files: ["**/*.{ts,tsx}"],

index.html

@@ -1,43 +1,45 @@
 <!DOCTYPE html>
 <html lang="en" class="dark">
   <head>
-    <title>Ditto — Your content. Your vibe. Your rules.</title>
+    <title>Eranos — Power to the people.</title>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover, interactive-widget=resizes-content" />
-    <meta name="description" content="Ditto — Your content. Your vibe. Your rules." />
+    <meta name="description" content="Eranos — a peer-to-peer crowdfunding app on Nostr. Fund campaigns directly with Grin, no middlemen." />
 
     <!-- Open Graph -->
-    <meta property="og:title" content="Ditto" />
-    <meta property="og:description" content="Your content. Your vibe. Your rules." />
-    <meta property="og:image" content="https://ditto.pub/og-image.jpg" />
+    <meta property="og:title" content="Eranos" />
+    <meta property="og:description" content="Power to the people." />
+    <meta property="og:image" content="https://eranos.fund/og-image.jpg" />
     <meta property="og:image:width" content="1200" />
     <meta property="og:image:height" content="630" />
     <meta property="og:image:type" content="image/jpeg" />
     <meta property="og:type" content="website" />
-    <meta property="og:url" content="https://ditto.pub" />
-    <meta property="og:site_name" content="Ditto" />
+    <meta property="og:url" content="https://eranos.fund" />
+    <meta property="og:site_name" content="Eranos" />
 
     <!-- Twitter / X -->
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="Ditto" />
-    <meta name="twitter:description" content="Your content. Your vibe. Your rules." />
-    <meta name="twitter:image" content="https://ditto.pub/og-image.jpg" />
+    <meta name="twitter:title" content="Eranos" />
+    <meta name="twitter:description" content="Power to the people." />
+    <meta name="twitter:image" content="https://eranos.fund/og-image.jpg" />
 
-    <meta http-equiv="content-security-policy" content="default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; frame-src 'self' https:; font-src 'self' https:; base-uri 'self'; manifest-src 'self'; connect-src 'self' blob: https: wss:; img-src 'self' data: blob: https:; media-src 'self' blob: https:">
-    <link rel="icon" type="image/svg+xml" href="/logo.svg">
-    <link rel="apple-touch-icon" href="/apple-touch-icon.png">
-    <meta name="theme-color" content="#161b2e" media="(prefers-color-scheme: dark)">
-    <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
+    <meta http-equiv="content-security-policy" content="default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:; child-src 'self' blob:; style-src 'self' 'unsafe-inline'; frame-src 'self' https:; font-src 'self' https:; base-uri 'self'; manifest-src 'self'; connect-src 'self' blob: https: wss:; img-src 'self' data: blob: https:; media-src 'self' blob: https:">
+    <link rel="icon" type="image/x-icon" href="/favicon.ico">
+    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png">
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+    <meta name="theme-color" content="#0a0c14" media="(prefers-color-scheme: dark)">
+    <meta name="theme-color" content="#faa805" media="(prefers-color-scheme: light)">
     <link rel="manifest" href="/manifest.webmanifest">
-    <style>@keyframes ditto-spin{to{transform:rotate(360deg)}}</style>
+    <style>@keyframes agora-spin{to{transform:rotate(360deg)}}</style>
   </head>
-  <body style="margin:0;background:hsl(228 20% 10%)">
+  <body style="margin:0;background:hsl(0 0% 10%)">
     <!-- Pre-React loading screen. Lives OUTSIDE #root so React doesn't
          touch it. Removed by main.tsx once the app has mounted. -->
-    <div id="preloader" style="position:fixed;inset:0;z-index:9999;display:flex;align-items:center;justify-content:center;background:hsl(228 20% 10%)">
+    <div id="preloader" style="position:fixed;inset:0;z-index:9999;display:flex;align-items:center;justify-content:center;background:hsl(0 0% 10%)">
       <div style="display:flex;flex-direction:column;align-items:center;gap:24px">
-        <div data-logo style="width:48px;height:48px;background:hsl(258 70% 60%);-webkit-mask:url(/logo.svg) center/contain no-repeat;mask:url(/logo.svg) center/contain no-repeat"></div>
-        <div data-spinner style="width:24px;height:24px;border:2.5px solid hsl(258 70% 60% / 0.25);border-top-color:hsl(258 70% 60%);border-radius:50%;animation:ditto-spin .7s linear infinite"></div>
+        <div data-logo style="width:48px;height:48px;background:hsl(14 79% 58%);-webkit-mask:url(/logo.svg) center/contain no-repeat;mask:url(/logo.svg) center/contain no-repeat"></div>
+        <div data-spinner style="width:24px;height:24px;border:2.5px solid hsl(14 79% 58% / 0.25);border-top-color:hsl(14 79% 58%);border-radius:50%;animation:agora-spin .7s linear infinite"></div>
       </div>
     </div>
     <!-- Blocking script: reads theme from localStorage and applies it

ios/App/App.xcodeproj/project.pbxproj

@@ -15,9 +15,10 @@
 		504EC30F1FED79650016851F /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 504EC30E1FED79650016851F /* Assets.xcassets */; };
 		504EC3121FED79650016851F /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 504EC3101FED79650016851F /* LaunchScreen.storyboard */; };
 		50B271D11FEDC1A000F3C39B /* public in Resources */ = {isa = PBXBuildFile; fileRef = 50B271D01FEDC1A000F3C39B /* public */; };
-		B1A2C3D40001000100000001 /* SandboxPlugin.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40001000100000002 /* SandboxPlugin.swift */; };
 		B1A2C3D40002000100000001 /* DittoBridgeViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40002000100000002 /* DittoBridgeViewController.swift */; };
 		B1A2C3D40005000100000001 /* PrivacyInfo.xcprivacy in Resources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40005000100000002 /* PrivacyInfo.xcprivacy */; };
+		B1A2C3D40006000100000001 /* DittoNotificationPlugin.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40006000100000002 /* DittoNotificationPlugin.swift */; };
+		B1A2C3D40007000100000001 /* NostrPoller.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40007000100000002 /* NostrPoller.swift */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
@@ -31,10 +32,11 @@
 		504EC3131FED79650016851F /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
 		50B271D01FEDC1A000F3C39B /* public */ = {isa = PBXFileReference; lastKnownFileType = folder; path = public; sourceTree = "<group>"; };
 		958DCC722DB07C7200EA8C5F /* debug.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; name = debug.xcconfig; path = ../debug.xcconfig; sourceTree = SOURCE_ROOT; };
-		B1A2C3D40001000100000002 /* SandboxPlugin.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SandboxPlugin.swift; sourceTree = "<group>"; };
 		B1A2C3D40002000100000002 /* DittoBridgeViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DittoBridgeViewController.swift; sourceTree = "<group>"; };
 		B1A2C3D40004000100000002 /* App.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = App.entitlements; sourceTree = "<group>"; };
 		B1A2C3D40005000100000002 /* PrivacyInfo.xcprivacy */ = {isa = PBXFileReference; lastKnownFileType = text.xml; path = PrivacyInfo.xcprivacy; sourceTree = "<group>"; };
+		B1A2C3D40006000100000002 /* DittoNotificationPlugin.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DittoNotificationPlugin.swift; sourceTree = "<group>"; };
+		B1A2C3D40007000100000002 /* NostrPoller.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NostrPoller.swift; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -72,8 +74,9 @@
 				50379B222058CBB4000EE86E /* capacitor.config.json */,
 				B1A2C3D40004000100000002 /* App.entitlements */,
 				504EC3071FED79650016851F /* AppDelegate.swift */,
-				B1A2C3D40001000100000002 /* SandboxPlugin.swift */,
 				B1A2C3D40002000100000002 /* DittoBridgeViewController.swift */,
+				B1A2C3D40006000100000002 /* DittoNotificationPlugin.swift */,
+				B1A2C3D40007000100000002 /* NostrPoller.swift */,
 				504EC30B1FED79650016851F /* Main.storyboard */,
 				504EC30E1FED79650016851F /* Assets.xcassets */,
 				504EC3101FED79650016851F /* LaunchScreen.storyboard */,
@@ -168,8 +171,9 @@
 			buildActionMask = 2147483647;
 			files = (
 				504EC3081FED79650016851F /* AppDelegate.swift in Sources */,
-				B1A2C3D40001000100000001 /* SandboxPlugin.swift in Sources */,
 				B1A2C3D40002000100000001 /* DittoBridgeViewController.swift in Sources */,
+				B1A2C3D40006000100000001 /* DittoNotificationPlugin.swift in Sources */,
+				B1A2C3D40007000100000001 /* NostrPoller.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -319,9 +323,9 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 2.6.6;
+				MARKETING_VERSION = 2.9.1;
 				OTHER_SWIFT_FLAGS = "$(inherited) \"-D\" \"COCOAPODS\" \"-DDEBUG\"";
-				PRODUCT_BUNDLE_IDENTIFIER = pub.ditto.app;
+				PRODUCT_BUNDLE_IDENTIFIER = fund.eranos.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
 				SWIFT_VERSION = 5.0;
@@ -343,8 +347,8 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 2.6.6;
-				PRODUCT_BUNDLE_IDENTIFIER = pub.ditto.app;
+				MARKETING_VERSION = 2.9.1;
+				PRODUCT_BUNDLE_IDENTIFIER = fund.eranos.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "";
 				SWIFT_VERSION = 5.0;

ios/App/App/App.entitlements

@@ -4,8 +4,8 @@
 <dict>
 	<key>com.apple.developer.associated-domains</key>
 	<array>
-		<string>webcredentials:ditto.pub</string>
-		<string>webcredentials:ditto.pub?mode=developer</string>
+		<string>webcredentials:eranos.fund</string>
+		<string>webcredentials:eranos.fund?mode=developer</string>
 	</array>
 </dict>
 </plist>

ios/App/App/AppDelegate.swift

@@ -1,36 +1,45 @@
 import UIKit
 import Capacitor
+import BackgroundTasks
+import UserNotifications
 
 @UIApplicationMain
-class AppDelegate: UIResponder, UIApplicationDelegate {
+class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
 
     var window: UIWindow?
 
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-        // Override point for customization after application launch.
+        // Register the background task handler for notification polling.
+        // Must happen before the app finishes launching.
+        DittoNotificationPlugin.registerBackgroundTask()
+
+        // Set ourselves as the notification center delegate so we can:
+        // 1. Show banners even when the app is in the foreground.
+        // 2. Handle notification taps to navigate the WebView.
+        UNUserNotificationCenter.current().delegate = self
+
+        // Register notification categories with summary formats for iOS grouping.
+        registerNotificationCategories()
+
         return true
     }
 
     func applicationWillResignActive(_ application: UIApplication) {
-        // Sent when the application is about to move from active to inactive state. This can occur for certain types of temporary interruptions (such as an incoming phone call or SMS message) or when the user quits the application and it begins the transition to the background state.
-        // Use this method to pause ongoing tasks, disable timers, and invalidate graphics rendering callbacks. Games should use this method to pause the game.
     }
 
     func applicationDidEnterBackground(_ application: UIApplication) {
-        // Use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later.
-        // If your application supports background execution, this method is called instead of applicationWillTerminate: when the user quits.
     }
 
     func applicationWillEnterForeground(_ application: UIApplication) {
-        // Called as part of the transition from the background to the active state; here you can undo many of the changes made on entering the background.
+        // Trigger an immediate poll when returning to foreground to catch up
+        // on any notifications missed while backgrounded.
+        DittoNotificationPlugin.pollNow()
     }
 
     func applicationDidBecomeActive(_ application: UIApplication) {
-        // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
     }
 
     func applicationWillTerminate(_ application: UIApplication) {
-        // Called when the application is about to terminate. Save data if appropriate. See also applicationDidEnterBackground:.
     }
 
     func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
@@ -46,4 +55,66 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
         return ApplicationDelegateProxy.shared.application(application, continue: userActivity, restorationHandler: restorationHandler)
     }
 
+    // MARK: - UNUserNotificationCenterDelegate
+
+    /// Show notification banners even when the app is in the foreground.
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        willPresent notification: UNNotification,
+        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+    ) {
+        completionHandler([.banner, .sound])
+    }
+
+    /// Handle notification tap: navigate the Capacitor WebView to /notifications.
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        didReceive response: UNNotificationResponse,
+        withCompletionHandler completionHandler: @escaping () -> Void
+    ) {
+        let userInfo = response.notification.request.content.userInfo
+        let path = userInfo["url"] as? String ?? "/notifications"
+
+        // Navigate the Capacitor WebView to the notifications page.
+        DispatchQueue.main.async { [weak self] in
+            guard let rootVC = self?.window?.rootViewController as? DittoBridgeViewController else {
+                completionHandler()
+                return
+            }
+            let js = "window.location.pathname !== '\(path)' && (window.location.pathname = '\(path)');"
+            rootVC.webView?.evaluateJavaScript(js) { _, _ in }
+        }
+
+        completionHandler()
+    }
+
+    // MARK: - Notification Categories
+
+    /// Register notification categories with summary formats for native iOS
+    /// notification grouping. When multiple notifications share a thread
+    /// identifier, iOS automatically collapses them and uses the summary
+    /// format to describe the group.
+    private func registerNotificationCategories() {
+        let categories: [UNNotificationCategory] = [
+            makeCategory(id: NostrPoller.categoryReactions, summary: "%u more reactions"),
+            makeCategory(id: NostrPoller.categoryReposts, summary: "%u more reposts"),
+            makeCategory(id: NostrPoller.categoryZaps, summary: "%u more zaps"),
+            makeCategory(id: NostrPoller.categoryMentions, summary: "%u more mentions"),
+            makeCategory(id: NostrPoller.categoryComments, summary: "%u more comments"),
+            makeCategory(id: NostrPoller.categoryBadges, summary: "%u more badge awards"),
+            makeCategory(id: NostrPoller.categoryLetters, summary: "%u more letters"),
+        ]
+        UNUserNotificationCenter.current().setNotificationCategories(Set(categories))
+    }
+
+    private func makeCategory(id: String, summary: String) -> UNNotificationCategory {
+        return UNNotificationCategory(
+            identifier: id,
+            actions: [],
+            intentIdentifiers: [],
+            hiddenPreviewsBodyPlaceholder: nil,
+            categorySummaryFormat: summary,
+            options: []
+        )
+    }
 }