docs(readme): promote Claude orientation to a top-level section

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>
2026-05-26 08:38:52 +02:00 · 2026-05-26 08:38:52 +02:00 · 8ebf16d069
commit 8ebf16d069
parent 1a75a04c2f
1 changed files with 75 additions and 35 deletions
--- a/README.md
+++ b/README.md
@ -112,41 +112,9 @@ in follow-up passes.
 ### 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.
-
-### Claude orientation seeding (optional)
-
-If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
-opt in to having curated CLAUDE.md files seeded into your workspace.
-The files live under `files/` in this repo and are symlinked into
-`~/dev/` via home-manager's `mkOutOfStoreSymlink` — edits in your
-checkout take effect on the next Claude session, no rebuild.
-
-Wire it in `settings.nix`:
-
-```nix
-devEnv = {
-  enable = true;
-  scaffoldPath = "/home/<you>/dev/lnbits-sensei";   # absolute path to your checkout
-  claude = {
-    enable = true;                                  # ~/dev/lnbits/CLAUDE.md
-    workspaceOrientation = false;                   # also ~/dev/CLAUDE.md (opt-in;
-                                                    # clobbers any existing one)
-  };
-};
-```
-
- `claude.enable` seeds `~/dev/lnbits/CLAUDE.md` from
-  `files/lnbits-CLAUDE.md` — project-level orientation that loads for
-  any Claude session in the lnbits worktree subtree (settings
-  precedence, Quasar UMD self-closing-tag rule, auth-decorator
-  distinctions, …).
- `claude.workspaceOrientation` *additionally* seeds `~/dev/CLAUDE.md`
-  from `files/dev-CLAUDE.md` — generic workspace orientation. Off by
-  default because most people already maintain their own.
-
-If you don't use Claude Code, leave both off — the same content is in
-`docs/` for human reading.
+for the verb set. See **[Claude orientation](#claude-orientation)**
+below if you want AI-assisted work to pick up the project's gotchas
+for free.

 ### Workspace layout (the `~/dev/` tree)

@ -226,6 +194,78 @@ lb dev             # cd ~/dev/lnbits/dev
 lb fix-issue-123   # cd ~/dev/lnbits/fix-issue-123
 ```

+## Claude orientation
+
+For workflows that use [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+lnbits-sensei ships curated workspace orientation that gets symlinked
+into `~/dev/` so AI-assisted work picks up lnbits-specific gotchas
+without anyone copying files around or re-explaining them in every
+session.
+
+**Concrete example.** A Claude session iterating in
+`~/dev/lnbits/extensions/<my-ext>/templates/` automatically inherits
+the per-project `CLAUDE.md` from `~/dev/lnbits/`, which carries the
+**Vue/Quasar UMD "no self-closing tags"** rule. Without that seed,
+Claude would happily emit:
+
+```html
+<q-input v-model="amount" label="Amount" />
+```
+
+Correct in any Vue SFC repo, **silently broken** under LNbits's UMD
+load model — the browser's HTML parser doesn't honor self-close on
+non-void elements, the close tag gets implied at the wrong place, and
+nesting corrupts. With the seed loaded, the model writes:
+
+```html
+<q-input v-model="amount" label="Amount"></q-input>
+```
+
+— the form that actually works. Same story for every other gotcha
+the per-project CLAUDE.md surfaces:
+
+- **Settings precedence** — editing `.env` post-first-boot is a no-op
+  for editable fields. AI knows to check `system_settings` rows or
+  Admin UI, not chase env-var edits.
+- **Auth decorators** — `require_admin_key` (per-wallet write) ≠
+  `check_admin` (instance admin). Easy to misuse.
+- **Upstream PR target** — `lnbits/lnbits` accepts PRs against `dev`,
+  not `main`. Lowercase conventional-commit titles.
+- **CLINK ↔ LNbits scope** — `ndebit` / `noffer` semantics live in
+  Lightning.Pub, not LNbits. Don't propose CLINK shims for LNbits.
+
+The full set lives in `docs/`; the seeded `CLAUDE.md` files are tight
+summaries with pointers back.
+
+### How it works
+
+Files in this repo's `files/` directory are symlinked to your `~/dev/`
+paths via home-manager's `mkOutOfStoreSymlink` — edits in your
+checkout take effect on the next Claude session, no rebuild.
+
+- `files/lnbits-CLAUDE.md` → `~/dev/lnbits/CLAUDE.md` (per-project)
+- `files/dev-CLAUDE.md` → `~/dev/CLAUDE.md` (workspace, opt-in)
+
+### Wiring
+
+In your `settings.nix`:
+
+```nix
+devEnv = {
+  enable = true;
+  scaffoldPath = "/home/<you>/dev/lnbits-sensei";   # absolute path
+  claude = {
+    enable = true;                # ~/dev/lnbits/CLAUDE.md
+    workspaceOrientation = false; # also ~/dev/CLAUDE.md (opt-in;
+                                  # clobbers any existing one)
+  };
+};
+```
+
+If you don't use Claude Code, leave both off — the same content is in
+`docs/` for human reading. The seeding is purely an optional layer on
+top of the human-facing docs, not a replacement for them.
+
 ## Further reading

 - [`docs/remotes.md`](docs/remotes.md) — the three remote-topology