create-caspian-app 1.5.3 → 1.5.5

package/dist/.github/copilot-instructions.md

@@ -24,6 +24,9 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 
 ## Global Rules
 
+- **Required frontend feedback loop:** for every UI change or browser-error fix, run `npm run logs` before editing and after reloading the affected route and exercising the changed interactions. It reads `.casp/browser-log.jsonl`; the developer's terminal is not your only source of frontend errors. Read both errors and warnings. A green Python/template/test gate or a visually correct first paint is not browser verification. If the browser or dev session is unavailable, report that verification gap explicitly.
+- **Read `pp.props` in the owning script, never directly in authored markup.** Forward incoming props onto the native root, then expose top-level script bindings: `const dialogOpen = !!pp.props.open; const isRotating = !!pp.props.rotate; const projectId = pp.props.projectId || '';`. Use `open="{dialogOpen}"`, `hidden="{isRotating}"`, and `project-id="{projectId}"`. Nested boundary/slot evaluation does not guarantee the script-local prop bag; `open="{!!pp.props.open}"` can throw even when root forwarding is correct. Script-defined callbacks/effects/RPC handlers may use `pp.props`. Do not mask this with optional chaining, replace browser `{...}` with Jinja `{{...}}`, or freeze derived props in state. Read `pulsepoint.md` "Read props in the script, bind names in markup" and `components.md` before editing prop-driven components.
+
 - Use this decision order: `caspian.config.json` for optional feature enablement, app runtime and app-owned code for current project behavior, matching workspace instruction files under `.github/instructions/**/*.instructions.md` for task-specific implementation guidance, installed `casp` runtime for framework internals, and packaged markdown docs for Caspian feature discovery and task routing.
 - As the app grows, prefer `src/components/` for reusable application UI and reserve `src/lib/` for reusable non-UI code such as services, validators, adapters, and shared helpers.
 - Read `./caspian.config.json` almost immediately before making feature, tooling, scaffolding, or file-placement decisions. Treat it as the workspace feature gate for flags such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, `websocket`, and `componentScanDirs`.
@@ -45,7 +48,7 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Use `npm run build` for deployment prep or an explicit build request, not as the default validation step for routine route, feature, or documentation edits.
 - **This workspace has an app-level quality gate, and running it is mandatory — not optional.** Any time you create, edit, or delete app-owned Python (`main.py`, `src/**`) — whether fixing a bug, adding a new file, refactoring, or implementing a feature — you must run `npm run check` (which calls `uv run python settings/check.py`) and get it fully green before treating the change as done. **A change is not complete while the gate reports anything.** It type checks with `pyright`, lints with `ruff`, and runs `pytest` in one pass, prints each problem as `path:line:col [tool:code] message`, and exits non-zero; fix every reported location and re-run until it passes clean. Do not report work as finished, hand it back, or move on to the next task on the assumption that it passes — actually run it and confirm green output first. Write app-owned Python to pass type checking (annotate parameters and returns, avoid untyped `Any` drift) and add or extend tests in `tests/` for the behavior you change. See `### tests/**/*.py and settings/check.py`.
 - **Know the gate's boundary: `npm run check` validates Python only** (`pyright` + `ruff` + `pytest` over `main.py`, `src/**`, and `settings/*.py`). It does **not** validate authored markup (the templates inside `index.py`, `layout.py`, and component `.py` files), `globals.css`/Tailwind, or `public/js/**` — a broken template, an invalid `x-*` tag, a single-root violation, or a PulsePoint error will pass the gate and only surface at render time. So a green gate means "the Python is sound," not "the page works." When you change templates, components, styles, or browser JS, verify them by actually loading the affected route in the browser (use the BrowserSync URL from `./settings/bs-config.json`) and checking it renders without console errors — do not treat a passing `npm run check` as proof that front-end work is correct.
