caspian-utils 0.1.1 → 0.1.3

package/dist/docs/ai-validation-checklist.md

@@ -56,7 +56,7 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | Make a grouped shell keep sidebar scroll while resetting page content on child-route navigation. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [core-runtime-map.md](./core-runtime-map.md) | `src/app/**/layout.html`, `public/js/pp-reactive-v2.js`, `main.py` | `pp-reset-scroll` placement, push-vs-history scroll behavior, and shared-shell ownership |
 | Create a new contact page with interactive form behavior. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md) | `src/app/**/index.html`, `main.py`, `.venv/Lib/site-packages/casp/components_compiler.py`, `.venv/Lib/site-packages/casp/scripts_type.py` | single-root template shape, script-inside-root authoring, and authored-vs-runtime boundaries |
 | Add a button, filter, or form interaction to a route template. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) | `src/app/**/index.html`, `public/js/pp-reactive-v2.js`, `main.py` | PulsePoint `on*` event attributes, `pp.state`, directives, `Object.fromEntries(new FormData(...).entries())` for simple form submits, and avoiding id-driven `querySelector` or `addEventListener` wiring |
-| Add a file manager page with upload progress and persisted metadata. | [index.md](./index.md), [file-uploads.md](./file-uploads.md), [fetch-data.md](./fetch-data.md), [database.md](./database.md) | `src/app/**/index.html`, `src/app/**/index.py`, `src/lib/**`, `prisma/schema.prisma` when Prisma applies | route-owned upload actions, persisted metadata flow, and Prisma-backed storage boundaries |
+| Add a file manager page with upload progress and persisted metadata. | [index.md](./index.md), [file-uploads.md](./file-uploads.md), [fetch-data.md](./fetch-data.md), [database.md](./database.md) | `src/app/**/index.html`, `src/app/**/index.py`, `src/lib/**`, `prisma/schema.prisma` when Prisma applies | route-owned upload actions, persisted metadata flow, and mandatory Prisma Python ORM use for database reads and writes when Prisma is enabled |
 | Explain why authored Caspian templates use a plain `<script>` instead of `type="text/pp"`. | [index.md](./index.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md), [routing.md](./routing.md) | `main.py`, `.venv/Lib/site-packages/casp/scripts_type.py`, `.venv/Lib/site-packages/casp/components_compiler.py` | script rewriting, `pp-component` injection, and authored-vs-runtime boundaries |
 | Debug why `StateManager` does not persist across a full redirect. | [index.md](./index.md), [state.md](./state.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/state_manager.py` | wire vs non-wire reset behavior and `request.state.session` dependency |
 | Trace the auth cookie and CSRF cookie names used in development. | [index.md](./index.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/auth.py` | development cookie scoping and CSRF or session naming ownership |
@@ -64,6 +64,7 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | Decide whether a dashboard child route should use page caching. | [index.md](./index.md), [cache.md](./cache.md), [routing.md](./routing.md), [fetch-data.md](./fetch-data.md) | `main.py`, `.venv/Lib/site-packages/casp/cache_handler.py`, the route's `index.py` | route-level cache ownership, cacheable HTML scope, and invalidation points |
 | Add a PulsePoint context provider to a reusable component. | [index.md](./index.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md) | `ts/TemplateCompiler.ts`, `public/js/pp-reactive-v2.js`, component `.html`, `.venv/Lib/site-packages/casp/components_compiler.py` | lowercase HTML-first `*.provider` usage, logical ancestry, single-root template shape |
 | Add upload progress to an existing file manager. | [index.md](./index.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md), [file-uploads.md](./file-uploads.md), [fetch-data.md](./fetch-data.md) | `src/app/**/index.py`, `src/app/**/index.html`, `src/lib/**`, `public/js/pp-reactive-v2.js` | `pp.rpc` upload options, state replacement, persisted metadata, BrowserSync ignore rules |
+| Add or debug a live WebSocket channel. | [index.md](./index.md), [websockets.md](./websockets.md), [core-runtime-map.md](./core-runtime-map.md), [pulsepoint.md](./pulsepoint.md), [auth.md](./auth.md) | `caspian.config.json`, `main.py`, `src/lib/websocket/**`, `src/app/**`, `settings/bs-config.json` | `websocket` feature gate, endpoint registration, origin checks, auth/session handling, native `WebSocket` client lifecycle, and BrowserSync URL selection |
 | Decide whether MCP files should be created. | [index.md](./index.md), [mcp.md](./mcp.md), [commands.md](./commands.md), [project-structure.md](./project-structure.md) | `caspian.config.json`, `settings/restart-mcp.ts`, `package.json`, `src/lib/mcp/**` when enabled | `mcp` feature gate, update workflow, nested FastMCP config ownership |
 
 Treat the table as a prompt pack for spot checks, not as a full validation matrix.
@@ -76,6 +77,8 @@ Treat the table as a prompt pack for spot checks, not as a full validation matri
 - AI treats runtime HTML examples as authored template examples.
 - AI generates a route or component template with a valid-looking root element but leaves a sibling top-level `<script>` or second top-level element after it.
 - AI starts first-party interactivity with ids, `data-*` attributes, `querySelector`, `addEventListener`, manual `fetch`, manual `innerHTML`, or per-input `pp-ref` payload collection instead of PulsePoint `on*` attributes, form submit events, state, directives, and `pp.rpc()`.
+- AI bypasses the generated Prisma Python ORM in a Prisma-enabled project with direct database drivers, custom fetch helpers, JSON active stores, browser-side database fetches, or a second app-owned database abstraction.
+- AI extracts one-route backend logic into `src/lib/**` even though the logic is not shared; route-specific first-render queries, RPC actions, validation, and response shaping belong in the owning `src/app/**/index.py`.
 - AI puts `pp-reset-scroll="true"` on the whole shell or `body` when only the page-content pane should reset, causing persistent sidebars or rails to lose their scroll position.
 - AI decides behavior from memory without checking the owning implementation details.
 

package/dist/docs/commands.md

@@ -179,9 +179,12 @@ In skip-prompt mode, the default feature values are:
 
 - `backendOnly: false`
 - `tailwindcss: false`
-- `typescript: false`
-- `mcp: false`
-- `prisma: false`
+- `typescript: false`
+- `mcp: false`
+- `prisma: false`
+- `websocket: false`
+
+If a project needs WebSockets after creation, set `websocket: true` in `caspian.config.json`, then run the project update workflow so framework-managed files and any scaffolded socket surfaces stay aligned before assuming `@app.websocket(...)` routes or `src/lib/websocket/**` exist.
 
 ### 4.2 Backend-only combinations
 

package/dist/docs/core-runtime-map.md

@@ -7,8 +7,9 @@ related:
   links:
     - /docs/project-structure
     - /docs/routing
-    - /docs/auth
+    - /docs/auth
     - /docs/fetch-data
+    - /docs/websockets
     - /docs/pulsepoint
     - /docs/pulsepoint-runtime-map
     - /docs/index
@@ -59,6 +60,7 @@ Use this table when the task names a framework feature but the owning file is no
 | Baseline response headers and safe public-file serving | `main.py` imports from `casp.runtime_security` | `.venv/Lib/site-packages/casp/runtime_security.py` | [auth.md](./auth.md), [project-structure.md](./project-structure.md) |
 | RPC and server actions | route or component Python modules with `@rpc()` | `casp.rpc`, `main.py` middleware | [fetch-data.md](./fetch-data.md), [file-uploads.md](./file-uploads.md) |
 | Streaming | route `page()` generators, RPC generators | `casp.streaming`, `casp.rpc`, `main.py` | [fetch-data.md](./fetch-data.md) |
+| WebSockets | `main.py` `@app.websocket(...)` endpoints when `caspian.config.json` has `websocket: true`, `src/lib/**` socket helpers, route-owned browser clients in `src/app/**` | FastAPI app-owned ASGI endpoints in `main.py` | [websockets.md](./websockets.md), [auth.md](./auth.md), [pulsepoint.md](./pulsepoint.md) |
 | Server state | request handlers and RPC actions | `casp.state_manager`, `main.py` middleware | [state.md](./state.md) |
 | Page caching | route-level `Cache(...)` declarations | `casp.cache_handler`, `main.py` cache check/save | [cache.md](./cache.md) |
 | Validation | route and RPC input boundaries | `casp.validate` | [validation.md](./validation.md) |
@@ -111,7 +113,8 @@ Use these behavior checkpoints when AI needs the fastest verification path for a
 | Runtime area | Verify these behaviors |
 | --- | --- |
 | `main.py` routing and request flow | route registration, path and query injection, static asset handling, session-middleware wiring, response-header middleware, and exception rendering |
-| `public/js/pp-reactive-v2.js` browser runtime | SPA interception, history-vs-push scroll behavior, `pp-reset-scroll` semantics, and browser-side `pp.rpc()` behavior |
+| `main.py` WebSockets | `cfg.websocket` route-registration gate, `@app.websocket(...)` paths, origin checks before `accept()`, auth/session extraction, message-size and idle-timeout handling, close codes, and connection cleanup |
+| `public/js/pp-reactive-v2.js` browser runtime | SPA interception, history-vs-push scroll behavior, `pp-reset-scroll` semantics, and browser-side `pp.rpc()` behavior |
 | `casp.auth` | auth settings, signin and signout flow, provider wiring, and page protection behavior |
 | `casp.rpc` and streamed RPC responses | middleware interception, CSRF and session expectations, registry behavior, and helper-level RPC contracts |
 | `casp.layout` | layout discovery, metadata merge, root handling, and layout rendering rules |

package/dist/docs/database.md

@@ -14,7 +14,9 @@ related:
 
 This page documents the Prisma workflow for Caspian projects where `caspian.config.json` enables Prisma.
 
-When a project enables Prisma, use `prisma/schema.prisma` for schema management, `prisma.config.ts` for Prisma config and seed wiring, and reuse an app-owned `src/lib/prisma/` package when the project includes one.
+When a project enables Prisma, use `prisma/schema.prisma` for schema management, `prisma.config.ts` for Prisma config and seed wiring, and reuse an app-owned `src/lib/prisma/` package when the project includes one.
+
+High-priority rule: when `caspian.config.json` has `prisma: true`, Python-side database access must use the generated Prisma Python ORM. Route `page()` functions, route-owned `@rpc()` actions, auth handlers, upload flows, and shared helpers should import the generated client from `src/lib/prisma/**` instead of inventing direct driver calls, hand-written SQL wrappers, JSON manifests as active stores, app-specific HTTP fetches, or browser-side database fetches. Use raw SQL only through Prisma as a narrow fallback when the generated ORM cannot express a query clearly.
 
 Treat `caspian.config.json` as the single source of truth for whether Prisma is enabled in a workspace. If `prisma` is false and the user wants Prisma, ask first, then update `caspian.config.json` and run `npx casp update project` before assuming Prisma-managed files exist.
 
@@ -29,7 +31,7 @@ The standard Prisma flow in Caspian is:
 5. Run `npx ppy generate` so the Python ORM classes stay aligned with the updated schema.
 6. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access, and never hand-edit generated ORM classes.
 
-Use this workflow instead of writing raw SQL first. Drop to raw SQL only when a query cannot be expressed clearly with the generated client.
+Use this workflow instead of writing raw SQL first. Drop to raw SQL only through Prisma when a query cannot be expressed clearly with the generated client.
 
 ## Environment Setup
 
@@ -157,7 +159,7 @@ If Python route or RPC code needs database access, import from `src.lib.prisma`
 
 ## Python Route Usage
 
-If the project ships an app-owned Python Prisma-style layer under `src/lib/prisma/`, treat it as async-first and reuse it from route and RPC code.
+If the project ships an app-owned Python Prisma-style layer under `src/lib/prisma/`, treat it as async-first and reuse it from route and RPC code. In a Prisma-enabled project, this is the required data-access path for Python code.
 
 Example:
 
@@ -178,7 +180,7 @@ Prisma calls fit naturally in:
 - `async def page()` for first-render data
 - `@rpc()` actions for browser-triggered reads and writes
 
-Keep route-specific Prisma I/O in `page()` or `@rpc()` actions. The installed layout engine supports synchronous and async `layout()` results, but layout work should stay focused on shared subtree props or metadata.
+Keep route-specific Prisma I/O in that route's `page()` or `@rpc()` actions in `src/app/**/index.py`. The installed layout engine supports synchronous and async `layout()` results, but layout work should stay focused on shared subtree props or metadata. Move Prisma helpers into `src/lib/**` only when the same behavior is reused by multiple routes, features, or integrations.
 
 See `fetch-data.md` for the recommended route-render versus RPC split.
 
@@ -325,12 +327,13 @@ users = await prisma.query_raw(
 )
 ```
 
-Use raw SQL sparingly. Prefer the generated Prisma API when the query can be expressed clearly there.
+Use raw SQL sparingly and only through Prisma. Prefer the generated Prisma API when the query can be expressed clearly there.
 
 ## Recommended Project Rules
 
 - Keep the schema in `prisma/schema.prisma` and follow the required regeneration order after changes: `npx prisma migrate dev`, optional seed flow, then `npx ppy generate`.
-- Reuse `src/lib/prisma/` for Python-side database access instead of creating a second bridge.
+- Reuse `src/lib/prisma/` for Python-side database access instead of creating a second bridge.
+- When Prisma is enabled, do not bypass the Prisma Python ORM with direct database drivers, custom fetch functions, JSON files as active stores, or browser-side database access.
 - Never hand-edit generated Prisma or Python ORM classes.
 - Keep reusable database helpers in `src/lib/`, and keep route-specific orchestration in `src/app/`.
 - Use `await` with Prisma operations.
@@ -349,7 +352,8 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 - Run `npx ppy generate` after schema changes to refresh the Python ORM classes.
 - Never hand-edit generated Prisma or Python ORM classes.
 - Read `prisma.config.ts` and `prisma/seed.ts` when you need the current project's Prisma tooling examples.
-- Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
+- Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
+- Treat use of the Prisma Python ORM as mandatory for Python-side database reads and writes in Prisma-enabled projects.
 - For file managers and uploads, persist metadata in Prisma and keep blob storage separate. See [file-uploads.md](./file-uploads.md).
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.
 - Use `async def page()` for route-specific first-render reads. Use `layout()` only for shared subtree props or metadata, and use `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.

package/dist/docs/fetch-data.md

@@ -23,6 +23,10 @@ This page explains how data fetching works in Caspian. Use route functions for i
 
 Treat RPC as the default way for browser code to talk to Python in Caspian. For CRUD operations and any browser-initiated backend reads after first render, default to `@rpc()` on the server and `pp.rpc()` in PulsePoint code. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
 
+WebSockets are the main exception for long-lived bidirectional live channels when `caspian.config.json` has `websocket: true`. If the task needs a native browser `WebSocket`, persistent broadcast channel, presence, live chat, or socket origin/auth handling, confirm that flag and read [websockets.md](./websockets.md) before adding endpoint or client code. Do not use WebSockets as a replacement for ordinary RPC form submits or CRUD work.
+
+When `caspian.config.json` has `prisma: true`, the Python side of those route and RPC actions must use the generated Prisma Python ORM from `src/lib/prisma/**` for database reads and writes. The browser asks Python through `pp.rpc(...)`; Python asks the database through Prisma. Do not replace either side with a custom browser fetch, direct database driver, hand-written SQL helper, JSON active store, or second app-owned data-fetch abstraction.
+
 Browser-triggered data work should still be PulsePoint-first at the event layer. Bind the initiating click, submit, input, upload, refresh, filter, or pagination control in authored HTML with `onclick`, `onsubmit`, `oninput`, `onchange`, or another native `on*` attribute handled by PulsePoint. For normal form submissions, read named controls with `Object.fromEntries(new FormData(event.currentTarget).entries())` in the submit handler and pass that object directly to `pp.rpc(...)`; the route's Python `@rpc()` action should validate, normalize, and decide what to persist. Do not set up first-party data actions by assigning ids and then wiring `querySelector(...)`, `addEventListener(...)`, manual `fetch(...)`, manual DOM repainting, or per-input `pp-ref` payload collection.
 
 MCP is a separate integration surface. Do not place app-owned FastMCP tools in route `index.py` files or treat `@rpc()` actions as a replacement for MCP tools. Use `mcp.md` and `src/lib/mcp/` only when `caspian.config.json` has `mcp: true`. If `mcp` is false, do not assume those files exist.
@@ -49,6 +53,7 @@ When a page belongs to a grouped subtree such as a dashboard, account area, admi
 - Use `page()` for route-level data required before HTML renders, and use `layout()` only for shared subtree props or metadata.
 - When a route renders UI and also needs backend work, keep the HTML in the sibling `index.html`; `index.py` should prepare data and call `render_page(__file__, ...)`, not inline the route markup.
 - Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render, including CRUD operations and follow-up reads.
+- When Prisma is enabled, route all Python database I/O inside `page()`, `layout()` when truly shared, `@rpc()` actions, and reusable helpers through the generated Prisma Python ORM.
 - Trigger those browser actions through PulsePoint event attributes in the HTML, not through a separate DOM listener layer.
 - For simple form submits, prefer `onsubmit="{submitForm(event)}"` plus `Object.fromEntries(new FormData(event.currentTarget).entries())` over `pp-ref` fields and effect-managed submit listeners.
 - Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
@@ -86,7 +91,7 @@ Notes:
 - Use a normal parent folder such as `dashboard/` when the section name should appear in the URL. Use a route-group folder such as `(reports)/` only when the shared wrapper should organize child routes without adding a URL segment.
 - Keep reusable database or API clients under `src/lib/`; keep route-specific orchestration in `src/app/`.
 
-If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the project's schema, migration, and generation workflow. If the project includes an app-owned Python database layer under `src/lib/prisma/`, reuse it instead of creating another helper.
+If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the project's schema, migration, and generation workflow. If the project includes an app-owned Python database layer under `src/lib/prisma/`, reuse it instead of creating another helper. In Prisma-enabled projects, direct driver access and custom fetch helpers are exceptions to avoid, not alternate defaults.
 
 ## Interactive Data With RPC
 
@@ -135,6 +140,8 @@ Call it from the client with `pp.rpc()`:
 </script>
 ```
 
+Do not call `fetch("/api/todos")` from the browser for normal Caspian CRUD when the route can expose an `@rpc()` action. Do not use `fetch()` or a database driver in Python to work around Prisma when `src/lib/prisma/**` already provides the generated ORM client.
+
 For form submissions, let the form event provide the submitted values. The inputs' `name` attributes define the RPC payload keys, and the Python action owns trimming, validation, coercion, and persistence decisions.
 
 ```html
@@ -179,7 +186,8 @@ Important:
 
 - `pp.rpc()` posts to the current route RPC bridge.
 - Older docs may refer to `pp.fetchFunction()`. In this repo's current runtime, the supported helper is `pp.rpc()`.
-- Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when debugging browser-side RPC options such as streaming, upload progress, abort behavior, redirects, or SPA interaction.
+- Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when debugging browser-side RPC options such as streaming, upload progress, abort behavior, redirects, or SPA interaction.
+- Use [websockets.md](./websockets.md) when `caspian.config.json` has `websocket: true` and the browser and server need a persistent bidirectional channel instead of request/response RPC or one-way SSE streaming.
 
 ## Streaming Responses
 

package/dist/docs/file-conventions.md

@@ -83,7 +83,7 @@ Use `index.html` by itself when the route is UI-only.
 
 ## `index.py`
 
-`index.py` is the backend companion for a route.
+`index.py` is the backend companion for a route.
 
 Add it when the route needs:
 
@@ -92,9 +92,13 @@ Add it when the route needs:
 - auth checks or redirects
 - route-level `Cache(...)`
 - route-owned `@rpc()` actions
-- server-side context before rendering the sibling template
-
-For UI routes, `index.py` does not replace `index.html`. It prepares data and calls `render_page(__file__, ...)` so Caspian renders the sibling template.
+- server-side context before rendering the sibling template
+
+For UI routes, `index.py` does not replace `index.html`. It prepares data and calls `render_page(__file__, ...)` so Caspian renders the sibling template.
+
+Keep logic here when it belongs only to this route. That includes route-specific first-render queries, `@rpc()` actions, auth checks, redirects, filters, validation, upload orchestration, and response shaping. Move logic to `src/lib/**` only when it is shared across routes, components, integrations, or features. Do not extract one-route logic into a library just because it is written in Python.
+
+When `caspian.config.json` has `prisma: true`, route-specific database access in `index.py` should use the generated Prisma Python ORM from `src/lib/prisma/**`. Shared database helpers may live in `src/lib/**`, but they should still call the generated Prisma Python ORM rather than a separate fetch or driver layer.
 
 Example:
 
@@ -251,11 +255,12 @@ If rendering `error.html` fails, the runtime falls back to a minimal plain HTML
 Use this order when deciding where a concern belongs:
 
 1. Put visible route markup in `index.html`.
-2. Add `index.py` only when the same route needs backend work.
-3. Put shared subtree wrapper markup in `layout.html`.
-4. Add `layout.py` only when that shared shell needs synchronous Python props or metadata.
-5. Add `loading.html` when SPA navigation needs an immediate scoped loading state.
-6. Use root `not-found.html` for unmatched URLs.
-7. Use root `error.html` for unhandled exceptions.
+2. Add `index.py` only when the same route needs backend work.
+3. Keep route-specific logic in `index.py`; move logic into `src/lib/**` only when it is actually shared.
+4. Put shared subtree wrapper markup in `layout.html`.
+5. Add `layout.py` only when that shared shell needs synchronous Python props or metadata.
+6. Add `loading.html` when SPA navigation needs an immediate scoped loading state.
+7. Use root `not-found.html` for unmatched URLs.
+8. Use root `error.html` for unhandled exceptions.
 
 Use [routing.md](./routing.md) for the broader file-based routing model, [metadata.md](./metadata.md) for page and layout metadata, [cache.md](./cache.md) for route caching in `index.py`, and [pulsepoint.md](./pulsepoint.md) for the authored template contract and browser runtime behavior.

package/dist/docs/index.md

@@ -11,8 +11,9 @@ related:
     - /docs/core-runtime-map
     - /docs/pulsepoint-runtime-map
     - /docs/mcp
-    - /docs/file-uploads
-    - /docs/file-conventions
+    - /docs/file-uploads
+    - /docs/websockets
+    - /docs/file-conventions
     - /docs/project-structure
     - /docs/components
 ---
@@ -23,7 +24,7 @@ Treat these docs as reusable Caspian feature guidance. Treat `./caspian.config.j
 
 The docs can mention optional features even when those features are disabled in a project. Their job is to explain how a feature works, when a doc applies, and which files to inspect next once the feature is confirmed as relevant.
 
-Before making feature, tooling, or file-placement decisions in a Caspian project, read `./caspian.config.json` almost immediately. That file tells you which optional capabilities are enabled, such as Prisma, MCP, TypeScript, Tailwind, backend-only mode, and component scan directories.
+Before making feature, tooling, or file-placement decisions in a Caspian project, read `./caspian.config.json` almost immediately. That file tells you which optional capabilities are enabled, such as Prisma, MCP, WebSockets, TypeScript, Tailwind, backend-only mode, and component scan directories.
 
 ## Default Stack
 
@@ -33,8 +34,10 @@ When generating or editing a Caspian app, treat these as the default choices unl
 - For first-party HTML events and reactivity, use PulsePoint `on*` attributes, state, refs, effects, directives, and `pp.rpc()` instead of ordinary DOM wiring with ids, `data-*` state, `querySelector`, `addEventListener`, or manual `innerHTML`.
 - Treat every authored route, layout, and component HTML file like a React component return value: exactly one top-level parent HTML element or one imported `x-*` root, with any owned plain `<script>` kept inside that same root.
 - When `caspian.config.json` has `tailwindcss: true`, use Python `merge_classes(...)` plus browser `twMerge(...)` as the only supported Tailwind class-merging path.
-- Use `@rpc()` plus `pp.rpc()` for browser-triggered reads, writes, streaming, and uploads.
-- Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
+- Use `@rpc()` plus `pp.rpc()` for browser-triggered reads, writes, streaming, and uploads.
+- When `caspian.config.json` has `websocket: true`, use app-owned FastAPI WebSocket endpoints only for long-lived bidirectional live channels; keep normal browser-triggered data work on RPC.
+- When `caspian.config.json` has `prisma: true`, use the generated Prisma Python ORM from `src/lib/prisma/**` for Python-side database reads and writes. Do not invent a second fetch layer, raw driver wrapper, JSON active store, or browser-side data path that bypasses Prisma.
+- Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
 
 ## AI Doc Shape
 
@@ -82,8 +85,9 @@ The packaged Caspian docs referenced by this index live here:
 - `file-conventions.md` - quick decision guide for `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, and `error.html`, plus the owning runtime files to verify
 - `components.md` - Create reusable Python components, template-backed UI, HTML-first `x-*` component tags, the single-parent authored-root rule for component HTML files, and the Python-side `merge_classes(...)` contract when Tailwind CSS is enabled
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, first-party `on*` events, state, effects, directives, SPA navigation scroll restoration, `pp-reset-scroll`, and direct browser `twMerge(...)` usage when Tailwind CSS is enabled
-- `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
-- `file-uploads.md` - Route-local file uploads and file-manager flows with `@rpc()`, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync ignore rules
+- `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
+- `websockets.md` - WebSocket feature-gate guidance for projects where `caspian.config.json` has `websocket: true`, app-owned FastAPI endpoint placement, browser `WebSocket` clients inside PulsePoint templates, origin checks, auth/session handling, and when to choose sockets over RPC or SSE
+- `file-uploads.md` - Route-local file uploads and file-manager flows with `@rpc()`, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync ignore rules
 - `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows
 - `cache.md` - Route-level HTML caching with `Cache`, `CacheHandler`, TTL behavior, file-system storage, and invalidation patterns
 - `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
@@ -101,14 +105,16 @@ Preferred lookup order:
 2. Read `./caspian.config.json` before making any feature assumption. A doc existing in the package does not mean that feature is enabled in the current project.
 3. Before authoring or editing any `src/app/**` or component HTML template, apply the single-root invariant: one authored root only, any owned `<script>` inside that root, and no handwritten `pp-component` or `type="text/pp"`.
 4. Before inventing browser JavaScript, check whether the interaction is first-party UI behavior. If it is, use PulsePoint `on*` attributes, `pp.state`, refs, effects, directives, and `pp.rpc()` rather than id-driven DOM scripting.
-5. Treat `caspian.config.json` as the single source of truth for optional features. Use feature-specific docs only when the matching flag is enabled. If a feature is disabled and the user wants it, ask first, then update `caspian.config.json` and follow the update workflow in `commands.md`.
-6. If the task touches `main.py` or `.venv/Lib/site-packages/casp/**`, read `core-runtime-map.md` to jump to the controlling runtime file and the matching feature doc.
-7. If the task names a PulsePoint feature or directive, read `pulsepoint-runtime-map.md` for the fastest feature-to-runtime lookup, then read `pulsepoint.md` for authoring rules.
-8. After the feature is confirmed, inspect the actual project files that decide behavior, such as `package.json`, `main.py`, `src/app/**`, `src/lib/**`, `settings/**`, `prisma/**`, and the installed `casp` runtime.
-9. Use `file-conventions.md` for quick decisions about `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, and `error.html`; use `commands.md` for scaffold and update workflows, `project-structure.md` for placement decisions, and the feature docs such as `mcp.md`, `database.md`, `auth.md`, `fetch-data.md`, and `file-uploads.md` for task-specific guidance.
-10. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
-11. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
-12. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
+5. When Prisma is enabled, route all Python database work through the generated Prisma Python ORM. Use `database.md` before schema, migration, seed, or ORM decisions, and use `fetch-data.md` before wiring route data or RPC flows.
+6. If the task asks for WebSockets, live bidirectional channels, socket origin checks, or native browser `WebSocket` clients, confirm `caspian.config.json` has `websocket: true`, read `websockets.md`, then inspect `main.py`, `src/lib/**`, the owning `src/app/**` route, and `settings/bs-config.json`. If `websocket` is false and the user wants it, ask first, then enable the config flag and follow the update workflow.
+7. Treat `caspian.config.json` as the single source of truth for optional features. Use feature-specific docs only when the matching flag is enabled. If a feature is disabled and the user wants it, ask first, then update `caspian.config.json` and follow the update workflow in `commands.md`.
+8. If the task touches `main.py` or `.venv/Lib/site-packages/casp/**`, read `core-runtime-map.md` to jump to the controlling runtime file and the matching feature doc.
+9. If the task names a PulsePoint feature or directive, read `pulsepoint-runtime-map.md` for the fastest feature-to-runtime lookup, then read `pulsepoint.md` for authoring rules.
+10. After the feature is confirmed, inspect the actual project files that decide behavior, such as `package.json`, `main.py`, `src/app/**`, `src/lib/**`, `settings/**`, `prisma/**`, and the installed `casp` runtime.
+11. Use `file-conventions.md` for quick decisions about `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, and `error.html`; use `commands.md` for scaffold and update workflows, `project-structure.md` for placement decisions, and the feature docs such as `mcp.md`, `database.md`, `auth.md`, `fetch-data.md`, `websockets.md`, and `file-uploads.md` for task-specific guidance.
+12. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
+13. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
+14. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 
 ## Maintenance
 

package/dist/docs/project-structure.md

@@ -31,7 +31,7 @@ In that layout, the default stack is Python components for reusable UI, PulsePoi
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
 
-Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
+Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, `websocket`, and `componentScanDirs`.
 
 Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific files and docs only after the matching flag is confirmed as enabled. If a feature is disabled and the user wants it, ask first, then update `caspian.config.json` and follow the update workflow in `commands.md`.
 
@@ -40,9 +40,10 @@ Treat `caspian.config.json` as the single source of truth for optional feature e
 - `src/` contains routes, page templates, styles, reusable components, and shared libraries.
 - `src/components/` contains reusable application UI components and optional same-name HTML templates.
 - `src/lib/` contains reusable non-UI code such as helpers, services, validators, adapters, and shared support modules.
-- `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
-- `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
-- `prisma/` contains the Prisma schema and seed scripts.
+- `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
+- `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
+- `src/lib/websocket/` contains reusable socket helpers when WebSockets are enabled and the project includes shared session, auth, connection, or broadcast utilities.
+- `prisma/` contains the Prisma schema and seed scripts.
 - `public/` contains static assets served directly.
 - `settings/` contains BrowserSync, build, restart, and generated-project helper files.
 - `main.py` is the application entry point.
@@ -77,9 +78,11 @@ my-app/
     lib/
       auth/
         auth_config.py
-      mcp/
-        fastmcp.json
-        mcp_server.py
+      mcp/
+        fastmcp.json
+        mcp_server.py
+      websocket/
+        websocket_security.py
       prisma/
         __init__.py
         db.py
@@ -94,7 +97,7 @@ my-app/
         docs/
 ```
 
-Optional directories such as `src/lib/mcp/` appear only when the relevant feature flag is enabled in `caspian.config.json`.
+Optional directories such as `src/lib/mcp/` and `src/lib/websocket/` appear only when the relevant feature flag is enabled in `caspian.config.json` and the project needs that app-owned surface.
 
 ## Directory Breakdown
 
@@ -104,9 +107,11 @@ This is the main application area. It contains route files, templates, styles, a
 
 ### `src/app/`
 
-This directory handles file-based routing. Route templates and route-specific backend logic live here.
-
+This directory handles file-based routing. Route templates and route-specific backend logic live here.
+
 For any route that renders UI, keep that markup in `src/app/**/index.html`. If the route is UI-only, `index.html` alone is enough. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Keep shared wrappers in `layout.html` and use `layout.py` only for shared props or metadata. Use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
+
+Keep backend logic in the owning route when it is route-specific. Move Python code into `src/lib/**` only when it is shared across routes, components, integrations, or features.
 
 When a folder represents a section with child routes, such as `dashboard`, `account`, `settings`, or `docs`, create `layout.html` in that folder and let the child routes live beneath it. See [routing.md](./routing.md) for the canonical section layout pattern.
 
@@ -148,7 +153,7 @@ Do not add `src/lib/security/runtime_security.py` for normal app work. Runtime s
 
 If your Python routes or RPC actions need reusable database access code, keep that helper layer under `src/lib/` and extend the existing `src/lib/prisma/` package.
 
-In a Prisma-enabled Caspian project, schema and seed files typically live under `prisma/`, while the Python-side adapter lives in application-owned code under `src/lib/prisma/` when that layer exists.
+In a Prisma-enabled Caspian project, schema and seed files typically live under `prisma/`, while the Python-side adapter lives in application-owned code under `src/lib/prisma/` when that layer exists. When `caspian.config.json` has `prisma: true`, Python-side database reads and writes should use that generated Prisma Python ORM instead of a custom fetch, raw driver, JSON active store, or second app-owned database abstraction.
 
 ### `src/lib/auth/`
 
@@ -323,7 +328,8 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Treat `package.json` scripts as opt-in operations. Do not run `npm run dev` or `npm run build` unless the user explicitly asks, the task genuinely requires that exact script, or deployment prep needs `npm run build`.
 - Treat `__pycache__/` directories, `.pyc` files, `public/css/styles.css`, `settings/component-map.json`, and `settings/files-list.json` as generated artifacts when the local stack is intentionally running. They are not authored source files.
 - Inspect `settings/component-map.json` and `settings/files-list.json` when you need the generated component or route inventory, but do not hand-edit them. The workspace regenerates them from `settings/component-map.ts` and `settings/files-list.ts`.
-- Put route templates and route-specific backend logic in `src/app/`.
+- Put route templates and route-specific backend logic in `src/app/`.
+- Put only genuinely shared helpers, services, adapters, and validation logic in `src/lib/`.
 - As the app grows, keep route-owned code in `src/app/`, reusable rendered UI in `src/components/`, and reusable non-UI support code in `src/lib/`.
 - When the user asks for a dashboard, admin area, account area, or any grouped set of child routes, create a parent folder in `src/app/` with `layout.html` and place the child routes beneath it. Use `(group)/layout.html` only when that parent should not appear in the URL.
 - Read [file-uploads.md](./file-uploads.md) when the task involves upload widgets, media libraries, or file-manager flows.

package/dist/docs/pulsepoint.md

@@ -81,6 +81,7 @@ Avoid building a parallel JavaScript layer for normal UI behavior:
 
 - Do not add ids only so a script can find elements with `document.querySelector(...)` or `document.getElementById(...)`.
 - Do not use `data-*` attributes as a private client state system when PulsePoint state or props should own the data.
+- Do not create click-in buttons by placing intent in `data-*` attributes and then scanning for those attributes. Put the action directly on the element with `onclick`, `oninput`, `onchange`, `onsubmit`, or another native `on*` event attribute.
 - Do not bind normal first-party clicks, input changes, submits, filters, menus, or toggles with `addEventListener(...)`.
 - Do not use form refs plus input refs plus `pp.effect(...)` solely to construct an RPC payload from normal submitted fields.
 - Do not repaint first-party lists or panels with manual `innerHTML` writes when `pp.state(...)` plus `pp-for` can express the same UI.
@@ -206,6 +207,86 @@ Avoid this for a normal form:
 ```
 
 Refs are still useful when the feature actually requires imperative access. They are not the first choice for reading standard form fields that the browser already exposes through the submit event. Keep client code minimal and put reviewable data normalization in the route's Python `@rpc()` action unless the client must transform values for UX before submitting.
+
+Basic two-way state pattern:
+
+```html
+<section>
+  <label>
+    Name
+    <input name="name" value="{name}" oninput="setName(event.target.value)" />
+  </label>
+
+  <p>Hello, {name || "friend"}.</p>
+  <button onclick="setName('')">Clear</button>
+
+  <script>
+    const [name, setName] = pp.state("");
+  </script>
+</section>
+```
+
+Basic RPC-backed form pattern:
+
+```html
+<section>
+  <form onsubmit="{saveContact(event)}" novalidate>
+    <input name="name" value="{name}" oninput="setName(event.target.value)" required />
+    <input name="email" type="email" required />
+
+    <button type="submit" disabled="{isSaving}">
+      {isSaving ? "Saving..." : "Save"}
+    </button>
+  </form>
+
+  <script>
+    const [name, setName] = pp.state("");
+    const [isSaving, setIsSaving] = pp.state(false);
+
+    async function saveContact(event) {
+      event.preventDefault();
+      if (isSaving) return;
+
+      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
+
+      setIsSaving(true);
+      try {
+        await pp.rpc("save_contact", data, { abortPrevious: true });
+      } finally {
+        setIsSaving(false);
+      }
+    }
+  </script>
+</section>
+```
+
+Back that form with a route-owned `@rpc()` action in the sibling `index.py`. If Prisma is enabled, the action should use the generated Prisma Python ORM for persistence.
+
+```python
+from casp.rpc import rpc
+from casp.validate import Validate
+from src.lib.prisma import prisma
+
+
+@rpc()
+async def save_contact(name: str, email: str):
+    name = name.strip()
+    email = email.strip().lower()
+
+    if not name:
+        raise ValueError("Name is required.")
+    if Validate.with_rules(email, "required|email") is not True:
+        raise ValueError("A valid email address is required.")
+
+    contact = await prisma.contact.create(
+        data={
+            "name": name,
+            "email": email,
+        }
+    )
+
+    return contact.to_dict()
+```
 
 ## Authoring Model
 
@@ -549,6 +630,7 @@ Example:
 - Event attributes are removed from the live DOM after binding and rebound after DOM morphing.
 - Owned template/event-owner internals are runtime-managed. Do not author them directly.
 - Do not replace normal PulsePoint event attributes with id-driven `querySelector(...)` plus `addEventListener(...)` wiring. If an imperative listener is unavoidable for an integration, attach and clean it up from `pp.effect(...)`.
+- Do not replace a normal `onclick` with a `data-action`, `data-target`, or similar attribute plus a script that scans the DOM. PulsePoint event attributes are the event contract for first-party Caspian UI.
 
 ## SPA, loading, and navigation helpers
 
@@ -614,6 +696,7 @@ Use these rules when generating or editing PulsePoint runtime code:
 - For grouped shells with independent shell and content scrolling, put `pp-reset-scroll="true"` on the content pane rather than the whole shell when only the page content should reset between child-route navigations.
 - Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
 - Avoid generating ids, `data-*` state, `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or custom event buses for normal Caspian UI behavior.
+- Avoid data-attribute click wiring such as `data-action="save"` plus a delegated listener. Use `onclick="save()"` or `onsubmit="{save(event)}"` in authored HTML and keep reactive state in `pp.state(...)`.
 - If you are explicitly editing raw runtime HTML or internals, keep `pp-component` unique per live instance.
 - In authored templates, use a plain `<script>` inside the root. In runtime HTML, the owned script appears as `script[type="text/pp"]`.
 - Keep template-facing variables at top level.

package/dist/docs/routing.md

@@ -29,8 +29,9 @@ Start with these rules:
 - Put application routes in `src/app/`.
 - For any route that renders a page, put the markup in `index.html`.
 - If a route is UI-only, `index.html` by itself is enough.
-- Add `index.py` only when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side logic.
-- Use a standalone `index.py` only for non-visual routes such as redirects or action-only handlers.
+- Add `index.py` only when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side logic.
+- Keep route-specific server logic in that route's `index.py`. Move logic into `src/lib/**` only when it is shared across routes, components, integrations, or features.
+- Use a standalone `index.py` only for non-visual routes such as redirects or action-only handlers.
 - When a folder owns child routes, use `layout.html` to wrap them. This is the default pattern for dashboards, admin sections, account areas, settings trees, and route groups.
 - In grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane in `layout.html` when that pane should reset on child-route navigation while the shell sidebar or rail keeps its own scroll.
 - Use `layout.py` when a layout needs shared props or metadata before rendering. The `layout()` function may be synchronous or async.
@@ -235,7 +236,9 @@ Use [pulsepoint.md](./pulsepoint.md) when you need the full authored-vs-rendered
 
 ### `index.py`
 
-Use `index.py` as the backend companion when a route needs metadata or async server-side logic. For routes that render UI, keep the markup in the sibling `index.html` and let `page()` call `render_page(__file__, ...)`. Do not inline route HTML inside `index.py`.
+Use `index.py` as the backend companion when a route needs metadata or async server-side logic. For routes that render UI, keep the markup in the sibling `index.html` and let `page()` call `render_page(__file__, ...)`. Do not inline route HTML inside `index.py`.
+
+If the logic belongs only to this route, keep it here. Examples include this page's first-render query, route-owned RPC actions, redirect decisions, route-specific validation, route-specific filters, and route-specific response shaping. Move code into `src/lib/**` when the same logic is reused or intentionally shared; do not extract one-route orchestration into a library just because it is Python code.
 
 Use `index.py` by itself only for non-visual routes such as redirects or action-only handlers. Because Caspian runs on FastAPI, the page entry should be async when it performs async work.
 
@@ -288,7 +291,7 @@ The key name is arbitrary, but it must match exactly between the dict returned f
 
 Use distinct names for those layout props. In the current router, the second dict is merged into the full layout context after path params and `request`, so a key such as `slug` or `request` can shadow an existing value.
 
-When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md).
+When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md). When Prisma is enabled, database reads and writes in this route logic or its shared helpers should use the generated Prisma Python ORM.
 
 For static and dynamic metadata rules, inheritance order, and social card fields, see [metadata.md](./metadata.md).
 
@@ -505,7 +508,8 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - Treat `src/app/` as the routing source of truth.
 - Use folder names to model URL segments.
 - If a route renders UI, create or update `index.html` for the markup.
-- Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
+- Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
+- Keep route-specific backend logic in the route's own `index.py`; extract to `src/lib/**` only for genuinely shared logic.
 - Keep visible page markup in `index.html` and shared subtree shells in `layout.html`; do not place route HTML in `index.py` or layout HTML in `layout.py`.
 - Use PulsePoint as the first-party interaction model for route and layout HTML. Avoid custom DOM wiring for normal events and reactivity.
 - When the user asks for a dashboard, admin area, account section, or any grouped subtree of child routes, create a parent folder with `layout.html` and place the child routes beneath it. Follow the same mental model as the Next.js App Router.

package/dist/docs/websockets.md

@@ -0,0 +1,165 @@
+---
+title: WebSockets
+description: Use this page when the task mentions FastAPI WebSocket endpoints, live channels, broadcast managers, browser `WebSocket`, origin checks, or authenticated socket sessions in Caspian.
+related:
+  title: Related docs
+  description: Use routing and PulsePoint for client placement, auth for session policy, and the core runtime map for endpoint ownership in `main.py`.
+  links:
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/auth
+    - /docs/fetch-data
+    - /docs/core-runtime-map
+    - /docs/index
+---
+
+WebSockets in Caspian are gated by `caspian.config.json` and implemented as app-owned FastAPI endpoints, not the default RPC data path.
+
+Use `@rpc()` plus `pp.rpc()` for ordinary browser-triggered reads, writes, uploads, and Server-Sent Event streams. Use WebSockets only when the task needs a bidirectional, long-lived channel such as live chat, collaboration, multiplayer state, server push that is not a good SSE fit, or presence.
+
+Treat `caspian.config.json` as the single source of truth for whether the WebSocket feature is enabled. If `websocket` is false, this page is reference material only; do not assume `@app.websocket(...)` endpoints, `src/lib/websocket/**`, or socket demo routes exist until the user chooses to enable the feature and the update workflow has run.
+
+## Source Of Truth
+
+Before adding, debugging, or documenting a WebSocket feature:
+
+- Read `caspian.config.json` first and confirm `websocket: true`.
+- If `websocket` is false and the user wants live channels, ask for confirmation before enabling it, then update the config and follow the project update workflow.
+- Inspect `main.py` for `@app.websocket(...)` routes, origin checks, close codes, message limits, idle timeout, and middleware interactions.
+- Inspect `src/lib/**` for app-owned socket helpers such as session extraction, auth payload checks, connection managers, or broadcast utilities.
+- Inspect the owning route under `src/app/**` for the browser client, first-render URL selection, and PulsePoint state around the native `WebSocket`.
+- Check `settings/bs-config.json` before testing development URLs through BrowserSync or a proxy.
+
+Packaged docs should describe this workflow generally. Keep endpoint names, route names, ports, and demo inventory project-owned; do not treat one app's route tree as the framework convention.
+
+## Recommended Shape
+
+When `caspian.config.json` has `websocket: true`, put socket endpoints in `main.py` when they are application-level ASGI routes:
+
+```python
+from fastapi import WebSocket, WebSocketDisconnect, status
+
+WEBSOCKET_PATH = "/ws/channel"
+
+@app.websocket(WEBSOCKET_PATH)
+async def websocket_live_endpoint(websocket: WebSocket):
+    if not is_origin_allowed(websocket):
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    await manager.connect(websocket)
+    try:
+        while True:
+            raw_message = await websocket.receive_text()
+            ...
+    except WebSocketDisconnect:
+        return
+    finally:
+        manager.disconnect(websocket)
+```
+
+Keep reusable socket helpers in `src/lib/**` when they are shared by more than one endpoint or route. Good candidates include connection managers, session helpers, auth-payload extraction, payload normalization, and shared broadcast code.
+
+Keep route-specific browser UI in `src/app/**/index.html` and route-specific first-render values in the matching `index.py`. For example, an `index.py` can pass `websocket_path` and a development-only BrowserSync-aware `websocket_url` into the template with `render_page(__file__, {...})`.
+
+## Browser Client Pattern
+
+Use PulsePoint for the component state and lifecycle, while using the native browser `WebSocket` object for the socket itself.
+
+```html
+<main>
+  <button onclick="{connectSocket()}" disabled="{isConnected}">Connect</button>
+  <button onclick="{disconnectSocket()}" disabled="{!isConnected}">Disconnect</button>
+
+  <script>
+    const websocketPath = "{{ websocket_path }}";
+    const socketRef = pp.ref(null);
+    const [status, setStatus] = pp.state("idle");
+    const isConnected = status === "connected";
+
+    function buildWebSocketUrl(path) {
+      const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+      return new URL(`${protocol}//${window.location.host}${path}`, window.location.href).toString();
+    }
+
+    function connectSocket() {
+      const socket = new WebSocket(buildWebSocketUrl(websocketPath));
+      socketRef.current = socket;
+
+      socket.addEventListener("message", (event) => {
+        const payload = JSON.parse(event.data);
+        ...
+      });
+    }
+
+    function disconnectSocket() {
+      socketRef.current?.close(1000, "Client disconnect");
+      socketRef.current = null;
+    }
+
+    pp.effect(() => {
+      return () => socketRef.current?.close(1000, "Page disposed");
+    }, []);
+  </script>
+</main>
+```
+
+This is one of the narrow cases where direct browser APIs and event listeners are expected. Keep them inside the owning PulsePoint component script, store the socket in `pp.ref(...)`, and keep rendered UI state in `pp.state(...)`.
+
+## Auth And Sessions
+
+HTTP route privacy does not automatically make a WebSocket endpoint private. If a socket is authenticated, the endpoint must explicitly inspect the session or auth payload available on the WebSocket scope and close unauthenticated clients.
+
+Use close code `1008` for policy violations such as failed origin checks or missing authentication. If the endpoint accepts before rejecting, send a small JSON error payload first so the browser UI can show a useful message.
+
+If the app refreshes auth sessions, verify whether the WebSocket helper refreshes session expiry and whether that session mutation is persisted in the current middleware stack. Do not assume HTTP `AuthMiddleware` behavior applies to `scope["type"] == "websocket"`.
+
+## Origin And Proxy Checks
+
+WebSocket endpoints should validate the `Origin` header before accepting connections, especially in production.
+
+Common allowed origins:
+
+- same-origin derived from the socket URL
+- explicit values from environment variables such as `WEBSOCKET_ALLOWED_ORIGINS`, `CORS_ALLOWED_ORIGINS`, `APP_BASE_URL`, `PUBLIC_BASE_URL`, or `SITE_URL`
+- localhost HTTP origins in development when the app intentionally permits local BrowserSync or proxy testing
+
+When testing locally, read `settings/bs-config.json` first and build `ws://` or `wss://` URLs from its active `local` value. Do not assume the BrowserSync port is the default.
+
+## Message Contract
+
+Document the JSON message contract near the endpoint and client that own it.
+
+Useful baseline conventions:
+
+- Clients send JSON objects, usually `{ "type": "message", "text": "..." }` or `{ "type": "ping" }`.
+- Servers send `ready`, `message`, `error`, and `pong` payloads as JSON.
+- Enforce a maximum incoming message size before parsing or broadcasting.
+- Close idle sockets after a configured timeout when the app does not need long silent connections.
+- Sanitize or trim outbound text so one client cannot broadcast unbounded data.
+- Disconnect stale sockets when sends fail.
+
+## WebSockets Vs RPC/SSE
+
+Choose the transport deliberately:
+
+| Need | Preferred transport |
+| --- | --- |
+| CRUD, form submits, button actions, upload progress | `@rpc()` plus `pp.rpc()` |
+| Server sends one-way progress chunks for a request | RPC streaming / SSE |
+| Browser and server both send messages over a persistent channel | WebSocket |
+| Presence, collaboration, live chat, multiplayer state | WebSocket |
+
+Do not replace normal Caspian RPC with WebSockets just because a page is interactive.
+
+## AI Retrieval Notes
+
+If an AI agent is working on WebSockets in a Caspian app:
+
+- Start with `caspian.config.json`. Continue only after confirming `websocket: true`, unless the task is specifically to enable the feature.
+- Use [core-runtime-map.md](./core-runtime-map.md) to connect `main.py` behavior back to this doc.
+- Use [routing.md](./routing.md) before changing the route files that render the client.
+- Use [pulsepoint.md](./pulsepoint.md) for authored template rules and component lifecycle cleanup.
+- Use [auth.md](./auth.md) before changing authenticated socket behavior.
+- Keep reusable connection/session helpers in `src/lib/websocket/**` when they are shared; keep route UI in whichever `src/app/**` route owns the live experience; keep app-level ASGI endpoints in `main.py` unless the runtime intentionally provides another registration layer.
+- Verify local test URLs from `settings/bs-config.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {