docs: surface lnbits workspace gotchas as a committed reference

New docs/lnbits-workspace-notes.md collects the day-to-day gotchas
that have repeatedly surprised people doing lnbits dev work — content
that lives in personal CLAUDE.md / memory notes elsewhere but is
genuinely useful as a public reference once stripped of identity.

Sections:
- pick a non-default port (5000 collides with macOS AirPlay etc.)
- LNBITS_SRC + docker-compose build context (commits don't reach
  the dev image if the build context points at a stale worktree;
  `docker compose config | grep -A2 lnbits` to verify)
- extension folder mounted as install target: clicking "Upgrade"
  in the LNbits UI extracts the catalog tarball over the mounted
  fork checkout, wiping .git
- Nostr key handling: upstream stores user nsecs plaintext in
  accounts.prvkey; signer-abstraction shape (LocalSigner with
  envelope-encrypted blob / RemoteBunkerSigner via NIP-46 /
  ClientSideOnlySigner) with the "prefer don't-store-the-key"
  principle
- CLINK protocol scope: Shocknet's 21001-21003 event kinds are
  Lightning.Pub-specific; LNbits has zero CLINK knowledge; how
  to think about cross-system designs without conflating them
- fork versioning: v<upstream>-<tag>.<N> + the PEP 440
  `+<tag>.<N>` package-version form for pyproject.toml
- codebase reading tips (key paths, --first-parent log reading)

Linked from README "Further reading". No personal identity in the
new doc — scrubbed of aiolabs/atitlan/bohm/etc references.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-05-25 20:24:28 +02:00
commit 6c9f76bd70
2 changed files with 167 additions and 0 deletions

View file

@ -202,6 +202,11 @@ lb fix-issue-123 # cd ~/dev/lnbits/fix-issue-123
- [`docs/lnbits-upstream-flow.md`](docs/lnbits-upstream-flow.md) —
reference for how `lnbits/lnbits` itself moves: `dev` / `main`
branch model, squash-merge convention, release tagging.
- [`docs/lnbits-workspace-notes.md`](docs/lnbits-workspace-notes.md) —
practical gotchas and design constraints for day-to-day lnbits work:
port choice, `LNBITS_SRC` build-context traps, the
extension-folder-upgrade-wipes-fork issue, Nostr key handling,
CLINK protocol scope, fork versioning.
## Contributing to this scaffold