create-caspian-app 1.3.27 → 1.4.0

package/README.md

@@ -1,77 +1,57 @@
 # Caspian — The Native Python Web Framework for the Reactive Web
 
-Caspian is a FastAPI-powered full-stack framework that brings reactive UI to Python without forcing a JavaScript backend. You write file-system routes, plain HTML templates, and `async def` Python — Caspian wires the browser to your server.
+Caspian is a FastAPI-powered full-stack framework that brings reactive UI to Python without a JavaScript backend. You write file-system routes, plain HTML templates, and `async def` Python — Caspian wires the browser to your server.
 
-- **FastAPI engine** — async-native, with the Starlette/FastAPI middleware and ecosystem underneath
-- **PulsePoint** — a shipped browser-side reactive runtime with a React-style hook API and **plain HTML** templates (no JSX, no build step required)
-- **"Zero-API" RPC** — call Python functions from the browser with `pp.rpc()`; no controllers, no route handlers, no fetch boilerplate
+- **FastAPI engine** — async-native, with the Starlette/FastAPI middleware ecosystem underneath
+- **PulsePoint** — a shipped browser runtime with a React-style hook API and **plain HTML** templates (no JSX, no build step required)
+- **"Zero-API" RPC** — call Python functions from the browser with `pp.rpc()`; no controllers, no fetch boilerplate
 - **File-system routing** with nested layouts, dynamic segments, and route groups (Next.js App Router mental model)
 - **Python components** — reusable `@component` functions rendered as HTML-first `x-*` tags
-- **Prisma ORM** with a generated, type-safe Python client
+- **Prisma ORM** with a generated, typed Python client
 - **Session auth** with RBAC and OAuth providers, plus fail-closed security defaults
 - **Optional**: Tailwind CSS, TypeScript tooling, MCP server, WebSockets — each gated by one config flag
 
+> **The full manual ships inside every project** at `node_modules/caspian-utils/dist/docs/` (start at `index.md`). This README is the tour; that folder is the reference.
+
 ---
 
 ## Quick Start
 
-### Requirements
-
-- **Python** `3.14` or newer
-- **Node.js** with `npm` and `npx` available (used for the CLI, Prisma, Tailwind, and the dev stack)
-
-```bash
-node -v
-python -V
-```
-
-### Create an app
+Requires **Python 3.14+** and **Node.js** with `npm`/`npx` (used for the CLI, Prisma, Tailwind, and the dev stack).
 
 ```bash
 npx create-caspian-app@latest
 ```
 
-The interactive wizard walks through:
-
-- Project name
-- Feature toggles: backend-only, Tailwind CSS, Prisma, MCP, TypeScript
-- Starter kit selection (`basic`, `fullstack`, `api`, `realtime`, or a custom Git source)
-
-### Run the dev server
+The wizard asks for a project name, feature toggles (backend-only, Tailwind, Prisma, MCP, TypeScript), and a starter kit (`basic`, `fullstack`, `api`, `realtime`, or a custom Git source). Then:
 
 ```bash
-cd my-app
 npm run dev
 ```
 
-> The generated `package.json` is the source of truth for what `npm run dev` does. Caspian projects typically run a **BrowserSync proxy plus PostCSS/Vite watchers**, not a Vite dev server that owns the page. When the dev stack is running, check `settings/bs-config.json` for the active local URL and port — the proxy does not always land on the default port.
+`npm run dev` runs a **BrowserSync proxy plus asset watchers**, not a Vite dev server that owns the page. The proxy does not always land on its default port — check `settings/bs-config.json` for the active URL.
 
 ---
 
 ## What "Reactive Python" looks like
 
-A route is a folder with one file: `index.py`. The markup lives inline as a template handed to `html(...)`, next to the server logic. Templates are **plain HTML** with `{expression}` interpolation and a small `<script>` for state.
-
-### The route — `src/app/todos/index.py`
+A route is a folder with one file: `index.py`. Markup lives inline in `html(r"""...""")`, next to the server logic.
 
 ```python
+# src/app/todos/index.py
 from casp.component_decorator import html
 from casp.layout import Metadata
 from casp.rpc import rpc
 from casp.validate import Rule, Validate
-from src.components.ui.Badge import Badge
 
-metadata = Metadata(
-    title="Todos",
-    description="A tiny Caspian todo list.",
-)
+from src.lib.prisma import prisma
+
+metadata = Metadata(title="Todos", description="A tiny Caspian todo list.")
 
 
 async def page():
     return html(r"""
 <section>
-  <x-badge variant="default">Tasks: {todos.length}</x-badge>
-
   <form onsubmit="{addTodo(event)}">
     <input name="title" required />
     <button type="submit" disabled="{isSaving}">Add</button>
@@ -79,7 +59,7 @@ async def page():
 
   <ul>
     <template pp-for="(todo, index) in todos">
-      <li key="{todo.id}" class="p-2 border-b">
+      <li key="{todo.id}" class="border-b p-2">
         {index + 1}. {todo.title}
         <button onclick="{removeTodo(todo.id)}">Remove</button>
       </li>
@@ -103,8 +83,7 @@ async def page():
         const data = Object.fromEntries(
           new FormData(event.currentTarget).entries(),
         );
-        const created = await pp.rpc("create_todo", data);
-        setTodos([created, ...todos]);
+        setTodos([await pp.rpc("create_todo", data), ...todos]);
         event.currentTarget.reset();
       } finally {
         setIsSaving(false);
@@ -131,7 +110,6 @@ async def create_todo(title: str):
     checked = Validate.with_rules(title, [Rule.REQUIRED, Rule.min(3)])
     if checked is not True:
         raise ValueError("Title must be at least 3 characters.")
-
     todo = await prisma.todo.create(data={"title": title.strip(), "completed": False})
     return todo.to_dict()
 
@@ -142,7 +120,7 @@ async def delete_todo(id: int):
     return {"deleted": True}
 ```
 
-That is the whole loop: no API routes, no client, no serializer. `pp.rpc("create_todo", data)` posts to the current route, Caspian resolves the decorated function, filters the payload against its signature, runs it, and returns JSON.
+That is the whole loop — no API routes, no client, no serializer. `pp.rpc("create_todo", data)` posts to the current route; Caspian resolves the decorated function, filters the payload against its signature, runs it, and returns JSON.
 
 ---
 
