caspian-utils 0.0.22 → 0.0.23

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

@@ -0,0 +1,77 @@
+---
+title: AI Validation Checklist
+description: Use this page when testing whether AI can find the right Caspian docs, core files, and verification checkpoints for a task after documentation or runtime changes.
+related:
+  title: Related docs
+  description: Start with the manifest, use the runtime map when needed, then validate against the matching feature guide and owning runtime behavior.
+  links:
+    - /docs/index
+    - /docs/core-runtime-map
+    - /docs/routing
+    - /docs/auth
+    - /docs/fetch-data
+    - /docs/pulsepoint
+---
+
+This page gives AI a small validation workflow for checking whether the packaged Caspian docs lead to the correct source files and runtime behaviors.
+
+Use it after changing packaged docs, after changing `main.py` or installed `casp` internals, or when you want to verify that AI can resolve a task without drifting across unrelated files.
+
+## Goal
+
+The goal is not to restate feature docs. The goal is to verify four things quickly:
+
+- AI starts from the correct manifest and feature gate.
+- AI reaches the correct packaged feature doc.
+- AI reaches the controlling app or runtime file.
+- AI reaches a concrete behavior checkpoint before making assumptions about behavior.
+
+## Fast Workflow
+
+1. Read [index.md](./index.md) to discover the local Caspian docs.
+2. Read `./caspian.config.json` before assuming any optional feature is enabled.
+3. If the task touches `main.py` or `.venv/Lib/site-packages/casp/**`, read [core-runtime-map.md](./core-runtime-map.md).
+4. Read the matching feature doc such as [routing.md](./routing.md), [auth.md](./auth.md), [fetch-data.md](./fetch-data.md), [pulsepoint.md](./pulsepoint.md), or [file-uploads.md](./file-uploads.md).
+5. Verify the claim against the actual project code and the installed runtime.
+6. Confirm the relevant behavior in the owning files surfaced by [core-runtime-map.md](./core-runtime-map.md) before treating the behavior as settled.
+
+## Pass Criteria
+
+A documentation path is in good shape when AI can do all of these without broad repo wandering:
+
+- identify whether the feature is enabled from `caspian.config.json`
+- choose the correct packaged doc from [index.md](./index.md)
+- jump to the controlling runtime file through [core-runtime-map.md](./core-runtime-map.md) when needed
+- distinguish app-owned files from installed framework internals
+- identify the concrete behavior that must be verified in the owning file
+- avoid suggesting changes to `main.py` or `.venv/Lib/site-packages/casp/**` unless the task truly requires runtime edits
+
+## Representative Prompt Suite
+
+Use prompts like these to check whether AI lands on the correct docs and files.
+
+| Prompt | First docs AI should read | Controlling files AI should reach | Verification focus |
+| --- | --- | --- | --- |
+| 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 |
+| 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 |
+| 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 |
+
+Treat the table as a prompt pack for spot checks, not as a full validation matrix.
+
+## Common Failure Modes
+
+- AI skips `caspian.config.json` and assumes an optional feature is enabled because a packaged doc exists.
+- AI reads only the packaged feature doc and never checks `main.py` or the installed runtime.
+- 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 decides behavior from memory without checking the owning implementation details.
+
+## Decision Rule
+
+- If the task is feature-oriented, start from [index.md](./index.md) and the matching feature doc.
+- If the task is behavior-oriented and the owner is unclear, jump to [core-runtime-map.md](./core-runtime-map.md).
+- If the task is still ambiguous after that, verify the controlling file and the specific behavior in scope before widening the search.

package/dist/docs/auth.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Use the fetch-data guide when sign-in or signout happens through RPC, then use the state guide for transient auth-adjacent request state, validation to guard credentials, and routing or project structure to place auth files correctly.
   links:
+    - /docs/core-runtime-map
     - /docs/fetch-data
     - /docs/state
     - /docs/validation
