From 6cabca3113fb8cecc7801ec74b6a05c27cd5180e Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 25 May 2026 13:09:46 +0200
Subject: [PATCH] docs: rewrite README around the dev CLI + remotes

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>
---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index a22dbbe..5054e8b 100644
--- a/README.md
+++ b/README.md
@@ -7,33 +7,55 @@ Opinionated, bare-skeleton scaffold for running an LNbits stack
 NixOS module pattern but stripped of any personal identity so the
 template is consumable as-is.
 
-The goal: clone, fill in your identity + remote topology (upstream
-only / github fork / extra private remote on gitea, forgejo,
-codeberg, …), and get a working LNbits dev environment with either:
+The goal: clone, fill in your identity + remote topology, and get a
+working LNbits dev environment driven by one command:
 
-- **FakeWallet** — no docker, no chains, nothing to start. Fast
-  iteration on extensions and frontend work.
-- **Full regtest** — multi-node LND + CLN + Eclair stack with
-  bitcoind, electrs, boltz, etc. For channel/payment integration
-  testing.
+```
+dev up                 # default: FakeWallet — no docker, instant
+dev up --regtest       # full multi-node regtest stack (LND + CLN + Eclair
+                       # + bitcoind + electrs); for channel/payment
+                       # integration testing
+dev down               # tear down whatever's running
+dev logs               # follow lnbits (+ docker, if regtest)
+dev shell              # drop into the lnbits venv (or a regtest container)
+```
+
+`--fakewallet` is the default mode because the iteration loop for
+extension and frontend work doesn't need real chains. `--regtest`
+exists for the moments when it does.
+
+## Remote topology
+
+`settings.nix` exposes three slots so the same scaffold works whether
+you push to GitHub only, run a private mirror, or both:
+
+```nix
+git.remotes = {
+  upstream = "https://github.com/lnbits/lnbits";   # always
+  fork     = null;                                  # or "https://github.com/<you>/lnbits"
+  extras   = [];                                    # or [{ name = "private"; url = "ssh://…"; }]
+};
+```
+
+See [`docs/remotes.md`](docs/remotes.md) for the three canonical
+patterns (upstream-only, github-fork-for-PRs, multi-remote-with-private
+host on forgejo / gitea / codeberg / sourcehut).
 
 ## Planned shape
 
 - `flake.nix` — pins `lnbits/lnbits` upstream + dev tooling.
-- `settings.nix` — single source of truth (user, email, host, remote
-  topology). User fills in.
-- `modules/lnbits/` — opinionated LNbits NixOS module.
-- `modules/dev-env/` — worktree mgmt, navigation helpers, regtest
-  spin-up, fakewallet default, upstream-PR helper. Generalized off
+- `settings.nix` — single source of truth (user, host, timezone, remote
+  topology). Consumer fills in.
+- `modules/core.nix` — `lnbits-sensei.*` option schema (features, bind addr).
+- `modules/git/remotes.nix` — remote topology abstraction.
+- `modules/dev-env/` — the `dev` CLI, worktree mgmt, regtest stack
+  spin-up, tmux session launcher, upstream-PR helper. Generalized off
   any private-host assumptions.
-- `modules/git/remotes.nix` — abstract remote topology (`upstream`,
-  `fork`, optional `extras` list).
 
 ## Development
 
 This repo is iterated on under the sandboxed-claude policy from
-[omnixy](https://github.com/TheArctesian/omnixy)'s
-`scripts/sandbox-claude.sh` — a per-launch `.claude/settings.json`
+omnixy's `scripts/sandbox-claude.sh` — a per-launch `.claude/settings.json`
 that allows nix/git/inspection and hard-denies sudo, push/remote,
 container engines, etc. Substantive scaffolding work happens in that
 sandbox; promotion (`git push`) is done from the main shell after
@@ -41,4 +63,4 @@ review.
 
 ## License
 
-TBD — leaning MIT to match omnixy.
+[MIT](LICENSE).