-- **To see browser-side errors, run `npm run logs` — never start a second `npm run dev`.** The dev terminal usually belongs to the developer, so its stdout is invisible to you. `npm run dev` starts by deleting `.casp/` and `caches/`, so launching your own copy corrupts the running server's state, takes different ports, and rewrites `settings/bs-config.json`. Instead, PulsePoint's browser errors are appended to `.casp/browser-log.jsonl` and rendered by `npm run logs` (also printed at the end of every `npm run check`, where it never affects the exit code). Read its verdicts literally: `CLEAN` means that route was opened and rendered without error; a route **absent from the listing was never opened**, which is no signal rather than a pass; and `dev server is NOT running` means the entries are leftover history, not current state. After a fix, get the route exercised again and re-run `npm run logs`; the flip to `CLEAN` is your confirmation. **What counts as exercising it depends on the status:** a mount error is cleared by a reload, but `NEEDS RECHECK` means an error thrown from an event handler, which only re-running that interaction (click/submit) can clear — a reload never will, and must not be reported as if it did. **Never diagnose from the raw `.casp/browser-log.jsonl`:** it is append-only history, so errors fixed minutes ago are still on disk and will send you hunting a bug that no longer exists — any later `load` or `resolved` event for the same route makes them historical. `UNCONFIRMED` means an error with no matching load in this log (a tab left open across a dev restart); ask for a reload before treating it as live. Details in `AGENTS.md`.
+- **To see browser-side errors, run `npm run logs` — never start a second `npm run dev`.** The dev terminal usually belongs to the developer, so its stdout is invisible to you. `npm run dev` starts by deleting `.casp/` and `caches/`, so launching your own copy corrupts the running server's state, takes different ports, and rewrites `settings/bs-config.json`. Instead, PulsePoint's browser errors are appended to `.casp/browser-log.jsonl` and rendered by `npm run logs` (also printed at the end of every `npm run check`, where it never affects the exit code). Read its verdicts literally: `CLEAN` means that route was opened and rendered without error; a route **absent from the listing was never opened**, which is no signal rather than a pass; and `dev server is NOT running` means the entries are leftover history, not current state. After a fix, reload and exercise the affected route, then re-run `npm run logs`; verify the behavior and absence of fresh errors or relevant warnings. **What counts as exercising it depends on the status:** a mount error is cleared by a reload, but `NEEDS RECHECK` can mean an interaction error or an error carried across a source change. Repeat the affected interaction (click/submit). The reporter does not observe successful clicks, so historical recheck entries can remain; report the retest evidence and remaining history separately instead of claiming the digest is `CLEAN`. **Prefer the digest over raw `.casp/browser-log.jsonl`:** the file includes history and is compacted on source changes. A later matching load can retire earlier mount errors, but interaction and carried entries can still need rechecking. If inspecting raw events to correlate a retest, use session, route, page id, and timestamp; a later event does not unconditionally clear every earlier error. Never delete logs or restart the server just to make the status look clean. `UNCONFIRMED` means an error with no matching load in this log (a tab left open across a dev restart); ask for a reload before treating it as live. Details in `AGENTS.md`.
 - Let the running dev stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Treat those as generated artifacts rather than authored source.
 - Never treat `__pycache__/` directories or `.pyc` files as files to edit, regenerate on purpose, or keep in the final diff.
 - Treat `settings/component-map.json` and `settings/files-list.json` as generated outputs owned by `settings/component-map.ts` and `settings/files-list.ts`; inspect them when needed, but do not hand-edit them.

package/dist/AGENTS.md

@@ -12,6 +12,8 @@ When you work here, use `caspian.config.json` and the code that actually runs as
 
 Do not treat the existence of a packaged doc as proof that the feature is enabled in this project.
 
+**Frontend verification is required for every UI change or browser-error fix.** Run `npm run logs` before editing to read the frontend reports from `.casp/browser-log.jsonl`, then reload the affected route, exercise the changed interactions, and run it again before reporting completion. A passing `npm run check` does not prove browser health: its browser-log section is informational and does not affect the exit code. Never skip this because Python tests passed or the first paint looks correct. See the browser-log rules under Workspace Clarifications for historical entries and unavailable browser access.
+
 ## Caspian Core Contracts (Read Before Any Analysis)
 
 Every rule in this section describes shipped behavior of the Caspian runtime this app runs on. Implement against these contracts, not framework intuition. When any claim here disagrees with `caspian.config.json`, the app code, or the installed runtime, the code wins — and this section should then be fixed together with the matching packaged doc.
@@ -135,12 +137,33 @@ Value-type contract (forwarding fixes presence, not type):
 | `class`, `for` — JS reserved words             | dropped; `pp.props.class` never exists                              |
 | value was `None`/`False`/`""`/empty collection | attribute omitted by `get_attributes` → `undefined` (never `false`) |
 
