diff --git a/CLAUDE.md b/CLAUDE.md
index 1ab8ab6..58e6517 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,55 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `npm run preview` - Preview production build locally
 - `npm run analyze` - Build with bundle analysis (opens visualization)
 
+**`npm run dev` serves the hub ONLY — standalone apps need their own script**
+
+Each standalone PWA (events, libra, wallet, chat, market, tasks, forum, …)
+is a separate Vite entry point with its own config, and the default dev
+server cannot serve it. Visiting `/events` under `npm run dev` returns a
+**500**, because `src/events-app/main.ts` imports `virtual:pwa-register`,
+which only exists when the PWA plugin from `vite.events.config.ts` is
+loaded:
+
+```
+[vite] Internal server error: Failed to resolve import
+"virtual:pwa-register" from "src/events-app/main.ts". Does the file exist?
+```
+
+The page renders an empty body, so it presents as a broken route or a
+relay-sync problem rather than a missing plugin. Use the per-app script:
+
+```
+npm run dev:events     # also dev:libra, dev:wallet, dev:chat, dev:market,
+                       # dev:tasks, dev:forum, ...
+```
+
+Vite takes the next free port (5181 when 5173 is busy), and **a standalone
+app routes only `/`, `/login`, `/settings`** — an event detail opens by
+clicking its card in the feed, not by navigating to `/<event-id>`, which
+falls through to the list.
+
+**Testing ticket purchases against a local LNbits**
+
+The purchase endpoint validates `frontend_url` against the instance's CORS
+allow-list and fails closed:
+
+```
+HTTP 400 {"detail":"frontend_url origin is not allowed."}
+```
+
+That is `_resolve_frontend_root` in the events extension working as
+designed — a wrong root means the buyer is returned to, and emailed a link
+into, the wrong app. Add the dev-server origin (e.g.
+`http://localhost:5181`) to `lnbits_cors_allowed_origins` before expecting
+a click-through purchase to complete locally.
+
+Create a throwaway buyer with `POST /api/v1/auth/register` (`username`,
+`password`, `password_repeat`); the login page opens on its "Demo Account"
+tab, so switch to **Sign In** before filling the credential fields.
+
+Note `CLAUDE.md` is **not** prettier-managed — running `prettier --write`
+on it reformats ~90 lines of embedded TypeScript samples. Leave it alone.
+
 **Electron Development**
 - `npm run electron:dev` - Run both Vite dev server and Electron concurrently
 - `npm run electron:build` - Full build and package for Electron