diff --git a/README.md b/README.md
index 5054e8b..fb3f4b5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # lnbits-sensei
 
-> **Status:** scaffold in progress. Not yet usable.
+> **Status:** eval-green skeleton. Module schema + flake wiring are real;
+> the `dev` CLI and dev-env bootstrap are stubs. Not yet usable end-to-end.
 
 Opinionated, bare-skeleton scaffold for running an LNbits stack
 — inspired by the [omnixy](https://github.com/TheArctesian/omnixy)
@@ -41,21 +42,103 @@ 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
+## Layout
 
-- `flake.nix` — pins `lnbits/lnbits` upstream + dev tooling.
-- `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.
+```
+flake.nix                       # inputs: nixpkgs, home-manager, lnbits-src
+flake.lock
+settings.nix                    # consumer fills in: user, host, identity, remotes
+configuration.nix               # NixOS entry — thin imports list
+home.nix                        # home-manager entry — thin
+hardware-configuration.nix      # placeholder; overwrite with nixos-generate-config
 
-## Development
+modules/
+├── core.nix                    # lnbits-sensei.* option schema
+├── lib.nix                     # shared helpers — config.lnbits-sensei.lib (stub)
+├── git/
+│   └── remotes.nix             # remote topology (upstream / fork / extras)
+└── dev-env/
+    ├── default.nix             # module entry; imports options + config + lib
+    ├── options.nix             # devEnv schema (projects, regtest, tmux)
+    ├── config.nix              # wires the schema into NixOS config (stub)
+    ├── lib.nix                 # dev-env-internal helpers (stub)
+    └── scripts/
+        └── dev.sh              # `dev` CLI dispatcher (stub)
 
-This repo is iterated on under the sandboxed-claude policy from
-omnixy's `scripts/sandbox-claude.sh` — a per-launch `.claude/settings.json`
+docs/
+└── remotes.md                  # the three remote-topology patterns
+
+LICENSE                         # MIT (placeholders — fill in year + holder)
+```
+
+`(stub)` files contain option schemas and TODO bodies; they evaluate
+cleanly but don't do real work yet. Substantive implementations land
+in follow-up passes.
+
+## Development flow
+
+### First-time bootstrap (per machine)
+
+1. **Clone** the repo into a working directory of your choice.
+
+2. **Edit `settings.nix`** — fill in `user`, `hostName`, `timeZone`,
+   `gitName`, `gitEmail`, and `git.remotes` (see
+   [docs/remotes.md](docs/remotes.md) for topology patterns).
+
+3. **Replace the placeholder hardware config** with your real one:
+
+   ```sh
+   sudo nixos-generate-config --root / --dir $(pwd)
+   ```
+
+   (The shipped `hardware-configuration.nix` evaluates but won't boot —
+   intentional, so a forgotten regeneration fails loudly rather than
+   silently booting on someone else's disk layout.)
+
+4. **Validate** the schema before activating anything:
+
+   ```sh
+   nix flake check --no-build
+   ```
+
+   Should print `all checks passed!`.
+
+5. **Switch** when ready:
+
+   ```sh
+   sudo nixos-rebuild switch --flake .#<hostName>
+   ```
+
+### Day-to-day (planned — `dev.sh` is a stub today)
+
+The `dev` CLI is the single entry point. See the top of this README
+for the verb set.
+
+### Project worktrees (planned)
+
+Declare the projects you work in via `settings.nix`:
+
+```nix
+devEnv.projects = {
+  lnbits = {
+    url = "https://github.com/lnbits/lnbits";
+    worktrees = {
+      main = { branch = "main"; };
+      dev  = { branch = "dev"; };
+    };
+  };
+};
+```
+
+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.
+
+## Contributing
+
+Iteration happens under the sandboxed-claude policy from 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