caspian-utils 0.0.17 → 0.0.19

package/dist/docs/components.md

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: Use this page when the task mentions `@component`, reusable UI, component imports, same-name `.html` templates, or where shared components belong in a Caspian project.
+description: Use this page when the task mentions `@component`, reusable UI, HTML-first `x-*` component tags, component imports, same-name `.html` templates, or where shared components belong in a Caspian project.
 related:
   title: Related docs
   description: Use the structure guide for file placement, the routing guide for route templates, the PulsePoint guide for browser-side scripts, and the data guide for component-owned RPC flows.
@@ -12,9 +12,11 @@ related:
     - /docs/index
 ---
 
-Components in Caspian are Python functions decorated with `@component`.
+Components in Caspian are implemented as Python functions decorated with `@component`.
 
-Import them into a template with an `@import` comment, then render them with JSX-style tags such as `<MyComponent />` or `<MyComponent>...</MyComponent>`.
+In authored HTML, import them with an `@import` comment and render them with HTML-first kebab-cased `x-*` tags such as `<x-my-component />` or `<x-my-component>...</x-my-component>`.
+
+Treat that `x-*` form as the current Caspian component contract for authored templates.
 
 Component tooling scans Python files under the paths listed in `caspian.config.json`. When `componentScanDirs` includes `src/`, `src/components/` is the clean default location for reusable UI, even though any scanned path can work.
 
@@ -60,17 +62,17 @@ Place component imports at the top of the HTML template, above the authored root
 ```html
 <!-- @import Container from "../components" -->
 
-<Container class="py-10">
+<x-container class="py-10">
   <h1>Dashboard</h1>
-</Container>
+</x-container>
 ```
 
-The import comment is the bridge between the Python component file and the JSX-style tag.
+The import comment is the bridge between the Python component export and the `x-*` tag you author in HTML.
 
 Treat `<!-- @import ... -->` as a file-level directive, not as rendered markup. It does not count as the template root, and it should not be nested inside the root wrapper element.
 
 - `<!-- @import Container from "../components" -->` resolves `Container.py` from that folder.
-- The component function name should match the tag name you render, such as `Container` for `<Container />`.
+- The exported component name maps to the tag you render by kebab-casing it and prefixing `x-`, such as `Container` for `<x-container />` or `CommandDialog` for `<x-command-dialog />`.
 - Grouped imports and aliases are also supported, for example `<!-- @import { Button, Card as UserCard } from "../components/ui" -->`.
 - If one Python file exports several `@component` functions, point `from` at that exact file instead of assuming one file per tag.
 - In that case, prefer one grouped import so every rendered tag resolves back to the same Python module.
@@ -81,9 +83,9 @@ Good:
 <!-- @import { Button, Input, Label } from "../../../lib/maddex" -->
 
 <section class="auth-panel auth-panel-compact fade-up">
-  <Label>Email</Label>
-  <Input type="email" />
-  <Button>Continue</Button>
+  <x-label>Email</x-label>
+  <x-input type="email" />
+  <x-button>Continue</x-button>
 </section>
 ```
 
@@ -106,17 +108,17 @@ If `Breadcrumb.py` defines `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `Br
 <!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "../maddex/Breadcrumb.py" -->
 
 <div class="dashboard-topbar">
-  <Breadcrumb class="dashboard-breadcrumbs" aria-label="Dashboard breadcrumbs">
-    <BreadcrumbList class="dashboard-breadcrumbs__list">
-      <BreadcrumbItem class="dashboard-breadcrumbs__item">
-        <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
-      </BreadcrumbItem>
-      <BreadcrumbSeparator class="dashboard-breadcrumbs__separator" />
-      <BreadcrumbItem class="dashboard-breadcrumbs__item">
-        <BreadcrumbPage class="dashboard-breadcrumbs__page">Reports</BreadcrumbPage>
-      </BreadcrumbItem>
-    </BreadcrumbList>
-  </Breadcrumb>
+  <x-breadcrumb class="dashboard-breadcrumbs" aria-label="Dashboard breadcrumbs">
+    <x-breadcrumb-list class="dashboard-breadcrumbs__list">
+      <x-breadcrumb-item class="dashboard-breadcrumbs__item">
+        <x-breadcrumb-link href="/dashboard">Dashboard</x-breadcrumb-link>
+      </x-breadcrumb-item>
+      <x-breadcrumb-separator class="dashboard-breadcrumbs__separator" />
+      <x-breadcrumb-item class="dashboard-breadcrumbs__item">
+        <x-breadcrumb-page class="dashboard-breadcrumbs__page">Reports</x-breadcrumb-page>
+      </x-breadcrumb-item>
+    </x-breadcrumb-list>
+  </x-breadcrumb>
 </div>
 ```
 
