docs: showcase the ~/dev/ workspace layout the dev-env materializes

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>

README.md

@@ -42,7 +42,7 @@ 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).
 
-## Layout
+## Repository layout
 
 ```
 flake.nix                       # inputs: nixpkgs, home-manager, lnbits-src
@@ -114,9 +114,38 @@ in follow-up passes.
 The `dev` CLI is the single entry point. See the top of this README
 for the verb set.
 
-### Project worktrees (planned)
+### Workspace layout (the `~/dev/` tree)
 
-Declare the projects you work in via `settings.nix`:
+The dev-env module's job is to put every project, every worktree, and
+every upstream PR in a predictable place — so navigation, grepping
+across reference code, and switching between branches stays mechanical.
+
+```
+~/dev/
+├── repos/                           # bare repos, one per project
+│   ├── lnbits.git
+│   ├── lnbits-extensions.git
+│   └── …
+│
+├── lnbits/                          # one dir per project; worktrees inside
+│   ├── main/                        #   worktree on `main`
+│   ├── dev/                         #   worktree on `dev`
+│   └── fix-issue-123/               #   ad-hoc feature worktree
+│
+├── lnbits-extensions/
+│   ├── main/
+│   └── …
+│
+├── upstream-prs/                    # PRs against upstreams (separate tree)
+│   ├── lnbits-fix-payment-race/     #   each worktree branched from upstream/main
+│   └── …
+│
+├── shared/                          # cross-project utilities / notes
+├── scratch/                         # ephemeral one-off scratchpads
+└── refs/                            # curated read-only reference repos
+```
+
+Declare which projects materialize via `settings.nix`:
 
 ```nix
 devEnv.projects = {
@@ -130,10 +159,38 @@ devEnv.projects = {
 };
 ```
 
-The forthcoming bootstrap script will materialize a bare repo at
-`${devEnv.root}/repos/lnbits.git` and check out one worktree per
-declared entry. Navigation helpers (`cd`-shortcuts à la omnixy's
-`lb dev`) get generated from the same project list.
+The forthcoming bootstrap (`dev bootstrap`, name TBD) materializes the
+bare repo at `~/dev/repos/lnbits.git` and checks out one worktree per
+declared entry.
+
+**Why bare repos + worktrees** (rather than fresh clones per branch):
+
+- One copy of the git object database on disk — five branches checked
+  out is five lightweight worktrees, not five clones.
+- `git fetch` once and every worktree sees the new refs.
+- The worktree directory name *is* the branch — no "wait, what am I on?"
+
+**Why a separate `upstream-prs/` tree:**
+
+PRs against upstream repos (e.g. `lnbits/lnbits`) want to branch from
+*upstream's* `main`, not your day-to-day fork. Mixing PR branches into
+the per-project tree pollutes the branch list and tempts "I'll just
+commit this here" accidents. The `upstream-prs/` tree makes the
+contract explicit: this worktree is on `upstream/main`, branch off,
+push to your fork, open the PR. Helper (planned):
+
+```
+prb lnbits fix-payment-race   # create ~/dev/upstream-prs/lnbits-fix-payment-race
+                              # branched from upstream/main, fork as push target
+```
+
+**Navigation helpers** (planned) — short aliases generated from
+`devEnv.projects`:
+
+```
+lb dev             # cd ~/dev/lnbits/dev
+lb fix-issue-123   # cd ~/dev/lnbits/fix-issue-123
+```
 
 ## Contributing