The root README pitched a unified 'dev up' CLI and called the dev-env
stubs — both stale now that the real implementation has landed. Rewrite
the status header, the day-to-day command set, the module file tree, and
drop the (planned)/(stub) markers on bootstrap, prb, and nav helpers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New docs/secrets-management.md walks through getting secrets out of
.env and into sops-encrypted YAML, assuming zero familiarity with
sops or age. Companion to the wiring landed in the prior commit.
Sections:
- Why bother — the .env failure modes (history leaks, plaintext on
disk) and what sops/age fixes.
- What's in the box — pointers to the existing scaffold (flake input,
modules/secrets.nix, .sops.yaml, .gitignore guards), why it's inert
until the first encrypted file lands.
- Step-by-step — install tools, generate the age key (with a clear
warning about back-ups + no recovery), paste the public key into
.sops.yaml, create the first encrypted file via `sops`, declare
secrets in NixOS, reference via config.sops.secrets.<name>.path,
activate.
- Common operations — edit / view / rotate / updatekeys.
- Multi-host server deployment — per-host age keys at
/var/lib/sops-nix/key.txt, path_regex-scoped recipients in
.sops.yaml so each host only decrypts its own secrets.
- Pitfalls — don't commit unencrypted YAML, don't lose the key,
updatekeys ≠ rotation, sops -d outputs are sensitive, the
pathExists gate fails-silently-on-delete trap.
Linked from README "Further reading" with a one-liner noting the
sops-nix wiring already ships with the scaffold.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The seeding mechanism was previously buried as a sub-subsection inside
Development flow. Promote it to its own ## Claude orientation section
with a concrete value-prop: a Claude session in
~/dev/lnbits/extensions/<ext>/templates/ inherits the Vue/Quasar UMD
"no self-closing tags" rule from the per-project CLAUDE.md, so the
model writes the explicit-close form instead of the silently-broken
self-close that would corrupt LNbits template nesting.
Lists the other gotchas the seeding surfaces (settings precedence,
auth decorators, upstream PR target, CLINK ↔ LNbits scope) so a
reader scanning the README sees what they get without enabling the
option first.
Development flow's day-to-day subsection now points down to the new
section instead of explaining the wiring inline; the wiring snippet
moved to the Claude orientation section where it sits next to the
value-prop.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two new docs to round out the lnbits-specific reference set:
docs/lnbits-frontend-gotchas.md — the Vue/Quasar UMD traps that don't
manifest under the build-step model most tutorials assume. Sections:
- No self-closing tags. UMD-loaded templates are parsed by the
browser's HTML parser, which doesn't honor self-close on non-void
elements; nesting silently breaks. Fine in .vue SFCs because the
build step rewrites them — but lnbits templates aren't SFCs.
- CSS specificity vs Quasar utilities. LNbits applies !important
overrides on .text-caption / .text-grey-*; class-based rules in
extension pages lose. Reach for inline :style bindings or static
style="" attrs instead.
- Cache busting via ?v={server_startup_time}. Bumping JS requires a
server restart; templates re-render every request.
- Dark-mode color discipline. bg-{color}-1 utilities don't get a
default text-inversion in dark theme; pair every pale background
with an explicit text class.
docs/lnbits-extension-dev.md — auth + testing + migration pattern.
Sections:
- Auth decorators table: require_invoice_key, require_admin_key,
check_admin, check_super_user. The require_admin_key vs
check_admin distinction is the most common misuse — one is
wallet-level write access (any user), the other is instance admin.
- Testing: FakeWallet for CRUD/API/UI, regtest only for real
Lightning behavior. Why the dev CLI defaults to --fakewallet.
- The migrations_fork.py pattern: keep migrations.py byte-identical
to upstream, put fork-only schema deltas in a sibling file loaded
under <ext>_fork in dbversions. Covers: architecture facts
(dbversions in core DB, no cross-DB atomicity → idempotent
migrations mandatory), squash recipe for adoption, one-time
dbversions surgery for installs that previously ran old fork
migrations, the upstream-overlap rebase scenario.
Both linked from README "Further reading". No personal identity in
either file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the omnixy-pattern out-of-store-symlink wiring so consumers can
opt into Claude Code orientation without copying anything by hand.
Files live in lnbits-sensei (so they evolve via PR), symlinks point
back at the consumer's checkout (so edits take effect on the next
Claude session without a nixos-rebuild).
New files under files/:
- dev-CLAUDE.md — generic workspace orientation. Workspace layout,
quick command set, pointers to docs/. Opt-in (clobbers an existing
~/dev/CLAUDE.md, so off by default).
- lnbits-CLAUDE.md — per-project orientation for the lnbits worktree
subtree. Inline summary of the four most-stepped-on gotchas
(settings precedence, Quasar UMD self-closing rule, auth-decorator
distinctions, upstream PR target = `dev` not `main`) plus pointers
to the docs/ for full reference.
New options under lnbits-sensei.devEnv:
- scaffoldPath — absolute path to the consumer's lnbits-sensei
checkout. types.str (not types.path) intentionally: types.path
would copy the file into the Nix store and defeat
mkOutOfStoreSymlink. Required when any claude.* flag is on.
- claude.enable — seeds ~/dev/lnbits/CLAUDE.md.
- claude.workspaceOrientation — additionally seeds ~/dev/CLAUDE.md.
Wiring lives in home.nix (gated via `osConfig.lnbits-sensei.devEnv.*`)
rather than the dev-env NixOS module, since the file destinations are
under home-manager's purview and the home-manager scope is where
`mkOutOfStoreSymlink` is in scope.
`nix flake check` stays green — `optionalAttrs` is lazy, so
`scaffoldPath` isn't accessed when claude.{enable,workspaceOrientation}
are both false (their defaults).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
Two new docs under docs/:
- upstream-prs.md — how to send a PR upstream using the
~/dev/upstream-prs/ worktree flow. Opens with a "Primer" section
for anyone new to forks / pull requests (the three remote roles —
upstream / github-fork / origin — explained as a table), then the
per-project prerequisites, the prb/prc helper-driven workflow, and
a "Common pitfalls" section.
- lnbits-upstream-flow.md — reference for how lnbits/lnbits actually
moves: the dev/main branch split, the squash-merge PR convention,
the non-FF release merge from dev into main, and how to read the
history with --first-parent. Adapted from internal aiolabs notes
with the fork-versioning specifics stripped; closing section is
generic guidance for anyone maintaining their own long-lived fork.
README links both from a new "Further reading" section. The prior
"Contributing" section is retitled "Contributing to this scaffold"
to avoid colliding with the new upstream-PR doc on the term.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous "Project worktrees (planned)" subsection only described
one project's worktrees in the abstract. Replace with a section that
shows the full ~/dev/ tree the dev-env module is designed to build —
bare repos under `~/dev/repos/`, per-project worktree dirs, and a
separate `~/dev/upstream-prs/` tree for PRs branched from upstream's
main.
Includes the rationale (one object DB, no clone churn; explicit PR
contract via the separated tree) and stub examples of the navigation
helpers (`lb dev`, `prb lnbits foo`) the module will eventually
generate from `devEnv.projects`.
Renames the prior "## Layout" → "## Repository layout" so the README
distinguishes the two trees (this repo's source layout vs the
on-disk workspace it manifests).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds two sections to the README:
- `## Layout` — annotated tree of the actual files in the repo, with
`(stub)` markers on the modules whose bodies are TODO. Replaces the
previous "Planned shape" bullet list (was aspirational and lying about
files that didn't exist, e.g. `modules/lnbits/`).
- `## Development flow` — three subsections: first-time bootstrap (clone,
settings, nixos-generate-config, flake check, switch), day-to-day via
the `dev` CLI, and project worktrees from `devEnv.projects`.
Status line bumped from "scaffold in progress" to "eval-green skeleton"
to match where we actually are — module schema + flake wiring are real,
CLI + dev-env bootstrap remain stubs.
Renames `## Development` to `## Contributing` since "Development flow"
is now the user-facing section.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects the post-cleanup shape: single `dev up [--fakewallet|--regtest]`
entry point (the two parallel wrappers are gone), no modules/lnbits/
line (deleted), license footer points at the MIT file we already shipped,
and a settings.nix.git.remotes snippet so a reader sees the topology
toggle without opening docs/remotes.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empty placeholder commit anchoring the repo. Substantive scaffolding
(flake.nix, modules/, settings.nix) lands in follow-ups iterated under
the sandboxed-claude policy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
