docs: add AGENTS.md knowledge base (root, protocol engine, e2e)

AGENTS.md

@@ -0,0 +1,87 @@
+# 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, 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` | 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
+
+```bash
+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 comes from `github:TheCryptoDonkey/lnurlcash-kit` pinned to
+  a commit — the `prepare` script (our merged PR#1) builds dist on install.
+- 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).