@@ -317,7 +319,7 @@ Keep synchronous components as the default. Switch to `async def` only when the
 
 - Put reusable components in `src/components/` and keep route files in `src/app/`.
 - If the component includes PulsePoint behavior, prefer a thin Python wrapper plus a same-name `.html` template.
-- Keep the component file name, exported function name, and tag name aligned, such as `Button.py`, `def Button(...)`, and `<Button />`.
+- Keep the component file name, exported function name, and authored tag aligned, such as `Button.py`, `def Button(...)`, and `<x-button />`.
 - Accept `children` or `**props` when the component should support nested content.
 - Keep page-level data loading in `page()` when the data is not intrinsic to the component itself.
 - If you add `@rpc()` functions inside a component file, keep their names globally unique because component RPCs are not route-scoped.

package/dist/docs/fetch-data.md

@@ -17,9 +17,9 @@ related:
     - /docs/index
 ---
 
-This page explains how data fetching works in Caspian. Use route functions for initial page data and use RPC actions for browser-triggered reads, writes, streams, and uploads.
+This page explains how data fetching works in Caspian. Use route functions for initial page data and use RPC actions for browser-triggered reads, writes, streams, uploads, and normal CRUD work.
 
-Treat RPC as the default way for browser code to talk to Python in Caspian. 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.
+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.
 
 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.
 
@@ -36,15 +36,18 @@ In practice, most pages use both:
 2. Render that data into `index.html`.
 3. Call `pp.rpc()` for refreshes, form submits, toggles, infinite scroll, or streamed updates.
 
+If a route only needs UI and does not need first-render data, metadata, or other backend behavior, skip `index.py` and keep the page in `index.html` alone.
+
 ## Default Data Rule
 
 - Use `page()` for async or route-level data required before HTML renders, and use `layout()` only for synchronous shared props or metadata.
-- Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render.
+- 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.
 - Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
 
 ## Initial Data In `index.py`
 
-Use the route's backend file for data that should exist before the template is rendered.
+Use the route's backend file for data that should exist before the template is rendered. Keep the rendered page markup in the sibling `index.html`; if no backend data or logic is needed, omit `index.py` entirely.
 
 Example:
 
@@ -120,6 +123,7 @@ Call it from the client with `pp.rpc()`:
 
 Use RPC for:
 
+- CRUD reads and writes after the initial render
 - Button-triggered refreshes
 - Form submissions and mutations
 - Polling or background refreshes
@@ -292,7 +296,7 @@ If an AI agent is choosing how to load data in Caspian, apply these rules first.
 - Put first-render data loading in `src/app/**/index.py`.
 - Put shared section props in `layout.py` only when multiple child routes need the same synchronous data.
 - Keep async I/O in `page()` or `@rpc()` because the current layout engine does not await `layout()`.
-- Treat RPC as the default read and write layer between PulsePoint code and Python route logic.
+- Treat RPC as the default read and write layer between PulsePoint code and Python route logic, especially for CRUD and interactive backend reads.
 - Use `@rpc()` for backend functions that should be callable from the browser.
 - Use `pp.rpc()` for client-side calls; do not prefer older `pp.fetchFunction()` wording.
 - Prefer route-render data plus RPC over inventing parallel REST endpoints for normal Caspian page interactions.

package/dist/docs/index.md

@@ -42,7 +42,7 @@ The packaged Caspian docs referenced by this index live here:
 - `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for projects where `caspian.config.json` enables MCP
 - `database.md` - Prisma schema, migration, seed, and client-generation workflow for projects where `caspian.config.json` enables Prisma, plus Python-side helper caveats
 - `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, public-vs-private route mode guidance, RPC-first signout guidance, RBAC, and OAuth provider helpers
-- `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and the single-parent root rule for component HTML files
+- `components.md` - Create reusable Python components, template-backed UI, HTML-first `x-*` component tags, and the single-parent root rule for component HTML files
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
 - `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

package/dist/docs/metadata.md

@@ -31,6 +31,8 @@ Metadata is typically defined in one of two files:
 - `layout.py` for defaults shared by everything below that folder
 - `index.py` for route-specific metadata
 
