caspian-utils 0.1.0 → 0.1.2

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

@@ -55,14 +55,14 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | Create a protected dashboard section with child routes and a shared shell. | [index.md](./index.md), [routing.md](./routing.md), [auth.md](./auth.md), [project-structure.md](./project-structure.md) | `src/app/**`, `src/lib/auth/auth_config.py`, `main.py`, `.venv/Lib/site-packages/casp/layout.py` | section layout ownership, route privacy mode, and child-route wrapping |
 | 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, 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 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 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 |
 | Find how route params and query params reach `page()`. | [index.md](./index.md), [routing.md](./routing.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/layout.py` | path-dict delivery, query coercion, and `request` injection |
 | 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) | `public/js/pp-reactive-v2.js`, component `.html`, `.venv/Lib/site-packages/casp/components_compiler.py` | `Context.Provider` usage, logical ancestry, single-root template shape |
+| 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 |
 | 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 |
 
@@ -75,7 +75,9 @@ Treat the table as a prompt pack for spot checks, not as a full validation matri
 - AI edits framework internals when the task only requires app-owned route or helper changes.
 - 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`, or manual `innerHTML` instead of PulsePoint `on*` attributes, state, directives, and `pp.rpc()`.
+- 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/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,7 +23,9 @@ 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.
 
-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. Do not set up first-party data actions by assigning ids and then wiring `querySelector(...)`, `addEventListener(...)`, manual `fetch(...)`, or manual DOM repainting.
+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,7 +51,9 @@ 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.
 
 ## Initial Data In `index.py`
@@ -85,7 +89,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
 
@@ -107,14 +111,18 @@ from src.lib.prisma import prisma
 async def list_todos():
     return await prisma.todo.find_many()
 
-@rpc(require_auth=True, limits="20/minute")
-async def create_todo(title: str):
-    return await prisma.todo.create(
-        data={"title": title, "completed": False}
-    )
+@rpc(require_auth=True, limits="20/minute")
+async def create_todo(title: str):
+    title = title.strip()
+    if not title:
+        raise ValueError("Title is required.")
+
+    return await prisma.todo.create(
+        data={"title": title, "completed": False}
+    )
 ```
 
-Call it from the client with `pp.rpc()`:
+Call it from the client with `pp.rpc()`:
 
 ```html
 <script>
@@ -127,10 +135,39 @@ Call it from the client with `pp.rpc()`:
     const todo = await pp.rpc("create_todo", { title });
     console.log(todo);
   }
-</script>
-```
-
-Use RPC for:
+</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
+<form onsubmit="{createTodoFromForm(event)}" novalidate>
+  <input name="title" required />
+  <button type="submit" disabled="{isSaving}">Add</button>
+
+  <script>
+    const [isSaving, setIsSaving] = pp.state(false);
+
+    async function createTodoFromForm(event) {
+      event.preventDefault();
+
+      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
+      if (isSaving) return;
+
+      setIsSaving(true);
+      try {
+        await pp.rpc("create_todo", data, { abortPrevious: true });
+      } finally {
+        setIsSaving(false);
+      }
+    }
+  </script>
+</form>
+```
+
+Use RPC for:
 
 - CRUD reads and writes after the initial render
 - Button-triggered refreshes

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

@@ -33,8 +33,9 @@ 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 `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
 
@@ -101,14 +102,15 @@ 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. 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`.
+7. 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.
+8. 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.
+9. 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.
+10. 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.
+11. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
+12. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
+13. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 
 ## Maintenance
 

package/dist/docs/project-structure.md

@@ -104,9 +104,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 +150,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 +325,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-runtime-map.md

@@ -37,10 +37,10 @@ If an inspected browser DOM disagrees with authored template source, remember th
 | State | `pp.state(initial)` | `pp-reactive-v2.js` | setters accept values or updater functions, state belongs to the component instance |
 | Effects | `pp.effect(...)`, `pp.layoutEffect(...)` | `pp-reactive-v2.js` | callbacks may return cleanup functions, promises are not awaited |
 | Refs | `pp.ref(...)`, `pp-ref` | `pp-reactive-v2.js` | generated ref internals are runtime-managed; do not author `data-pp-ref` |