@@ -150,33 +128,30 @@ That is the whole loop: no API routes, no client, no serializer. `pp.rpc("create
 
 ### 1. Routing
 
-Your directory structure under `src/app` is your URL structure.
-
-| File                          | URL           |
-| ----------------------------- | ------------- |
-| `src/app/index.py`            | `/`           |
-| `src/app/about/index.py`      | `/about`      |
-| `src/app/blog/posts/index.py` | `/blog/posts` |
+The directory structure under `src/app` is the URL structure.
 
 ```
-src/app/users/[id]/index.py        ->  /users/123          (dynamic segment)
-src/app/docs/[...slug]/index.py    ->  /docs/a/b/c         (catch-all)
-src/app/(auth)/login/index.py      ->  /login              (route group, no URL segment)
+src/app/index.py                   ->  /
+src/app/blog/posts/index.py        ->  /blog/posts
+src/app/users/[id]/index.py        ->  /users/123        (dynamic segment)
+src/app/docs/[...slug]/index.py    ->  /docs/a/b/c       (catch-all)
+src/app/(auth)/login/index.py      ->  /login            (route group, no URL segment)
 src/app/dashboard/layout.py        ->  wraps every /dashboard/* page
 ```
 
-#### Route file conventions
+Path params arrive as one positional dict (`async def page(params: dict)`); query params inject by name; `request` injects when declared. `page()` returns `html(r"""...""", **context)`, or a `(page_html, layout_props)` tuple whose keys become `{{ layout.* }}` in a parent layout.
+
+**Special files.** Only `index.py` is required — the rest are optional, and each owns a behavior you should not hand-build.
 
-| File             | Owns                                                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------------------------------- |
-| `index.py`       | The page: `page()` returning `html(...)` markup, `metadata`, route-owned `@rpc()` actions, redirects, first-render data |
-| `layout.py`      | The section wrapper: `layout()` returning the shell template (with `<slot />`) plus optional props and server logic |
-| `loading.py`     | Route-scoped navigation loader: synchronous `loading()` returning `html(...)` markup                          |
-| `not_found.py`   | Global 404 page: `page()` returning `html(...)` markup and metadata                                           |
-| `error.py`       | Global 500 page: `page()` receiving safe error context and returning `html(...)` markup                       |
+| File           | Export                             | Owns                                                                          |
+| -------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
+| `index.py`     | `page()`                           | The page, plus `metadata`, route-owned `@rpc()`, redirects, first-render data |
+| `layout.py`    | `layout()`                         | A subtree shell containing `<slot />`, plus optional props and metadata       |
+| `loading.py`   | `loading()`                        | Loading UI shown while navigating **between routes**                          |
+| `not_found.py` | `page()`                           | Global 404 page                                                               |
+| `error.py`     | `page(error_message, error_trace)` | Global 500 page                                                               |
 
-`page()` returns `html(r"""...""", **context)`. It can also return a
-`(page_html, layout_props)` tuple, whose dict keys become `{{ layout.* }}` in a parent layout.
+`loading.py` is worth knowing because it is easy to reinvent: `loading()` is **synchronous and takes no parameters**, its URL scope comes from its folder (the closest ancestor wins), and its markup is injected as **raw HTML** — Jinja `{{ }}` interpolates, but `<x-*>` tags, `{ }` bindings, and `<script>` do nothing inside it. Mark the pane it replaces with `pp-loading-content="true"` in the layout. Most subtrees have none, and a route with no loader simply fades; add one only when a section wants it, and never replace it with a spinner component or a navigation-event listener.
 
 ---
 
@@ -185,9 +160,8 @@ src/app/dashboard/layout.py        ->  wraps every /dashboard/* page
 PulsePoint borrows React's **hook API** and its **component decomposition model**. It does **not** borrow JSX. This is the single most common source of broken pages.
 
 ```html
-<!-- ❌ These silently corrupt the page -->
+<!-- ❌ Silently corrupts the page -->
 <div class="{cls}">…</div>
-<!-- unquoted brace attr -->
 {isOpen &&
 <div>Panel</div>
 } {items.map(item => (
@@ -204,114 +178,60 @@ PulsePoint borrows React's **hook API** and its **component decomposition model*
 
 An unquoted `class={...}` is **invalid HTML**: the parser splits it on spaces into junk attributes, the component root never compiles, and the route serves a blank page **with no console error**.
 
-**Sanity check:** delete every `{}` from your template. What remains must still be valid HTML.
-
-There is no `pp-if`, `pp-show`, `pp-else`, or `pp-key`. Conditionals are `hidden="{...}"` or a ternary inside `{...}`. Keyed lists use plain `key`.
+**Sanity check:** delete every `{}` from the template. What remains must still be valid HTML.
 
-#### The complete author-facing template surface
+**The directive list is closed.** There is no `pp-if`, `pp-show`, `pp-else`, `pp-model`, or `pp-key`.
 
-| Syntax                                                          | Where                                      | Purpose                       |
-| --------------------------------------------------------------- | ------------------------------------------ | ----------------------------- |
-| `{expression}`                                                  | Text nodes and **quoted** attribute values | Interpolation                 |
-| `onclick`, `oninput`, `onchange`, `onsubmit`, any `on*`         | Any element                                | Event binding                 |
-| `pp-for="item in items"` / `"(item, index) in items"`           | **`<template>` only**                      | Keyed list rendering          |
-| `key="{expr}"`                                                  | The repeated element                       | Diffing identity              |
-| `pp-ref="name"` / `pp-ref="{expr}"`                             | Native elements and `x-*` tags             | Imperative element access     |
-| `pp-style="{cssText}"`                                          | Any element                                | Dynamic inline style (string) |
-| `pp-spread="{...obj}"`                                          | Any element                                | Spread object into attributes |
-| `<token.provider value="{v}">` (lowercase)                      | Anywhere                                   | Context provider              |
-| `pp-spa="false"`                                                | An `<a>`                                   | Opt one link out of SPA navigation, which starts automatically on mount |
-| `pp-reset-scroll="true"`, `pp-scroll-key="name"`                | A scroll container                         | Scroll restoration control    |
-| `pp-loading-content`, `pp-loading-url`, `pp-loading-transition` | Navigation regions                         | Loading UI                    |
+| Syntax                                                | Where                                      | Purpose                            |
+| ----------------------------------------------------- | ------------------------------------------ | ---------------------------------- |
+| `{expression}`                                        | Text nodes and **quoted** attribute values | Interpolation                      |
+| `onclick`, `oninput`, `onsubmit`, any `on*`           | Any element                                | Event binding                      |
+| `pp-for="item in items"` / `"(item, index) in items"` | **`<template>` only**                      | List rendering                     |
+| `key="{expr}"`                                        | The repeated element                       | Diffing identity                   |
+| `pp-ref="name"` / `pp-ref="{expr}"`                   | Native elements and `x-*` tags             | Imperative element access          |
+| `defaultvalue` / `defaultchecked`                     | Form controls                              | Uncontrolled seed (lowercase)      |
+| `pp-style="{cssText}"`                                | Any element                                | Dynamic inline style (string)      |
+| `pp-spread="{...obj}"`                                | Any element                                | Spread object into attributes      |
+| `<token.provider value="{v}">` (lowercase)            | Anywhere                                   | Context provider                   |
+| `pp-spa="false"`                                      | An `<a>`                                   | Opt one link out of SPA navigation |
+| `pp-reset-scroll`, `pp-scroll-key`                    | A scroll container                         | Scroll restoration control         |
+| `pp-loading-content="true"`                           | The pane swapped during navigation         | Where `loading.py` markup lands    |
 
-Never handwrite runtime-managed attributes (`pp-component`, `pp-owner`, `pp-ref-owner`, `pp-ref-forward`, `data-pp-*`, …). Component logic belongs in a plain, untyped `<script>`; the render pipeline and browser runtime capture it safely.
+A form control is controlled (`value="{state}"` + `oninput`) **or** uncontrolled (`defaultvalue="{expr}"`) for its lifetime, never both. Never hand-write runtime-managed attributes (`pp-component`, `pp-owner`, `pp-ref-forward`, `pp-loading-url`, `data-pp-*`, …) — the pipeline injects them.
 
-#### The single-root rule
-
-Every route, layout, and component template must have **exactly one** top-level element (or one imported `x-*` root), with any owned `<script>` **inside** that root. Caspian injects `pp-component` on the final root and errors if it cannot find one.
+**Root shape.** Default to one top-level element with the owned `<script>` **inside** it. Beyond that: a **component** with sibling top-level nodes becomes a fragment (the `<>…</>` equivalent) that adds no element to the DOM — but a fragment has no root, so it **cannot receive props**; give it a single native root when it takes any. A **page or layout** with sibling top-level nodes gets a layout-neutral `display: contents` boundary host instead, so skip the meaningless wrapper `<div>` when the sections really are siblings.
 
 ---
 
 ### 3. PulsePoint hooks
 
-Component `<script>` blocks are plain JavaScript. The `pp` object mirrors React hooks:
-
-| Hook                                          | Returns / purpose                                                      |
-| --------------------------------------------- | ---------------------------------------------------------------------- |
-| `pp.state(initial)`                           | `[value, setValue]` — setter accepts a value or an updater             |
-| `pp.effect(fn, deps?)`                        | After render; may return a cleanup function                            |
-| `pp.layoutEffect(fn, deps?)`                  | Synchronously after DOM mutation                                       |
-| `pp.ref(initial?)`                            | `{ current }`                                                          |
-| `pp.memo(fn, deps)` / `pp.callback(fn, deps)` | Memoized value / stable function                                       |
-| `pp.reducer(reducer, initial)`                | `[state, dispatch]`                                                    |
-| `pp.context(token)`                           | Read a context value from an ancestor provider                         |
-| `pp.portal(ref, target?)`                     | Render into another DOM target, preserving logical ancestry            |
-| `pp.id()`                                     | Stable unique id for `id`/`for`/`aria-*` pairing                       |
-| `pp.errorBoundary()`                          | `[error, reset]` — catches render and effect throws in descendants     |
-| `pp.syncExternalStore(subscribe, snapshot)`   | Subscribe to a source the component doesn't own (`matchMedia`, stores) |
-| `pp.imperativeHandle(ref, create, deps?)`     | Publish an imperative API to a parent's ref                            |
-| `pp.transition()`                             | `[isPending, startTransition]`                                         |
-| `pp.deferredValue(value, initial?)`           | Lags one commit behind the source                                      |
-| `pp.optimistic(passthrough, reducer?)`        | Optimistic UI that reconciles against a confirmed value                |
-| `pp.props`                                    | Props bag derived from the rendered root's attributes                  |
-
-Runtime utilities: `pp.createContext`, `pp.mount`, `pp.redirect`, `pp.rpc`, `pp.socket`, `pp.enablePerf`, `pp.disablePerf`, `pp.getPerfStats`, `pp.resetPerfStats`.
-
-React APIs with **no** PulsePoint equivalent: `forwardRef`, `memo()` as a wrapper, `lazy`, `Suspense`, `useInsertionEffect`, `useActionState`, `useFormStatus`, free-function `startTransition`.
+Component `<script>` blocks are plain JavaScript, evaluated in component scope. Only **top-level** declarations reach the template. Props are read from `pp.props` — there is no injected `props` variable.
 
-Inside an `on*` attribute the runtime injects `event` plus the aliases `e`, `$event`, `target`, `currentTarget`, and `el`.
+- **State & derivation** — `pp.state`, `pp.reducer`, `pp.memo`, `pp.callback`, `pp.deferredValue`, `pp.optimistic`
+- **Lifecycle** — `pp.effect`, `pp.layoutEffect` (cleanups must be synchronous; always pass a dependency array)
+- **DOM & identity** — `pp.ref`, `pp.id` (for `id`/`for`/`aria-*` — never index-derived ids), `pp.portal`, `pp.imperativeHandle`
+- **Cross-tree** — `pp.createContext` + a lowercase `<themecontext.provider value="{theme}">` tag + `pp.context(token)` in descendants
+- **Resilience & external data** — `pp.errorBoundary` (`[error, reset]`), `pp.syncExternalStore` (subscribe must be `pp.callback(..., [])`-stable), `pp.transition`
 
-#### Context
+Utilities: `pp.mount`, `pp.redirect`, `pp.rpc`, `pp.socket`, and `pp.enablePerf` / `disablePerf` / `getPerfStats` / `resetPerfStats`.
 
-Providers are authored as **lowercase** tags derived from the token variable name:
+React APIs with **no** equivalent: `forwardRef`, `memo()` as a wrapper, `lazy`, `Suspense`, `useInsertionEffect`, `useActionState`, `useFormStatus`, free-function `startTransition`. `pp.transition()` reports an accurate `isPending` but does not time-slice — rendering is synchronous.
 
-```html
-<section>
-  <script>
-    const ThemeContext = pp.createContext("light");
-    const [theme, setTheme] = pp.state("dark");
-  </script>
-
-  <themecontext.provider value="{theme}">
-    <button onclick="setTheme(theme === 'dark' ? 'light' : 'dark')">
-      Theme: {theme}
-    </button>
-    <x-child-panel />
-  </themecontext.provider>
-</section>
-```
+Inside an `on*` attribute the runtime injects `event` plus the aliases `e`, `$event`, `target`, `currentTarget`, and `el`.
 
-A descendant reads it with `const theme = pp.context(ThemeContext);`.
+**Performance ownership:** `pp.state` means "a render is required". Timers, request generations, cursors, and RPC-only query text belong in `pp.ref`, whose mutation never renders. Debouncing a setter limits frequency, not render cost.
 
 ---
 
 ### 4. Components
 
-Components are Python functions decorated with `@component`, imported at the top of a template and rendered as kebab-cased `x-*` tags.
-
-#### Return a string (small, presentational)
-
-```python
-from casp.component_decorator import component
-from casp.html_attrs import get_attributes, merge_classes
-
-@component
-def Container(children: str = "", **props) -> str:
-    final_class = merge_classes("mx-auto max-w-7xl px-4", props.pop("class", ""))
-    attributes = get_attributes({"class": final_class}, props)
-    return f"<div {attributes}>{children}</div>"
-```
-
-#### Single-file with `html(...)` (small/medium, the common case)
-
-Keep markup, server interpolation, and the PulsePoint script inline. Three brace dialects coexist:
-`{{ value }}` is server-side Jinja, `{{ value | json }}` safely serializes into a `<script>`,
-`{# … #}` is a Jinja comment, and `{ value }` is left untouched for PulsePoint.
+A component is a `@component` function whose markup is authored inline and rendered as a kebab-cased `x-*` tag.
 
 ```python
 from casp.component_decorator import component, html
 from casp.html_attrs import get_attributes, merge_classes
 
+
 @component
 def UserCard(user=None, **props):
     attributes = get_attributes({
@@ -319,55 +239,40 @@ def UserCard(user=None, **props):
         "user-name": user["name"],
     }, props)
 
-    # html
-    return html("""
-      <div {{ attributes }}>
-        <h3>{{ user.name }}</h3>
-        <button onclick="setLikes(likes + 1)">Likes: {likes}</button>
-        <script>
-          const [likes, setLikes] = pp.state({{ user.likes | json }});
-        </script>
-      </div>
-    """, attributes=attributes, user=user)
+    return html(r"""
+<div {{ attributes }}>
+  <h3>{{ user.name }}</h3>
+  <button onclick="{setLikes(likes + 1)}">Likes: {likes}</button>
+  <script>
+    const [likes, setLikes] = pp.state({{ user.likes | json }});
+  </script>
+</div>
+""", attributes=attributes, user=user)
 ```
 
-> Use a raw string (`r"""…"""`) when the inline `<script>` contains backslashes (regex, `\n`).
+**`html(r"""...""")` is the one markup form** — always a raw triple-quoted literal. A non-raw string rewrites backslashes, so a regex or `\n` in the component script means one thing in the source and another at render. Never build markup as an **f-string**: it inverts the brace dialects (`{x}` becomes server interpolation), skips autoescaping while still marking the output trusted, and skips the `<x-*>` scope stash.
+
+Three brace dialects coexist inside that literal: `{{ value }}` is server-side Jinja (autoescaped), `{{ value | json }}` safely serializes a server value into a `<script>`, `{# … #}` is a Jinja comment, and `{ value }` is left untouched for PulsePoint in the browser.
 
-#### Importing and rendering
+**Composition is Python-import-driven** — the import _is_ the registration:
 
 ```python
-from casp.component_decorator import html
 from src.components.Container import Container
 from src.components.ui.Button import Button
-from src.components.Breadcrumb import Breadcrumb, BreadcrumbItem, BreadcrumbLink
-
-
-def page():
-    return html(r"""
-<x-container class="py-10">
-  <x-button variant="outline">Continue</x-button>
-</x-container>
-""")
+from src.lib.ppicons import ArrowRight, Search   # -> <x-arrow-right />, <x-search />
 ```
 
-- `Container` → `<x-container />`, `CommandDialog` → `<x-command-dialog />`.
-- A module's `x-*` tags resolve from the Component objects imported into that module — the Python import **is** the registration.
-- If one Python file exports several components, import them **from that module**, not from per-name modules that do not exist.
-- Slot content resolves in the scope where it was authored, so the module that writes an `x-*` tag must import that component.
+`Container` → `<x-container />`, `CommandDialog` → `<x-command-dialog />`. If one file exports several components, import them from that file. Slot content resolves in the scope where it was **authored**, so the module writing an `x-*` tag must import it.
 
-#### Props: every prop the template reads must be re-emitted on the root
+**Every prop the template reads must be re-emitted on the root.** This is the most common silent failure:
 
-This is the most common silent failure in Python components:
+1. Attributes on the `x-*` tag reach Python as **raw string kwargs**, kebab-case converted to camelCase — `open="{permOpen}"` arrives as the literal string `"{permOpen}"`.
+2. The component must deliberately re-emit them onto its single rendered root via `get_attributes({...}, props)` + `{{ attributes }}`.
+3. PulsePoint derives `pp.props` from **the rendered root's attributes**, evaluating brace expressions in the parent's scope.
 
-1. Attributes on the `x-*` tag arrive in Python as **raw string kwargs** (`open="{permOpen}"` arrives as the literal `"{permOpen}"`), kebab-case converted to camelCase.
-2. The Python component must deliberately re-emit them onto its single rendered root via `get_attributes({...}, props)` + `{{ attributes }}`.
-3. PulsePoint derives `pp.props` from **the rendered root's attributes** and evaluates pure `{expr}` values in the parent's scope.
+A prop accepted in Python but not re-emitted is silently `undefined` — no server error, no console warning. Forwarding does not preserve types either: a brace expression keeps its real type, a literal (`volume="0"`) arrives as a **string**, a valueless attribute arrives as `true`, `None`/`False`/`""` are omitted entirely, and JS reserved words such as `class` are dropped from `pp.props`.
 
-A prop accepted by Python but not re-emitted is silently `undefined` in the browser — no server error, no console warning. Forwarding also does not preserve types: a brace expression keeps its real type, a literal (`volume="0"`) arrives as a **string**, a valueless attribute arrives as `true`, `None`/`False`/`""` are omitted entirely, and JS reserved words such as `class` are dropped from `pp.props`.
-
-#### Tailwind class merging
-
-When `tailwindcss: true`, Python `merge_classes(...)` emits a frontend-ready `{twMerge(...)}` expression, and the browser's global `twMerge(...)` resolves conflicts. That pair is the only supported merge path.
+When `tailwindcss: true`, `merge_classes(...)` emits a frontend-ready `{twMerge(...)}` expression that the browser's `twMerge(...)` resolves. Pass it straight through — never wrap or re-merge it.
 
 ---
 
@@ -377,44 +282,28 @@ When `tailwindcss: true`, Python `merge_classes(...)` emits a frontend-ready `{t
 await pp.rpc(name, data?, optionsOrAbort?)
 ```
 
-- Posts to the **current route**; resolves the `@rpc()` function of that name in the route's `index.py`.
-- Smart serialization — switches to `FormData` automatically when a `File` is present.
-- CSRF token injected as `X-CSRF-Token`.
-- Server redirect headers are honored through `pp.redirect()`.
-- Passing `true` as the third argument means `{ abortPrevious: true }`.
+Posts to the **current route** and resolves the `@rpc()` function of that name in its `index.py`. Serialization switches to `FormData` automatically when a `File` is present, the CSRF token is injected as `X-CSRF-Token`, and server redirects are honored through `pp.redirect()`. Passing `true` as the third argument means `{ abortPrevious: true }`.
 
 Options: `abortPrevious`, `url`, `csrfUrl`, `credentials`, `onStream`, `onStreamError`, `onStreamComplete`, `onUploadProgress`, `onUploadComplete`.
 
-**Payload safety:** RPC keys are filtered against the function signature, so a parameter is client-settable only when it is declared. Declaring `**kwargs` opts into the whole payload — do that deliberately.
+**Payload safety:** RPC keys are filtered against the function signature, so a parameter is client-settable only when declared. Declaring `**kwargs` opts into the whole payload — do that deliberately, and always derive identity and ownership server-side from the session.
 
-#### Upload progress
+**Uploads** — pass the `File` through and read progress:
 
-```html
-<input type="file" onchange="{upload(event.target.files?.[0])}" />
-<progress max="100" value="{percent ?? 0}"></progress>
-
-<script>
-  const [percent, setPercent] = pp.state(null);
-
-  async function upload(file) {
-    if (!file) return;
-    await pp.rpc(
-      "upload_asset",
-      { file },
-      {
-        onUploadProgress: ({ percent }) => setPercent(percent),
-        onUploadComplete: () => setPercent(100),
-      },
-    );
-  }
-</script>
+```js
+await pp.rpc(
+  "upload_asset",
+  { file },
+  {
+    onUploadProgress: ({ percent }) => setPercent(percent),
+    onUploadComplete: () => setPercent(100),
+  },
+);
 ```
 
 `onUploadProgress` receives `{ loaded, total, percent }`; `total` and `percent` are `null` when the length is not computable.
 
-#### Streaming (the path for AI/LLM token output)
-
-A generator `@rpc()` becomes a `text/event-stream` response:
+**Streaming** (the path for AI/LLM token output) — a generator `@rpc()` becomes a `text/event-stream` response:
 
 ```python
 @rpc()
@@ -460,7 +349,7 @@ Browser-side checks are UX only. Server-side validation at the RPC/route boundar
 
 ### 7. Authentication
 
-Session-based, configured centrally in `src/lib/auth/auth_config.py` and wired in `main.py`.
+Session-based, configured centrally in `src/lib/auth/auth_config.py` and wired in `main.py`:
 
 ```python
 from casp.auth import Auth, GithubProvider, GoogleProvider, configure_auth
@@ -470,26 +359,17 @@ configure_auth(build_auth_settings())
 Auth.set_providers(GithubProvider(), GoogleProvider())
 ```
 
-| Method                                                       | Purpose                                                           |
-| ------------------------------------------------------------ | ----------------------------------------------------------------- |
-| `auth.sign_in(data, token_validity=None, redirect_to=False)` | Store the payload, set a CSRF token; returns `"ok"` or a redirect |
-| `auth.sign_out(redirect_to=None)`                            | Clear the session and redirect                                    |
-| `auth.is_authenticated()`                                    | `False` when the payload is missing, malformed, or expired        |
-| `auth.get_payload()`                                         | Read the signed-in payload                                        |
-| `auth.refresh_session()`                                     | Extend expiry when `token_auto_refresh=True`                      |
-| `auth.check_role(user, allowed_roles)`                       | RBAC check against the configured role field                      |
-
-Guards: `@rpc(require_auth=True)` for actions, `@guest_only()` / route-level guards for pages, and central public-vs-private route policy in `auth_config.py`.
+The `auth` instance exposes `sign_in(data, token_validity=None, redirect_to=False)`, `sign_out(redirect_to=None)`, `is_authenticated()`, `get_payload()`, `refresh_session()`, and `check_role(user, allowed_roles)`. Guards are `@rpc(require_auth=True)` for actions and `@require_auth()` / `@guest_only()` for pages, with public-vs-private route policy declared centrally.
 
 **OAuth is already wired.** `Auth.set_providers(...)` registers `/api/auth/signin/{google,github}` and `/api/auth/callback/{google,github}`. Link a button and set the credentials in `.env` — do not hand-roll the flow.
 
-**Redirect ownership is centralized.** Do not re-implement `next=` handling or post-login routing in a sign-in page; `auth_config.py` owns protected-route redirects, auth-route redirects, and `default_signin_redirect` (defaults to `/dashboard`).
+**Redirect ownership is centralized.** Do not re-implement `next=` handling or post-login routing in a sign-in page; `auth_config.py` owns protected-route redirects, auth-route redirects, and `default_signin_redirect`.
 
 ---
 
 ### 8. Database (Prisma)
 
-Enabled by `"prisma": true`. Define one `prisma/schema.prisma` and generate a typed Python client into `src/lib/prisma/`.
+Enabled by `"prisma": true`. Define one `prisma/schema.prisma`; the typed Python client is generated into `src/lib/prisma/`.
 
 ```python
 from src.lib.prisma import prisma
@@ -501,7 +381,7 @@ users = await prisma.user.find_many(
 )
 ```
 
-After schema changes, in this order:
+**Two generators, one schema.** After any schema change, run exactly two commands in order — sync the database, then regenerate the Python ORM:
 
 ```bash
 npx prisma migrate dev
@@ -511,9 +391,9 @@ npx prisma migrate dev
 npx ppy generate
 ```
 
-If the seed flow depends on the new schema, run `npx prisma generate` first, then `npx prisma db seed` — **`db seed` may clear or overwrite tables; confirm the datasource before running it.**
+`npx prisma generate` builds the **Node** client used by `prisma/seed.ts` and writes zero Python — it is never a substitute for `npx ppy generate`. Run it before `npx prisma db seed`, and note that **`db seed` may clear or overwrite tables; confirm the datasource first.**
 
-`src/lib/prisma/__init__.py`, `db.py`, `models.py`, and `settings/prisma-schema.json` are generated by `npx ppy generate`. Never hand-edit them, and never add a second data layer (raw drivers, hand-written SQL helpers, JSON stores, browser-side fetches) alongside the ORM.
+`src/lib/prisma/**` and `settings/prisma-schema.json` are generated. Never hand-edit them, and never add a second data layer alongside the ORM.
 
 ---
 
@@ -530,15 +410,14 @@ Every optional capability is gated by one flag in `caspian.config.json`. **That
 | `mcp`         | A FastMCP server mounted into the same app (`/mcp`)                  |
 | `websocket`   | Named sockets — `@socket()` in Python, `pp.socket()` in the browser  |
 
-#### WebSockets — named sockets
-
-Use RPC for ordinary reads, writes, uploads, and SSE streams. Reach for a socket only for **long-lived bidirectional** channels: chat, collaboration, presence, multiplayer state.
+#### Named sockets
 
-An rpc is a question with one answer, and an rpc stream is an answer that arrives in pieces. A **named socket** is the third shape — both sides may speak, at any time, for as long as the page is open. It is the socket counterpart of `@rpc()`/`pp.rpc()`: one decorated Python function, one browser call.
+Use RPC for ordinary reads, writes, uploads, and one-way streams. Reach for a socket only when **both sides may speak at any time**: chat, collaboration, presence, multiplayer state. A named socket is the socket counterpart of `@rpc()`/`pp.rpc()` — one decorated Python function, one browser call.
 
 ```python
 from src.lib.websocket.sockets import Socket, socket
 
+
 @socket()
 async def echo(label: str, socket: Socket):
     while (text := await socket.recv()) is not None:
@@ -546,59 +425,51 @@ async def echo(label: str, socket: Socket):
             break  # The browser is gone.
 ```
 
-```html
-<script>
-  const sock = pp.ref(null);
-
-  pp.effect(() => {
-    sock.current = pp.socket(
-      "echo",
-      { label: "you" },
-      {
-        onMessage: (value) => append(value),
-        onError: (error) => setStatus(error.message),
-      },
-    );
-    return () => sock.current.close();
-  }, []);
-</script>
-```
-
-Open the socket inside `pp.effect(..., [])`, keep the handle in `pp.ref(...)`, and close it in the effect's cleanup. The handle exposes `send(value)`, `close(code?, reason?)`, and `readyState`; handlers are `onOpen`, `onMessage(value)`, `onError(error)`, `onClose({ code, reason, wasClean })`.
-
-**The wire:**
+```js
+const sock = pp.ref(null);
 
-- Every socket connects to **one endpoint**, wired once in `main.py` and gated by the flag. The function is named in a query parameter, so socket names are **application-wide** — the function's own name, and a duplicate is refused at registration.
-- Arguments do **not** travel in the URL (a URL is logged by every proxy on the way) but as the connection's **first frame**: one JSON object, exactly the payload `pp.rpc` would have posted. The client sends it automatically on open. Keys are filtered against the handler's signature, like RPC.
-- Every frame after that is one JSON value, in either direction.
-- There is no status line inside an open connection, so **failure is a frame**: `{"error": "..."}` — that key alone — followed by a close. The client routes it to `onError`, never `onMessage`, and the server refuses to send that shape as an ordinary message.
-- A handler that returns is a conversation that ends: the connection closes. `await socket.send(...)` returning `False` means the browser is gone — a signal to stop, not an error to report.
+pp.effect(() => {
+  sock.current = pp.socket(
+    "echo",
+    { label: "you" },
+    {
+      onMessage: (value) => append(value),
+      onError: (error) => setStatus(error.message),
+    },
+  );
+  return () => sock.current.close();
+}, []);
+```
 
-**Broadcast:** `socket.sender()` returns a `SocketSender` — the sending half, detached from the conversation and safe to hold in shared state. A room is a `SocketPool` of senders, which prunes connections whose browser has left as it broadcasts. Keep authenticated and guest traffic in **separate pools** so a private broadcast can never fan out to a guest connection.
+Open the socket inside `pp.effect(..., [])`, keep the handle in `pp.ref(...)`, close it in the cleanup. The handle exposes `send(value)`, `close(code?, reason?)`, and `readyState`; handlers are `onOpen`, `onMessage(value)`, `onError(error)`, `onClose({ code, reason, wasClean })`.
 
-**Auth is declared per socket, not per endpoint.** `@socket()` is public, `@socket(require_auth=True)` needs a session, `@socket(allowed_roles=[...])` adds RBAC — all delegating to Caspian's `Auth`. This matters because the HTTP middleware stack early-returns on `scope["type"] == "websocket"`: `AuthMiddleware` never sees a handshake, so the socket endpoint authorizes each connection itself, alongside the anti-CSWSH origin check, connection ceiling, message-size limit, per-connection message rate, and idle timeout. The socket session is read-only — mutations are not persisted back to the cookie over a WebSocket.
+The wire, in short:
 
-A hand-written `@app.websocket(...)` route with a native browser `WebSocket` remains the escape hatch for wires the JSON-frame contract cannot carry (binary frames, non-JSON protocols) — and then the app owns every one of those checks itself.
+- Every socket connects to **one endpoint**, wired once in `main.py`. The function is named in a query parameter, so socket names are **application-wide** and a duplicate is refused at registration.
+- Arguments travel as the connection's **first frame** — one JSON object, exactly the payload `pp.rpc` would have posted — not in the URL, which every proxy logs. Keys are filtered against the handler signature, like RPC.
+- There is no status line inside an open connection, so **failure is a frame**: `{"error": "..."}`, then a close — routed to `onError`, never `onMessage`. A handler that returns ends the conversation, and `await socket.send(...)` returning `False` means the browser is gone: a signal to stop, not an error to report.
+- **Broadcast:** `socket.sender()` returns a detached `SocketSender` safe to hold in shared state; a room is a `SocketPool` of senders that prunes departed connections as it broadcasts. Keep authenticated and guest traffic in **separate pools**.
+- **Auth is declared per socket:** `@socket()` is public, `@socket(require_auth=True)` needs a session, `@socket(allowed_roles=[...])` adds RBAC.
 
-A socket declared in a route's `index.py` registers when that route first renders, which is necessarily before the browser can open it. A socket shared by several routes belongs in `src/lib/**`.
+A socket in a route's `index.py` registers when that route first renders; one shared by several routes belongs in `src/lib/**`. A hand-written `@app.websocket(...)` route stays the escape hatch for wires the JSON-frame contract cannot carry (binary frames, non-JSON protocols) — and then the app owns every security check itself.
 
 #### MCP
 
-When `mcp: true`, a FastMCP server is mounted into the same app so one deploy serves both web and MCP. The endpoint is mounted **outside** the routing tree, so `AuthMiddleware` does not cover it — `MCP_AUTH_TOKEN` is its credential. With no token it stays open in development and returns **503 in production**.
+When `mcp: true`, a FastMCP server is mounted into the same app so one deploy serves both web and MCP. The endpoint sits **outside** the routing tree, so `AuthMiddleware` does not cover it — `MCP_AUTH_TOKEN` is its credential. With no token it stays open in development and returns **503 in production**.
 
 ---
 
 ## Security defaults
 
-Caspian ships fail-closed defaults. Things worth knowing before you change them:
+Caspian ships fail-closed. Worth knowing before changing any of it:
 
 - **`APP_ENV` resolves fail-closed.** Only an explicit development value (`dev`, `development`, `local`, `staging`, `test`, `testing`) enables relaxations. Unset or misspelled counts as **production**.
-- **Server-interpolated values never carry live PulsePoint syntax.** The Jinja environment encodes `{` / `}` as entities on every non-`Markup` value, so stored user data can never execute as a template expression. `Markup` is the trust boundary — `| safe`, `get_attributes(...)`, `merge_classes(...)`, and the `json` filter legitimately keep their braces.
-- **Authenticated renders are never cached.** The page cache keys on the URI alone, so a request-eligibility check gates both the read and the write; a route's `Cache(...)` cannot override it.
+- **Server-interpolated values never carry live PulsePoint syntax.** Jinja encodes `{` / `}` as entities on every non-`Markup` value, so stored user data cannot execute as a template expression. `Markup` is the trust boundary — `| safe`, `get_attributes(...)`, `merge_classes(...)`, and the `json` filter legitimately keep their braces.
+- **Authenticated renders are never cached.** The page cache keys on the URI alone, so an eligibility check gates both read and write; a route's `Cache(...)` cannot override it.
 - **RPC payload keys are filtered against the function signature.**
 - **`/uploads` serves user content in attachment mode**; only real image types render inline. First-party `/css`, `/js`, and `/assets` stay inline.
+- **Sockets authorize themselves.** The HTTP middleware stack early-returns on `scope["type"] == "websocket"`, so `AuthMiddleware` never sees a handshake — HTTP route privacy does not extend to a socket.
 - **CSRF protection, strict Origin validation, HttpOnly cookies, security headers, and page rate limiting** are on by default.
-- **Sockets authorize themselves.** The HTTP middleware stack early-returns on `scope["type"] == "websocket"`, so `AuthMiddleware` never sees a handshake. The named-socket endpoint runs the origin check, connection cap, and per-socket auth itself — HTTP route privacy does not extend to a socket.
 
 Security-relevant environment variables: `MCP_AUTH_TOKEN`, `RATE_LIMIT_PAGES` (default `200/minute`), `CONTENT_SECURITY_POLICY` (replaces the default policy wholesale), `MAX_WEBSOCKET_CONNECTIONS`, `MAX_WEBSOCKET_MESSAGE_BYTES`, `MAX_WEBSOCKET_MESSAGES_PER_WINDOW`, `WEBSOCKET_RATE_WINDOW_SECONDS`, `WEBSOCKET_IDLE_TIMEOUT_SECONDS`, and `WEBSOCKET_ALLOWED_ORIGINS` (**required in production** — the same-origin fallback is derived from the client-supplied `Host` header and is development-only).
 
@@ -608,23 +479,18 @@ Security-relevant environment variables: `MCP_AUTH_TOKEN`, `RATE_LIMIT_PAGES` (d
 
 ```
 my-app/
-├── main.py                      # FastAPI entry point, middleware stack, WebSocket + MCP mounts
+├── main.py                      # FastAPI entry point, middleware stack, socket + MCP mounts
 ├── caspian.config.json          # Feature flags — the single source of truth
-├── pyproject.toml               # Python deps and tooling config
-├── package.json                 # CLI/tooling scripts
-├── prisma/
-│   ├── schema.prisma
-│   └── seed.ts
+├── prisma/schema.prisma
 ├── src/
 │   ├── app/                     # File-system routes
-│   │   ├── layout.py            # Root layout (template + props from layout())
+│   │   ├── layout.py            # Root layout
 │   │   ├── index.py             # Home page (markup + logic in one file)
 │   │   ├── globals.css
-│   │   ├── error.py             # Global 500 page
-│   │   ├── not_found.py         # Global 404 page
-│   │   ├── dashboard/loading.py # /dashboard navigation loading UI
-│   │   └── users/[id]/
-│   │       └── index.py         # /users/:id
+│   │   ├── not_found.py         # Global 404
+│   │   ├── error.py             # Global 500
+│   │   ├── dashboard/loading.py # Optional: /dashboard navigation loading UI
+│   │   └── users/[id]/index.py  # /users/:id
 │   ├── components/              # Reusable UI (@component)
 │   └── lib/                     # Non-UI code
 │       ├── auth/auth_config.py
@@ -635,19 +501,17 @@ my-app/
 └── settings/                    # Dev stack config and generated indexes
 ```
 
-### Placement rules
+**Placement rules**
 
-- **Route-owned** logic (first-render query, route `@rpc()` actions, redirects, route validation) stays in that route's `index.py`. Move it to `src/lib/**` only when it is genuinely shared.
+- **Route-owned** logic (first-render query, route `@rpc()` actions, redirects, validation) stays in that route's `index.py`. Move it to `src/lib/**` only when genuinely shared.
 - **Reusable UI** goes in `src/components/`; **helpers, services, adapters** go in `src/lib/`.
-- **Compose pages from components.** A route's page template should read as a short assembly of `x-*` chunks (topbar, sidebar, header, sections, forms, footer), not a wall of markup. Plan the breakdown before writing the route.
-- **Generated, never hand-edited:** `src/lib/prisma/**`, `settings/prisma-schema.json`, `settings/files-list.json`, `settings/component-map.json`, `public/css/styles.css`, `__pycache__/`.
+- **Compose pages from components.** A route's template should read as a short assembly of `x-*` chunks (topbar, sidebar, sections, forms, footer), not a wall of markup. Plan the breakdown before writing the route.
+- **Generated, never hand-edited:** `src/lib/prisma/**`, `settings/prisma-schema.json`, `settings/files-list.json`, `settings/component-map.json`, `public/css/styles.css`.
 
 ---
 
 ## CLI reference
 
-### Create
-
 ```bash
 npx create-caspian-app my-app
 ```
@@ -664,21 +528,9 @@ npx create-caspian-app my-app
 | `--starter-kit-source=<url>` | Git repository for `--starter-kit=custom`         |
 | `--list-starter-kits`        | Print the built-in starter catalog                |
 
-In `-y` mode every feature defaults to `false`. Starter kit presets can still be overridden by explicit flags: `npx create-caspian-app my-app --starter-kit=fullstack --typescript`.
-
-`websocket` has no create flag — enable it in `caspian.config.json` after scaffold, then run the update command.
+In `-y` mode every feature defaults to `false`, and starter-kit presets can still be overridden by explicit flags. `websocket` has no create flag — enable it in `caspian.config.json` after scaffold, then run `npx casp update project` (which also accepts `--tag beta` / `--version 1.2.3` and `-y`). Use `excludeFiles` in `caspian.config.json` to protect files you have customized (commonly `./src/lib/auth/auth_config.py`) from being overwritten on update.
 
-### Update an existing project
-
-```bash
-npx casp update project
-```
-
-Also accepts a positional tag or version, or the named forms `--tag beta`, `--tag=beta`, `--version 1.2.3`, `--version=1.2.3`, plus `-y`. Supplying more than one version source is an error. On Windows the updater resolves `npx.cmd`, and the creator reuses an existing `.venv` rather than recreating it.
-
-Use `excludeFiles` in `caspian.config.json` to protect files you have customized (a common entry is `./src/lib/auth/auth_config.py`) from being overwritten on update. Excluded files are yours to merge going forward.
-
-### Project scripts
+**Project scripts**
 
 | Command                | What it does                                                       |
 | ---------------------- | ------------------------------------------------------------------ |
@@ -687,50 +539,30 @@ Use `excludeFiles` in `caspian.config.json` to protect files you have customized
 | `npm run static`       | Export every static route to `static/` (SSG)                       |
 | `npm run static:serve` | Preview the exported folder on an auto-selected free loopback port |
 
-These are opt-in workflows. Don't run them as a validation step just because source files changed.
+These are opt-in workflows — don't run them as a validation step just because source files changed.
 
 ---
 
 ## Static export (SSG)
 
-`npm run static` boots the app and writes `static/<route>/index.html` plus copied public assets — the equivalent of Next.js `output: export`. It always runs `npm run build` first so the export walks a fresh route index.
+`npm run static` boots the app and writes `static/<route>/index.html` plus copied public assets — the equivalent of Next.js `output: export`, running `npm run build` first so the export walks a fresh route index. Policy is **warn & skip**: dynamic routes are pre-rendered only when their `index.py` exports `static_paths` (the `getStaticPaths` equivalent); auth-gated, non-200, and non-HTML routes are reported and skipped.
 
-Policy is **warn & skip**: dynamic routes are pre-rendered only when their `index.py` exports `static_paths` (the `getStaticPaths` equivalent); auth-gated, non-200, and non-HTML routes are reported and skipped.
-
-`npm run static:serve` serves only `static/`, binds loopback `127.0.0.1` (network exposure is opt-in via `HOST=0.0.0.0`), and walks upward from port 8000 until it finds a free one — **read the port it prints**.
-
-`pp.rpc()`, auth, WebSockets, streaming, and per-request server data are all inert in a static export.
+`npm run static:serve` serves only `static/`, binds loopback `127.0.0.1` (network exposure is opt-in via `HOST=0.0.0.0`), and walks upward from port 8000 until it finds a free one — **read the port it prints**. `pp.rpc()`, auth, WebSockets, streaming, and per-request server data are all inert in a static export.
 
 ---
 
 ## Ecosystem
 
-### ppicons — 1,500+ Lucide-based icons as Python components
+Two CLIs install ready-made Python components into `src/lib/`, where they behave like any other `x-*` tag:
 
 ```bash
-npx ppicons add Rocket
+npx ppicons add Rocket          # 1,500+ Lucide-based icons
+npx maddex add button card dialog   # shadcn-style UI kit
 ```
 
 ```python
-from src.lib.ppicons.Rocket import Rocket
-```
-
-```html
-<x-rocket class="w-6 h-6 text-primary" />
-```
-
-### maddex — shadcn-style UI component kit for Caspian
-
-```bash
-npx maddex add button card dialog
-```
-
-```python
-from src.lib.maddex.Button import Button
-```
-
-```html
-<x-button variant="outline">Continue</x-button>
+from src.lib.ppicons import Rocket        # -> <x-rocket class="size-6" />
+from src.lib.maddex.Button import Button  # -> <x-button variant="outline">Continue</x-button>
 ```
 
 ---