diff --git a/README.md b/README.md
index fb3f4b5..8030ac6 100644
--- a/README.md
+++ b/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