-| Context | `pp.createContext(...)`, `<Context.Provider>`, `pp.context(token)` | `pp-reactive-v2.js` | ancestry is logical component ancestry; do not invent `pp-context` or `pp.provideContext` |
+| Context | `pp.createContext(...)`, lowercase `<themecontext.provider>`, `pp.context(token)` | `TemplateCompiler.ts`, `NestedBoundaryManager.ts`, `pp-reactive-v2.js` | authored provider tags are HTML-first and lowercase; `TemplateCompiler.transformContextProviderTags(...)` rewrites `*.provider` to runtime-owned `pp-context-provider`; ancestry is logical component ancestry; do not invent `pp-context` or `pp.provideContext` |
 | Portals | `pp.portal(ref, target?)` | `pp-reactive-v2.js` | context should preserve logical ancestry through the registry |
 | Lists | `<template pp-for="item in items">` | `pp-reactive-v2.js` | `pp-for` belongs on `<template>`, use plain `key`, not `pp-key` |
-| Events | native `onclick`, `oninput`, `onchange`, `onsubmit` | `pp-reactive-v2.js` | first-party events belong in `on*` attributes; event scope exposes `event`, `e`, `$event`, `target`, `currentTarget`, and `el`; avoid id-driven `querySelector`/`addEventListener` for normal UI |
+| Events | native `onclick`, `oninput`, `onchange`, `onsubmit` | `pp-reactive-v2.js` | first-party events belong in `on*` attributes; event scope exposes `event`, `e`, `$event`, `target`, `currentTarget`, and `el`; normal form submits should use `Object.fromEntries(new FormData(event.currentTarget).entries())` instead of per-input refs; avoid id-driven `querySelector`/`addEventListener` for normal UI |
 | RPC | `pp.rpc(...)` in scripts, `@rpc()` in Python | `pp-reactive-v2.js`, `casp/rpc.py` | use `pp.rpc`, not legacy `pp.fetchFunction`; protected actions use `@rpc(require_auth=True)` |
 | Upload progress | `pp.rpc(..., { onUploadProgress })` | `pp-reactive-v2.js`, `casp/rpc.py` | XHR path is used for progress callbacks; replace state from returned payload |
 | Streaming | `pp.rpc(..., { onStream })` | `pp-reactive-v2.js`, `casp/rpc.py`, `casp/streaming.py` | server generators become SSE responses |
@@ -63,31 +63,32 @@ If an inspected browser DOM disagrees with authored template source, remember th
 - Author one root element or one imported `x-*` root per route, layout, or component template.
 - Keep any owned plain `<script>` inside that same root.
 - Do not handwrite `pp-component`, `type="text/pp"`, `data-pp-ref`, `pp-owner`, `pp-event-owner`, or other runtime-managed attributes.
-- Use `pp.rpc(...)` for current browser-to-server calls.
-- Use native `on*` attributes for button clicks, form submits, input changes, filters, toggles, and menus instead of adding ids and manual listeners.
-- Use `Context.Provider` and `pp.context(...)` for context.
+- Use `pp.rpc(...)` for current browser-to-server calls.
+- Use native `on*` attributes for button clicks, form submits, input changes, filters, toggles, and menus instead of adding ids and manual listeners.
+- For ordinary form submits, bind `onsubmit` on the form and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; reserve `pp-ref` for imperative access rather than routine payload collection.
+- Use lowercase provider tags such as `<themecontext.provider>` and `pp.context(...)` for context.
 - Use `pp-for` only on `<template>` and plain `key` for keyed lists.
 - Prefer PulsePoint state and directives over manual `innerHTML` repainting.
 - Keep direct DOM APIs inside `pp.ref(...)` plus `pp.effect(...)` only when a third-party or browser API integration actually requires them.
 
 ## Compact Examples
 
-Context provider:
-
-```html
-<section>
-  <script>
-    const ThemeContext = pp.createContext("light");
+Context provider:
+
+```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>
-  </ThemeContext.Provider>
-</section>
-```
+  <themecontext.provider value="{theme}">
+    <button onclick="setTheme(theme === 'dark' ? 'light' : 'dark')">
+      Theme: {theme}
+    </button>
+  </themecontext.provider>
+</section>
+```
 
 Upload progress:
 

