From 8ebf16d06968de49829629fb91fda192bcffee63 Mon Sep 17 00:00:00 2001 From: Padreug Date: Tue, 26 May 2026 08:38:52 +0200 Subject: [PATCH] docs(readme): promote Claude orientation to a top-level section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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//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) --- README.md | 110 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 8dd7b38..43fbc08 100644 --- 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//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//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 + +``` + +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 + +``` + +— 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//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