+On routes that render UI, keep the page markup in the sibling `index.html`. `index.py` is the metadata and backend companion, not the place to store route HTML. If a route needs no metadata or backend behavior, omit `index.py` and keep the page as `index.html` only.
+
 The current `Metadata` implementation supports three fields:
 
 - `title`

package/dist/docs/project-structure.md

@@ -26,7 +26,7 @@ Caspian uses a lean project layout that keeps application code in `src`, databas
 
 As an app grows, keep reusable rendered UI in `src/components/`, keep reusable non-UI support code in `src/lib/`, and keep route-owned files in `src/app/`. That split keeps page composition separate from shared component and service code.
 
-In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
+In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for CRUD operations and browser-triggered backend reads, and `casp.validate` for input validation at route and action boundaries.
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
 
@@ -105,6 +105,8 @@ This is the main application area. It contains route files, templates, styles, a
 
 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. Use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
+
 When authoring a route HTML file such as `src/app/**/index.html`, keep the whole template inside exactly one top-level lowercase HTML element. Treat it the same way you would a React component returning one parent element: wrap the route markup and any owned PulsePoint script in the same root.
 
 Do not handwrite `pp-component="..."` or `type="text/pp"` in those source templates. Author a plain `<script>` inside the root when you need PulsePoint logic, and let Caspian add the runtime attributes during render.
@@ -117,9 +119,9 @@ Use this folder for reusable UI components that should be imported into route te
 
 As the app grows, default to `src/components/` for application-level UI that will be shared across routes or features. Keep page-only markup close to the route in `src/app/`, but move shared cards, forms, shells, navigation, and other reusable visual building blocks into `src/components/`.
 
-The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
+The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior. In authored HTML, that component is consumed as `<x-button />`.
 
-One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, instead of assuming each tag has its own sibling `.py` file.
+One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, and render them as `<x-breadcrumb />`, `<x-breadcrumb-item />`, and `<x-breadcrumb-list />` instead of assuming each tag has its own sibling `.py` file.
 
 For component HTML files, follow the same one-parent rule as route HTML files: one top-level lowercase HTML element only, with no sibling roots and no top-level script sitting outside that root.
 
@@ -227,7 +229,9 @@ If this layout imports reusable components, place each `<!-- @import ... -->` co
 
 ### `src/app/index.py`
 
-The backend logic for the route. This is where route behavior can load first-render data, expose `@rpc()` actions, and import framework features such as auth helpers, `casp.validate`, and route-level `Cache(...)` declarations.
+The backend logic companion for the route. Use this file when the same route needs first-render data, metadata, `@rpc()` actions, auth helpers, `casp.validate`, route-level `Cache(...)` declarations, redirects, or other server behavior.
+
+If the route renders UI, keep the markup in the sibling `index.html` and let `index.py` call `render_page(__file__, ...)` with whatever context the template needs. Do not store route HTML in `index.py`. A lone `index.py` should be reserved for non-visual routes.
 
 When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that route's `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`.
 
@@ -235,9 +239,11 @@ When a route owns a file manager or upload UI, keep the owning upload and delete
 
 The route template. It supports standard HTML, `<!-- @import ... -->` component imports, and PulsePoint directives, and it should be the default place for reactive frontend behavior in Caspian.
 
+If a route renders UI and needs no backend behavior, this file alone is sufficient. If the route also has an `index.py` companion, keep the visible page markup here.
+
 Treat import comments as top-of-file directives that belong above the route's single authored root element.
 
-Use `components.md` when the task involves authoring reusable `<MyComponent />` tags backed by Python files.
+Use `components.md` when the task involves authoring reusable `<x-my-component />` tags backed by Python files.
 
 ### `src/app/globals.css`
 
