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

src/lnurlcash/AGENTS.md

@@ -0,0 +1,50 @@
+# src/lnurlcash — protocol engine
+
+Framework-free LNURLcash core: no Vue, no Pinia, no Quasar imports. Pinia
+stores call these modules and apply returned changesets; UI never touches
+lnurlcash-kit directly.
+
+## FUND-CRITICAL INVARIANTS (non-negotiable)
+
+- Rotate on every receive, and immediately after claiming a fresh mint.
+- A note's declared amount is a claim; the service's `maxWithdrawable` is
+  authoritative.
+- A melt's "OK" only means the payment is in flight — the verify URL (or
+  the note becoming spendable again) is the real outcome.
+- An ambiguous mutation NEVER loses fresh secrets: rescued into tracked
+  notes, probed, or surfaced to the caller unverified.
+- Definitive service answers (NoteSpentError / NoteUnknownError /
+  PendingNoteError) always propagate distinctly — never papered over by an
+  unverified fallback.
+
+## STRUCTURE
+
+```
+ops.ts / ops/    # flows: carve (exact-amount), mint, pay, receiveBearer,
+                 # transfer (inter-mint); ops.ts is the façade
+storage/         # encrypted bearers + activity log, settings, backup,
+                 # nwcConnections, passkeySlots; storage.ts is the façade
+keys.ts          # BIP39, LUD-05 linking key derivation, password wrap
+passkeys.ts + passkeyWrap.ts   # WebAuthn PRF wrap (same linking key)
+nostrBackup.ts + nostr/        # kind-30078 backup, NIP-44 self-encryption
+nwc.ts + nwc/    # NIP-47 wallet service
+fees.ts          # mint fee math (gross/net direction!) + cached quotes
+trustedMints.ts  # key pinning, rekey staging, backup merge rules
+test-utils.ts    # mock mint harness used by *.test.ts
+```
+
+## CONVENTIONS
+
+- Style: NO semicolons, 2-space indent, single quotes, `{braced}` imports
+  without inner spaces — deliberately different from the rest of the app
+  (eslint override); keep the tested core diffable against its lineage.
+- Storage: localStorage keys `sattle_*`; strict shape validation on read,
+  malformed entries dropped; read-modify-write under `withStorageLock`.
+- Network: kit calls only; injectable transport/options so tests never
+  touch the network. No WebSocket at import time (lazy `import()`).
+- Every module header comment explains the WHY, including failure models.
+
+## TESTS
+
+`npx vitest run` — node environment, `*.test.ts` next to the modules.
+Adversarial mock mint from lnurlcash-conformance via test-utils.