-Design rules: read booleans defensively (`!!pp.props.playing`); coerce server literals before strict comparison; avoid native-attribute collisions (`title` makes a tooltip — prefer `user-name`); camelCase round-trips through kebab-case (`isFullscreen` ↔ `is-fullscreen`). `get_attributes` aliases: `className`/`class_name` → `class`, `htmlFor`/`html_for` → `for`, `defaultValue` → `defaultvalue`, `defaultChecked` → `defaultchecked`. When Tailwind is enabled, `merge_classes(...)` emits a live `{twMerge(...)}` expression — pass it straight through, never wrap or re-merge it, and pop the incoming `class` from `props` first.
+Design rules: read booleans defensively inside the owning script (`const isPlaying = !!pp.props.playing;`) and use `{isPlaying}` in markup; coerce server literals before strict comparison; avoid native-attribute collisions (`title` makes a tooltip — prefer `user-name`); camelCase round-trips through kebab-case (`isFullscreen` ↔ `is-fullscreen`). `get_attributes` aliases: `className`/`class_name` → `class`, `htmlFor`/`html_for` → `for`, `defaultValue` → `defaultvalue`, `defaultChecked` → `defaultchecked`. When Tailwind is enabled, `merge_classes(...)` emits a live `{twMerge(...)}` expression — pass it straight through, never wrap or re-merge it, and pop the incoming `class` from `props` first.
 
 `pp-ref` on an `x-*` tag is parent-owned and binds the component's concrete DOM root (forwarded through composition hosts). A component can opt out by declaring an explicit `ppRef` parameter. For a child-defined imperative API, pass a parent ref as an ordinary prop and publish with `pp.imperativeHandle(pp.props.controlRef, () => ({...}), [])` — never author `pp-ref-forward`.
 
 Deep dive: `node_modules/caspian-utils/dist/docs/components.md` "Receiving Props In A Python Component", "Every Prop A Template Reads Must Be Forwarded To The Root", and "HTML Attribute Helper Contract" (the full `get_attributes`/`merge_classes` behavior and end-to-end examples).
 