package/dist/docs/pulsepoint.md

@@ -55,6 +55,7 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 - Use PulsePoint component roots, scripts, directives, and runtime helpers for interactive UI.
 - Use PulsePoint state, effects, refs, and template directives as the default reactivity model in authored Caspian templates.
 - Bind first-party events in the HTML with PulsePoint-handled native `on*` attributes such as `onclick`, `oninput`, `onchange`, and `onsubmit`.
+- For ordinary forms, bind the submit event in the `<form>` and collect named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`. Let input `name` attributes define the payload keys, then validate and normalize those values in Python. Do not use `pp.ref(...)` on every input or an effect-managed listener just to read submitted values.
 - When the browser needs CRUD operations or follow-up reads from the backend, call `pp.rpc()` from PulsePoint code and back it with route or backend `@rpc()` actions.
 - Keep server-rendered HTML plus PulsePoint enhancement as the baseline architecture.
 - For dashboards, admin areas, account sections, docs sections, and other grouped subtrees, keep shared shell markup and shared PulsePoint behavior in the parent folder's `layout.html`, then keep child-route PulsePoint state local to each `index.html`. Follow the same mental model as the Next.js App Router.
@@ -69,9 +70,10 @@ Default to this workflow:
 - Put the button, form, input, toggle, menu, filter, upload control, or list markup directly in the route, layout, or component HTML template.
 - Bind events with native `on*` attributes handled by PulsePoint, for example `onclick="save()"`, `oninput="setQuery(event.target.value)"`, or `onsubmit="{submitForm(event)}"`.
 - This is the PulsePoint `onClick`/native event-attribute model. Authored examples use lowercase HTML spellings such as `onclick` because browser HTML normalizes attribute names, but the important rule is to bind the event in the template instead of wiring it later with DOM selectors.
+- For simple form submissions, let HTML own the form shape and let the submit event carry the values: use `const data = Object.fromEntries(new FormData(event.currentTarget).entries())` inside the handler, then pass that object directly to `pp.rpc(...)`. In a form-level submit handler, `event.target` is usually the form too, but `event.currentTarget` is the copy-safe default because it always means the element that owns the handler.
 - Keep reactive values in `pp.state(...)`.
 - Render conditional text, classes, attributes, lists, and styles with template expressions, `pp-for`, `pp-style`, `pp-spread`, and other PulsePoint-supported template features.
-- Use `pp.ref(...)` and `pp-ref` when a real element reference is needed.
+- Use `pp.ref(...)` and `pp-ref` when a real imperative element reference is needed, such as focus, measurement, media, canvas, third-party widgets, or resetting a specific file/password input after a successful action.
 - Use `pp.effect(...)` or `pp.layoutEffect(...)` for lifecycle work that must happen after render.
 - Use `pp.rpc(...)` for browser-triggered backend reads and writes.
 
@@ -79,7 +81,9 @@ 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.
 - Do not create a custom client-side store, event bus, or hydration routine for behavior that belongs in a PulsePoint component script.
 
@@ -134,6 +138,155 @@ Avoid this first-party pattern:
 ```
 
 That second shape recreates a separate event and rendering system inside a Caspian component. It is harder to maintain because it bypasses PulsePoint's rerender, event rebinding, refs, cleanup, and backend RPC conventions.
