chore: Claude/agent guidance and workspace files

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

files/dev-CLAUDE.md

@@ -0,0 +1,728 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> **Source-of-truth path:** `/etc/nixos/files/dev-CLAUDE.md`. `~/dev/CLAUDE.md`
+> is a home-manager `mkOutOfStoreSymlink` to here (`/etc/nixos/home.nix`).
+> `~/dev/` is not a git repo. Edits at either path take effect immediately
+> (no rebuild needed), but **commit from `/etc/nixos`**.
+
+## What this directory is
+
+`~/dev/` is **not** a single repo — it's a workspace of sibling projects for
+the aiolabs / atitlan.io stack (Lightning + Nostr). Most projects are
+forgejo-hosted at `git.atitlan.io`. Per-project CLAUDE.md files are the
+source of truth for each repo; this file holds workspace-level facts that
+cross-cut multiple repos.
+
+## Layout convention
+
+Bare repos live under `repos/<name>.git/` and are checked out as
+**worktrees** named after the branch (or purpose): `lnbits/main/`,
+`lnbits/dev/`, `lamassu-next/lightning-pub/`, etc. Single-worktree projects
+typically use `<project>/main/` (`host5-home/main`, `quartz-module/main`,
+`webapp-module/main`, `fava-module/main`).
+
+## Per-project CLAUDE.md (defer to these)
+
+- `webapp/CLAUDE.md` — Vue 3 + Vite + Electron client (Nostr + Lightning).
+  Heavy guidance on modular DI architecture, Shadcn forms, mobile file-input
+  defenses. Read before touching anything under `webapp/`.
+- `bitspire/bitspire/CLAUDE.md`
+- `quartz-module/main/CLAUDE.md`
+- `docs/castle-docs/CLAUDE.md`
+
+## Key cross-cutting locations
+
+- **`deploy/server-deploy/`** — Unified NixOS infrastructure flake. Consumes
+  project repos here as flake inputs (`url = "git+ssh://...aiolabs/<x>"`).
+  See `flake.nix` for the canonical map of which repos feed which hosts.
+- **`local/docker/regtest/`** — Local multi-node Lightning regtest stack
+  (LND/CLN/Eclair + bitcoind/electrs/boltz/fava). See `local/README.md`.
+  **Default lnbits dev path is FakeWallet — no docker needed.** Only spin up
+  regtest when testing real channels/payments.
+
+  **`LNBITS_SRC` branch awareness:** the dev compose builds lnbits from
+  `${LNBITS_SRC:-~/dev/lnbits/main}`. If `LNBITS_SRC` points elsewhere
+  (e.g. a feature branch), commits to `lnbits/main` **don't reach the
+  dev image even after `--no-cache` rebuild**. Verify resolved context
+  with `docker compose config | grep -A2 lnbits` before assuming a
+  rebuild picked up your patch.
+
+  **Extension folder = LNbits install target:** the compose mounts
+  `~/dev/shared/extensions/` at `/shared` and sets `LNBITS_EXTENSIONS_PATH=
+  /shared`, so the extension git checkout *is* the installed extension.
+  Clicking "Upgrade" in the LNbits UI extracts the catalog archive
+  directly over the checkout, wiping `.git`. Mitigation: aio semver
+  MUST beat upstream tag (see catalog rules).
+- **`refs/`** — Curated mirrors of upstream reference codebases (Beancount,
+  Lemmy, LNbits, LND/CLN/Eclair, nostr-tools, khatru, …) plus weekly
+  digests. Manifest `refs.toml`; refresh via `bin/refresh`, digest via
+  `bin/digest`. Layout: `repos/<group>/<owner>/<name>`. Use for grep/browse
+  — *don't* import for builds; pin via flake input or submodule instead.
+- **`shared/extensions`, `shared/lamassu-server`, `shared/nix-bitcoin`** —
+  shared paths used across multiple worktrees.
+- **`upstream-prs/`** — branches staged for upstream contribution.
+- **`lnbits-extensions/`** — extension catalog (`extensions.json`).
+
+## Working in this workspace
+
+- Treat each subdirectory as its own repo with its own conventions, branches,
+  remotes. Don't assume changes in one project belong with changes in another.
+- Many lnbits worktrees share the same bare repo — be mindful which branch
+  you're on, especially when running migrations or touching shared state.
+- The `webapp` repo's `dev` branch is the staging channel for
+  `demo.aiolabs.dev`; `main` feeds production. Dev = staging, not "demo".
+
+### Webapp release flow
+
+1. Push to `aiolabs/webapp` **`dev`** (not main).
+2. Bump `webapp-dev` input in `deploy/server-deploy/flake.lock`
+   (`nix flake lock --update-input webapp-dev`). Tracks `dev`.
+3. Deploy to `host4` (`./deploy.sh host4`). Smoke as staging vet.
+4. Once vetted: fast-forward `aiolabs/webapp` **`main`** to dev's commit
+   + bump the `webapp` (not `webapp-dev`) input in `flake.lock`.
+
+**Never push runtime webapp changes directly to main.** If you find
+runtime commits on main that should have gone through dev, **stop and
+notify the user** — recovery is destructive and needs explicit auth.
+
+**Carve-out: non-runtime / tooling-only changes can go direct to main +
+rebase dev on top.** Root-level dotfiles and dev tooling that don't ship
+in the Vite/Electron bundle (`.mcp.json`, editorconfig, CLAUDE.md, root
+README) have nothing to vet on staging. Pattern: commit on main, push,
+then `cd ~/dev/webapp/dev && git fetch && git rebase origin/main &&
+git push --force-with-lease`. Still PR for anything touching `src/`,
+`electron/`, `package.json`/`pnpm-lock.yaml`, build config.
+
+- Production-bound changes need a corresponding `flake.lock` bump in
+  `deploy/server-deploy/` to actually reach a host.
+- **Git staging discipline:** never `git add -A` / `git add .` — list
+  filenames explicitly. Hard rule from a 2026-05-14 incident that leaked
+  an LNbits auth key.
+
+---
+
+## aiolabs Forgejo conventions
+
+### Fork versioning (lnbits + extensions)
+
+Universal across all LNbits-derived aio forks:
+
+- **Tag scheme:** `v<upstream-version>-aio.<patch-number>`. Examples:
+  `v1.5.4-aio.1`, `v1.3.0-aio.2`. Bump upstream segment on rebase, reset
+  patch counter to `1`.
+- **Hyphen pre-release suffix on tags + extension `config.json`**, NOT
+  `+aio.N` build-metadata. Confirmed across multiple bumps.
+- **EXCEPTION: lnbits `pyproject.toml` requires PEP 440 → `+aio.N` there
+  only.** Hyphen-suffix isn't PEP 440-valid. Same release, two spellings:
+  git tag `v1.5.4-aio.1`, `pyproject.toml` `1.5.4+aio.1`. The latter is
+  what `importlib.metadata` returns and the UI footer displays.
+- **Tag at deploy-ready boundaries, not every commit.** Tags mark vetted
+  states; direct-commit-to-main is fine, but don't tag broken intermediate
+  commits.
+- **Lint pipeline** for aio forks: black + mypy + prettier + ruff.
+
+For `aiolabs/lnbits`: `deploy/server-deploy` pulls lnbits as a flake input
+pinned by commit. The tag is a human-readable label, not a functional
+dependency — but makes `git log --decorate` and archaeology vastly clearer.
+
+### `aiolabs/lnbits-extensions` catalog rules
+
+`extensions.json` is consumed at runtime by LNbits via
+`LNBITS_EXTENSIONS_MANIFESTS`; archives are sha256-pinned per entry.
+
+**The catalog repo is NOT tagged.** It's a curated manifest, not a fork.
+Deploy reads it live from `…/raw/branch/main/extensions.json`; audit trail
+is `git log` on main, rollback is `git revert`.
+
+- **Production points ONLY at our manifest, never upstream.** The deployed
+  `LNBITS_EXTENSIONS_MANIFESTS` points at
+  `git.atitlan.io/aiolabs/lnbits-extensions/raw/branch/main/extensions.json`
+  (`deploy/server-deploy/modules/services/lnbits.nix:73`). Production
+  users can only install / upgrade what we've curated. Cycle: upstream
+  releases → vet in dev → rebase to aio → update our manifest. Never add
+  `github.com/lnbits/<ext>` URLs for an extension with an active aio fork.
+- **Don't overwrite a version entry in place.** When bumping, *add a new
+  entry* alongside the old — instances running the previous version need
+  it to remain resolvable.
+- **Aio semver MUST beat the upstream tag we're forking** (dev hygiene).
+  Regtest compose doesn't override `LNBITS_EXTENSIONS_MANIFESTS`, so dev
+  sees LNbits's built-in default catalog AND our manifest. LNbits's
+  "upgrade" picks highest semver across all visible entries; if upstream
+  outranks our `-aio.N`, clicking Upgrade wipes our `.git`. Always bump
+  aio fork to `v<upstream>-aio.1` immediately on rebase.
+- **Catalog bumps don't require a `flake.lock` bump.** LNbits fetches the
+  manifest live; nix doesn't bake archives in. Explicit exception to the
+  "production-bound changes need a flake.lock bump" rule.
+
+### Extension version-bump procedure
+
+When user says "bump <ext> and update lnbits-extensions":
+
+1. Sanity-check ext repo: clean tree, on `main`, `git log <last-tag>..main`
+   matches intended release.
+2. Choose semver bump from the diff.
+3. **Push the branch first** (force-push after rebase OK for solo-maintainer
+   forks). Origin/main is recoverable; the tag isn't.
+4. **Test locally on dev LNbits BEFORE tagging.** Restart regtest to load
+   new on-disk code (or uninstall+reinstall via UI); smoke happy paths,
+   watch logs for migrations + exceptions. Once installs pull the catalog,
+   bad tags are hand-fix-every-install messy.
+5. Tag at HEAD and push: `git tag v… && git push origin v…`.
+6. Fetch archive, compute sha256: `curl -sL .../archive/v….zip | sha256sum`.
+7. Add a new entry to `aiolabs/lnbits-extensions/extensions.json` (don't
+   overwrite the old).
+8. Commit + push catalog. Live immediately — no flake.lock bump.
+
+### Forgejo issue labels (aiolabs/webapp)
+
+When creating issues on `aiolabs/webapp`, apply labels via
+`add_issue_labels` immediately on creation. Two axes:
+- **App scope:** `app:activities`, `app:webapp`, `app:marketplace`,
+  `app:wallet`, etc.
+- **Issue type:** `type:bug`, `type:feat`, `type:chore`, etc.
+
+### PR flow on aiolabs-forked extensions (default since 2026-06-12)
+
+For aio LNbits ext forks (`aiolabs/lnurlp`, `aiolabs/withdraw`,
+`aiolabs/events`, `aiolabs/libra`, …), **feature-branch + PR is the
+default flow** — these extensions move real money and feed production
+instances, putting them in the same review category as `aiolabs/lnbits`
+and `aiolabs/webapp`.
+
+**Why the flip** (was direct-commit-to-main while single-maintainer):
+a libra refactor regression (typed entry links breaking the approval
+flow, libra-#42) shipped straight to a production-feeding main on
+2026-06-12. The PR gate buys a review pause + a place for CI/tests
+before main moves.
+
+Flow: branch → push → open PR (creation via MCP is fine) → **hand off
+to the user to merge via the Forgejo web UI** (see PR-merge rule in
+user-global CLAUDE.md — the MCP merge endpoint is unreliable and the
+user has a final-review ritual). Trivial typo/docs-only commits can
+still ride direct-to-main at the user's discretion — ask if unsure.
+
+(L3 Forgejo branch protection on main for these repos is the parked
+enforcement follow-up, same as for lnbits/webapp.)
+
+### Issue closing — manual, not commit-keyword auto-close
+
+Do NOT use Forgejo closing keywords (`Closes #N`, `Fixes #N`) in commit
+messages on aiolabs repos. Reference issues as prose (`(libra-#42)` in
+the subject, plain `#42` in the body) and **close the issue manually**
+after the fix lands.
+
+**Why:** auto-close fires when the commit hits main, but on this stack
+"on main" ≠ "deployed" — issues should stay open (or at least be closed
+deliberately) until the fix actually reaches the affected instance.
+Confirmed by user 2026-06-12 (libra-#42).
+
+### aiolabs identity vs upstream
+
+Forks live on Forgejo at `git.atitlan.io/aiolabs/*`. User's handle there
+is `padreug`. Fork-internal references (contributors, repo URLs, PR/issue
+links) use Forgejo + `padreug`. GitHub handle (`your-github-username`) is separate
+— only for upstream PRs. Identity-rewrite details in user-global
+`~/.claude/CLAUDE.md`.
+
+---
+
+## LNbits extension development
+
+### Auth decorators
+
+| Decorator | Auth scope | Returns |
+|---|---|---|
+| `require_invoice_key` | Wallet invoice key — read access | Wallet |
+| `require_admin_key` | Wallet admin key — write to **own wallet only** | Wallet |
+| `check_admin` | **LNbits admin user** (super_user + lnbits_admin_users), Bearer | Account |
+| `check_super_user` | LNbits super user only, Bearer | Account |
+
+`require_admin_key` is **easily confused** with `check_admin` and means
+something very different. The first is a wallet-level write key (any user
+can have one for their own wallet); the second is LNbits-instance admin
+access. Use `check_admin` for cross-user / admin-only operations.
+
+### Testing
+
+Use FakeWallet (`LNBITS_BACKEND_WALLET_CLASS=FakeWallet`) for extension
+CRUD / API / UI tests. Spin up full regtest only when end-to-end Lightning
+payment behavior is actually under test (regtest costs build + container
+time and adds no fidelity for non-payment flows).
+
+### Fork-migrations pattern (`migrations_fork.py`)
+
+Per `aiolabs/lnbits#8` — fork-only schema deltas go in `migrations_fork.py`
+alongside the upstream-tracked `migrations.py`, loaded by our patched
+`migrate_extension_database()` under `<ext.id>_fork` in `dbversions`. Keeps
+upstream rebases conflict-free for the migration file.
+
+**Architecture facts:**
+
+- `dbversions` lives in the **core LNbits DB** (`database.sqlite3`), not
+  per-extension. Schema: `(db TEXT PRIMARY KEY, version INT)`;
+  `update_migration_version` is INSERT-OR-UPDATE so a new `<ext>_fork`
+  row appears on first run with no core-side migration.
+- Extension data tables live in `ext_<id>.sqlite3` (SQLite) or a Postgres
+  schema named after `<id>`. Created lazily on first `Database.connect()`.
+- **No cross-DB atomicity.** Extension migration commits to
+  `ext_<id>.sqlite3`; `dbversions` upsert commits to `database.sqlite3`.
+  If extension write succeeds and dbversions fails, migration is orphaned
+  and re-runs on next startup. **Every migration MUST be idempotent**
+  (`_alter_add_column_safe`, `CREATE TABLE IF NOT EXISTS`, etc.).
+
+**Squash recipe for adopting the pattern on existing forks:**
+
+1. Restore `migrations.py` to upstream-byte-identical (drop fork-only
+   functions and any helpers added for them).
+2. Create `migrations_fork.py` with a single `m001_aio_<ext>_schema`
+   that idempotently applies every fork-only delta the old migrations did.
+3. Use `_alter_add_column_safe` per ALTER and `CREATE TABLE IF NOT EXISTS`
+   per table — no-ops cleanly on installs that already ran old migrations.
+
+**One-time fix on installs adopting the pattern AFTER previously running
+old fork migrations:** their `dbversions['<ext>']` row is ahead of upstream
+(e.g. `events|11`). After moving to `migrations_fork`, the next upstream
+rebase that adds e.g. `m007` would compare `7 > 11 → false` and silently
+skip. **Reset the row before the rebase lands:**
+
+```sql
+-- Run against the core DB, not the extension DB.
+UPDATE dbversions SET version = <upstream-max> WHERE db = '<ext>';
+```
+
+Containerized: `docker compose exec lnbits python3 -c "..."` since the
+file is root-owned inside the container.
+
+**Upstream-overlap at rebase time:** if upstream eventually adds a schema
+change we already carry in `migrations_fork.py`, fresh installs work (our
+guards swallow dups) but **existing installs crash** when upstream's
+non-idempotent migration runs. Mitigation:
+
+1. **Prune the redundant block from `migrations_fork.py`** so future fresh
+   installs get the column from upstream.
+2. **Pre-deploy `dbversions` surgery on affected installs:**
+   `UPDATE dbversions SET version = <upstream-max> WHERE db = '<ext>'`.
+
+Don't patch upstream's migration with idempotency guards in our fork —
+breaks the "migrations.py == upstream byte-identical" property.
+
+**Upstream PR follow-up:** the extension loader change in
+`migrate_extension_database()` is upstreamable as a sibling to the
+in-flight `core_fork` PR (`your-github-username/lnbits @ add-fork-migrations-namespace`).
+Fork-internal patch for now.
+
+### Settings precedence — env seeds DB on first boot, then DB wins
+
+LNbits has two sources of truth for settings depending on lifecycle, and
+the switch happens automatically. Verified 2026-05-24 against `~/dev/lnbits/main`.
+
+**On boot with `lnbits_admin_ui=True`** (`lnbits/core/services/users.py:
+231-247`, `check_admin_settings`):
+1. Read DB row via `get_super_settings()`.
+2. If DB empty → seed from `.env` via `init_admin_settings()` (first-boot
+   only).
+3. `update_cached_settings(settings_db.dict())` overwrites in-memory
+   `Settings` with the DB row. **`.env` values loaded by Pydantic at
+   startup are clobbered.**
+
+**Practical consequence:** once an instance has booted once, editing
+`.env` and restarting **changes nothing** for editable fields. Change via
+Admin UI (`PUT /api/v1/settings`, gated by `check_admin`) or by clearing
+relevant `system_settings` table rows.
+
+**Exceptions where `.env` still wins every boot:**
+- `super_user` — env overrides DB at `users.py:243-245`.
+- `lnbits_admin_ui=False` — DB-load block skipped entirely.
+- All `ReadOnlySettings` fields (`settings.py:1132` + parents): `host`,
+  `port`, `lnbits_extensions_path`, `lnbits_path`, `lnbits_title` (API
+  title — NOT `lnbits_site_title` which is editable), `lnbits_data_folder`,
+  `lnbits_database_url`, `auth_secret_key`, `first_install_token`,
+  `lnbits_admin_ui`, `lnbits_allowed_funding_sources`.
+  `update_cached_settings` skips any key in `readonly_variables`. Editable
+  settings (site title/tagline, theme, watchdog, fee defaults, rate limits,
+  per-funding-source credentials, the whole Admin UI form) get DB-frozen.
+
+**`LNBITS_FIRST_INSTALL_TOKEN` rotation does NOT reset settings to env.**
+It creates a new super_user account with a fresh UUID and sets
+`settings.first_install = True`, re-enabling `/first_install` for a
+locked-out admin to re-claim the instance. No env values flow back through.
+
+**Deploy-side consequence for `deploy/server-deploy/modules/services/
+lnbits.nix`:** editable env vars only take effect on fresh install
+(empty `settings` table). For existing deploys, "set it in nix, redeploy,
+done" only works for `ReadOnlySettings` fields.
+
+---
+
+## Nostr architecture
+
+### Patterns reference is the source of truth
+
+Before writing or reviewing any Nostr-related code in `~/dev/webapp/`,
+read **`docs/nostr-patterns/`** first. After implementing or refining a
+pattern (or fixing a subtle Nostr bug), **update the relevant topic file
+in the same commit**. If new, add to the index. Drift between reference
+and code defeats the purpose.
+
+### Reference implementations (curated mirror)
+
+`~/dev/refs/repos/nostr/<owner>/<repo>/` holds upstream nostr codebases
+worth grepping for patterns: `nostr-protocol/nips`, `fiatjaf/khatru`,
+`fiatjaf/nostr-tools`, etc. Refresh weekly via `~/dev/refs/bin/refresh`;
+digest under `~/dev/refs/digests/`. For new features: check
+`docs/nostr-patterns/` (internal) → then `refs/repos/nostr/` (external).
+
+### Key in-flight initiatives
+
+- **LNbits nostr transport** — `aiolabs/lnbits` PR #4
+  (`nostr-native-transport` branch). NIP-44 v2 encrypted kind-21000 RPC
+  over relays, modeled after Lightning.Pub. Lets HTTP-allergic clients
+  (ATMs, kiosks behind NAT) reach LNbits through commodity relays.
+- **Lightning.Pub reference** — `~/dev/lamassu-next/lightning-pub/`. Key files:
+  `extension-loader/proto/autogenerated/ts/nostr_transport.ts`,
+  `extension-loader/src/services/nostr/nostrPool.ts`. Patterns: dual NIP-44
+  v1+v2 support, content sharding for large messages.
+
+### Long-term direction
+
+The eventual goal is webapp + LNbits extensions communicating **exclusively
+over Nostr** — eliminating HTTP. Prefer architectural decisions that move
+toward Nostr-native. Don't create HTTP-only patterns that will need to be
+ripped out. The nostr transport PR (#4) is the first concrete step.
+
+### Bunker for everything: no nsec at rest on LNbits
+
+Once `aiolabs/lnbits#18` (NIP-46 bunker integration) lands, **every nsec
+on the LNbits host gets retired** — operator users AND the server identity.
+There is no two-tier endgame where users go through bunker and the server
+keeps `NOSTR_TRANSPORT_PRIVATE_KEY` on disk.
+
+The plausible-looking carve-outs (server "conceptually different," boot
+bootstrap complexity, latency, failure modes) don't survive the threat
+model: the LNbits host runs extension code, payment plumbing, a public API
+— disk/root access there must NOT equal Nostr-identity compromise.
+
+**Concrete rules:**
+- Every signing call routes through the signer abstraction
+  (`lnbits.core.signers.resolve_signer` from `#17`). Impls: `LocalSigner`
+  (envelope-encrypted at rest, **transitional**), `ClientSideOnlySigner`
+  (operator-driven, no server signing), `RemoteBunkerSigner` (NIP-46 via
+  `#18` — endgame).
+- No `if server_is_special:` branch anywhere. Server identity is one more
+  account from the signer's perspective.
+- `NOSTR_TRANSPORT_PRIVATE_KEY` is acceptable as a transitional env-pinned
+  source for a `LocalSigner` adapter, but with an **explicit sunset**.
+- For extension code signing on behalf of operators: same abstraction. The
+  hybrid pattern at `aiolabs/spirekeeper` commit `e13178d` is the
+  template (try-import `resolve_signer`, fall back to direct prvkey on
+  pre-`#17` lnbits, both produce identical signed events).
+
+If tempted to keep static nsec "because it's just the server" or "because
+bunker isn't ready yet," push back: the whole point of bunker is removing
+static nsec from the LNbits host.
+
+### Respect protocol semantics over friction reduction
+
+When picking a transport / event-kind / message-format for a new feature,
+the protocol's intended use case wins over "an existing listener happens to
+fire." Quick-fix transport choices get locked in by callers and are harder
+to migrate later.
+
+**How to apply** — before wiring a new feature onto an existing listener:
+
+1. Name the relationship the feature serves (ATM↔Customer, ATM↔LNbits,
+   ATM↔Operator, Operator↔User, LNbits↔Bunker, …).
+2. Ask "what is this protocol / kind / RPC *for*?"
+3. If answers don't align, design or pick the right primitive even if a
+   wrong-purpose listener already exists.
+
+Exception: explicit, time-bounded stopgaps with a written migration path.
+
+**Worked example (2026-05-29 / `aiolabs/bitspire#56`).** Cassette-config
+publishing was nearly routed through `clink.onManagement` (kind-21003)
+because the listener existed. CLINK is a payment-flow protocol; repurposing
+would have conflated payment + operator-config concerns. The right
+primitive was kind-30078 (NIP-78 replaceable, NIP-44 encrypted,
+`["p", atm_npub]`-tagged).
+
+### Nostr kind allocations — avoid the CLINK band (21001–21003)
+
+The Nostr ephemeral range (20000–29999) is technically unallocated but
+several application-protocol families have squatted on specific kinds.
+**CLINK has claimed 21001 / 21002 / 21003** for Offers / Debits / Manage
+(see `refs/repos/shocknet/shocknet/CLINK/`). We want CLINK-compat preserved
+as we adopt it for ATM cash-in/cash-out flows.
+
+**Rule: kind:21001–kind:21099 is OFF-LIMITS for aiolabs-specific events.**
+CLINK may add adjacent kinds; on-the-wire collisions with
+`["clink_version"]`-tagged events aren't worth the namespace-squatting
+savings.
+
+**Suggested aiolabs band: 22000–22099** for non-replaceable application
+events specific to our stack. Pick incrementally; document each allocation
+here so future sessions don't reuse a number.
+
+**Settlement-receipt rotation (2026-06-02):** kind:21001 was originally
+locked in for bitSpire settlement receipts (`aiolabs/lnbits#22` +
+`aiolabs/spirekeeper#11`) before CLINK was in scope. Collision found
+during a CLINK primer review. Settlement receipts will land on a non-21001
+kind before either PR ships; rotation plan tracked on `aiolabs/spirekeeper#20`.
+
+**Replaceable events (kind:30000–39999) are a separate namespace.**
+Kind:30078 (NIP-78 application-specific data) is fine for fee_config,
+cassette state, fleet roster — by-design replaceable state-of-the-world
+events.
+
+### Standalone app pattern (webapp)
+
+Modules can be deployed as standalone PWAs alongside the main webapp via a
+**second Vite entry point**. Used for `activities` (sortir); may replicate
+for marketplace / wallet / others.
+
+For a new standalone app from an existing module:
+1. **HTML entry**: `<app-name>.html` at project root → `src/<app-name>-app/main.ts`.
+2. **App shell**: `src/<app-name>-app/{main.ts, App.vue}`.
+3. **Vite config**: `vite.<app-name>.config.ts` with its own build target
+   and PWA scoping (see service worker rules in `webapp/CLAUDE.md`).
+4. **npm script**: `dev:<app-name>` and (for the demo host) a roll-up.
+
+The standalone Vue frontend lives in `webapp/` alongside other AIO
+standalone apps (chat, forum, market, tasks, wallet, activities, libra) —
+the corresponding extension repo (`~/dev/shared/extensions/<name>/` if any)
+holds only the LNbits backend Python code.
+
+---
+
+## Matrix homeserver: Continuwuity
+
+Self-hosted Matrix homeserver in the Rust/conduwuit lineage. Lives in
+`deploy/server-deploy/modules/services/matrix.nix` for castle hosts that
+opt into `services.matrix-stack.enable`. Sibling stack: LiveKit SFU,
+lk-jwt-service, Element Web, Element Call SPA, `.well-known/matrix/`
+delegation on the apex.
+
+### Required config to avoid quiet breakage
+
+- **`well_known.client` + `well_known.server`** — without these,
+  Continuwuity uses `server_name` (the apex) when generating user-facing
+  URLs like password reset links. Set to `https://matrix.${domain}` and
+  `matrix.${domain}:443` to mirror the JSON nginx serves at
+  `/.well-known/matrix/` on the apex.
+
+- **`allow_registration = true` is safe.** It does NOT mean open
+  registration. Without `registration_token`/`_file` AND without the
+  `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`
+  flag, Continuwuity rejects self-serve signups.
+
+### First-user bootstrap
+
+When no admin exists yet, Continuwuity auto-generates a one-time
+registration token at startup and prints it to journalctl. This
+**overrides** any `registration_token_file` you might wire up. After the
+first user registers, they're auto-promoted to admin.
+
+### Admin commands
+
+All admin ops happen in the auto-created control room via `!admin <group>
+<cmd>`. Groups: `token`, `users`, `appservice`, `rooms`, `federation`,
+`media`, `server`. Full reference:
+<https://continuwuity.org/reference/admin/index.html>.
+
+Token issuance flags are **mutually exclusive** — pick exactly one of
+`--once`, `--max-uses N`, `--max-age <30s|5m|7d>`, `--immortal`.
+
+### Bridges + bots
+
+Continuwuity registers appservices via admin commands (`!admin appservice
+register` with pasted YAML), not via `app_service_config_files` like
+Synapse. The NixOS `services.mautrix-*.registerToSynapse` shortcut does
+NOT apply — bridges go through a manual paste step. Bot-only flows
+(maubot, custom matrix-nio scripts) don't need appservice registration.
+
+## Maubot plugin development
+
+Maubot is the standard Python plugin framework for Matrix bots; one
+running maubot daemon hosts many plugin-bots. Plugin source at
+`~/dev/maubot-plugins/<name>/`.
+
+### `maubot.yaml` — `database_type` is API style, not storage backend
+
+Valid values: `asyncpg` (modern, what `mautrix.util.async_db` provides) or
+`sqlalchemy` (legacy). NOT `sqlite` or `postgres` — that's the storage
+backend, chosen at the daemon level via `plugin_databases.sqlite` /
+`plugin_databases.postgres`. Wrong value fails at instance start with
+`RuntimeError: Unrecognized database type sqlite`.
+
+### Parent command + freeform text + subcommands
+
+For `!journal <text>` (parent) plus `!journal show [@user]` / `!journal
+today` (subcommands), `@command.new` needs **both** flags:
+
+```python
+@command.new("journal", require_subcommand=False, arg_fallthrough=False)
+@command.argument("text", pass_raw=True, required=False)
+async def journal(self, evt, text=""): ...
+
+@journal.subcommand("show", help="...")
+@command.argument("user", required=False)
+async def show(self, evt, user=None): ...
+```
+
+Without `require_subcommand=False`, non-subcommand input shows auto-help
+instead of recording. Without `arg_fallthrough=False`, `pass_raw=True`
+greedily consumes the rest, so `!journal show @alice` gets recorded as an
+entry. Same pattern as upstream `maubot/reminder`.
+
+### Multi-line freeform parent commands need `@command.passive`
+
+The above only works when **everything is on one line**. For multi-line
+content (`!journal\n- item one\n- item two`), `@command.new` silently
+drops it — maubot's parser only treats *space* as the command/args
+delimiter, so a newline immediately after the command name makes maubot
+fail to recognise the command at all. No handler invoked, no error logged.
+
+**Fix:** use `@command.passive` with a regex admitting any whitespace,
+then dispatch subcommands manually:
+
+```python
+_JOURNAL_RE = re.compile(r"^!journal(?:[ \t\r\n]+(.*))?$", re.DOTALL)
+
+@command.passive(regex=_JOURNAL_RE)
+async def journal(self, evt, match):
+    rest = (match[1] or "").strip()
+    if not rest: ...
+    first_token, _, after = rest.partition("\n")[0].partition(" ")
+    if first_token == "show": ...
+    else: ...  # record `rest` verbatim — multi-line preserved
+```
+
+You lose `@parent.subcommand("...")` ergonomics but gain reliability for
+prose-style inputs. **Rule of thumb:** for commands whose dominant use is
+free-text that may span lines, default to passive.
+
+### Database access (asyncpg style)
+
+```python
+from mautrix.util.async_db import UpgradeTable, Connection
+
+upgrade_table = UpgradeTable()
+
+@upgrade_table.register(description="Initial schema")
+async def upgrade_v1(conn: Connection) -> None:
+    await conn.execute("CREATE TABLE ...")
+
+class MyBot(Plugin):
+    @classmethod
+    def get_db_upgrade_table(cls) -> UpgradeTable:
+        return upgrade_table
+
+    @command.new("foo")
+    async def foo(self, evt):
+        await self.database.execute("INSERT INTO entries VALUES ($1, $2)", a, b)
+        rows = await self.database.fetch("SELECT ... LIMIT 10")
+```
+
+Placeholders are `$1, $2, ...` regardless of backend; `async_db` normalizes
+across asyncpg/aiosqlite.
+
+### Iteration loop
+
+Edit + bump `version` in `maubot.yaml`, then:
+
+```
+cd ~/dev/maubot-plugins/<plugin>
+zip -j ../<plugin>.mbp maubot.yaml <plugin>.py
+```
+
+Upload via Plugins → click existing plugin → upload new `.mbp`. Instance
+reload requires hitting **Save** on the instance after upload — toggling
+Enabled and walking away doesn't persist.
+
+### Wiping a plugin's data
+
+Each plugin has its own SQLite DB under `plugin_databases.sqlite`. Cleanest
+reset is the maubot UI's per-instance Database tab — `DELETE FROM <table>`
+runs against the live DB without restart. Nuking the file works but loses
+migration version tracking.
+
+### Pyright false positives
+
+`maubot` / `mautrix` imports unresolved + `.subcommand` "unknown attribute"
+warnings are expected — the SDK is dynamic and pyright can't introspect
+the decorators. Ignore.
+
+---
+
+## Upstream lnbits PR conventions
+
+For PRs to `github.com/lnbits/lnbits`:
+
+- **Base branch is `dev`, not `main`.** 100% of recent merged PRs target
+  `dev`. `main` gets release commits (`Merge branch 'dev'` + version bumps).
+- **Commit titles: lowercase conventional commits.** `feat:`, `fix:`,
+  `chore:`, `chore(deps):`, `docs:`, `ci:`. Not capitalized.
+- **Identity:** push under GitHub identity (`your-github-username`), not Forgejo.
+  See user-global `~/.claude/CLAUDE.md` for re-author details.
+
+Verified against last 25 merged PRs on 2026-04-28.
+
+---
+
+## Documentation discipline
+
+For any aiolabs repo with a structured `docs/` tree:
+
+**Any commit that materially changes a database table, an API endpoint,
+order/event flow, Nostr publishing convention, or CMS structure must
+update the relevant note in `docs/` in the same commit.** Architecture
+decisions get ADRs at `docs/adr-NNNN-<slug>.md`.
+
+Drift between docs and code defeats the purpose. Don't park doc updates
+for "later" — they get forgotten and docs lose signal.
+
+---
+
+## LNbits + Quasar UMD — frontend gotchas
+
+Applies to anything rendering into LNbits' page shell: lnbits core
+(`~/dev/lnbits/*`) and every extension (`~/dev/shared/extensions/*`,
+`~/dev/lnbits-extensions/`). All use **Vue 3 + Quasar 2 as UMD globals** —
+no build step, Jinja templates with per-page JS.
+
+**No self-closing tags.** Per Quasar's UMD rules
+(https://quasar.dev/start/umd/#usage), components need explicit-close:
+
+```html
+<!-- correct -->
+<q-input v-model="foo" label="Foo"></q-input>
+
+<!-- wrong — silently broken in UMD/no-build mode -->
+<q-input v-model="foo" label="Foo" />
+```
+
+Self-closing is fine in `.vue` SFCs (build step rewrites them), but
+UMD-loaded templates are parsed by the browser's HTML parser, which
+doesn't honor self-close on non-void elements — close tag gets implied at
+the wrong place, nesting breaks silently, subsequent siblings end up
+inside the prior component.
+
+**CSS specificity trap.** LNbits applies theme overrides on Quasar
+typography utilities (`.text-caption`, `.text-grey-*`) with `!important`.
+Class-based CSS in an extension — *even with `!important`* — loses unless
+the selector is strictly more specific. Inline `style` attrs (static or
+via Vue `:style`) win without an arms race.
+
+**Rule:** for per-element typography/color overrides on LNbits pages, use
+Vue `:style` bindings, not `<style>` blocks targeting utility classes.
+Background/border tweaks at card-level are fine via classes.
+
+**Cache busting.** Static assets served with `?v={server_startup_time}`
+(`lnbits/helpers.py: static_url_for`). Bumping JS requires server restart;
+Jinja templates re-render every request. If browser keeps serving stale
+JS after restart, hard-refresh (Ctrl+Shift+R) to bypass HTTP cache.
+
+**Dark-mode color discipline.** Pale `bg-{color}-1` utilities render
+white-on-cream under dark theme — pair every pale background with an
+explicit dark text class (`bg-red-1 text-grey-9` etc).