+### Read props in the script; expose bindings to the template
+
+Forwarding props to the root and making them available to markup are separate requirements. Read `pp.props` inside the owning component's `<script>`, then expose top-level bindings for `{...}` expressions. Do not access `pp.props` directly in authored markup, including child `x-*` attributes, slot content, text, boolean attributes, or inline event expressions. Nested boundary and owned-slot evaluation cannot be assumed to receive the script-local `pp.props` bag.
+
+```html
+<!-- Wrong: open="{!!pp.props.open}", hidden="{!!pp.props.rotate}",
+     project-id="{pp.props.projectId}" -->
+<x-dialog open="{dialogOpen}">
+  <p hidden="{isRotating}">Enter a replacement value.</p>
+</x-dialog>
+<script>
+  const dialogOpen = !!pp.props.open;
+  const isRotating = !!pp.props.rotate;
+  const projectId = pp.props.projectId || "";
+</script>
+```
+
+This is a template excerpt: keep it inside the component's single root, forward its incoming props, and import the child component. Pass `project-id="{projectId}"` at the child call site. Script-defined callbacks, effects, and RPC handlers may still read `pp.props`. These are browser `{...}` bindings, not server Jinja `{{...}}` interpolation. Do not change brace dialects or use `pp.props?.open` to hide a scope error. Derive bindings each render; do not freeze incoming props with `pp.state(pp.props.open)` unless intentionally creating independent state.
+
+Diagnostic signatures include `Failed to eval "!!pp.props.open"`, `Failed to evaluate prop expression`, and `Cannot read properties of undefined (reading 'rotate')` from owned content. A missing field in a valid prop bag is different from the bag itself being unavailable. Check root forwarding, then script-to-template scope, then repeat the interaction and inspect the frontend log. See [Read props in the script, bind names in markup](node_modules/caspian-utils/dist/docs/pulsepoint.md#read-props-in-the-script-bind-names-in-markup).
+
 ### PulsePoint templates — plain HTML, never JSX
 
 The React comparison covers exactly two things: the `pp.*` hook API inside `<script>` and how components are split by responsibility. **The markup is plain HTML parsed by an HTML parser.** The one-line test before finishing any template: _would it still be valid HTML with every `{}` deleted?_
@@ -174,7 +197,7 @@ Deep dive: `node_modules/caspian-utils/dist/docs/pulsepoint.md` "PulsePoint Is N
 
 ### Component scripts — hooks and runtime API
 
-The script is a plain, untyped `<script>` inside the root: captured by the runtime before materialization, evaluated in component scope via `new Function(...)`. No `import`/`export`/top-level `await`. Only **top-level** declarations reach the template (functions, `const`s, every destructuring shape). Props are read via `pp.props` — there is no injected `props` variable.
+The script is a plain, untyped `<script>` inside the root: captured by the runtime before materialization, evaluated in component scope via `new Function(...)`. No `import`/`export`/top-level `await`. Only **top-level** declarations reach the template (functions, `const`s, every destructuring shape). Inside the script, props are read via `pp.props` — there is no injected `props` variable. Export top-level bindings for markup; do not read `pp.props` directly in template expressions.
 
 Hooks (closed list): `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp.ref`, `pp.memo`, `pp.callback`, `pp.reducer`, `pp.context`, `pp.portal`, `pp.id`, `pp.errorBoundary`, `pp.syncExternalStore`, `pp.imperativeHandle`, `pp.transition`, `pp.deferredValue`, `pp.optimistic`, plus `pp.props`. Utilities: `pp.createContext`, `pp.mount`, `pp.redirect`, `pp.rpc`, `pp.socket`, `pp.enablePerf`/`disablePerf`/`getPerfStats`/`resetPerfStats`. No `forwardRef`, `Suspense`, `lazy`, `useActionState`, or `pp.provideContext` — do not invent hooks.
 
@@ -289,7 +312,7 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - Use `node_modules/caspian-utils/dist/docs/file-conventions.md` for the general special-file model, then verify the completed Python migration in `main.py` and `.venv/Lib/site-packages/casp/**`: routes use `index.py`, layouts use `layout.py`, navigation loading UI uses `loading.py`, and global fallback pages use `not_found.py` and `error.py`. This app has no authored `.html` special files.
 - **If navigation loading UI is wanted, it is `loading.py` — never hand-roll it.** The file itself is optional and most subtrees do not have one; this rule governs the implementation, not whether to add the feature. A spinner component, a global `isLoading` store, a `pp:navigation:start`/`pp:navigation:complete` listener, or a manual overlay built for route-to-route navigation is a reimplementation of the shipped runtime (`casp/loading.py` collects the files, `caspian_config.py` derives their URL scopes, the browser runtime resolves the closest ancestor scope and swaps the `pp-loading-content="true"` pane). The full contract is in the "Special files" block above; the shipped example is `src/app/dashboard/loading.py` plus the `pp-loading-content="true"` bar in `src/app/dashboard/layout.py`. In-page waits (RPC, submit, filter, upload) are `pp.state` in the owning component and are not this feature.
 - When `caspian.config.json` has `prisma: true`, database reads and writes from Python routes, layouts, RPC actions, upload flows, auth flows, and helpers must use the generated Prisma Python ORM in `src/lib/prisma/**`. Do not create a separate database fetch layer with raw drivers, hand-written SQL helpers, JSON manifests, app-specific HTTP fetches, or browser-side data fetches to replace the ORM. Use raw SQL only as a narrow Prisma ORM fallback when the generated client cannot express a query clearly.
-- Development restarts must preserve the database lifecycle. `settings/python-server.ts` sends an authenticated shutdown command through a private child stdin pipe and waits for Uvicorn to exit before force-kill is considered; `main.py` handles that command with `uvicorn.Server.should_exit`, and, only when `cfg.prisma` is true, conditionally imports the generated client and registers a Prisma lifespan that awaits `prisma.disconnect()` during shutdown. A Prisma-disabled project may have no `src.lib.prisma` package, so never move that import outside the feature gate. Keep Prisma's lifespan ahead of later lifespans so it exits last, do not make it connect eagerly, and do not replace the normal restart path with immediate `taskkill /F` / `SIGKILL`—that bypasses FastAPI cleanup and churns database connections during source edits.
+- Development restarts must preserve the database lifecycle. `settings/python-server.ts` sends an authenticated shutdown command through a private child stdin pipe and waits for Uvicorn to exit before force-kill is considered; `main.py` handles that command with `uvicorn.Server.should_exit`, and, only when `cfg.prisma` is true, conditionally imports the generated client and registers a Prisma lifespan that awaits `prisma.disconnect()` during shutdown. **Two independent conditions gate that import, not one.** `cfg.prisma` says the feature is _enabled_; `src/lib/prisma/` existing on disk says the ORM has actually been _generated_. A Prisma-disabled project has no such package, and neither does a freshly scaffolded or freshly cloned project whose `prisma/schema.prisma` exists but where `npx ppy generate` has never run — so the import is guarded by `PRISMA_PACKAGE_DIR.is_dir()` inside the `cfg.prisma` gate, and the lifespan is registered on `prisma is not None` rather than on the flag. Never move the import outside either guard, and do not collapse them back into one: a bare `ModuleNotFoundError` at import kills the dev stack before a single route renders, with a traceback that names no fix. A directory that exists but fails to import is a genuinely broken install (missing driver dependency, half-written generation) and keeps its own traceback. Missing-and-enabled warns and keeps serving in development but raises at boot in production, where every database call would fail at request time anyway — the same fail-closed rule as `APP_ENV`. Every consumer must therefore treat `main.prisma` as possibly `None`. Keep Prisma's lifespan ahead of later lifespans so it exits last, do not make it connect eagerly, and do not replace the normal restart path with immediate `taskkill /F` / `SIGKILL`—that bypasses FastAPI cleanup and churns database connections during source edits.
 - **After any `prisma/schema.prisma` change, exactly two commands are required, in order.** Step 1 — sync the database, pick one: `npx prisma migrate dev` (development default, creates and applies a migration) or `npx prisma db push` (migration-less direct sync). Step 2 — always: `npx ppy generate`, the **only** command that regenerates the Python ORM the app imports (`src/lib/prisma/__init__.py`, `db.py`, `models.py`, `settings/prisma-schema.json`). The two generators are different toolchains from the same schema: `npx prisma generate` builds the Node/TypeScript `@prisma/client` used only by `prisma/seed.ts` and writes zero Python — it is never a substitute for `npx ppy generate`. Never hand-write or patch the generated Python ORM instead of regenerating it; the generated client is ready to import from `src.lib.prisma`. See `node_modules/caspian-utils/dist/docs/database.md` "Two Generators, One Schema".
 - Treat `npx prisma db seed` as a delicate, potentially destructive operation. In this workspace, seed scripts may clear tables before inserting fresh records. Before running that command, an AI agent must propose the exact command, warn that it can delete or overwrite database data including production data if the datasource is wrong, confirm the datasource when practical, and wait for explicit user approval.
 - Component-first page composition is the highest-priority authoring rule for this workspace (see `.github/copilot-instructions.md`). Build pages as a short assembly of `x-*` chunk components (top menu, sidebar, header, content sections, cards, forms, footer) and keep each chunk's long markup inside its own focused single-file `html(...)` component, so the page template in `src/app/**/index.py` stays small instead of holding a wall of HTML. Plan the chunk breakdown before writing the route, not as a later cleanup pass.
@@ -331,12 +354,12 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - **A BOM makes a Python file invisible to the `templates` gate.** `check_templates.py` reads files with `path.read_text(encoding="utf-8")` and `ast.parse`, and a UTF-8 BOM makes that parse raise, which the scanner swallows as "skip this file". One file (`src/components/dashboard/ProductsPage.py`) carried a BOM and was silently exempt from every template rule, including `html-form` — it had been using the non-raw `html("""...""")` shape the whole time. `ruff format` strips the BOM, so the violation surfaced the moment formatting ran. If a template rule ever seems not to apply to a file, check for a BOM before assuming the rule is wrong.
 - **`npm run logs` is how an agent checks front-end health, because the dev terminal usually belongs to someone else.** The developer typically runs `npm run dev` in their own shell, so its stdout is invisible to an agent session — and starting a second dev stack is the wrong fix: `npm run dev` begins with `projectName`, which **deletes `.casp/` and `caches/`** out from under the running server, and then binds different ports and rewrites `settings/bs-config.json`, orphaning the browser tab the developer is actually looking at. **Never start a second `npm run dev` to get a log.** Instead `settings/dev-log-bridge.ts` appends every event to `.casp/browser-log.jsonl` (JSONL, one event per line, gitignored, truncated per dev session because `.casp/` is recreated at startup), and `settings/browser_log.py` renders it via `npm run logs`. `npm run check` prints the same digest at the end of its run but **never lets it affect the exit code** — whether a route has been exercised depends on someone clicking around, and a gate that flaky gets ignored; `--fail-on-error` opts in for scripts that want it, `--no-browser` skips the section.
   - **The log records successful page loads, not just errors.** This is the property that makes it safe to act on, and it must not be removed as redundant. A clean reload writes nothing on its own, so without `load` events a fixed error would sit in the file forever and an agent would "fix" a bug that no longer exists. A route's status is therefore whatever happened during its **most recent load**: one clean reload retires every earlier error for that route (reported as `N earlier error(s) resolved`). Errors are tied to their load by a client-generated `page` id, never by arrival order, because two `fetch` POSTs can land out of sequence.
-  - **`NEEDS RECHECK` is the status that matters most — a reload does not re-test everything.** A reload re-runs mount, so it is real evidence against a mount-phase error. It never clicks a button, so it proves nothing about an error thrown from an event handler. Errors are classified by how long after their page load they arrived (`phase: "mount"` within 2s, `"interaction"` after), and an interaction error is **not** cleared by a later load — it is carried as `NEEDS RECHECK` with its timing shown. Treating that as `CLEAN` is exactly how a live bug gets signed off; this was a real defect in an earlier version of this tool, on a route whose `onclick` threw 17s after load. To clear one, repeat the interaction (click/submit) and re-run `npm run logs`.
+  - **`NEEDS RECHECK` can represent interaction errors or errors carried across source changes — a reload does not re-test everything.** A reload re-runs mount, so it is real evidence against a mount-phase error. It never clicks a button, so it proves nothing about an error thrown from an event handler. Errors are classified by how long after their page load they arrived (`phase: "mount"` within 2s, `"interaction"` after), and an interaction error is **not** cleared by a later load — it is carried as `NEEDS RECHECK` with its timing shown. Treating that as `CLEAN` is exactly how a live bug gets signed off; this was a real defect in an earlier version of this tool, on a route whose `onclick` threw 17s after load. Repeat the interaction (click/submit) and re-run `npm run logs`. The reporter does not record successful clicks, so an old recheck entry may remain even after a successful retest. Confirm there are no fresh errors or relevant warnings and report the interaction evidence separately; do not claim the status became `CLEAN` if it did not.
   - **The log is compacted on every source change, not appended forever.** A dev session left running for hours would otherwise grow an unbounded file (~331 KB / ~85k tokens in a measured 6-hour session), and `.casp/` is only wiped by a full `npm run dev`, which nobody does mid-session. So when `src/**` changes, `compactBrowserLog(...)` rewrites the file down to the session header, a `{"type":"restart"}` marker, and the errors still open — resolved history is dropped. Survivors are marked `"carried": true` and dropped at the _next_ compaction, so a stale interaction error cannot haunt the log forever. Reading the digest costs ~855 tokens regardless of session length, because it is bounded by route count, not time.
-  - **Do not diagnose from the raw JSONL.** It is history, not state: it can hold errors resolved minutes ago, and errors carried across a source change. Always prefer `npm run logs`, which derives current status. If you do read the file, the `session` line's `readme` states the rule — **a later `load` or `resolved` supersedes earlier errors on that route, except `phase: "interaction"` errors, which a reload cannot re-test.**
+  - **Do not diagnose from raw JSONL alone.** It is history, not state: it can hold errors resolved minutes ago, and errors carried across a source change. Always prefer `npm run logs`, which derives current status. If you do read the file, the `session` line's `readme` states the rule — **a later matching load can retire earlier mount errors, but interaction errors and carried entries can remain pending recheck.** When the digest retains history after a retest, correlate raw details by session, route, page id, and timestamp; never treat every line as a new failure.
   - **`UNCONFIRMED` means an error with no matching `load` in this log** — almost always a browser tab left open across a dev restart, reporting against a page that was rendered under the previous session. The error was real when it fired but may already be fixed. Ask for a reload of that route and re-run `npm run logs` before treating it as a live bug; do not start editing code on an `UNCONFIRMED` line alone.
   - **Read the three not-an-error states literally.** `NONE` = no dev session ever wrote — nothing has been observed. `WARN … dev server is NOT running` = the log is left over from an exited session; treat every line as history. `CLEAN` on a route means _that route was opened and rendered without error_. A route absent from the listing was never opened, which is **no signal, not a pass** — say so rather than reporting the front end healthy.
-  - **How to act on a failure.** The digest gives route, message, and the top stack frames. Fix the owning `src/app/<route>/index.py` or the component it names, then get the route exercised again and re-run `npm run logs`. What "exercised" means depends on the status: a mount error needs a **reload**; a `NEEDS RECHECK` interaction error needs the **same interaction repeated** — a reload will not clear it and should not be expected to. The flip to `CLEAN` is the confirmation. Do not treat a still-present error as unfixed until it has actually been re-exercised; the log cannot know about a fix nobody has run.
+  - **How to act on a failure.** The digest gives route, message, and the top stack frames. Fix the owning `src/app/<route>/index.py` or the component it names, then get the route exercised again and re-run `npm run logs`. What "exercised" means depends on the status: a mount error needs a **reload**; a `NEEDS RECHECK` interaction error needs the **same interaction repeated** — a reload will not clear it and should not be expected to. A `CLEAN` digest supports the retest, but historical `NEEDS RECHECK` entries may remain because the reporter cannot observe successful interactions. Record what was exercised and whether any fresh errors or warnings followed. Do not treat a retained historical entry as a fresh failure or claim browser verification when the route or interaction was never exercised. If browser access or the dev session is unavailable, state that gap explicitly.
   - Coverage is in `tests/test_browser_log.py`. The event shape is defined by `LogEvent` in `settings/dev-log-bridge.ts` and consumed by `build_report(...)` in `settings/browser_log.py`; change both together. Known limit: the client script runs per full document load, so **SPA navigations do not emit a `load` event** — the log tracks full page loads only.
 
 - Security posture is enforced in three places and must stay in sync: `casp.runtime_security` (environment resolution, security headers, safe public-file serving), `main.py` (middleware stack, MCP gate, cache eligibility, the named-socket endpoint), and the Caspian-owned files under `src/lib/**` — `src/lib/auth/auth_config.py` (route privacy and RBAC policy) and `src/lib/websocket/sockets.py` (socket origin check, connection ceiling, auth delegation, and per-connection limits). Key behaviors an agent must not silently undo:

package/dist/main.py

@@ -81,19 +81,55 @@ from collections.abc import Callable
 load_dotenv()
 cfg = get_config()
 
-# Prisma is optional. A project generated with `prisma: false` has no
-# `src.lib.prisma` package, so both the import and lifespan registration must be
-# behind the feature gate.
-prisma: Any = None
-if cfg.prisma:
-    from src.lib.prisma import prisma as configured_prisma
+# Declared before the Prisma and MCP blocks below, which need it to decide
+# whether a missing generated client, an unauthenticated endpoint, or an open
+# CORS policy is tolerable. Resolved fail-closed: only an explicit development
+# APP_ENV turns the relaxations on.
+IS_PRODUCTION = is_production_environment()
 
-    prisma = configured_prisma
+# Prisma is optional, and its Python ORM is *generated* rather than authored, so
+# there are two independent conditions -- the feature flag in
+# `caspian.config.json`, and whether `npx ppy generate` has actually produced
+# `src/lib/prisma/`. A project generated with `prisma: false` has no such
+# package; neither does a freshly cloned or freshly scaffolded project whose
+# schema exists but has never been generated. Both must leave the app importable,
+# so the import, the lifespan registration, and every consumer treat `prisma` as
+# possibly `None`.
+PRISMA_PACKAGE_DIR = Path(__file__).resolve().parent / "src" / "lib" / "prisma"
+
+PRISMA_NOT_GENERATED_MESSAGE = (
+    "Prisma is enabled in caspian.config.json but the Python ORM has not been "
+    "generated, so src/lib/prisma/ does not exist. Sync the database with "
+    "`npx prisma migrate dev` (or `npx prisma db push`), then run "
+    "`npx ppy generate` to generate the client."
+)
 
-# Declared before the MCP block below, which needs it to decide whether an
-# unauthenticated endpoint or an open CORS policy is tolerable. Resolved
-# fail-closed: only an explicit development APP_ENV turns the relaxations on.
-IS_PRODUCTION = is_production_environment()
+prisma: Any = None
+if cfg.prisma:
+    if PRISMA_PACKAGE_DIR.is_dir():
+        # Present but unimportable is a genuinely broken install (a missing
+        # driver dependency, a half-written generation). Let that traceback
+        # through rather than degrading to a confusing "not generated" hint.
+        # The ignore matches the optional MCP import below: a generated module
+        # is absent from a static checkout, so the type checker cannot see it.
+        from src.lib.prisma import prisma as configured_prisma  # type: ignore[import-not-found]
+
+        prisma = configured_prisma
+    elif IS_PRODUCTION:
+        # A deployment that enabled Prisma and shipped without the generated
+        # client is broken: every database call would fail at request time.
+        # Fail at boot instead, consistent with the fail-closed APP_ENV rule.
+        raise RuntimeError(PRISMA_NOT_GENERATED_MESSAGE)
+    else:
+        # In development this is the ordinary "I have not generated it yet"
+        # state. Warn once at boot and keep serving, so the dev stack does not
+        # die with a bare ModuleNotFoundError before a single route renders.
+        print(
+            f"[caspian] WARNING: {PRISMA_NOT_GENERATED_MESSAGE} "
+            "Database access is unavailable until then; the rest of the app runs normally.",
+            file=sys.stderr,
+            flush=True,
+        )
 
 # Resolve APP_TIMEZONE once at import so an unknown zone name fails at boot with
 # a named error, rather than on whichever request first formats a date. Only the
@@ -324,7 +360,9 @@ def get_app_lifespans() -> list[LifespanFactory]:
 
     # Keep the database alive until every later lifespan has shut down. This does
     # not connect eagerly; it only guarantees cleanup when Uvicorn exits cleanly.
-    if cfg.prisma:
+    # Gated on the client being importable, not just on the feature flag: with
+    # Prisma enabled but not yet generated there is nothing to disconnect.
+    if prisma is not None:
         lifespans.append(prisma_lifespan)
 
     # MCP lifecycle

package/dist/tests/test_main_helpers.py

@@ -16,9 +16,21 @@ from conftest import run_async
 
 
 class TestPrismaLifespan:
-    def test_disconnects_on_shutdown(self, monkeypatch):
+    @staticmethod
+    def _install_client(monkeypatch) -> AsyncMock:
+        """Stand in for the generated Prisma client.
+
+        `src/lib/prisma/` is generated by `npx ppy generate`, so it is absent in
+        a fresh checkout and `main.prisma` is then `None`. The lifespan contract
+        is about whatever object `main.prisma` holds, so the tests supply one
+        rather than depending on generation having been run.
+        """
         disconnect = AsyncMock()
-        monkeypatch.setattr(main.prisma, "disconnect", disconnect)
+        monkeypatch.setattr(main, "prisma", SimpleNamespace(disconnect=disconnect))
+        return disconnect
+
+    def test_disconnects_on_shutdown(self, monkeypatch):
+        disconnect = self._install_client(monkeypatch)
 
         async def exercise_lifespan():
             async with main.prisma_lifespan(main.app):
@@ -29,12 +41,29 @@ class TestPrismaLifespan:
 
     def test_disabled_prisma_is_not_registered(self, monkeypatch):
         monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=False))