+
+Preferred form submit pattern:
+
+```html
+<section>
+  <form onsubmit="{saveProfile(event)}" class="grid gap-4" novalidate>
+    <input name="name" value="{{ user_name }}" autocomplete="name" required />
+    <input name="email" type="email" value="{{ user_email }}" autocomplete="email" required />
+    <input name="password" type="password" autocomplete="new-password" />
+
+    <button type="submit" disabled="{isSubmitting}">
+      {isSubmitting ? "Saving..." : "Save changes"}
+    </button>
+  </form>
+
+  <script>
+    const [isSubmitting, setIsSubmitting] = pp.state(false);
+
+    async function saveProfile(event) {
+      event.preventDefault();
+      if (isSubmitting) return;
+
+      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
+
+      setIsSubmitting(true);
+      try {
+        await pp.rpc("save_profile", data, { abortPrevious: true });
+      } finally {
+        setIsSubmitting(false);
+      }
+    }
+  </script>
+</section>
+```
+
+Avoid this for a normal form:
+
+```html
+<section>
+  <form pp-ref="{formRef}">
+    <input pp-ref="{nameRef}" name="name" />
+    <input pp-ref="{emailRef}" name="email" />
+  </form>
+
+  <script>
+    const formRef = pp.ref(null);
+    const nameRef = pp.ref(null);
+    const emailRef = pp.ref(null);
+
+    pp.effect(() => {
+      const form = formRef.current;
+      if (!form) return;
+
+      const submit = (event) => {
+        event.preventDefault();
+        return pp.rpc("save_profile", {
+          name: nameRef.current?.value ?? "",
+          email: emailRef.current?.value ?? "",
+        });
+      };
+
+      form.addEventListener("submit", submit);
+      return () => form.removeEventListener("submit", submit);
+    }, []);
+  </script>
+</section>
+```
+
+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
 
@@ -296,12 +449,12 @@ Notes:
 
 ## Context
 
-Context is implemented in the current runtime, but the current API follows a React-style `Context.Provider` pattern rather than a legacy `pp.provideContext(...)` helper.
+Context is implemented in the current runtime with a React-style provider pattern rather than a legacy `pp.provideContext(...)` helper. Because Caspian templates are HTML-first, authored provider tags should be written in lowercase HTML form, for example `<themecontext.provider>`, even when the JavaScript token is named `ThemeContext`.
 
 How it works:
 
 - Create a token with `pp.createContext(defaultValue)`.
-- Provide a value with `Context.Provider`.
+- Provide a value with a lowercase provider tag such as `<themecontext.provider value="{theme}">`.
 - Read it in a descendant component with `pp.context(token)`.
 - Resolution walks the logical component parent chain stored in the registry, not the live DOM.
 - Portaled descendants still resolve providers through component ancestry.
@@ -315,23 +468,24 @@ Important:
 - Context is component-level, not directive-based. There is no `pp-context` attribute.
 - `pp.context(token)` resolves from ancestors. A component does not consume the value it provides in the same render.
 - If provider and consumer live in different component script scopes, pass the token through props or store it in shared outer or global state.
-- The preferred authoring style is a provider tag in the template. The runtime also supports imperative `ThemeContext.Provider({ value })` calls during render, but the tag form is clearer for AI-generated authored templates.
-- Do not invent or document `pp.provideContext`. The current runtime explicitly does not expose it.
+- The preferred authoring style is a lowercase provider tag in the template. The TypeScript runtime's `TemplateCompiler.transformContextProviderTags(...)` recognizes `*.provider` tags case-insensitively and rewrites them to runtime-owned `<pp-context-provider>` boundaries. The runtime context lookup is also case-insensitive, so `<themecontext.provider>` can resolve a script binding named `ThemeContext`.
+- The runtime also supports imperative `ThemeContext.Provider({ value })` calls during render, but that form provides from the component boundary rather than documenting the HTML subtree shape. Use it only when component-wide provision is intended.
+- Do not invent or document `pp.provideContext`. The current runtime explicitly does not expose it.
 
 Provider example:
 
 ```html
 <section>
-  <script>
-    const ThemeContext = pp.createContext("light");
-    const [theme] = pp.state("dark");
-  </script>
-
-  <ThemeContext.Provider value="{theme}">
-    <p>This subtree receives the provided theme.</p>
-  </ThemeContext.Provider>
-</section>
-```
+  <script>
+    const ThemeContext = pp.createContext("light");
+    const [theme] = pp.state("dark");
+  </script>
+
+  <themecontext.provider value="{theme}">
+    <p>This subtree receives the provided theme.</p>
+  </themecontext.provider>
+</section>
+```
 
 Consumer example for a child component that receives the token through props:
 
@@ -401,9 +555,10 @@ Example:
 </div>
 ```
 