@@ -272,7 +278,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - 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/`.
 - Read [file-uploads.md](./file-uploads.md) when the task involves upload widgets, media libraries, or file-manager flows.
 - Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
-- Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, import comments, and single-root template rules.
+- Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, `x-*` component tags, import comments, and single-root template rules.
 - When deciding between `src/components/` and `src/lib/`, use `src/components/` for anything rendered as reusable UI and `src/lib/` for helpers, services, validators, adapters, and shared business logic.
 - Use [mcp.md](./mcp.md) only when `caspian.config.json` enables MCP and the task involves FastMCP tool definitions, nested config discovery, or local MCP commands.
 - Keep `<!-- @import ... -->` comments above the single authored root element in route, layout, and component HTML files.
@@ -281,7 +287,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Use `settings/bs-config.ts` when uploaded public assets should not trigger BrowserSync reloads during the local stack.
 - Put app-owned FastMCP code in `src/lib/mcp/` only when `caspian.config.json` enables MCP.
 - Use PulsePoint conventions in route templates for reactive frontend behavior.
-- Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.
+- Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows, especially CRUD operations and interactive backend reads.
 - Use `casp.cache_handler` when a route's first-render HTML should be reused safely across requests.
 - Use `casp.validate` at route and RPC boundaries, and move reusable validators into `src/lib/` when multiple routes share them.
 - Use `database.md` when the task involves Prisma schema changes, migrations, seed logic, or project-specific database helper conventions.

package/dist/docs/pulsepoint.md

@@ -16,9 +16,9 @@ related:
 
 This file documents the PulsePoint contract for the shipped Caspian browser runtime. Treat it as the AI-facing source of truth when generating or reviewing interactive Caspian UI.
 
-If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the runtime implemented in this repo.
+If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the current Caspian runtime.
 
-Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
+Use `components.md` for authoring Python `@component` files, same-name HTML templates, and HTML-first `x-*` component tags. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
 
 PulsePoint is the default reactive frontend layer for Caspian. In the current runtime it follows a React-like component pattern, but it is HTML-first rather than JSX-first.
 
@@ -36,6 +36,7 @@ Important current facts:
 
 - `public/js/pp-reactive-v2.js` exposes the global `pp` runtime and auto-mounts on DOM ready.
 - `main.py` renders the final HTML, runs `transform_components(...)`, then runs `transform_scripts(...)` before returning the response.
+- Authored route and component templates compose reusable server components as HTML-first `x-*` tags before the browser runtime mounts.
 
 If docs, generated examples, or older notes disagree with `public/js/pp-reactive-v2.js` plus `main.py`, follow the code that actually runs.
 
@@ -44,12 +45,14 @@ If docs, generated examples, or older notes disagree with `public/js/pp-reactive
 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.
+- 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.
 - Only introduce another frontend runtime when the user explicitly asks for it or the project already depends on one.
 
 ## Authoring Model
 
-PulsePoint authoring in this repo is split into two layers:
+PulsePoint authoring is split into two layers:
 
 - The authored layer: route, layout, and component templates under `src/` with plain HTML plus a plain `<script>`.
 - The runtime layer: the browser sees `pp-component` roots and `script[type="text/pp"]` after Caspian transforms the HTML.
@@ -413,10 +416,12 @@ These are runtime details.
 Use these rules when generating or editing PulsePoint runtime code:
 
 - Treat PulsePoint as the default reactive frontend for Caspian app code.
+- 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.
 - If a development-only source tree exists behind the shipped runtime, treat it as optional implementation detail rather than something generated apps are guaranteed to contain.
 - In authored Caspian templates, do not handwrite `pp-component` or `type="text/pp"`; let the render pipeline inject them.
+- Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
 - 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

@@ -25,8 +25,10 @@ Caspian uses a high-performance file-system router built on top of FastAPI. Your
 Start with these rules:
 
 - Put application routes in `src/app/`.
-- Use `index.html` for a template-only route.
-- Use `index.py` when the route needs metadata or async server-side logic.
+- 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.
 - Use `layout.html` to wrap child routes.
 - Use `layout.py` when a layout needs shared synchronous props or metadata before rendering.
 
@@ -46,7 +48,7 @@ If you already know the Next.js App Router, use this translation layer:
 | Next.js concept | Caspian equivalent |
 | --- | --- |
 | `app/` | `src/app/` |
-| `page.tsx` | `index.html` or `index.py` |
+| `page.tsx` | `index.html` plus optional `index.py` companion |
 | `layout.tsx` | `layout.html` and optional `layout.py` |
 | `[id]` | `[id]` |
 | `[...slug]` | `[...slug]` |
@@ -61,21 +63,33 @@ This means most App Router habits carry over directly:
 
 ## Core Concepts
 
-Every route lives inside `src/app`. A route is a folder that contains either an `index.html` file, an `index.py` file, or both as part of the route implementation.
+Every route lives inside `src/app`. For routes that render UI, `index.html` owns the markup and `index.py` is only an optional companion for server logic or metadata.
+
+Use this decision rule when creating routes:
+
+| Route shape | Files |
+| --- | --- |
+| UI only | `index.html` |
+| UI plus backend logic or metadata | `index.html` and `index.py` |
+| No rendered page, backend only | `index.py` |
 
 Examples:
 
-| File | URL |
+| Files | URL |
 | --- | --- |
 | `src/app/index.html` | `/` |