+        monkeypatch.setattr(main, "prisma", None)
 
         assert main.prisma_lifespan not in main.get_app_lifespans()
 
+    def test_enabled_but_ungenerated_prisma_is_not_registered(self, monkeypatch):
+        """Prisma enabled in config but never generated leaves nothing to close.
+
+        Registration is gated on the client being importable, not on the flag,
+        so the app still boots when `npx ppy generate` has not been run.
+        """
+        monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=True))
+        monkeypatch.setattr(main, "prisma", None)
+
+        assert main.prisma_lifespan not in main.get_app_lifespans()
+
+    def test_generated_prisma_is_registered(self, monkeypatch):
+        monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=True))
+        self._install_client(monkeypatch)
+
+        assert main.prisma_lifespan in main.get_app_lifespans()
+
     def test_disconnects_when_another_lifespan_raises(self, monkeypatch):
-        disconnect = AsyncMock()
-        monkeypatch.setattr(main.prisma, "disconnect", disconnect)
+        disconnect = self._install_client(monkeypatch)
 
         async def exercise_lifespan():
             try:
@@ -46,6 +75,21 @@ class TestPrismaLifespan:
         run_async(exercise_lifespan())
         disconnect.assert_awaited_once_with()
 
+    def test_lifespan_is_a_noop_without_a_generated_client(self, monkeypatch):
+        """The shutdown half must tolerate `prisma` being `None`.
+
+        `get_app_lifespans` already skips registration in that state, but the
+        lifespan is public and is exercised directly by tests and by anyone
+        composing lifespans by hand.
+        """
+        monkeypatch.setattr(main, "prisma", None)
+
+        async def exercise_lifespan():
+            async with main.prisma_lifespan(main.app):
+                pass
+
+        run_async(exercise_lifespan())
+
 
 class TestDevControlPipe:
     def test_valid_shutdown_command_stops_server(self):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",