-## Refs
-
-- Use `pp-ref="nameInput"` when the ref object or callback is already available in scope.
+## Refs
+
+- Refs are for imperative element access. Do not use `pp-ref` as the default way to read normal form input values on submit; prefer the form's `onsubmit` event plus `Object.fromEntries(new FormData(event.currentTarget).entries())`.
+- Use `pp-ref="nameInput"` when the ref object or callback is already available in scope.
 - Use `pp-ref="{registerRef(id)}"` when you want the compiler to capture a dynamic ref expression.
 - `pp.ref(null)` is the normal way to create a ref object.
 - Callback refs and `{ current }` refs are both supported.
@@ -469,10 +624,13 @@ Example:
 - Treat this as the HTML form of `onClick`-style PulsePoint event binding. Prefer lowercase examples in authored HTML because the browser normalizes attribute names.
 - Event values may be raw code or wrapped in `{...}`.
 - The runtime injects `event`, `e`, `$event`, `target`, `currentTarget`, and `el`.
+- For form submit handlers, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` when collecting named fields for `pp.rpc(...)`.
+- `event.target` can also work for form-level submit handlers, but examples use `event.currentTarget` so nested event origins do not change which element becomes the `FormData` source.
 - Do not use hyphenated event attrs like `on-click`.
 - 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
 
@@ -528,6 +686,7 @@ Use these rules when generating or editing PulsePoint runtime code:
 
 - Treat PulsePoint as the default reactive frontend for Caspian app code.
 - For first-party HTML interactions, use PulsePoint `on*` event attributes, state, refs, effects, directives, and `pp.rpc()` before reaching for DOM APIs.
+- For simple forms, bind `onsubmit` in the authored HTML and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; do not generate per-input refs or effect-managed submit listeners just to gather values.
 - Treat `pp.rpc()` as the default browser-to-server path for CRUD operations and interactive backend reads.
 - Use `public/js/pp-reactive-v2.js` as the shipped runtime contract AI should follow.
 - Keep `main.py` in view because it injects the runtime-facing attributes and rewrites authored scripts before the browser sees them.
@@ -537,10 +696,11 @@ 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.
-- Follow the React-style context pattern: `pp.createContext(...)`, `<Context.Provider value="{...}">`, and `pp.context(token)`.
+- Follow the HTML-first context pattern: `pp.createContext(...)`, a lowercase provider tag such as `<themecontext.provider value="{...}">`, and `pp.context(token)`.
 - Do not invent `pp.provideContext`, `pp-context`, or other legacy context helpers.
 - Keep `pp-for` on `<template>` and use plain `key`.
 - Use native `on*` attributes, not framework-specific event syntax.
@@ -581,7 +741,7 @@ These are current runtime caveats that matter for authors and AI tools:
 - The global `pp` singleton auto-mounts on DOM ready, and `pp.mount()` is idempotent.
 - `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Their callbacks are not promise-aware.
 - `pp.context()` resolves through ancestor components, not the current component's own pending providers.
-- `pp.provideContext` is not part of the current runtime API. Use `Context.Provider`.
+- `pp.provideContext` is not part of the current runtime API. Use an HTML-first lowercase provider tag such as `<themecontext.provider>`.
 - `pp.portal()` preserves logical ancestry through the registry, so context and prop refresh behavior continue to work through portaled descendants.
 
 ## Final reminder

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.
@@ -184,7 +185,7 @@ Place those import comments at the top of the file, above the authored root elem
 
 Route templates follow the same authored-vs-runtime contract documented in [pulsepoint.md](./pulsepoint.md) and the same single-root discipline documented in [components.md](./components.md): keep one authored parent node, keep any `<!-- @import ... -->` directives above that root, use a plain `<script>` inside that root when needed, and do not handwrite `pp-component` or `type="text/pp"`. That root may be a native HTML element or a single imported `x-*` component tag, but after expansion it must resolve to one final HTML root.
 
-When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`.
+When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`. For simple form submits, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` over per-input `pp-ref` payload collection.
 
 For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent node that contains the entire route markup. This includes any owned script.
 
@@ -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/package.json

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