sattle/AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2026-08-20 Commit: 7841a13 Branch: main

OVERVIEW

sattle — end-user PWA wallet for LNURLcash (LUD-25) Lightning bearer notes. Quasar 2 / Vue 3 (script setup + TS) / Pinia / vue-i18n. Capacitor 8 Android wrapper lives in android/; the PWA is the canonical build.

STRUCTURE

src/lnurlcash/    # protocol engine + storage, framework-free (own AGENTS.md)
src/stores/       # Pinia: wallet, mints, activity, nostrBackup, nwc
src/components/   # dialogs (send/, receive/), QrCode, QrScanner, UnlockForm
src/pages/        # IndexPage (main), Settings*, ManageMints, MoveFunds, Nwc,
                  # Backup, Security, Welcome (onboarding)
src/capabilities/ # ONLY place Capacitor plugins are imported
src/boot/         # wallet init, deeplinks
e2e/              # Playwright (own AGENTS.md)

WHERE TO LOOK

Task	Location	Notes
Any fund movement	src/lnurlcash/ops/	engine returns changesets, never mutates state
Add a settings page	src/pages/ + router/routes.ts + SettingsPage group	back-button header pattern
Native feature	src/capabilities/	never import plugins elsewhere
Change wallet state	stores call ops + addBearers/markSpent	add fresh notes BEFORE marking spent
Mint fee math	src/lnurlcash/fees.ts	gross vs net direction matters

CODE MAP

Module	Role
lnurlcash/ops.ts	façade: carve/mint/pay/receiveBearer/transfer
lnurlcash/storage/	AES-GCM bearers+activity, owner-bound credentials and trusted mints, backup (merge entry point), settings
lnurlcash/keys.ts	BIP39 + LUD-05 linking key; password wrap
lnurlcash/passkeys.ts	WebAuthn PRF wrap of the SAME linking key
lnurlcash/nostrBackup.ts	kind-30078 NIP-44 backup + restore via applyBackup
lnurlcash/nwc/	NIP-47 wallet service (per-connection budget)
stores/wallet.ts	serialized owner lifecycle; state none/locked/unlocked; linking key in memory only while unlocked

CONVENTIONS

• Commit style: semantic (feat:, fix:, build:, ci:, test:), English.
• Releases: release-please (.github/workflows/release.yml) — never bump versions or write changelog entries by hand; merge the release PR.
• Hash router; BlankLayout for /welcome (q-page needs a layout).
• Dark theme, #002222 bg, mint #55ffcc primary; sattle-card surfaces.
• Quasar Notify plugin is enabled — use it for toasts.
• Brand assets: src/assets/sattle-{wallet,text}.png (raster; source SVGs live outside the repo).

ANTI-PATTERNS (THIS PROJECT)

• NEVER mutate wallet state inside src/lnurlcash/** — engine is pure.
• NEVER auto-apply a mint's advertised new signing key — stage as pending rekey.
• NEVER log note URLs / k1 values.
• No type suppression (as any, @ts-ignore) anywhere.
• No new runtime deps without a recorded reason (nostr-tools is the bar).

COMMANDS

npx quasar dev -m spa      # dev
npx vitest run             # unit (node env, mock mint)
npm run test:e2e           # playwright, system chromium (CHROMIUM_PATH)
npx vue-tsc --noEmit       # typecheck
npx quasar build -m pwa    # production build
npm run cap:sync           # build + cap sync android

NOTES

• NixOS: use the flake dev shell (nodejs_22 + chromium for e2e). sass-embedded is aliased to pure-JS sass via npm overrides.
• lnurlcash-kit@0.1.1 and lnurlcash-conformance@0.1.1 are exact npm registry packages. Keep their manifest pins, registry tarball URLs, and lock integrity values intact.
• Credential and authorization records are bound to the canonical owner ID derived from the linking key. Ordinary writes require an exact match with the persisted saved-key owner. Ownerless legacy records migrate only after a proven unlock, never from a restored file claim or passkey-first attempt.
• Wallet create, unlock, lock, restore, and forget transitions are serialized. Forget locks first, drains NWC, clears runtime keys and owner namespaces, then removes the saved key only after biometric deletion succeeds.
• Storage events are wakeups, not authoritative payloads. Re-read matching storage on an event, including key === null, before converging state or invalidating a stale owner tab. Web Locks serialize supported browsers but do not make another tab's localStorage cache current; trusted mints reconcile through a durable IndexedDB commit mirror before success. withStorageLock falls back to local execution without a cross-tab guarantee.
• tsconfig deliberately relaxed (exactOptionalPropertyTypes etc. off) to keep the protocol core untouched; src/lnurlcash has an eslint override.
• Gitea remote dropped; origin = GitHub. Gitea mirror = pull-mirror on the Gitea side (no secrets needed).