@@ -63,6 +64,7 @@ from casp.auth import (
 - The installed framework implementation lives in `.venv/Lib/site-packages/casp/auth.py`.
 - Treat `auth_config.py` as project code and `casp/auth.py` as framework code.
 - If upstream docs and the installed implementation disagree, prefer the installed implementation for local project guidance.
+- Use [core-runtime-map.md](./core-runtime-map.md) when an auth task crosses `main.py` bootstrap behavior such as development cookie scoping or middleware ownership.
 
 ## Centralized Auth Settings
 
@@ -167,6 +169,7 @@ The installed auth code reads several values from `.env` when explicit values ar
 - `AUTH_COOKIE_NAME` backs `AuthSettings.cookie_name`.
 - `SESSION_LIFETIME_HOURS` controls `SessionMiddleware.max_age` in the current `main.py` bootstrap.
 - `APP_ENV=production` enables secure session cookies and the `Secure` flag on the current CSRF cookie.
+- `CASPIAN_BROWSER_SYNC_PORT` can override the development cookie scope suffix used by the current `main.py` bootstrap.
 - `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_REDIRECT_URI` back `GoogleProvider`.
 - `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` back `GithubProvider`.
 
@@ -174,6 +177,8 @@ Keep these secrets out of route files and out of committed source.
 
 In the current bootstrap, set `AUTH_COOKIE_NAME` explicitly in `.env`. The pasted `main.py` uses `session` as the fallback `SessionMiddleware` cookie name, while `AuthSettings` falls back to `auth_token` when the env var is absent.
 
+In development, the current `main.py` does not always use those base cookie names directly. `_scoped_cookie_name(...)` appends the active BrowserSync or dev port to both the session cookie name and the CSRF cookie name when `APP_ENV` is not `production`. The scope is resolved from `CASPIAN_BROWSER_SYNC_PORT`, then from `settings/bs-config.json`, then from `PORT`. That means a local stack can emit names such as `session_5091` and `pp_csrf_5091` instead of the unsuffixed production names.
+
 ## Startup Wiring
 
 Apply the centralized settings once during startup, before normal request handling begins.
@@ -279,7 +284,7 @@ Because Starlette runs the last-added middleware first, the effective request or
 Current behavior by layer:
 
 - `SessionMiddleware` provides `request.session` for the rest of the stack.
-- `CSRFMiddleware` ensures `request.session["csrf_token"]` exists and emits a `pp_csrf` cookie.
+- `CSRFMiddleware` ensures `request.session["csrf_token"]` exists and emits a scoped CSRF cookie based on `pp_csrf`, for example `pp_csrf_5091` in development or plain `pp_csrf` when no dev scope is active.
 - `AuthMiddleware` sets request context with `Auth.set_request(request)`, initializes `StateManager`, runs provider callbacks, skips configured static asset paths, and enforces public, auth, private, and role-based route redirects.
 - `RPCMiddleware` handles `POST` requests with `X-PP-RPC: true` and forwards them to Caspian's RPC handler after auth and session setup are already available.
 
@@ -449,6 +454,7 @@ A typical credential-based auth setup often uses this route shape:
 src/
     app/
         (auth)/
+            layout.html
             signin/
                 index.py
                 index.html
@@ -458,12 +464,17 @@ src/
             signout/
                 index.py
         dashboard/
-            index.py
             index.html
+            layout.html
+            settings/
+                index.py
+                index.html
 ```
 
 Use `guest_only()` on signin and signup routes, use `auth.sign_in(...)` inside the owning RPC action after validation and credential checks, prefer RPC for signout UI actions, and protect private destinations with `require_auth()` or central route policy.
 
+When auth pages share a wrapper without adding a URL segment, use a route group such as `(auth)/layout.html`. When a protected area such as `dashboard` owns multiple child routes, apply the section layout pattern from [routing.md](./routing.md): put the shared shell in `dashboard/layout.html` and place child routes such as `dashboard/settings/index.html` beneath it.
+
 Preferred signout pattern: auth-protected RPC from a page or component.
 
 Use this when the logout trigger lives in a page, layout, header, dropdown, or reusable component. The HTML can live at page level or component level.
@@ -531,6 +542,24 @@ def page():
     })
 ```
 
+If the protected destination is a section rather than a single page, prefer a folder-level layout for the shared shell.
+
+```text
+src/
+    app/
+        dashboard/
+            layout.html
+            index.html
+            settings/
+                index.py
+                index.html
+            billing/
+                index.py
+                index.html
+```
+
+In that pattern, `dashboard/layout.html` owns the shared sidebar, header, and frame, while each child route decides whether it needs its own `index.py` for auth checks, metadata, RPC actions, or server-side data.
+
 For signup flows, use the same route ownership pattern as signin: validate the input, create the user, build a safe payload without password fields, and then call `auth.sign_in(...)` with the redirect target you want.
 
 Signup example:
@@ -765,6 +794,7 @@ If an AI agent is deciding how to handle auth in Caspian, apply these rules firs
 - Decide route mode early in `src/lib/auth/auth_config.py`: use `is_all_routes_private=True` when most routes should require auth, otherwise keep `is_all_routes_private=False` and list protected routes in `private_routes`.
 - In app-owned starter config, treat `is_all_routes_private=False` as the default starting point, which means routes begin public until the app opts into stricter protection.
 - Treat `public_routes` as the public exception list for all-private apps. In the current defaults, `/` stays public and `auth_routes=["/signin", "/signup"]` stays public too.
+- For protected grouped sections, follow the section layout pattern in [routing.md](./routing.md) and keep auth-specific route policy in `src/lib/auth/auth_config.py`.
 - Apply settings at startup in `main.py` with `configure_auth(build_auth_settings())`.
 - Register provider instances in `main.py` with `Auth.set_providers(...)` when Google or GitHub OAuth is enabled.
 - Use `auth.sign_in(...)` and `auth.sign_out(...)` for session lifecycle changes.

package/dist/docs/cache.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Use the routing guide to place route-level cache declarations correctly, then pair cache with fetch-data when deciding what can be safely served from reused HTML.
   links:
+    - /docs/core-runtime-map
     - /docs/routing
     - /docs/fetch-data
     - /docs/project-structure
@@ -27,6 +28,8 @@ from casp.cache_handler import Cache, CacheHandler
 
 The current installed implementation lives in `.venv/Lib/site-packages/casp/cache_handler.py`.
 
+Use [core-runtime-map.md](./core-runtime-map.md) when a cache task crosses `main.py` request flow, cache lookup timing, and the installed cache-handler internals.
+
 The real API surface is:
 
 - declarative route config with `Cache(ttl=..., enabled=...)`
@@ -41,7 +44,8 @@ Use caching when a route is expensive to render but the final HTML is stable eno
 
 - Use `Cache(...)` at module scope in a route's `index.py` when you want that route to participate in Caspian's page cache.
 - Cache public HTML that is safe to share between visitors.
-- Avoid caching dashboards, auth callbacks, request-specific error states, flash-message flows, or any page whose HTML changes per user.
+- Avoid caching personalized section shells such as authenticated dashboards, auth callbacks, request-specific error states, flash-message flows, or any page whose HTML changes per user.
+- If a dashboard, account area, admin area, or grouped subtree uses a parent `layout.html`, evaluate each child route separately. Public child pages may still be cacheable, but personalized section layouts generally are not.
 - Invalidate cached pages after writes, publishes, deletes, or admin actions that change what those routes should render.
 - Treat page caching as HTML reuse, not as a replacement for database caching or RPC response caching.
 
@@ -237,7 +241,7 @@ Good candidates for page caching are:
 
 Poor candidates are:
 
-- authenticated dashboards
+- authenticated dashboards and other personalized section layouts
 - per-user feeds or notification views
 - forms whose server-rendered HTML includes request-specific or sensitive state
 - pages that need sub-second freshness unless you have reliable invalidation hooks
@@ -249,6 +253,7 @@ If an AI agent is deciding whether or how to cache a Caspian route, apply these
 - Use `Cache` from `casp.cache_handler` for route-level page caching.
 - Prefer `cache_settings = Cache(...)` at module scope over a bare call when writing maintained project code.
 - Use `enabled=False` for pages whose HTML is personalized, auth-sensitive, or too volatile to reuse safely.
+- When a user asks about caching a dashboard, admin area, account area, or grouped subtree, check whether the shared `layout.html` is personalized before caching any child route. Shared authenticated shells are usually poor cache candidates even when some public child pages are cacheable.
 - Use `CacheHandler.invalidate_by_uri(...)` after writes that change cached public content.
 - Use `CacheHandler.reset_cache()` only for targeted maintenance, debugging, or full cache clears.
 - Use leading-slash URIs consistently when interacting with `CacheHandler`.

package/dist/docs/components.md

@@ -6,6 +6,7 @@ related:
   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.
   links:
     - /docs/project-structure
+    - /docs/core-runtime-map
     - /docs/routing
     - /docs/pulsepoint
     - /docs/fetch-data
@@ -29,6 +30,17 @@ As the app grows, treat `src/components/` as the default home for reusable appli
 - Use `render_html(...)` with a same-name `.html` file when the component has more markup, PulsePoint behavior, or clearer separation between Python logic and UI.
 - Keep page-level workflows in `src/app/`, move reusable UI into `src/components/`, and keep helpers, services, validators, and adapters in `src/lib/`.
 
+## Framework Internals Note
+
+When the task is about component internals rather than normal app-owned components, these runtime files are the most relevant:
+
+- `.venv/Lib/site-packages/casp/component_decorator.py` owns `@component`, `Component`, `render_html(...)`, and component loading.
+- `.venv/Lib/site-packages/casp/components_compiler.py` owns `@import` parsing, `x-*` tag resolution, root validation, and `pp-component` injection.
+- `.venv/Lib/site-packages/casp/html_attrs.py` owns `get_attributes(...)` and the Python-side `merge_classes(...)` contract.
+- `.venv/Lib/site-packages/casp/syntax_compiler.py` owns Caspian template syntax transpilation before Jinja render.
+
+Use [core-runtime-map.md](./core-runtime-map.md) when you need the broader runtime-module map.
+
 ## Basic Component
 
 This is the simplest pattern: accept props, assemble the final class value, and return HTML.
@@ -106,6 +118,8 @@ Place component imports at the top of the HTML template, above the authored root
 
 The import comment is the bridge between the Python component export and the `x-*` tag you author in HTML.
 
+In section-based apps, follow the same mental model as the Next.js App Router: import shared shell components such as sidebars, topbars, breadcrumbs, and section frames in the parent folder's `layout.html`, then import page-specific components in each child route's `index.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.
@@ -208,62 +222,28 @@ This keeps the component easy to read: Python owns the server-side logic and tem
 
 ## Auto-Injected `pp-component` And PulsePoint Script Type
 
-Treat `pp-component="componentName"` and `type="text/pp"` as framework output, not authored source.
+Treat `pp-component="componentName"` and `type="text/pp"` as framework output, not authored source. The canonical authored-vs-runtime explanation lives in [pulsepoint.md](./pulsepoint.md).
 
 - Do not manually add `pp-component="..."` to route templates, layout templates, or component HTML files.
 - Do not manually add `type="text/pp"` to authored PulsePoint scripts.
 - The Python render pipeline injects `pp-component` onto the single root element during render.
 - `main.py` runs `transform_scripts(...)`, which rewrites authored body `<script>` tags to `<script type="text/pp">` before the browser runtime mounts.
-- Add a plain `<script>` only when the route or component actually needs PulsePoint logic.
-- When you do add a PulsePoint script, keep it inside that single root element.
-
-Examples in runtime docs often show rendered HTML that already contains `pp-component` and `type="text/pp"`. That is the final output shape, not the normal authoring pattern.
-
-### Authored Source vs Rendered Output
-
-Author this:
-
-`Counter.html`
-
-```html
-<div>
-  <h3>[[ label ]]</h3>
-  <button onclick="setCount(count + 1)">
-    {count}
-  </button>
-
-  <script>
-    const [count, setCount] = pp.state(0);
-  </script>
-</div>
-```
-
-Do not author this by hand:
-
-```html
-<div pp-component="counter_ab12cd34">
-  <h3>Clicks</h3>
-  <button onclick="setCount(count + 1)">0</button>
-
-  <script type="text/pp">
-    const [count, setCount] = pp.state(0);
-  </script>
-</div>
-```
-
-The second example is the runtime shape after the Python side injects `pp-component` onto the component root.
+- Add a plain `<script>` only when the route or component actually needs PulsePoint logic, and keep it inside that single root element.
+- If a runtime example already shows `pp-component` and `type="text/pp"`, treat it as rendered output rather than authored source.
 
 ## Single-Root Rule
 
-Every component HTML template must render exactly one top-level lowercase HTML element.
+Every component HTML template must render exactly one authored top-level parent node.
 
-The same rule applies to route templates such as `src/app/**/index.html`: one root element, no sibling roots, and no manual `pp-component` authoring.
+The same rule applies to route and layout templates such as `src/app/**/index.html` and `src/app/**/layout.html`. See [routing.md](./routing.md) and [pulsepoint.md](./pulsepoint.md) for the non-component versions of the same authoring contract.
 
 Top-of-file `<!-- @import ... -->` directives are allowed before that root element and do not violate the single-root rule.
 
-This is not just style guidance. The installed compiler injects `pp-component` onto the root element, and it raises an error when the template has no root, multiple sibling roots, stray top-level text, or a component tag as the root.
+In source, that parent may be a native HTML element or a single imported `x-*` component tag. After component expansion, the template must still resolve to one final native HTML root so Caspian has exactly one place to inject `pp-component`.
 
-For AI-generated templates, treat this as a hard authoring rule: write the HTML the same way a React component returns one parent element. If the template needs a PulsePoint script, keep that script inside the same parent root.
+This is not just style guidance. The installed compiler injects `pp-component` onto the final root element, and it raises an error when the template has no root, multiple sibling roots, or stray top-level text.
+
+For AI-generated templates, treat this as a hard authoring rule: write the HTML the same way a React component returns one parent node. If the template needs a PulsePoint script, keep that script inside the same parent root.
 
 Good:
 
@@ -296,9 +276,7 @@ Also bad:
 <p>Body</p>
 ```
 
-Also avoid making another component tag the root of the HTML file. The root must be a normal lowercase HTML element such as `<div>`, `<section>`, or `<article>`.
-
-Think about this rule the same way you would in a React component: one parent element per template root. In Caspian, that requirement exists so the Python renderer has exactly one place to attach `pp-component`.
+If you choose an imported `x-*` component as the authored root of the file, make sure it resolves to one native HTML root when compiled. Do not leave an unresolved component tag as the root, and do not emit multiple top-level component siblings.
 
 ## Props, Types, And Children
 
@@ -355,6 +333,7 @@ Keep synchronous components as the default. Switch to `async def` only when the
 ## Best Practices
 
 - Put reusable components in `src/components/` and keep route files in `src/app/`.
+- For dashboards, admin areas, account sections, and route groups with child routes, put the shared shell in the parent folder's `layout.html` and compose it from reusable components there instead of repeating the same shell in every child `index.html`.
 - 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 authored tag aligned, such as `Button.py`, `def Button(...)`, and `<x-button />`.
 - Accept `children` or `**props` when the component should support nested content.

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

@@ -0,0 +1,83 @@
+---
+title: Core Runtime Map
+description: Use this page when the task touches `main.py`, installed `casp` internals, or when AI needs to know which core file controls a behavior and which packaged doc explains it.
+related:
+  title: Related docs
+  description: Start with the structure guide, then jump from the runtime file to the matching feature doc.
+  links:
+    - /docs/project-structure
+    - /docs/routing
+    - /docs/auth
+    - /docs/fetch-data
+    - /docs/pulsepoint
+    - /docs/index
+---
+
+This page maps the app entry point and the installed Caspian runtime modules to the packaged docs that explain them.
+
+Use it when you already know a behavior is controlled by `main.py` or `.venv/Lib/site-packages/casp/**` and you need the fastest path from symptom to source file.
+
+## When To Read This Page
+
+- a packaged doc mentions a runtime contract and you need the exact file that implements it
+- `main.py` or the installed `casp` package disagrees with older notes or examples
+- the task is about framework internals rather than normal app-owned route or component code
+- AI needs to know which packaged doc should be kept aligned with a core-file change
+
+## App Entry Point
+
+| Concern | Core file | Read first | Why it matters |
+| --- | --- | --- | --- |
+| App bootstrap and request flow | [main.py](../../../../main.py) | [project-structure.md](./project-structure.md), [routing.md](./routing.md), [auth.md](./auth.md) | FastAPI app creation, static asset routes, middleware order, route registration, cache check and save, exception handlers, and final HTML transforms all live here. |
+
+Important current `main.py` behaviors AI should keep in mind:
+
+- In development, `_scoped_cookie_name(...)` appends the active BrowserSync or dev port to both the session cookie name and the CSRF cookie name. The scope is resolved from `CASPIAN_BROWSER_SYNC_PORT`, then `settings/bs-config.json`, then `PORT`.
+- `register_single_route(...)` passes path params to `page()` as one positional dict, injects matching query params by name, and injects `request` by keyword when declared.
+- The render pipeline is `transform_components(...)`, then `render_with_nested_layouts(...)`, then `transform_scripts(...)`.
+- Route-level generators returned from `page()` are wrapped in `SSE(...)` before the response is sent.
+- Middleware is added in source order as `RPCMiddleware`, `AuthMiddleware`, `CSRFMiddleware`, `SessionMiddleware`, so the effective request order is reversed at runtime.
+
+## Installed Runtime Map
+
+| Runtime file | Primary responsibility | Read these docs |
+| --- | --- | --- |
+| [.venv/Lib/site-packages/casp/layout.py](../../../../.venv/Lib/site-packages/casp/layout.py) | `render_page(...)`, `render_layout(...)`, nested layout discovery, metadata merge, and the synchronous `layout()` contract | [routing.md](./routing.md), [metadata.md](./metadata.md) |
+| [.venv/Lib/site-packages/casp/auth.py](../../../../.venv/Lib/site-packages/casp/auth.py) | `AuthSettings`, route privacy checks, session payloads, OAuth providers, CSRF helper behavior, and redirect logic | [auth.md](./auth.md) |
+| [.venv/Lib/site-packages/casp/rpc.py](../../../../.venv/Lib/site-packages/casp/rpc.py) | `@rpc()` registration, rate limits, request handling, auth-aware action checks, and streamed RPC responses | [fetch-data.md](./fetch-data.md) |
+| [.venv/Lib/site-packages/casp/streaming.py](../../../../.venv/Lib/site-packages/casp/streaming.py) | `SSE`, `ServerSentEvent`, and generator-to-event-stream wrapping | [fetch-data.md](./fetch-data.md) |
+| [.venv/Lib/site-packages/casp/state_manager.py](../../../../.venv/Lib/site-packages/casp/state_manager.py) | request-scoped state, session bucket persistence, listener lifecycle, and wire-request reset behavior | [state.md](./state.md) |
+| [.venv/Lib/site-packages/casp/cache_handler.py](../../../../.venv/Lib/site-packages/casp/cache_handler.py) | `Cache`, cache manifest handling, filename generation, disk-backed HTML storage, and invalidation | [cache.md](./cache.md) |
+| [.venv/Lib/site-packages/casp/validate.py](../../../../.venv/Lib/site-packages/casp/validate.py) | `Validate`, `Rule`, sanitization, and file-validation internals | [validation.md](./validation.md) |
+| [.venv/Lib/site-packages/casp/component_decorator.py](../../../../.venv/Lib/site-packages/casp/component_decorator.py) | `@component`, `render_html(...)`, component loading, and prop normalization before component calls | [components.md](./components.md) |
+| [.venv/Lib/site-packages/casp/components_compiler.py](../../../../.venv/Lib/site-packages/casp/components_compiler.py) | `@import` parsing, `x-*` component resolution, single-root validation, and `pp-component` injection | [components.md](./components.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md) |
+| [.venv/Lib/site-packages/casp/scripts_type.py](../../../../.venv/Lib/site-packages/casp/scripts_type.py) | rewriting authored body `<script>` tags to `type="text/pp"` in rendered HTML | [pulsepoint.md](./pulsepoint.md), [routing.md](./routing.md), [components.md](./components.md) |
+| [.venv/Lib/site-packages/casp/html_attrs.py](../../../../.venv/Lib/site-packages/casp/html_attrs.py) | `get_attributes(...)`, alias normalization, and the Python-side `merge_classes(...)` contract | [components.md](./components.md) |
+| [.venv/Lib/site-packages/casp/caspian_config.py](../../../../.venv/Lib/site-packages/casp/caspian_config.py) | typed config loading, feature-flag reads, `settings/files-list.json` parsing, and route rule derivation | [project-structure.md](./project-structure.md), [commands.md](./commands.md), [routing.md](./routing.md) |
+| [.venv/Lib/site-packages/casp/syntax_compiler.py](../../../../.venv/Lib/site-packages/casp/syntax_compiler.py) | transpiling Caspian `<[[ ... ]]>` and `<template casp-*>` syntax before template render | [components.md](./components.md), [routing.md](./routing.md) |
+
+Secondary helpers such as `html_native.py`, `loading.py`, and `string_helpers.py` support the modules above. Read them only when a higher-level runtime file is still insufficient to explain the behavior you are tracing.
+
+## Verification Focus
+
+Use these behavior checkpoints when AI needs the fastest verification path for a runtime behavior before widening the search.
+
+| Runtime area | Verify these behaviors |
+| --- | --- |
+| `main.py` routing and request flow | route registration, path and query injection, static asset handling, and exception rendering |
+| `casp.auth` | auth settings, signin and signout flow, provider wiring, and page protection behavior |
+| `casp.rpc` and streamed RPC responses | middleware interception, CSRF and session expectations, registry behavior, and helper-level RPC contracts |
+| `casp.layout` | layout discovery, metadata merge, root handling, and layout rendering rules |
+| `casp.components_compiler`, `casp.component_decorator`, `casp.scripts_type`, and template-root injection | `@import` parsing, `x-*` expansion, syntax transpilation, deterministic root keys, `pp-component` injection, and authored-script rewriting to `type="text/pp"` |
+| `casp.state_manager` | wire vs non-wire reset behavior, request-state persistence assumptions, and AttributeDict access |
+| `casp.cache_handler` | filename generation, manifest writes, TTL handling, and invalidation behavior |
+| `casp.caspian_config` | config parsing, files index building, and Next.js-style route inventory behavior |
+
+When a runtime or packaged-doc change touches one of these areas, verify the relevant behavior in the owning source file before inferring behavior from memory.
+
+## Decision Rule
+
+- Start with the packaged feature doc that matches the task.
+- Use this runtime map when that doc needs to point AI to the controlling source file.
+- Prefer app code and `main.py` over packaged docs when the task is about the current workspace behavior.
+- Do not modify `main.py` or `.venv/Lib/site-packages/casp/**` just because a packaged doc mentions them. Edit those files only when the user asks for a runtime change or when the task is explicitly about framework behavior.

package/dist/docs/fetch-data.md

@@ -8,6 +8,7 @@ related:
     - /docs/auth
     - /docs/mcp
     - /docs/state
+    - /docs/core-runtime-map
     - /docs/database
     - /docs/file-uploads
     - /docs/cache
@@ -38,6 +39,8 @@ In practice, most pages use both:
 
 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.
 
+When a page belongs to a grouped subtree such as a dashboard, account area, admin section, or docs section, apply the section layout pattern from [routing.md](./routing.md): keep the shared shell in the parent folder's `layout.html` and let each child route own only its route-specific `index.html` and optional `index.py`.
+
 ## 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.
@@ -75,6 +78,7 @@ Notes:
 
 - Prefer `async def page()` when your database or API client is async-capable.
 - Put shared section-level props in `layout.py` when multiple child routes need the same synchronous payload. The current layout engine does not await `layout()`.
+- 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.
@@ -86,7 +90,8 @@ Use RPC when the browser needs to call Python after the initial page load.
 Framework internals note:
 
 - The `@rpc()` decorator and Caspian RPC bridge internals live in `.venv/Lib/site-packages/casp/rpc.py`.
-- Treat that file as framework code. Read it when you need to understand or debug Caspian's RPC behavior, not when you are adding normal app-level actions.
+- Streamed response helpers such as `SSE` and `ServerSentEvent` live in `.venv/Lib/site-packages/casp/streaming.py`.
+- Treat those files as framework code. Read them when you need to understand or debug Caspian's RPC or streaming behavior, not when you are adding normal app-level actions.
 
 Define a server action with `@rpc()`:
 
@@ -177,6 +182,8 @@ Client example:
 
 Use streaming when the user should see partial progress instead of waiting for a single final payload.
 
+In the current runtime, generator and async-generator RPC results are wrapped with `SSE(...)` inside `casp.rpc.py`, and route-level generator results are also wrapped by `main.py` before the response is returned.
+
 ## File Uploads
 
 RPC actions can accept FastAPI upload types, but the preferred Caspian pattern is route-local upload actions in `src/app/**/index.py`, shared persistence helpers in `src/lib/`, and reactive client updates through `pp.rpc()`.
@@ -288,6 +295,23 @@ A common pattern is:
 - Render that data into the HTML template
 - Use RPC for subsequent filters, mutations, refreshes, streaming, or uploads
 
+For section-based apps, that pattern usually lives inside a parent layout:
+
+```text
+src/
+  app/
+    dashboard/
+      layout.html
+      reports/
+        index.py
+        index.html
+      users/
+        index.py
+        index.html
+```
+
+In that pattern, `dashboard/layout.html` owns the shared frame while each child route handles its own first-render data in `index.py` and its own interactive updates through `@rpc()`.
+
 If the first-render HTML is expensive to produce and safe to share between visitors, add route-level caching with [cache.md](./cache.md) and invalidate affected URIs after successful mutations.
 
 ## AI Retrieval Notes
@@ -297,6 +321,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()`.
+- For grouped subtrees, follow the section layout pattern in [routing.md](./routing.md) before deciding where `page()` data and `@rpc()` actions belong.
 - 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.

package/dist/docs/file-uploads.md

@@ -18,6 +18,8 @@ This page documents the recommended file upload and file manager pattern for Cas
 
 Treat uploads as normal route behavior. Keep the owning browser UI in the route template, keep upload and delete `@rpc()` actions in the owning route `index.py`, and move reusable storage or persistence helpers into `src/lib/`.
 
+If the file manager lives inside a grouped subtree such as a dashboard, account area, or admin area, apply the section layout pattern from [routing.md](./routing.md): keep the shared shell in the parent folder's `layout.html` and keep the file-manager route itself in a child folder.
+
 ## Default Pattern
 
 - Keep first-render file manager data in `page()` so the initial HTML already contains the current asset list and storage summary.
@@ -52,6 +54,20 @@ The normal Caspian file-manager flow is:
 6. The RPC action returns refreshed manager data.
 7. PulsePoint replaces the route state and `pp-for` rerenders the list.
 
+Section example:
+
+```text
+src/
+  app/
+    dashboard/
+      layout.html
+      files/
+        index.py
+        index.html
+```
+
+In that pattern, `dashboard/layout.html` owns the shared dashboard shell, while `dashboard/files/index.py` owns the initial file-manager payload and the upload or delete `@rpc()` actions.
+
 ## Example Route-Local RPC
 
 ```python
@@ -171,4 +187,5 @@ const PUBLIC_IGNORE_DIRS = ["uploads"];
 - Use `database.md` when Prisma models or relations must change for upload metadata.
 - Use `validation.md` for MIME, extension, and other boundary checks, then keep explicit size and auth checks in the owning RPC action.
 - Use `project-structure.md` for placement rules, especially `src/app/` versus `src/lib/` and `public/uploads/`.
+- For grouped file-manager sections, follow the section layout pattern in [routing.md](./routing.md) and keep the upload page in a child route folder beneath the shared shell.
 - Use `commands.md` and `settings/bs-config.ts` when uploads should not trigger BrowserSync reloads during `npm run dev`.

package/dist/docs/index.md

@@ -5,8 +5,10 @@ related:
   title: Next Steps
   description: Start with installation, review the CLI commands, then use the structure and component guides to place Caspian files correctly.
   links:
+    - /docs/ai-validation-checklist
     - /docs/installation
     - /docs/commands
+    - /docs/core-runtime-map
     - /docs/mcp
     - /docs/file-uploads
     - /docs/project-structure
@@ -38,12 +40,15 @@ The packaged Caspian docs referenced by this index live here:
 
 ## Available Documents
 
+- `index.md` - packaged docs manifest and the default first entry point for AI retrieval in this directory
+- `ai-validation-checklist.md` - workflow and representative prompts for checking whether AI can find the correct Caspian docs, core files, and verification checkpoints
 - `installation.md` - First-time setup flow for creating a new Caspian application
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
+- `core-runtime-map.md` - map of `main.py` plus installed `casp` modules to the packaged docs that explain them and the behaviors AI should trace there
 - `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, HTML-first `x-*` component tags, the single-parent root rule for component HTML files, and the Python-side `merge_classes(...)` contract when Tailwind CSS is enabled
+- `components.md` - Create reusable Python components, template-backed UI, HTML-first `x-*` component tags, the single-parent authored-root rule for component HTML files, and the Python-side `merge_classes(...)` contract when Tailwind CSS is enabled
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, client-side behaviors, and direct browser `twMerge(...)` usage when Tailwind CSS is enabled
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
 - `file-uploads.md` - Route-local file uploads and file-manager flows with `@rpc()`, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync ignore rules
@@ -51,7 +56,7 @@ The packaged Caspian docs referenced by this index live here:
 - `cache.md` - Route-level HTML caching with `Cache`, `CacheHandler`, TTL behavior, file-system storage, and invalidation patterns
 - `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
 - `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
-- `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, route groups, nested layouts, and single-root route templates
+- `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, dashboard and section layouts, route groups, nested layouts, single-parent authored templates, and backend Python companions that do not own visible markup
 - `project-structure.md` - Default Caspian layout and where route files, reusable UI in `src/components/`, reusable non-UI code in `src/lib/`, and database files belong
 
 ## AI Retrieval Notes
@@ -63,10 +68,12 @@ Preferred lookup order:
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
 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. 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`.
-4. 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.
-5. 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.
-6. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
-7. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
+4. 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.
+5. 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.
+6. 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.
+7. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
+8. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
+9. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 
 ## Maintenance
 

package/dist/docs/metadata.md

@@ -31,7 +31,9 @@ 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.
+For dashboard sections, account areas, docs sections, and route groups, apply the section layout pattern from [routing.md](./routing.md): put shared metadata defaults in the section's `layout.py`, then override them in child `index.py` files only when a leaf page needs different SEO.
+
+On routes that render UI, keep the page markup in the sibling `index.html` and keep shared wrapper markup in `layout.html`. `index.py` and `layout.py` are metadata and backend companions, not the places to store visible route or layout 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:
 
@@ -118,6 +120,8 @@ Priority order:
 2. Nested `layout.py` files override those defaults for a section.
 3. `index.py` metadata or runtime `Metadata(...)` inside the route has the highest priority.
 
+For example, a dashboard section usually keeps shared defaults in `src/app/dashboard/layout.py`, while a grouping folder that should stay out of the URL can keep its shared defaults in `src/app/(marketing)/layout.py`.
+
 Within a single file, the layout engine applies static metadata first and then applies runtime metadata from `Metadata(...)`, so runtime values win for matching keys.
 
 If a child route overrides only the title, the description and other fields continue to fall through from the nearest parent that defines them.
@@ -128,6 +132,14 @@ Example structure:
 src/
   app/
     layout.py
+        (marketing)/
+            layout.py
+            pricing/
+                index.py
+        dashboard/
+            layout.py
+            settings/
+                index.py
     blog/
       layout.py
       [slug]/
@@ -137,6 +149,7 @@ src/
 Typical result:
 
 - Root layout defines the site-wide title template and default description.
+- Route-group or section layouts such as `(marketing)/layout.py` or `dashboard/layout.py` define shared defaults for that subtree.
 - Blog layout overrides section-level fields for `/blog/*`.
 - Blog page overrides the final post title and any page-specific social tags.
 
@@ -185,6 +198,8 @@ Keep visual layout data and SEO metadata separate.
 
 - Put site-wide defaults in `src/app/layout.py`.
 - Put section defaults in nested `layout.py` files such as `src/app/blog/layout.py`.
+- For dashboard, admin, account, docs, or grouped sections with child routes, put the shared defaults in that section folder's `layout.py` and keep the shared wrapper in the sibling `layout.html`.
+- Use a route-group `layout.py` such as `src/app/(marketing)/layout.py` only when the grouping folder should not appear in the final URL.
 - Put page-specific static metadata in `index.py`.
 - Put dynamic metadata inside `page()` after you have route params or fetched data.
 
@@ -196,6 +211,7 @@ If an AI agent is deciding where to put SEO fields, apply these rules first.
 - Prefer module-level `metadata = Metadata(...)` for static routes.
 - Instantiate `Metadata(...)` inside `page()` when metadata depends on params, fetched records, or generated content.
 - Put shared defaults in `layout.py` and let leaf pages override only what they need.
+- For grouped subtrees, follow the section layout pattern in [routing.md](./routing.md) and keep shared metadata defaults in the parent folder's `layout.py`.
 - If a single route only needs to tweak a wrapping layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` instead of moving that prop into metadata.
 - Use `extra` for Open Graph and Twitter card tags.
 - Access `extra` values in templates with bracket syntax such as `metadata['og:image']`.

package/dist/docs/project-structure.md

@@ -6,6 +6,7 @@ related:
   description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the MCP guide for server layout, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
   links:
     - /docs/installation
+    - /docs/core-runtime-map
     - /docs/components
     - /docs/auth
     - /docs/mcp
@@ -105,11 +106,13 @@ 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.
+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 synchronous props or metadata. 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.
+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.
 
-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.
+If the shared wrapper should not add a URL segment, use a parenthesized route-group folder such as `(marketing)/layout.html` instead of a normal folder name. Use a normal folder such as `dashboard/` only when that segment should be part of the public URL.
+
+When authoring route or layout HTML, follow the authoring contract documented in [routing.md](./routing.md) and [pulsepoint.md](./pulsepoint.md): keep one authored root, keep `<!-- @import ... -->` directives above that root, use a plain `<script>` inside the root when needed, and do not handwrite `pp-component` or `type="text/pp"`.
 
 See `routing.md` for the full App Router-style rules for dynamic segments, route groups, and nested layouts.
 
@@ -123,9 +126,7 @@ The common Caspian pattern is a Python file such as `Button.py` with `@component
 
 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.
-
-Do not handwrite `pp-component="..."` or `type="text/pp"` in component source templates either. Write plain `<script>` inside the single root and let the render pipeline inject the runtime shape.
+For component HTML files, follow the component authoring rules in [components.md](./components.md): one top-level parent node, no sibling roots, plain `<script>` inside that root when needed, and no handwritten `pp-component` or `type="text/pp"`.
 
 The directories listed in `componentScanDirs` determine where component tooling scans. When that list includes `src/`, `src/components/` is a conventionally clean location, not a hard-coded runtime requirement.
 
@@ -211,6 +212,12 @@ When runtime uploads write into `public/uploads/`, keep the public-root-relative
 
 `settings/bs-config.ts` matches ignore entries against paths relative to the `public/` root, so nested uploaded files do not trigger reloads.
 
+### `settings/bs-config.json`
+
+When the local BrowserSync stack is running, this generated file is the active URL snapshot.
+
+Use it when AI needs the current local, external, or UI URL instead of the configured defaults, and use it when tracing the development cookie scope logic in `main.py` because `_dev_cookie_scope()` can read the active port from this file.
+
 ### `src/lib/auth/auth_config.py`
 
 The project auth configuration file. Use this path when changing authentication behavior.
@@ -231,6 +238,16 @@ The root layout shared across pages.
 
 If this layout imports reusable components, place each `<!-- @import ... -->` comment above the authored root `<html>` element instead of nesting the comment inside `<html>` or `<body>`.
 
+Nested section layouts follow the same pattern in child folders such as `src/app/dashboard/layout.html` or `src/app/(marketing)/layout.html`. Use those nested layouts for shared dashboard shells, grouped page wrappers, sidebars, headers, or section-level metadata defaults.
+
+Keep visible wrapper markup in `layout.html`, not in `layout.py`.
+
+### `src/app/layout.py`
+
+The backend companion for a layout. Use this file for shared synchronous props, metadata defaults, and other server-side preparation for the sibling `layout.html`.
+
+Do not store layout HTML in `layout.py`. Keep the authored wrapper in `layout.html` and let `layout.py` return props or metadata.
+
 ### `src/app/index.py`
 
 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.
@@ -247,6 +264,8 @@ If a route renders UI and needs no backend behavior, this file alone is sufficie
 
 Treat import comments as top-of-file directives that belong above the route's single authored root element.
 
+That authored root may be a native HTML element or a single imported `x-*` component tag, but after component expansion it must still resolve to one final HTML root.
+
 Use `components.md` when the task involves authoring reusable `<x-my-component />` tags backed by Python files.
 
 ### `src/app/globals.css`
@@ -257,12 +276,21 @@ Global application styles.
 
 The installed Caspian framework package. This is framework internals, not normal application code.
 
+Use [core-runtime-map.md](./core-runtime-map.md) when you need the fastest concern-to-file lookup across this directory.
+
 Notable internal files include:
 
 - `.venv/Lib/site-packages/casp/rpc.py` for the RPC decorator and related server-action internals
 - `.venv/Lib/site-packages/casp/layout.py` for layout rendering, metadata handling, and routing-related internals
 - `.venv/Lib/site-packages/casp/cache_handler.py` for route-level cache declarations, cache manifest handling, disk-backed HTML writes, and invalidation internals
 - `.venv/Lib/site-packages/casp/validate.py` for direct validators, rule-based validation, sanitization, and file-validation internals
+- `.venv/Lib/site-packages/casp/auth.py` for auth settings, route-protection checks, and OAuth internals
+- `.venv/Lib/site-packages/casp/state_manager.py` for request-scoped server state and persistence caveats
+- `.venv/Lib/site-packages/casp/component_decorator.py` for `@component`, `render_html(...)`, and component loading
+- `.venv/Lib/site-packages/casp/components_compiler.py` for `@import` parsing, `x-*` resolution, root validation, and `pp-component` injection
+- `.venv/Lib/site-packages/casp/scripts_type.py` for converting authored `<script>` tags to `type="text/pp"`
+- `.venv/Lib/site-packages/casp/caspian_config.py` for config loading and route inventory parsing
+- `.venv/Lib/site-packages/casp/streaming.py` for `SSE` and streamed response helpers
 
 ### `node_modules/caspian-utils/dist/docs/`
 
@@ -280,13 +308,14 @@ If an AI agent is deciding where to make changes, use these rules first.
 - 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/`.
 - 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.
 - 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__)`, `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.
-- For route and component HTML files, always emit one top-level lowercase HTML element. Good: one wrapper containing the content and a plain `<script>` when needed. Bad: a wrapper element followed by a sibling top-level `<script>`, or handwritten `pp-component="..."` and `type="text/pp"` attributes in source.
+- Follow the single-root authoring contract in [routing.md](./routing.md), [components.md](./components.md), and [pulsepoint.md](./pulsepoint.md): one authored root, any owned `<script>` inside that root, and no handwritten `pp-component` or `type="text/pp"` in source templates.
 - Put shared helpers and reusable libraries in `src/lib/`.
 - 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.
@@ -301,6 +330,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Put static files in `public/`.
 - Put entry-point changes in `main.py`.
 - Put feature and framework-level project configuration in `caspian.config.json`.
+- Read [core-runtime-map.md](./core-runtime-map.md) when the task touches `main.py` or installed `casp` internals and the controlling file is not obvious yet.
 - Treat `.venv/Lib/site-packages/casp/` as framework internals unless the task is specifically about Caspian core behavior.
 - Use `.venv/Lib/site-packages/casp/rpc.py` when investigating or documenting Caspian RPC internals.
 - Use `.venv/Lib/site-packages/casp/layout.py` when investigating or documenting Caspian routing, layout, or metadata internals.

package/dist/docs/pulsepoint.md

@@ -8,6 +8,7 @@ related:
     - /docs/components
     - /docs/routing
     - /docs/fetch-data
+    - /docs/core-runtime-map
     - /docs/project-structure
     - /docs/index
 ---
@@ -36,10 +37,14 @@ 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.
+- `.venv/Lib/site-packages/casp/components_compiler.py` injects `pp-component` on the final resolved root after component expansion.
+- `.venv/Lib/site-packages/casp/scripts_type.py` rewrites authored body `<script>` tags to `type="text/pp"`.
 - 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.
 
+Use [core-runtime-map.md](./core-runtime-map.md) when the controlling runtime file is not obvious yet.
+
 ## Default Frontend Rule
 
 When a Caspian page needs reactive browser behavior, use PulsePoint.
@@ -48,10 +53,13 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 - 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.
+- 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.
 - Only introduce another frontend runtime when the user explicitly asks for it or the project already depends on one.
 
 ## Authoring Model
 
+Treat this section as the canonical authored-vs-runtime contract for Caspian templates. When another packaged doc needs this rule set, link here instead of restating the full explanation.
+
 PulsePoint authoring is split into two layers:
 
 - The authored layer: route, layout, and component templates under `src/` with plain HTML plus a plain `<script>`.
@@ -59,11 +67,14 @@ PulsePoint authoring is split into two layers:
 
 For authored Caspian templates:
 
-- Keep exactly one top-level lowercase HTML root element.
+- Keep exactly one authored top-level parent node.
+- In source, that parent may be a native HTML element or a single imported `x-*` component tag, but after component expansion it must resolve to one final HTML root.
 - Put the component logic inside a plain `<script>` inside that same root.
 - Do not handwrite `pp-component="..."`.
 - Do not handwrite `type="text/pp"`.
 
+Keep visible route, layout, and component markup in the HTML templates. Treat `index.py` and `layout.py` as backend companions for data, metadata, props, RPC actions, auth, caching, redirects, and other server-side preparation, not as template bodies.
+
 Caspian already handles those details for you during render.
 
 That means AI-generated examples should default to authored template source, not raw runtime HTML.
@@ -111,7 +122,7 @@ Important:
 - At runtime, the owned script is `script[type="text/pp"]`.
 - The script lookup walks the current root and skips nested `pp-component` boundaries, so a parent does not consume a child component's script.
 - If multiple matching runtime scripts exist in the same root, the first matching owned script wins. Generate one script per root.
-- Authored route, layout, and component templates still need one top-level lowercase HTML root so Caspian can inject the component boundary correctly.
+- Authored route, layout, and component templates still need one top-level parent node so Caspian can inject the component boundary correctly after component expansion.
 - A scriptless component root still mounts and can receive props, refs, events, and nested children, but it has no local runtime scope beyond its props.
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
@@ -421,6 +432,7 @@ Use these rules when generating or editing PulsePoint runtime code:
 - 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.
+- For grouped subtrees, follow the section layout pattern in [routing.md](./routing.md), keep the shared interactive shell in the parent folder's `layout.html`, and keep route-specific PulsePoint code in each child `index.html`.
 - 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"]`.

package/dist/docs/routing.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Read the structure guide first, then use the components guide for reusable UI, the metadata guide for SEO fields, the cache guide for route-level HTML reuse, and the PulsePoint runtime guide for interactive route templates.
   links:
+    - /docs/core-runtime-map
     - /docs/project-structure
     - /docs/components
     - /docs/cache
@@ -29,8 +30,9 @@ Start with these rules:
 - 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.
+- 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.
 - Use `layout.py` when a layout needs shared synchronous props or metadata before rendering.
+- Keep visible route and layout markup in `index.html` and `layout.html`. Treat `index.py` and `layout.py` as backend companions, not as places to author visible HTML.
 
 Use [cache.md](./cache.md) when an `index.py` route also needs declarative page caching via `Cache(...)`.
 
@@ -38,6 +40,7 @@ Framework internals note:
 
 - Caspian's layout and route-resolution internals live in `.venv/Lib/site-packages/casp/layout.py`.
 - Treat that file as framework code. Read it when the task is about routing internals, layout resolution, or metadata behavior inside Caspian itself.
+- Use [core-runtime-map.md](./core-runtime-map.md) when a routing task crosses `main.py` route registration, parameter injection, and installed layout internals.
 
 See [metadata.md](./metadata.md) when a page or layout needs SEO fields.
 
@@ -61,6 +64,75 @@ This means most App Router habits carry over directly:
 - Use nested layouts for shared wrappers.
 - Use route groups to organize code without changing the public path.
 
+## Section Layout Pattern
+
+Treat this section as the canonical grouped-subtree structure rule for the packaged docs. Other pages should point here instead of repeating the full folder pattern.
+
+When a user asks for a dashboard, admin area, account section, docs section, or any grouped set of child routes, model it exactly like a Next.js App Router subtree.
+
+- Create a parent folder for the section.
+- Add `layout.html` in that folder for the shared shell.
+- Add `layout.py` only when that shared shell needs synchronous props or metadata.
+- Put each child page in its own route folder with `index.html` and an optional `index.py` companion.
+- Use a normal folder name such as `dashboard/` when the section name should appear in the URL.
+- Use a route-group folder such as `(marketing)/` when the folder should organize code and own a layout without adding a URL segment.
+
+Examples:
+
+```text
+src/
+  app/
+    dashboard/
+      layout.html
+      index.html
+      settings/
+        index.html
+      users/
+        index.html
+```
+
+This produces `/dashboard`, `/dashboard/settings`, and `/dashboard/users`, all wrapped by the `dashboard/layout.html` shell.
+
+```text
+src/
+  app/
+    (marketing)/
+      layout.html
+      pricing/
+        index.html
+      about/
+        index.html
+```
+
+This produces `/pricing` and `/about`, both wrapped by the `(marketing)/layout.html` shell even though `(marketing)` does not appear in the URL.
+
+Canonical end-to-end example:
+
+```text
+src/
+  app/
+    layout.html
+    layout.py
+    (marketing)/
+      layout.html
+      pricing/
+        index.html
+      about/
+        index.html
+    dashboard/
+      layout.html
+      layout.py
+      index.html
+      settings/
+        index.html
+        index.py
+      reports/
+        index.html
+        index.py
+```
+
+Use this pattern when the app has a public grouped section that should stay out of the URL and a private dashboard section that should appear in the URL. The root layout owns app-wide chrome, `(marketing)/layout.html` owns the shared public marketing shell, and `dashboard/layout.html` owns the shared dashboard shell for `/dashboard/*` child routes.
+
 ## Core Concepts
 
 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.
@@ -93,13 +165,9 @@ Route templates can import reusable Python components with `<!-- @import ... -->
 
 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.
 
-Do not manually add `pp-component="..."` to the route root. The Python render pipeline injects that attribute onto the route's single top-level lowercase HTML element.
-
-Do not manually add `type="text/pp"` to a route-owned script either. In source templates, write a plain `<script>` inside the root and let `main.py` call `transform_scripts(...)` before the browser runtime sees the HTML.
-
-That means route templates follow the same single-root discipline as component templates: one root element, no sibling roots, and PulsePoint scripts kept inside that root when needed.
+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.
 
-For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent element that contains the entire route markup.
+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.
 
 Good:
 
@@ -134,35 +202,7 @@ Also bad:
 </section>
 ```
 
-Example authored route template:
-
-```html
-<!-- @import StatsCard from "../components" -->
-
-<section class="dashboard-shell">
-  <x-stats-card title="Users" value="42" />
-
-  <script>
-    const [filter, setFilter] = pp.state("all");
-  </script>
-</section>
-```
-
-Rendered shape at runtime:
-
-```html
-<section pp-component="page_a1b2c3d4" class="dashboard-shell">
-  <div pp-component="statscard_e5f6g7h8" title="Users" value="42">
-    ...
-  </div>
-
-  <script type="text/pp">
-    const [filter, setFilter] = pp.state("all");
-  </script>
-</section>
-```
-
-Write the first form. Caspian produces the second form by injecting `pp-component` on the root and `type="text/pp"` on the owned script.
+Use [pulsepoint.md](./pulsepoint.md) when you need the full authored-vs-rendered example instead of this routing-focused reminder.
 
 ### `index.py`
 
@@ -280,14 +320,29 @@ Route groups are useful when you want to:
 - Split routes under different layout boundaries.
 - Improve project organization without changing the public URL structure.
 
+If the group needs a shared wrapper, put `layout.html` inside the `(group)` folder. That layout applies to every child route in the group while the group name stays out of the URL.
+
+Use this decision rule:
+
+- Use `dashboard/`, `account/`, or another normal folder when that segment should be part of the public path.
+- Use `(dashboard)`, `(marketing)`, or another parenthesized folder when you want shared organization or a shared layout without adding a public path segment.
+
 ## Layouts And Nesting
 
 Layouts work like the Next.js App Router layout system. A `layout.html` file wraps the routes beneath its folder, and nested layouts compose automatically.
 
+In practice, this means a dashboard is usually a folder-level layout, not a single oversized page. Put the shared sidebar, header, and frame in `dashboard/layout.html`, then create child routes such as `dashboard/settings/index.html` and `dashboard/reports/index.html` beneath it.
+
 When a layout imports components, keep each `<!-- @import ... -->` comment above the layout's authored wrapper element, such as the root `<section>` in a nested layout or the root `<html>` in the app layout.
 
 Resolved SEO fields are exposed to layouts as `[[ metadata.* ]]`, while values returned from `layout.py` are exposed separately as `[[ layout.* ]]`.
 
+### `layout.html`
+
+Use `layout.html` for the shared wrapper markup of a subtree. Keep the visible shell here, not in `layout.py`.
+
+Follow the same authoring contract used by route templates: one authored parent node, top-of-file `<!-- @import ... -->` directives above that root, plain `<script>` inside the root when needed, and no handwritten `pp-component` or `type="text/pp"`. See [pulsepoint.md](./pulsepoint.md) for the canonical authored-vs-runtime explanation.
+
 For example, a page inside `/dashboard/settings` is wrapped by the root layout first and then by the dashboard layout.
 
 Example root layout:
@@ -308,7 +363,7 @@ Example root layout:
 
 ### `layout.py`
 
-If a layout needs shared synchronous props or metadata, add a `layout.py` file next to the HTML layout.
+If a layout needs shared synchronous props or metadata, add a `layout.py` file next to the HTML layout. Treat it as the backend companion for the layout, not as the place to author visible wrapper markup.
 
 Example:
 
@@ -376,6 +431,10 @@ src/
     index.html
     about/
       index.html
+    (marketing)/
+      layout.html
+      pricing/
+        index.html
     users/
       [id]/
         index.html
@@ -395,9 +454,13 @@ src/
         index.py
     dashboard/
       layout.html
+      layout.py
+      index.html
       settings/
         index.html
         index.py
+      reports/
+        index.html
 ```
 
 ## AI Retrieval Notes
@@ -408,11 +471,14 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - 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`.
+- 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`.
+- 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.
+- Use a normal folder such as `dashboard/` when the segment should appear in the URL. Use `(group)/` only when the folder should organize or wrap child routes without adding a path segment.
 - 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.
 - When one route needs to change a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` and read that value as `[[ layout.dashboard_body_class ]]` in the wrapping `layout.html`.
 - Use `layout.py` for layout props that should apply across an entire subtree. Use `render_layout(__file__, {...})` only when the layout should consume direct local variables such as `[[ my_class ]]` instead of the standard `[[ layout.* ]]` namespace.
-- Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored root element.
+- Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored parent node.
 - Use [metadata.md](./metadata.md) when a route or layout needs SEO fields.
 - Use `[segment]` for single dynamic parameters.
 - Use `[...segment]` for catch-all route matching.

package/dist/docs/state.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Pair server request state with auth and RPC flows, then read the PulsePoint guide when the state really belongs in the browser instead of the request lifecycle.
   links:
+    - /docs/core-runtime-map
     - /docs/auth
     - /docs/fetch-data
     - /docs/pulsepoint
@@ -28,6 +29,8 @@ from casp.state_manager import StateManager
 
 The current installed implementation lives in `.venv/Lib/site-packages/casp/state_manager.py`.
 
+Use [core-runtime-map.md](./core-runtime-map.md) when a state task crosses `main.py` middleware setup, wire-request behavior, and the installed state-manager internals.
+
 The real API surface is:
 
 - request initialization with `StateManager.init(request)`

package/package.json

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