-| `src/app/about/index.py` | `/about` |
+| `src/app/about/index.html` | `/about` |
+| `src/app/dashboard/index.html` and `src/app/dashboard/index.py` | `/dashboard` |
 | `src/app/blog/posts/index.html` | `/blog/posts` |
+| `src/app/(auth)/signout/index.py` | `/signout` |
 
 ### `index.html`
 
 Use `index.html` for the route template. This is the route's view layer.
 
-Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with JSX-style tags such as `<Button />`. Use [components.md](./components.md) for the component authoring rules.
+If a route renders visible page content, that content belongs here even when the route also has an `index.py` companion.
+
+Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with HTML-first `x-*` tags such as `<x-button />`. Use [components.md](./components.md) for the component authoring rules.
 
 Place those import comments at the top of the file, above the authored root element. They are file-level directives, not children of the route root.
 
@@ -116,7 +130,7 @@ Also bad:
 ```html
 <section class="dashboard-shell">
   <!-- @import StatsCard from "../components" -->
-  <StatsCard title="Users" value="42" />
+  <x-stats-card title="Users" value="42" />
 </section>
 ```
 
@@ -126,7 +140,7 @@ Example authored route template:
 <!-- @import StatsCard from "../components" -->
 
 <section class="dashboard-shell">
-  <StatsCard title="Users" value="42" />
+  <x-stats-card title="Users" value="42" />
 
   <script>
     const [filter, setFilter] = pp.state("all");
@@ -152,7 +166,9 @@ Write the first form. Caspian produces the second form by injecting `pp-componen
 
 ### `index.py`
 
-Use `index.py` when the route needs metadata or async server-side logic. Because Caspian runs on FastAPI, the page entry should be async.
+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` 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.
 
 Example:
 
@@ -168,7 +184,7 @@ async def page():
     return render_page(__file__)
 ```
 
-Use this pattern when the route needs to fetch data, compute metadata, or do other non-blocking server work before rendering.
+Use this pattern when the route needs to fetch data, compute metadata, or do other non-blocking server work before rendering the sibling `index.html`.
 
 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).
 
@@ -186,10 +202,12 @@ Wrap a folder name in brackets to make it variable.
 
 | File | Example URL |
 | --- | --- |
-| `src/app/users/[id]/index.py` | `/users/123` |
+| `src/app/users/[id]/index.html` | `/users/123` |
 
 These segments are compiled into FastAPI path parameters for efficient route matching.
 
+Add a sibling `index.py` when the dynamic route needs params during render, metadata, or other backend logic.
+
 In the current `main.py` router, path params are collected into a single dict and passed as the first positional argument to `page()`. Matching query params can still be injected by name, and `request` is passed by keyword when declared.
 
 Example:
@@ -208,20 +226,22 @@ Use an ellipsis inside brackets to match multiple path parts.
 
 | File | Example URL |
 | --- | --- |
-| `src/app/docs/[...slug]/index.py` | `/docs/getting-started/setup` |
+| `src/app/docs/[...slug]/index.html` | `/docs/getting-started/setup` |
 
 Use catch-all routes when the number of path segments is not fixed ahead of time.
 
+Add a sibling `index.py` when that catch-all route also needs backend logic or metadata.
+
 ## Route Groups
 
 Wrap a folder name in parentheses to organize code without adding that segment to the URL.
 
 Examples:
 
-| File | URL |
+| Files | URL |
 | --- | --- |
-| `src/app/(auth)/login/index.py` | `/login` |
-| `src/app/(auth)/register/index.py` | `/register` |
+| `src/app/(auth)/signin/index.html` and `src/app/(auth)/signin/index.py` | `/signin` |
+| `src/app/(auth)/signup/index.html` and `src/app/(auth)/signup/index.py` | `/signup` |
 
 Route groups are useful when you want to:
 
@@ -292,18 +312,25 @@ src/
       index.html
     users/
       [id]/
+        index.html
         index.py
     docs/
       [...slug]/
+        index.html
         index.py
     (auth)/
       login/
+        index.html
         index.py
       register/
+        index.html
+        index.py
+      signout/
         index.py
     dashboard/
       layout.html
       settings/
+        index.html
         index.py
 ```
 
@@ -313,7 +340,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.
-- Use `index.html` for route templates and `index.py` for route-level async logic.
+- 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`.
 - Use [cache.md](./cache.md) when an `index.py` route should opt into page-level HTML caching.
 - Use `layout.html` for shared wrappers and `layout.py` for layout-level synchronous props or metadata.
 - Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored root element.

package/package.json

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